# YouTube Trending Videos Scraper (`automation-lab/youtube-trending-videos-scraper`) Actor Scrape ranked YouTube Trending videos by country and category with video IDs, titles, channels, views, thumbnails, and source URLs. - **URL**: https://apify.com/automation-lab/youtube-trending-videos-scraper.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** Social media - **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing Pay per event 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. Actors are written with capital "A". ## 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. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## YouTube Trending Videos Scraper Scrape public YouTube trending-style video results by country, category, and result limit. Use this actor to monitor what videos are gaining attention, build content research dashboards, and export structured YouTube video metadata without maintaining your own parser. ### What does YouTube Trending Videos Scraper do? YouTube Trending Videos Scraper collects ranked video rows for a selected country and category. It is designed for recurring monitoring jobs where you need a clean dataset instead of manually opening YouTube and copying titles. The actor returns video IDs, watch URLs, titles, channel names, published-time text, view counts when available, thumbnails, selected category, selected region, and the source URL used for the run. It first tries the public YouTube Trending page. If YouTube returns a logged-out shell with no video renderers, the actor can transparently use a public YouTube search fallback for the same trending category. Each row includes `sourceType` so you can see whether the result came from the official page or from the fallback. ### Who is it for? #### Content strategists Use the actor to spot video topics, formats, and hooks that are currently popular in a target market. #### Social media agencies Run the actor daily for multiple countries and categories, then compare rising topics across clients and regions. #### News and market monitors Track what public YouTube users are likely seeing around news, sports, entertainment, music, and education topics. #### Creator teams Export titles, thumbnails, durations, channels, and view-count text for inspiration boards and editorial calendars. #### Data analysts Feed ranked video metadata into spreadsheets, BI tools, warehouses, or notification workflows. ### Why use this actor? - ๐ŸŽฏ Country-aware input using YouTube `gl` region codes. - ๐Ÿงญ Category presets for general, music, gaming, movies, news, sports, fashion, and learning. - ๐Ÿ“ฆ Structured JSON dataset ready for export. - ๐Ÿ”— Direct YouTube watch URLs and video IDs. - ๐Ÿ–ผ๏ธ Thumbnail URLs for dashboards. - โฑ๏ธ Duration and published-time text when exposed by YouTube. - ๐Ÿ“Š View-count text plus parsed numeric views when possible. - ๐Ÿงพ Source URL and source type for auditing. - โš™๏ธ HTTP-only implementation for lower run cost. - ๐Ÿงช Conservative default input for cheap first tests. ### What data can you extract? | Field | Description | | --- | --- | | `rank` | Rank within the returned dataset. | | `videoId` | YouTube video identifier. | | `url` | Direct `https://www.youtube.com/watch?v=...` URL. | | `title` | Video title. | | `channelName` | Channel name when available. | | `channelUrl` | Channel URL when available. | | `publishedTimeText` | Human-readable freshness text, such as `2 days ago`. | | `viewCountText` | Human-readable views text. | | `viewCount` | Parsed numeric view count when possible. | | `durationText` | Video duration text. | | `thumbnailUrl` | Best available thumbnail URL. | | `badges` | Renderer badges such as verified labels when available. | | `category` | Category input used for the run. | | `region` | Country code input used for the run. | | `sourceType` | Official trending page or fallback search. | | `sourceUrl` | URL fetched for the returned rows. | | `scrapedAt` | ISO timestamp for the scrape. | ### How much does it cost to scrape YouTube trending videos? This actor uses pay-per-event pricing. There is a small start charge per run and a per-video charge for each saved dataset item. The default input is intentionally small so you can test the actor cheaply before scheduling larger jobs. For the latest exact price, check the Pricing tab on the Apify Store page. ### How to use YouTube Trending Videos Scraper 1. Open the actor on Apify. 2. Choose a country code, for example `US`, `GB`, `DE`, `IN`, or `BR`. 3. Pick a category such as `all`, `music`, `gaming`, or `news`. 4. Set `maxItems` to the number of videos you want. 5. Keep `fallbackToSearch` enabled unless you only want official-page rows. 6. Start the run. 7. Export the dataset as JSON, CSV, Excel, XML, or RSS. ### Input options #### `region` Two-letter country code used by YouTube. Examples: - `US` - `GB` - `DE` - `IN` - `BR` - `CA` - `AU` - `JP` #### `category` Supported values: - `all` - `music` - `gaming` - `movies` - `news` - `sports` - `fashion` - `learning` #### `maxItems` Maximum number of videos to save. Use a small value for test runs. Use a larger value for scheduled monitoring jobs. #### `language` YouTube interface language, for example `en`, `de`, `es`, `fr`, or `pt`. #### `fallbackToSearch` YouTube sometimes returns a logged-out page with no public video renderers. When this option is enabled, the actor uses public YouTube search for a matching trending query and records `sourceType: youtube_search_fallback`. Disable it if your workflow requires only official Trending-page rows. ### Example input ```json { "region": "US", "category": "all", "maxItems": 25, "language": "en", "fallbackToSearch": true } ```` ### Example output ```json { "rank": 1, "videoId": "dQw4w9WgXcQ", "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "title": "Example trending video title", "channelName": "Example Channel", "channelUrl": "https://www.youtube.com/@example", "publishedTimeText": "1 day ago", "viewCountText": "1.2M views", "viewCount": 1200000, "durationText": "12:34", "thumbnailUrl": "https://i.ytimg.com/vi/example/hqdefault.jpg", "badges": [], "category": "all", "region": "US", "sourceType": "youtube_search_fallback", "sourceUrl": "https://www.youtube.com/results?...", "scrapedAt": "2026-06-13T00:00:00.000Z" } ``` ### Tips for best results - Start with `maxItems: 25` to validate your workflow. - Schedule daily or hourly runs for trend monitoring. - Store `sourceType` in your downstream table so you can filter official-page rows separately. - Compare the same category across multiple regions. - Use `videoId` as a stable deduplication key. - Keep thumbnails for editorial review boards. - Use `viewCount` for numeric sorting when YouTube exposes view text. ### Common workflows #### Daily content briefing Schedule one run every morning for your target country. Send the dataset to Slack, email, Google Sheets, or a BI dashboard. #### Regional comparison Run the actor for `US`, `GB`, `DE`, `IN`, and `BR`. Join the results by timestamp and compare titles, channels, and categories. #### Creator inspiration board Export titles and thumbnails into a spreadsheet. Review hooks, formats, durations, and channels during planning meetings. #### News monitoring Use the `news` category and a small result limit. Alert your team when new high-interest topics appear. ### Integrations You can connect this actor to: - Google Sheets exports for editorial planning. - Make or Zapier for alerting workflows. - Slack or Discord notifications for daily trend digests. - BigQuery, Snowflake, or PostgreSQL for historical trend analysis. - Apify webhooks for event-driven automation. - Actor tasks for scheduled country/category monitoring. ### API usage #### Node.js ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('automation-lab/youtube-trending-videos-scraper').call({ region: 'US', category: 'all', maxItems: 25, language: 'en', fallbackToSearch: true, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items); ``` #### Python ```python from apify_client import ApifyClient import os client = ApifyClient(os.environ['APIFY_TOKEN']) run = client.actor('automation-lab/youtube-trending-videos-scraper').call(run_input={ 'region': 'US', 'category': 'all', 'maxItems': 25, 'language': 'en', 'fallbackToSearch': True, }) items = client.dataset(run['defaultDatasetId']).list_items().items print(items) ``` #### cURL ```bash curl -X POST "https://api.apify.com/v2/acts/automation-lab~youtube-trending-videos-scraper/runs?token=$APIFY_TOKEN" \ -H 'Content-Type: application/json' \ -d '{"region":"US","category":"all","maxItems":25,"language":"en","fallbackToSearch":true}' ``` ### MCP integration Use Apify MCP to run this actor from Claude Code, Claude Desktop, or compatible MCP clients. MCP endpoint: ```text https://mcp.apify.com/?tools=automation-lab/youtube-trending-videos-scraper ``` Claude Code setup: ```bash claude mcp add apify-youtube-trending https://mcp.apify.com/?tools=automation-lab/youtube-trending-videos-scraper ``` Claude Desktop JSON config: ```json { "mcpServers": { "apify-youtube-trending": { "url": "https://mcp.apify.com/?tools=automation-lab/youtube-trending-videos-scraper" } } } ``` Example prompts: - "Run the YouTube Trending Videos Scraper for US music and summarize the top 10 titles." - "Collect trending gaming videos for GB and export the dataset URL." - "Compare US and IN trending video titles from two actor runs." ### Reliability notes YouTube changes renderer structures over time. This actor walks multiple common renderer types and skips incomplete rows instead of failing on a single malformed item. The `sourceType` field is important because YouTube's public logged-out Trending page may not always expose video renderers from every network or region. When that happens, the fallback keeps the workflow productive while remaining transparent. ### Limitations - The actor does not log in to YouTube. - The actor does not use private cookies or user accounts. - Likes and comments are not guaranteed from public list pages. - View counts can be missing or approximate. - Official category URLs may vary by country and YouTube experiment. - Search fallback results are trending-style search results, not guaranteed official Trending rankings. ### Legality This actor collects public information visible without a YouTube account. You are responsible for using the data in a way that complies with applicable laws, YouTube's terms, and privacy requirements. Do not use the actor to collect private, personal, or account-only data. ### FAQ #### Does it require a YouTube API key? No. The actor uses public web pages and does not require your YouTube Data API quota. #### Why do I see `youtube_search_fallback` in `sourceType`? It means YouTube returned no video renderers on the logged-out Trending page for that request, so the actor used public search for the selected trending category. #### Can I scrape multiple countries in one run? The current version accepts one country per run. Create multiple Apify tasks if you want a scheduled multi-country monitor. #### Can I get likes and comments? List pages do not reliably expose likes or comment counts. Use the video URL with a separate video detail actor if you need those metrics. #### Why are some view counts null? YouTube sometimes hides or localizes view text. The actor keeps the raw `viewCountText` and parses `viewCount` only when the text is available and recognizable. ### Troubleshooting #### The dataset has fewer rows than requested YouTube may expose fewer public renderers for the selected country/category. Try a broader category such as `all`, enable `fallbackToSearch`, or reduce `maxItems`. #### The run fails with no videos extracted Try a different region, confirm `fallbackToSearch` is enabled, and rerun with a small `maxItems` value. ### Related scrapers Explore other Automation Lab YouTube and social media actors: - https://apify.com/automation-lab/youtube-scraper - https://apify.com/automation-lab/youtube-channel-scraper - https://apify.com/automation-lab/youtube-comments-scraper - https://apify.com/automation-lab/youtube-transcript-scraper - https://apify.com/automation-lab/youtube-search-scraper ### Changelog #### 0.1 Initial version with country/category input, ranked video output, official-page parser, and transparent public search fallback. # Actor input Schema ## `region` (type: `string`): Two-letter country code used by YouTube, such as US, GB, DE, IN, BR, CA, AU, or JP. ## `category` (type: `string`): YouTube trending lane to collect. Some category lanes may fall back to public search when the logged-out Trending page is empty. ## `maxItems` (type: `integer`): Maximum number of ranked videos to save to the dataset. ## `language` (type: `string`): YouTube interface language, for example en, de, es, fr, or pt. ## `fallbackToSearch` (type: `boolean`): If YouTube's logged-out Trending page returns no video renderers, collect public YouTube search results for the selected trending category instead of failing. ## Actor input object example ```json { "region": "US", "category": "all", "maxItems": 20, "language": "en", "fallbackToSearch": true } ``` # Actor output Schema ## `overview` (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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "region": "US", "category": "all", "maxItems": 20, "language": "en", "fallbackToSearch": true }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/youtube-trending-videos-scraper").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "region": "US", "category": "all", "maxItems": 20, "language": "en", "fallbackToSearch": True, } # Run the Actor and wait for it to finish run = client.actor("automation-lab/youtube-trending-videos-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("๐Ÿ’พ Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # ๐Ÿ“š Want to learn more ๐Ÿ“–? Go to โ†’ https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "region": "US", "category": "all", "maxItems": 20, "language": "en", "fallbackToSearch": true }' | apify call automation-lab/youtube-trending-videos-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/youtube-trending-videos-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "YouTube Trending Videos Scraper", "description": "Scrape ranked YouTube Trending videos by country and category with video IDs, titles, channels, views, thumbnails, and source URLs.", "version": "0.1", "x-build-id": "XiR9X7mNQzDeCWMH9" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~youtube-trending-videos-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-youtube-trending-videos-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/automation-lab~youtube-trending-videos-scraper/runs": { "post": { "operationId": "runs-sync-automation-lab-youtube-trending-videos-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/automation-lab~youtube-trending-videos-scraper/run-sync": { "post": { "operationId": "run-sync-automation-lab-youtube-trending-videos-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "region", "maxItems" ], "properties": { "region": { "title": "Country / region", "minLength": 2, "maxLength": 2, "type": "string", "description": "Two-letter country code used by YouTube, such as US, GB, DE, IN, BR, CA, AU, or JP.", "default": "US" }, "category": { "title": "Trending category", "enum": [ "all", "music", "gaming", "movies", "news", "sports", "fashion", "learning" ], "type": "string", "description": "YouTube trending lane to collect. Some category lanes may fall back to public search when the logged-out Trending page is empty.", "default": "all" }, "maxItems": { "title": "Maximum videos", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum number of ranked videos to save to the dataset.", "default": 50 }, "language": { "title": "Language", "type": "string", "description": "YouTube interface language, for example en, de, es, fr, or pt.", "default": "en" }, "fallbackToSearch": { "title": "Use search fallback", "type": "boolean", "description": "If YouTube's logged-out Trending page returns no video renderers, collect public YouTube search results for the selected trending category instead of failing.", "default": true } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```