YouTube Trending Videos by Country and Category

Get YouTube's most-popular (trending) videos for any country and category, ranked, with views, likes, comments, duration and channel, from the official YouTube Data API. Each row is one ranked video. You bring your own free YouTube Data API key; this actor never ships one and never stores yours.

Related actors: to look up one video you already know, use YouTube Video Stats Lookup; for a channel, YouTube Channel Lookup. This actor is about the chart.

Who uses it

• Creators and social teams see what is trending in Music, Gaming or News in the countries they publish in, before planning the next upload.
• Agencies and brand teams pull the daily top videos per market into Sheets, n8n or Make for a trend report.
• Researchers and newsletters snapshot the chart per country and category on a schedule and keep the history.

You need a free YouTube Data API key

The data comes from Google's own YouTube Data API v3, which only answers requests that carry a key. Getting one takes about 10 minutes and costs nothing: create a project in Google Cloud Console, enable YouTube Data API v3, then Credentials > Create credentials > API key. Paste it into the Your YouTube Data API v3 key field. The key is marked secret, is sent only to googleapis.com in a request header, and never appears in a row, a log or a link.

Without a key the run still succeeds: every country comes back as one row with status: NEEDS_KEY that tells you where to get the key, and you are never charged for it.

Quota. A free key has 10,000 units a day on your own Google project, and one chart page of 50 videos costs 1 unit, so quota is not the limit. A used-up quota comes back as a clear BLOCKED row, and resets at midnight Pacific time. Your use of the key is under your own agreement with YouTube (YouTube API Services Terms of Service).

How to use

1. In the Apify Console. Open the actor page and click Start — the regionCodes field is already pre-filled with a working example. Results land in the run's dataset as soon as each item is found.
2. Via the API. Call it directly with a POST request — no Console needed once you have an API token:

   curl "https://api.apify.com/v2/acts/accountable_eel~youtube-trending-videos-lookup/run-sync-get-dataset-items?token=<YOUR_TOKEN>" \
     -X POST \
     -H "Content-Type: application/json" \
     -d '{"regionCodes":["US"]}'
   

3. On a schedule. Save this actor as an Apify Task with the input you want, then add a Schedule (hourly, daily, weekly) so it runs on its own — no server of your own required.

Input

{
  "regionCodes": [
    "US"
  ]
}

One two-letter country code per line (ISO 3166-1, for example US, GB, DE, JP). Each country gets its own chart. You need your own free YouTube Data API key (field below) to get rows. Accepted formats: US, GB, DE.

Country. Two-letter ISO country codes, one per line. Each country is its own chart. UK is read as GB.

Category. "All categories" is YouTube's overall most-popular chart for the country. A category (Music, Gaming, News & Politics, Sports and so on) reads that category's own chart. Some countries have no chart for some categories; that comes back as a free NOT_FOUND row.

Videos per country. 1 to 100, default 20. Ranks run from 1 (most popular) down.

Output

One row per ranked video, for example:

query	found	status	regionCode	categoryFilter	chartSummary	videoCount	sourceUrl	videos	rank	videoId	title	channelTitle	channelId	publishedAt	categoryId	categoryName	viewCount	likeCount	commentCount	duration	durationSeconds	description	thumbnailUrl	defaultLanguage	url	scrapedAt
US	true	OK						<all videos (full list)>				<channel>								<duration (iso 8601)>	<duration (seconds)>	<description (first 300 characters)>				1970-01-01T00:00:00.000Z

A country with no chart, a bad country code, a rejected key and a run with no key all come back as a row with "found": false and a status (NOT_FOUND, BAD_FORMAT, BLOCKED, NEEDS_KEY) and are never charged. Values YouTube does not publish are null, never 0 or an empty string: a video with likes hidden has likeCount: null, a video with comments turned off has commentCount: null. Every row carries the video page in url, the API request it came from in sourceUrl (without your key), and scrapedAt.

Pricing

Pay-per-event. A flat per-run fee covers session/proxy warmup; you're billed per item only when data is actually found and returned — see .actor/pay_per_event.json for exact prices. A miss is never charged.

A top-20 chart is 20 videos. Countries without a key, misses and errors are free.

Example runs

Paste any of these into the Input tab, add your own key in the key field, and press Start. Without a key each returns one free NEEDS_KEY row per country so you can see the shape.

US overall chart, top 20. The default shape.

{
  "regionCodes": ["US"],
  "categoryId": "all",
  "maxResults": 20
}

Music chart in three countries, top 10 each.

{
  "regionCodes": ["GB", "DE", "FR"],
  "categoryId": "10",
  "maxResults": 10
}

Gaming chart in Japan, top 50.

{
  "regionCodes": ["JP"],
  "categoryId": "20",
  "maxResults": 50
}

Use it from Clay, n8n, Make, or an AI agent

This actor runs synchronously over plain HTTP — call it directly from a script, a workflow tool, or an AI agent, no Apify Console needed once you have an API token.

curl "https://api.apify.com/v2/acts/accountable_eel~youtube-trending-videos-lookup/run-sync-get-dataset-items?token=<YOUR_TOKEN>" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"regionCodes":["US"]}'

n8n. Add an HTTP Request node: Method POST, URL https://api.apify.com/v2/acts/accountable_eel~youtube-trending-videos-lookup/run-sync-get-dataset-items?token=<YOUR_TOKEN>, Body Content Type JSON, JSON Body {"regionCodes":["US"]} (swap in an expression from an earlier node for a real value).

Clay. Add an "HTTP API" column: Method POST, URL https://api.apify.com/v2/acts/accountable_eel~youtube-trending-videos-lookup/run-sync-get-dataset-items?token=<YOUR_TOKEN>, Body {"regionCodes":["{{country chart}}"]}, mapping the row's country chart into the regionCodes array.

MCP. In Claude, Cursor, or any MCP client with the Apify MCP server, ask for "youtube trending videos by country" — the agent will find and run this actor.