YouTube Most Popular Shorts (Top by Country & Category)

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

Features

• Two-step pipeline: search for short-form candidates + enrich with full metadata
• Discover Shorts for 50 countries via dropdown selector
• Filter by 32 YouTube categories (Music, Gaming, News, etc.) or select [All categories]
• Configurable time window (1–30 days) for freshness control
• Shorts heuristic classification (duration + optional text signals like #shorts)
• Multi-region and multi-category batching in a single run
• Human-readable category names (videoCategoryTitle) alongside category IDs
• Pagination support (up to 10 pages per combo)
• Deduplication across region-category combinations
• Rank numbering by view count within each region-category combo
• Run summary saved to Key-Value Store
• Pay-per-event ready (shorts-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 overall most popular
3. The actor calls videoCategories.list once per region to resolve category names
4. Step A — Discovery: For each region-category combo, calls search.list with videoDuration=short to find short-form candidates
5. Step B — Enrichment: Batch-fetches full video details via videos.list (up to 50 IDs per call)
6. Step C — Classification: Applies Shorts heuristic (duration ≤ 60s + optional text signals) to compute confidence
7. Step D — Ranking: Sorts by view count descending, assigns rank, deduplicates, and pushes to dataset

Shorts detection limitations

YouTube Data API does not provide a first-class "Shorts" flag. This actor uses a heuristic approach:

• Duration check: Videos ≤ 60 seconds (configurable) receive a +0.6 confidence boost
• Text signals: Title/description containing #shorts or shorts (configurable) add +0.2 each
• Videos below minShortsConfidence threshold are filtered out
• Some true Shorts may be missed; some short non-Shorts videos may be included

Input Parameters

Parameter	Type	Default	Description
regions	string[]	required	Select countries from dropdown (50 available)
categories	string[]	[]	Category filter: "[All categories]", "Music (10)", etc. Empty = all
timeWindowDays	integer	7	Only discover Shorts published within last N days (1–30)
orderBy	string	viewCount	Search order: viewCount, date, rating, relevance
maxResultsPerPage	integer	50	Results per API page (1–50)
maxPages	integer	2	Search pages per combo (1–10). Each costs 100 quota units
shortsMaxDurationSeconds	integer	60	Max duration to classify as Short
shortsDetectionMode	string	duration_plus_text	duration_only or duration_plus_text
shortsTextSignals	string[]	["#shorts","shorts"]	Text patterns for Shorts detection
minShortsConfidence	number	0.5	Minimum confidence to include (0–1)
includeRawApiResponses	boolean	false	Include raw API data in output
dedupeByVideoId	boolean	true	Skip duplicate videos across combos
apiKey	string	—	Optional YouTube Data API v3 key
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, top by views, last 7 days

{
  "regions": ["US"],
  "categories": [],
  "timeWindowDays": 7,
  "orderBy": "viewCount",
  "maxResultsPerPage": 50,
  "maxPages": 2,
  "shortsMaxDurationSeconds": 60,
  "shortsDetectionMode": "duration_plus_text",
  "shortsTextSignals": ["#shorts", "shorts"],
  "minShortsConfidence": 0.5,
  "dedupeByVideoId": true,
  "includeRawApiResponses": false,
  "requestTimeoutSecs": 30,
  "maxRetries": 3,
  "minDelayMs": 0,
  "debug": false
}

Example 2 — Travel & Events for US, latest first, last 7 days

{
  "regions": ["US"],
  "categories": ["19"],
  "timeWindowDays": 7,
  "orderBy": "date",
  "maxResultsPerPage": 50,
  "maxPages": 2,
  "shortsMaxDurationSeconds": 60,
  "shortsDetectionMode": "duration_plus_text",
  "shortsTextSignals": ["#shorts", "shorts"],
  "minShortsConfidence": 0.5,
  "dedupeByVideoId": true,
  "includeRawApiResponses": false,
  "requestTimeoutSecs": 30,
  "maxRetries": 3,
  "minDelayMs": 0,
  "debug": false
}

Output

Table view — Most Popular Shorts

Table view — All Fields

Output fields

Field	Type	Description
rank	integer	Position ranked by view count
retrievedAt	string	ISO 8601 timestamp when data was fetched
regionCode	string	Region this result was fetched for
videoCategoryId	string	Category ID
videoCategoryTitle	string	Category name (e.g., "Music", "Gaming")
videoId	string	YouTube video ID
url	string	Full video URL
title	string	Video title
description	string	Video description
publishedAt	string	ISO 8601 publish date
channelId	string	Channel ID
channelTitle	string	Channel name
duration	string	ISO 8601 duration (e.g., PT59S)
durationSeconds	integer	Duration in seconds
thumbnails	object	Thumbnail URLs (default, medium, high, standard, maxres)
statistics	object	{ viewCount, likeCount, commentCount }
isShortsCandidate	boolean	Whether the video passed Shorts classification
shortsSignals	string[]	Signals that contributed to classification
shortsConfidence	number	Confidence score (0–1)

JSON output example

{
  "rank": 1,
  "retrievedAt": "2026-02-27T03:27:12.448Z",
  "regionCode": "US",
  "videoCategoryId": "24",
  "videoCategoryTitle": "Entertainment",
  "videoId": "oFWQhXdGn2o",
  "url": "https://www.youtube.com/watch?v=oFWQhXdGn2o",
  "title": "I want Rumi 😅Roblox Brookhaven Funny Meme #roblox #funny #shorts",
  "description": "",
  "publishedAt": "2026-02-20T23:01:06Z",
  "channelId": "UCfF7GECIz-rj74KMh9S4ilg",
  "channelTitle": "MiAnimation🎬 ",
  "duration": "PT22S",
  "durationSeconds": 22,
  "thumbnails": {
    "default": {
      "url": "https://i.ytimg.com/vi/oFWQhXdGn2o/default.jpg",
      "width": 120,
      "height": 90
    },
    "medium": {
      "url": "https://i.ytimg.com/vi/oFWQhXdGn2o/mqdefault.jpg",
      "width": 320,
      "height": 180
    },
    "high": {
      "url": "https://i.ytimg.com/vi/oFWQhXdGn2o/hqdefault.jpg",
      "width": 480,
      "height": 360
    },
    "standard": {
      "url": "https://i.ytimg.com/vi/oFWQhXdGn2o/sddefault.jpg",
      "width": 640,
      "height": 480
    },
    "maxres": {
      "url": "https://i.ytimg.com/vi/oFWQhXdGn2o/maxresdefault.jpg",
      "width": 1280,
      "height": 720
    }
  },
  "statistics": {
    "viewCount": 46242891,
    "likeCount": 361345,
    "commentCount": 1326
  },
  "isShortsCandidate": true,
  "shortsSignals": [
    "duration<=60",
    "text:#shorts",
    "text:shorts"
  ],
  "shortsConfidence": 1
}

Quota usage

• search.list costs 100 quota units per request (this dominates cost)
• videos.list costs 1 quota unit per request (up to 50 IDs per batch)
• videoCategories.list costs 1 quota unit per region (called once per region)

Cost formula

For R regions, C categories (or 1 for All), P pages:

• Search calls: R x C x P (100 units each)
• Videos calls: ceil((R x C x P x maxResultsPerPage) / 50) (1 unit each)
• Total ≈ (R x C x P x 100) + ceil((R x C x P x maxResultsPerPage) / 50)

Example costs

Scenario	Search calls	Videos calls	Total units
1 region, all categories, 1 page	1	1	~101
2 regions, 2 categories, 2 pages	8	4	~804
5 regions, 3 categories, 2 pages	30	15	~3,015

Best practices for low cost

• Use fewer maxPages (each page = 100 units)
• Reduce maxResultsPerPage for quick tests
• Use timeWindowDays=7 (default) — wider windows increase result volume but not API cost

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 shorts emitted, search/videos API calls, estimated quota units
• Skipped counts (low confidence, duplicates)
• Per-combo breakdown (region, category, candidates found, classified, emitted, errors)