YouTube Trending Scraper

Capture a point-in-time snapshot of YouTube trending videos for any supported country — and optionally a Music, Gaming, Movies, or Now shelf — as structured Dataset rows you can schedule, export, and join to the rest of your enrichment stack.

Built by ScrapeMamba for Apify. This apify youtube scraper is the chart-pulse youtube scraper in the suite: open YouTube Trending Scraper, pick a country (default US), optionally choose a section and UI language, and cap how many videos you keep from the first trending page. Trending on YouTube moves fast — every run is a snapshot, not a historical archive. If you need to scrape YouTube charts without babysitting browsers, this Actor is the lightest-cost entry point before deeper youtube scraping (metadata, related graphs, or transcripts).

This Actor is the cheapest entry in the ScrapeMamba YouTube suite on Apify ($1.70 per 1,000 results). Use it when you want a pulse on what is rising in a market before you spend more on video details or captions.

---

Overview

YouTube’s Trending surface is a curated, region-sensitive chart. Marketers, researchers, and data teams often want YouTube trending videos in a warehouse — not in a browser tab — so they can:

• Diff daily or hourly chart membership by country
• Seed competitor and creator watchlists from what is trending on YouTube right now
• Feed downstream scrapers with fresh, high-signal video IDs

YouTube Trending Scraper calls ScrapeMamba’s /youtube/trending endpoint with your country, optional lang, and optional section. The Actor maps listing items into a stable video schema (videoId, title, author, channelId, views, length, publishedTime, thumbnail, url, and more), tags each row with the country and section you requested, and pushes them to the Apify Dataset.

Important behavioral facts (accurate to this Actor’s code):

• All input fields are optional. Defaults: country = US, maxResults = 50.
• First page only. Continuation tokens are ignored; a second page fetch returns an empty payload by design. Raising maxResults only keeps more items from that single first-page response (capped 1–500).
• No worker pool. One country (and one section) is fetched per run — there is no multi-country fan-out inside a single Actor start.
• Strict failure mode. If the trending fetch throws, the Actor pushes a type: "error" row, then exits with exit code 1.

Public YouTube data only. Private, region-blocked, or otherwise unavailable surfaces may produce empty charts or error rows.

---

Who this is not for

• Media downloaders — extracts chart metadata, not video/audio files.
• Historical ranking archives — charts change fast; store your own run timestamps and diffs.
• Personalized Trending — public surface only.

---

What it does

• Fetches the trending listing for an ISO country code (default US)
• Optionally targets a shelf via section: Now, Music, Gaming, or Movies
• Optionally passes a UI lang (for example en) when you want language-biased presentation
• Caps how many mapped videos to keep with maxResults (default "50", range 1–500)
• Writes type: "video" rows (and type: "error" on hard failure)
• Leaves section as null in the Dataset when you did not set a section

---

Why ScrapeMamba on Apify

Trending pages are HTML- and Innertube-heavy. Building and babysitting your own browser farm for a daily chart scrape is usually more expensive than the chart is worth. ScrapeMamba’s backend handles the fetch; this Apify Actor handles input validation, field mapping, Dataset persistence, schedules, and exports — the same operational model as the rest of the suite’s youtube scraper Actors.

You get a fixed schema for BI joins on videoId, Dataset export, schedules/webhooks, handoff into Search / Video / Channel Scrapers, and a youtube scraper api path via Apify Client.

If you already discover keywords with Search Scraper, Trending is the complementary “what the platform is pushing right now” feed.

---

Use cases

1. Daily market pulse

Schedule the Actor for country: "US" (or your primary market) every morning. Store Dataset snapshots by run ID or append fetchedAt in your warehouse ETL. Diff videoId sets day over day to see what entered, left, or stuck on the chart of YouTube trending videos.

2. Vertical shelf monitoring

Set section to Music, Gaming, or Movies when you care about a vertical, not the general Now chart. Run separate schedules per section if you need parallel coverage — this Actor does one section per run.

3. Seed lists for enrichment

Take trending videoId values and pipe them into YouTube Video Scraper for fuller metadata (description, likes when exposed, microformat dates). Optionally resolve uploaders with YouTube Channel Scraper.

4. Competitive and culture research

Compare the same section across countries (for example US vs IN vs GB) with separate runs. Because charts are snapshots of what is trending on YouTube, keep timestamps; do not assume yesterday’s Gaming shelf still looks like today’s.

5. Lightweight alerting

Webhook a schedule when a competitor channelId appears on today’s shelf.

6. Catalog seeding

Pull top N trending URLs into a CMS draft queue with a low maxResults (10–20).

---

Pricing

• $1.70 per 1,000 results (cheapest in the ScrapeMamba YouTube suite on Apify)

You pay for Dataset rows from the run. Validate Input before scheduling aggressively so failed runs do not burn compute.

---

Input

All fields are optional.

Field	Type	Required	Default	Description
country	string	No	US	ISO 3166-1 alpha-2 country code (normalized to uppercase). Invalid codes fall back to US.
lang	string	No	—	Optional UI language (for example en). Empty/blank values are omitted from the API body.
section	string (select)	No	—	Trending shelf: Now, Music, Gaming, or Movies. When unset, section on output rows is null.
maxResults	string / number	No	"50"	Maximum videos to keep from the first trending page. Clamped to 1–500.

Input JSON examples

Default US chart, first 50 videos:

{}

Music shelf in India, English UI, top 30:

{
  "country": "IN",
  "lang": "en",
  "section": "Music",
  "maxResults": "30"
}

Gaming shelf, United Kingdom:

{
  "country": "GB",
  "section": "Gaming",
  "maxResults": "50"
}

---

Output

Row types

type	When	Notes
video	Successful mapped listing item with a videoId	Includes country, section (null if unset), page, mapped fields, and raw
error	Hard failure of the trending fetch	Includes country, section, and error string; Actor then exits with code 1

Video field reference

Field	Description
type	Always "video" for success rows
country	Normalized country used for the request (for example US)
section	Shelf you selected, or null
page	Listing page index (effectively 1 — first page only)
videoId	Canonical 11-character YouTube ID
title	Video title when present on the listing
author	Channel display name when present
channelId	Uploader UC… ID when the listing exposes it
views	View count text or number as returned by the listing
length	Duration text when available
publishedTime	Relative or absolute publish string when present
description	Short description / snippet when present (may be truncated in mapping)
thumbnail	Best available thumbnail URL
url	Watch or Shorts URL derived from videoId
isShort	Boolean hint when the listing looks like a Short
raw	Underlying renderer / payload fragment for debugging

Items without a resolvable videoId are skipped and never pushed.

Example video row

{
  "type": "video",
  "country": "US",
  "section": "Music",
  "page": 1,
  "videoId": "dQw4w9WgXcQ",
  "title": "Example Trending Track",
  "author": "Example Artist",
  "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
  "views": "1.2M views",
  "length": "3:32",
  "publishedTime": "2 days ago",
  "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "isShort": false
}

Example error row

{
  "type": "error",
  "country": "US",
  "section": null,
  "error": "HTTP 500: Upstream fetch failed. ..."
}

---

Backend endpoint

The Actor POSTs to ScrapeMamba:

POST /youtube/trending

Request body fields (only non-empty values are sent):

API field	Source
country	Input country (default US)
lang	Input lang when set
section	Input section when set

The HTTP client retries on 429, 500, 502, 503, and 504 (up to 3 attempts with backoff).

Pagination note: Even though the shared helper can walk continuations for other Actors, this trending Actor’s fetchPage returns {} whenever a continuation token is present. Practically: first page only.

---

How to run on Apify (walkthrough)

1. Open YouTube Trending Scraper on Apify.
2. Click Start (or Try for free).
3. Leave Input empty for a default US chart of up to 50 videos, or set country / section / lang / maxResults.
4. Wait for the run to finish. Open the Dataset tab and confirm type: "video" rows.
5. Export JSON/CSV/Excel, or pull rows via the Apify API / client SDKs.
6. For production pulse checks, create an Apify Schedule (for example daily at 09:00 in your timezone) and optionally a webhook to your ETL.

Quick start checklist

1. One public country with a known Trending surface (start with US)
2. Confirm Dataset columns (videoId, title, country)
3. Add section only after the default shelf looks right
4. Schedule once you accept that charts are snapshots

---

Apify API example

Start a run with the Apify API:

curl "https://api.apify.com/v2/acts/scrapemamba~youtube-trending-scraper/runs" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "US",
    "section": "Gaming",
    "lang": "en",
    "maxResults": "40"
  }'

Node.js sketch with the Apify client:

import { ApifyClient } from 'apify-client';

const client = new ApifyClient();
const run = await client.actor('scrapemamba/youtube-trending-scraper').call({
  country: 'US',
  section: 'Music',
  maxResults: '50',
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items.filter((row) => row.type === 'video').length);

---

Errors and exit behavior

On trending fetch failure the Actor logs, pushes { type: "error", country, section, error }, then Actor.exit({ exitCode: 1 }). Schedules/CI can treat non-zero exit as hard failure. An empty-but-successful chart (zero mapped videos) does not force exit code 1.

Common errors: HTTP 429/5xx after retries, API returned success=false, 60s request timeout.

---

Best practices

1. Treat results as snapshots — store run time with every videoId list.
2. Start with defaults (US, empty Input) before adding sections.
3. One country/section per run — fan out with parallel Actor starts for multi-market coverage.
4. Keep maxResults realistic — first page only; 500 will not invent page two.
5. Enrich listing stats with Video Scraper when you need cleaner numeric fields.
6. Schedule to freshness needs — hourly for hot markets, daily when enough.
7. Public data only.

---

Limitations

• First trending page only — no continuation crawl
• Shelf availability varies by country and section
• Charts change quickly — never treat a Dataset as durable ranking history without your own timestamps
• Listing metadata is thinner than full video_details payloads
• Public data only
• Single-country fetch per run

---

Troubleshooting

Symptom	Likely cause	What to try
Run fails immediately, exit code 1	Upstream fetch failed	Inspect the Dataset type: "error" row and Actor logs; retry
Zero video rows, run succeeded	Empty/unmapped shelf for that country/section	Try US without section; inspect logs
Fewer rows than maxResults	First page simply has fewer items	Expected; lower the cap or accept the page size
Want page 2+ of trending	Not supported	Use Search / Channel Videos for broader catalogs
Relative view strings hard to chart	Listing format	Enrich IDs with Video Scraper
Need many countries	Single fetch design	Parallel Actor runs per country

---

FAQ

How to get YouTube trending videos by country?

Set Input country to an ISO 3166-1 alpha-2 code (US, IN, GB, DE, BR, …). Leave section empty for the default national chart, or set Music / Gaming / Movies / Now. Dataset rows include the normalized country. Need several markets? Launch one run per country (or an Apify task matrix) — no multi-country fan-out in a single start. That is how to get YouTube trending videos for a region as a snapshot.

Does this scrape more than the first trending page?

No. The Actor intentionally stops after the first page. maxResults only caps how many first-page items you keep (1–500).

Are all inputs optional?

Yes. Defaults are country: US and maxResults: 50. lang and section are omitted unless you set them.

What happens if I leave section empty?

The Actor requests the default trending surface for the country. Output rows store section: null.

Which section values are allowed?

Exactly the select enum: Now, Music, Gaming, Movies.

Why did my run exit with code 1?

A hard error occurred during the trending fetch (HTTP failure after retries, invalid response, and so on). Check the Dataset type: "error" row and Actor logs.

Is this the cheapest ScrapeMamba YouTube Actor?

Yes on Apify pricing for this suite: $1.70 / 1k results.

Can I scrape trending for multiple countries in one run?

Not inside a single start. Launch one run per country (or automate a matrix). There is no country worker pool.

How fresh is the data?

As fresh as YouTube’s public trending surface at request time. What is trending on YouTube can change within minutes; treat every Dataset as a snapshot.

Do I need the official YouTube Data API?

No. ScrapeMamba /youtube/trending on Apify is enough — a practical youtube scraper api path for charts without Data API quotas.

Can I get full descriptions and like counts from trending alone?

Often not. Chain YouTube Video Scraper on the videoId list.

Is private or personalized trending supported?

No. Public data only.

How do I automate daily charts?

Use an Apify Schedule, sync the Dataset, and store the run timestamp for diffs.

Is this a YouTube video downloader?

No — trending metadata only, not media files.

---

Pipeline patterns

Pulse → enrich: Trending → Video Scraper → optional Channel Scraper.
Pulse → graph: Trending → Related Videos (dedupe before expensive steps).
Pulse → text: Trending shortlist → Subtitles on priority IDs only.
Keyword vs chart: Search for queries; Trending for platform-promoted charts.

---

Export and automation

Dataset UI (JSON/CSV/Excel), Apify API/clients, Schedules, and webhooks for YouTube trending videos snapshots.

---

Related ScrapeMamba Actors

Actor	Best for
YouTube Search Scraper	Keyword discovery instead of charts
YouTube Video Scraper	Enrich trending IDs with fuller metadata
YouTube Channel Scraper	Uploader profiles for chart creators

Also: Channel Videos, Channel Shorts, Related Videos, Subtitles after you lock today’s ID list.

---

Compliance note

Use only on public YouTube trending data, per YouTube’s terms, applicable law, and your policies. Do not access private content or circumvent controls.