Discovering Viral Youtube Videos By Category

---

Inputs

Parameter	Type	Required	Default	Notes
type	string	Optional	n	Trending category: n (now), music, movies, gaming
gl	string	Optional	us	Country code (e.g. US, GB)
hl	string	Optional	en	Language code (e.g. en)
maxItems	number	Optional	Unlimited	Maximum videos to return
customMapFunction	string	Optional	—	JavaScript function to transform each output object

How to Run

Using run_actor.js (recommended)

# Quick answer (table)
node scripts/run_actor.js --actor "apidojo~youtube-trending-scraper" --input '{"type": "n", "gl": "us", "hl": "en", "maxItems": 50}'

# Save as CSV
node scripts/run_actor.js --actor "apidojo~youtube-trending-scraper" --input '{"type": "n", "gl": "us", "hl": "en", "maxItems": 50}' --output results.csv --format csv

# Save as JSON
node scripts/run_actor.js --actor "apidojo~youtube-trending-scraper" --input '{"type": "n", "gl": "us", "hl": "en", "maxItems": 50}' --output results.json --format json

REST API fallback

curl -X POST "https://api.apify.com/v2/acts/apidojo~youtube-trending-scraper/runs" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "n", "gl": "us", "hl": "en", "maxItems": 50}'

If Apify MCP is available: Use the Apify MCP call_actor tool with actor apidojo~youtube-trending-scraper and the input above.

---

Scoring & Ranking

Score each video by:

• views → normalized 0-1 (cap at 10M), weight 0.40
• likes → normalized 0-1 (cap at 500K), weight 0.35
• recency (trending = 1.0 by definition), weight 0.25

score = 0.40 * min(views / 10000000, 1.0) + 0.35 * min(likes / 500000, 1.0) + 0.25

---

Classification

Score	Tier	Label
≥ 0.70	A	MEGA_VIRAL
0.40–0.69	B	TRENDING
< 0.40	C	RISING

---

Edge Cases

• Category not available for country: Some countries only have n (all). Fall back to type=n.
• Stale data: Trending changes throughout the day — data is a snapshot.
• Music/movies category: Returns full songs or trailers — content type differs from regular videos.
• Livestreams in results: isLive=true items are ongoing streams — filter if you need VOD only.
• Country mismatch: gl must be a valid ISO country code (e.g., us, gb, de).