YouTube Most Popular Videos (Top by Country & Category)

Fetch the top most-popular YouTube videos by country and category using the YouTube Data API v3. API-only — no browser automation, fast, reliable, and cost-effective.

Features

• Fetch most popular videos for 50 countries via dropdown selector
• Filter by 32 YouTube categories (Music, Gaming, News, etc.) or select [All categories]
• Multi-region and multi-category batching in a single run
• Human-readable category names (videoCategoryTitle) alongside category IDs
• Pagination support (fetch more than 50 results per combo)
• Deduplication across region-category combinations
• Rank numbering per region-category combo
• Run summary saved to Key-Value Store
• Pay-per-event ready (video-result)

How it works

1. Select one or more regions (countries) from the dropdown
2. Select one or more categories — or choose [All categories] for the overall most popular
3. The actor calls videoCategories.list once per region to resolve category names
4. Then loops: regions → categories → pages, calling videos.list(chart=mostPopular)
5. Each video is ranked, deduplicated, and pushed to the dataset with 24 fields

Input Parameters

Parameter	Type	Default	Description
regions	string[]	required	Select countries from dropdown (50 available). e.g., ["US","AU","GB"]
categoryIds	string[]	[]	Select from dropdown: "[All categories]", "Music (10)", "Gaming (20)", etc. Empty = all
maxResultsPerPage	integer	50	Results per API page (1-50)
maxPages	integer	1	Pages per region-category combo
apiKey	string	—	Optional YouTube Data API v3 key (added to built-in rotation pool)
language	string	—	Language code for localization (e.g., en, ja)
dedupeAcrossCombos	boolean	true	Skip duplicate videos across combos
includeTopicDetails	boolean	false	Add topicDetails to response
includeStatus	boolean	false	Add status to response
includeLiveStreamingDetails	boolean	false	Add liveStreamingDetails to response
requestTimeoutSecs	integer	30	API request timeout
maxRetries	integer	3	Retries for transient 5xx errors
minDelayMs	integer	0	Delay between pages (rate smoothing)
debug	boolean	false	Verbose logging

Input examples

Example 1 — All categories for US and Australia

{
  "categoryIds": ["all"],
  "dedupeAcrossCombos": true,
  "regions": ["US", "AU"],
  "maxResultsPerPage": 50,
  "maxPages": 1
}

Example 2 — Specific categories (Short Movies + Autos) for AU and US

{
  "categoryIds": ["18", "2"],
  "dedupeAcrossCombos": true,
  "regions": ["AU", "US"],
  "maxResultsPerPage": 50,
  "maxPages": 1
}

Output

Table view — Most Popular Videos

Table view — All Fields

Output fields (24 fields)

Field	Type	Description
videoId	string	YouTube video ID
videoUrl	string	Full video URL
rank	integer	Position in the most-popular list
regionCode	string	Region this result was fetched for
videoCategoryId	string	Category ID
videoCategoryTitle	string	Category name (e.g., "Music", "Gaming")
title	string	Video title
description	string	Video description
publishedAt	string	ISO 8601 publish date
channelId	string	Channel ID
channelTitle	string	Channel name
thumbnails	object	Thumbnail URLs (default, medium, high, standard, maxres)
tags	string[]	Video tags
categoryIdFromSnippet	string	Raw category ID from video snippet
duration	string	ISO 8601 duration (e.g., PT5M10S)
definition	string	hd or sd
caption	string	"true" or "false"
licensedContent	boolean	Whether the content is licensed
viewCount	integer	Total views
likeCount	integer	Total likes (null if hidden)
commentCount	integer	Total comments (null if disabled)
liveBroadcastContent	string	none, live, or upcoming
retrievedAt	string	ISO 8601 timestamp when data was fetched

JSON output example

{
  "videoId": "iAtoZar5W58",
  "videoUrl": "https://www.youtube.com/watch?v=iAtoZar5W58",
  "retrievedAt": "2026-02-26T07:13:43.093Z",
  "rank": 1,
  "regionCode": "US",
  "videoCategoryId": "10",
  "videoCategoryTitle": "Music",
  "title": "Aaya Sher - Lyrical | The Paradise | Nani | Anirudh Ravichander | Srikanth Odela",
  "description": "Presenting the first single \"Aaya Sher\" from 'The Paradise'...",
  "publishedAt": "2026-02-24T14:44:06Z",
  "channelId": "UC68nKdrLbLL0Vj7ilVkLmmg",
  "channelTitle": "Saregama Telugu",
  "thumbnails": {
    "default": { "url": "https://i.ytimg.com/vi/iAtoZar5W58/default.jpg", "width": 120, "height": 90 },
    "medium": { "url": "https://i.ytimg.com/vi/iAtoZar5W58/mqdefault.jpg", "width": 320, "height": 180 },
    "high": { "url": "https://i.ytimg.com/vi/iAtoZar5W58/hqdefault.jpg", "width": 480, "height": 360 }
  },
  "tags": ["Anirudh Ravichander", "The Paradise Theme OST", "Nani The Paradise theme"],
  "categoryIdFromSnippet": "10",
  "duration": "PT4M57S",
  "definition": "hd",
  "caption": "false",
  "licensedContent": true,
  "viewCount": 19761396,
  "likeCount": 789769,
  "commentCount": 23899,
  "liveBroadcastContent": "none"
}

Quota usage

• videos.list costs 1 quota unit per request (up to 50 results)
• videoCategories.list costs 1 quota unit per region (called once per region)
• Total quota = regions + (regions x categories x pages)
• Example: 5 regions x 3 categories x 2 pages + 5 lookups = 35 units

Supported regions (50 countries)

Region	Country	Region	Country
US	United States	JP	Japan
GB	United Kingdom	KR	South Korea
AU	Australia	TW	Taiwan
CA	Canada	HK	Hong Kong
IN	India	SG	Singapore
DE	Germany	ID	Indonesia
FR	France	TH	Thailand
IT	Italy	PH	Philippines
ES	Spain	MY	Malaysia
PT	Portugal	VN	Vietnam
BR	Brazil	RU	Russia
MX	Mexico	UA	Ukraine
AR	Argentina	PL	Poland
CO	Colombia	NL	Netherlands
CL	Chile	BE	Belgium
SE	Sweden	ZA	South Africa
NO	Norway	EG	Egypt
DK	Denmark	NG	Nigeria
FI	Finland	KE	Kenya
AT	Austria	GH	Ghana
CH	Switzerland	AE	UAE
IE	Ireland	SA	Saudi Arabia
NZ	New Zealand	IL	Israel
TR	Turkey	CZ	Czech Republic
GR	Greece	RO	Romania

Common category IDs

ID	Category	ID	Category
1	Film & Animation	24	Entertainment
2	Autos & Vehicles	25	News & Politics
10	Music	26	Howto & Style
15	Pets & Animals	27	Education
17	Sports	28	Science & Technology
20	Gaming	29	Nonprofits & Activism
22	People & Blogs	30	Movies
23	Comedy	44	Trailers

Note: Not all categories are available in every region. The actor automatically resolves available categories per region.

Run summary

Each run saves a RUN_SUMMARY to the Key-Value Store with:

• Total videos emitted, API calls made, duplicates skipped
• Per-combo breakdown (region, category, count, errors)