# YouTube Trending Videos by Country and Category (`accountable_eel/youtube-trending-videos-lookup`) Actor

Get YouTube's most-popular (trending) videos for any country and category through the official YouTube Data API, with views, likes, comments, duration and channel. Bring your own free API key. Pay per ranked video.

- **URL**: https://apify.com/accountable_eel/youtube-trending-videos-lookup.md
- **Developed by:** [Adriana Voss](https://apify.com/accountable_eel) (community)
- **Categories:** Social media, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 ranked video returneds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 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](https://apify.com/accountable_eel/youtube-video-stats-lookup); for a channel, [YouTube Channel Lookup](https://apify.com/accountable_eel/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:
   ```bash
   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

```json
{
  "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 | <country> | <category filter> | <chart run> | <videos returned> | <source request> | \<all videos (full list)> | <rank> | <video id> | <title> | <channel> | <channel id> | <published on> | <category id> | <category> | <views> | <likes> | <comments> | \<duration (iso 8601)> | \<duration (seconds)> | \<description (first 300 characters)> | <thumbnail> | <language> | <video page> | 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.

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

**Music chart in three countries, top 10 each.**

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

**Gaming chart in Japan, top 50.**

```json
{
  "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.

```bash
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.

# Actor input Schema

## `regionCodes` (type: `array`):

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. You're only charged for the ones we actually find — a miss costs nothing.

## `youtubeApiKey` (type: `string`):

Optional but needed for rows. Get a free key in about 10 minutes: create a project in Google Cloud Console, enable YouTube Data API v3, then Credentials > Create credentials > API key. Free quota is 10,000 units a day and one chart page (50 videos) costs 1 unit. Without a key every country comes back as a NEEDS_KEY row that is never charged. The key is sent only to googleapis.com, in a request header, and is never stored, logged or written to the dataset.

## `categoryId` (type: `string`):

Which chart to read. 'All categories' is YouTube's overall most-popular chart for the country. Some countries have no chart for some categories; those come back as a free NOT_FOUND row.

## `maxResults` (type: `integer`):

Optional. Stop the run once this many results have been found — useful for a quick, cheap sample. Leave blank for no limit.

## `testRun` (type: `boolean`):

Turn this on to test your input on a small sample before running the full list. Turn it off to process everything.

## `onlyFound` (type: `boolean`):

Only keep rows where something was actually found. Misses are always free, whether or not you show them here.

## `includeKeywords` (type: `array`):

Optional. Only keep results that mention at least one of these words (e.g. a job title, a city, a product name). Leave empty to keep everything.

## `excludeKeywords` (type: `array`):

Optional. Drop any result that mentions one of these words. Leave empty to skip nothing.

## `columns` (type: `array`):

Choose which pieces of information to include in each result row. All are included by default.

## `expandRows` (type: `boolean`):

When on, each video found gets its own row instead of being grouped under its country chart. You're still only charged once per country chart, no matter how many rows it produces.

## `maxConcurrency` (type: `integer`):

Parallel requests. Keep conservative — this target has no browser fallback, so getting blocked costs more than slow-and-steady.

## Actor input object example

```json
{
  "regionCodes": [
    "US"
  ],
  "categoryId": "all",
  "testRun": false,
  "onlyFound": false,
  "includeKeywords": [],
  "excludeKeywords": [],
  "columns": [
    "regionCode",
    "categoryFilter",
    "chartSummary",
    "videoCount",
    "sourceUrl",
    "videos",
    "rank",
    "videoId",
    "title",
    "channelTitle",
    "channelId",
    "publishedAt",
    "categoryId",
    "categoryName",
    "viewCount",
    "likeCount",
    "commentCount",
    "duration",
    "durationSeconds",
    "description",
    "thumbnailUrl",
    "defaultLanguage",
    "url"
  ],
  "expandRows": true,
  "maxConcurrency": 2
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "regionCodes": [
        "US"
    ],
    "includeKeywords": [],
    "excludeKeywords": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("accountable_eel/youtube-trending-videos-lookup").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "regionCodes": ["US"],
    "includeKeywords": [],
    "excludeKeywords": [],
}

# Run the Actor and wait for it to finish
run = client.actor("accountable_eel/youtube-trending-videos-lookup").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "regionCodes": [
    "US"
  ],
  "includeKeywords": [],
  "excludeKeywords": []
}' |
apify call accountable_eel/youtube-trending-videos-lookup --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,accountable_eel/youtube-trending-videos-lookup"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/UKx6g7LfuAyQ6P2DI/builds/63oR9dKN9w1xYAEVS/openapi.json