YouTube Keywords Discovery Tool

Discover localized phrases from YouTube's public autocomplete endpoint and optionally attach rich first-page public YouTube search evidence. The actor does not estimate search volume, scrape private APIs, or label suggestions as trending.

What it collects

• Seed and expanded autocomplete queries, localized by language and country.
• One deduplicated record per discovered phrase, with the exact source query and suggestion position.
• Optional evidence for each phrase: video ID, title, description, channel name/ID/URL, displayed publish text, displayed view count and parsed count, displayed duration and seconds, badges, thumbnail set, canonical watch URL, evidence rank, and parser source.
• Exact four-field diagnostics (url, error, errorCode, scrapedAt) for blocked, failed, or empty public requests.
• An OUTPUT key-value record with item, request, proxy, failure, and timing counts.

Search evidence is limited to the first public results page because YouTube does not provide a stable documented pagination contract for this endpoint. Displayed view counts are preserved as page observations; they are not popularity or search-volume estimates.

Input

Field	Default	Rules	Description
keywords	—	Required; 1–20 unique strings, 1–200 chars	Seed phrases.
language	en	2–3 letters, optional region	Public page language, e.g. en or pt-BR.
country	US	Two letters	Public page country context.
maxSuggestionsPerKeyword	20	1–50	Maximum unique phrases per seed.
expandWithLetters	false	boolean	Also query seed a through seed z.
includeSearchEvidence	true	boolean	Retrieve public search evidence for each phrase.
maxSearchResults	5	0–10	Evidence rows per phrase; 0 skips evidence.
maxRetries	2	0–3	Bounded retries per public request.
includeDiagnostics	true	boolean	Emit exact diagnostic rows when an operation fails.
enableProxyFallback	true	boolean	Try the account-authorized Apify Proxy route after a direct failure, or direct after an explicit proxy failure.
requestDelayMs	250	0–5000	Delay between public requests.
requestTimeoutSecs	60	5–120	Timeout for one public request.
proxyConfiguration	—	optional object	Standard Apify Proxy configuration. Proxy URLs must not contain credentials.

Example:

{
  "keywords": ["how to cook pasta", "best programming language"],
  "language": "en",
  "country": "US",
  "maxSuggestionsPerKeyword": 10,
  "includeSearchEvidence": true,
  "maxSearchResults": 3,
  "maxRetries": 2,
  "includeDiagnostics": true,
  "enableProxyFallback": true
}

Output record

{
  "recordType": "youtube_keyword_discovery",
  "seedKeyword": "python tutorial",
  "keyword": "python tutorial for beginners",
  "source": "youtube-public-autocomplete",
  "sourceQuery": "python tutorial",
  "suggestionPosition": 1,
  "locale": {"language": "en", "country": "US"},
  "searchEvidenceCount": 1,
  "evidenceAvailable": true,
  "searchEvidenceUrl": "https://www.youtube.com/results?search_query=python+tutorial+for+beginners&hl=en&gl=US",
  "searchEvidence": [{
    "videoId": "abcdefghijk",
    "title": "Example video",
    "channelName": "Example channel",
    "viewCountText": "1.2M views",
    "viewCount": 1200000,
    "durationText": "1:24",
    "durationSeconds": 84,
    "thumbnailUrl": "https://i.ytimg.com/vi/abcdefghijk/hqdefault.jpg",
    "url": "https://www.youtube.com/watch?v=abcdefghijk",
    "rank": 1,
    "searchUrl": "https://www.youtube.com/results?search_query=python+tutorial+for+beginners&hl=en&gl=US",
    "sourceRenderer": "ytInitialData.videoRenderer"
  }],
  "discoveryMethod": "seed-query",
  "requestedMaxSuggestions": 10,
  "requestedMaxSearchResults": 3,
  "retrievedAt": "2026-09-08T10:30:00.000Z"
}

Run locally with apify run --purge --input-file qa-inputs/youtube-keywords-discovery-tool/local-validation.json, inspect storage/datasets/default/, and run npm run validate-dataset. Deploy with apify push, then call the cloud Actor with the proxy-enabled QA input and compare the dataset and OUTPUT store.