YouTube Search Suggestions Scraper
Get public YouTube autocomplete suggestions for keyword research, content discovery, and SEO planning.
Input schema
Input fields, types, required flags, descriptions, defaults, and prefills come from the published definition. Prefill examples are distinct from defaults.
| Field | Type | Required | Description |
|---|---|---|---|
queries | array | required | Keywords or phrases to expand with YouTube autocomplete. Short 1-3 word seeds work best. |
mode | string | optional | How far to expand each seed. Exact is one request; All runs every working expansion axis. |
source | string | optional | YouTube search, YouTube Music, or both. YouTube Music is a separate music-biased source. |
Show all input fields
| Field | Type | Required | Description |
|---|---|---|---|
queries | array | required | Keywords or phrases to expand with YouTube autocomplete. Short 1-3 word seeds work best. |
mode | string | optional | How far to expand each seed. Exact is one request; All runs every working expansion axis. |
source | string | optional | YouTube search, YouTube Music, or both. YouTube Music is a separate music-biased source. |
language | string | optional | Language used to localize suggestions. |
market | string | optional | Country or region used to localize suggestions. |
maxItems | integer | optional | Global cap on suggestion rows across all seeds and sources. |
maxSuggestionsPerSeed | integer | optional | Cap on rows kept for each seed after the expansion plan runs. |
maxQueriesPerSeed | integer | optional | Cap on autocomplete requests per seed and source. Exact stays one request. |
expansionDepth | integer | optional | 0 = selected mode only. 1-2 re-query the best suggestions for deeper long-tail coverage. |
dedupeAcrossSeeds | boolean | optional | Keep one row when the same suggestion appears for more than one seed. Per-seed duplicates are always removed. |
minLength | integer | optional | Drop suggestions shorter than this many characters. |
maxLength | integer | optional | Drop suggestions longer than this many characters. |
containsKeyword | string | optional | Keep suggestions containing this text. Prefix with ! to exclude it instead. |
excludeTerms | array | optional | Drop suggestions containing any of these terms. |
minWordCount | integer | optional | Drop suggestions with fewer words than this. |
onlyQuestions | boolean | optional | Keep only suggestions that look like questions. |
mustContainSeed | boolean | optional | Keep only suggestions that contain the seed keyword. |
includeEntityCards | boolean | optional | Keep channel and topic suggestions, with their entity metadata, when YouTube returns them. |
includeSearchUrl | boolean | optional | Add a ready-to-open YouTube or YouTube Music search URL to every row. |
Download the published input schema
View complete JSON
{
"description": "Collect YouTube's live search autocomplete for seed queries, with optional A-Z, question and modifier expansion.",
"properties": {
"containsKeyword": {
"description": "Keep suggestions containing this text. Prefix with ! to exclude it instead.",
"editor": "textfield",
"title": "Contains keyword",
"type": "string"
},
"dedupeAcrossSeeds": {
"default": false,
"description": "Keep one row when the same suggestion appears for more than one seed. Per-seed duplicates are always removed.",
"prefill": false,
"title": "Remove duplicates across seeds",
"type": "boolean"
},
"excludeTerms": {
"default": [],
"description": "Drop suggestions containing any of these terms.",
"editor": "stringList",
"items": {
"type": "string"
},
"prefill": [],
"title": "Exclude terms",
"type": "array"
},
"expansionDepth": {
"default": 0,
"description": "0 = selected mode only. 1-2 re-query the best suggestions for deeper long-tail coverage.",
"maximum": 2,
"minimum": 0,
"prefill": 0,
"title": "Recursion depth",
"type": "integer"
},
"includeEntityCards": {
"default": true,
"description": "Keep channel and topic suggestions, with their entity metadata, when YouTube returns them.",
"prefill": true,
"title": "Include channel and topic cards",
"type": "boolean"
},
"includeSearchUrl": {
"default": true,
"description": "Add a ready-to-open YouTube or YouTube Music search URL to every row.",
"prefill": true,
"title": "Include search links",
"type": "boolean"
},
"language": {
"default": "en",
"description": "Language used to localize suggestions.",
"editor": "select",
"enum": [
"en",
"es",
"fr",
"de",
"it",
"pt",
"nl",
"pl",
"sv",
"no",
"da",
"fi",
"cs",
"el",
"hu",
"ro",
"bg",
"hr",
"sk",
"sl",
"et",
"lv",
"lt",
"ga",
"is",
"mt",
"ru",
"uk",
"be",
"sr",
"bs",
"mk",
"sq",
"ar",
"tr",
"he",
"fa",
"ur",
"ku",
"ja",
"ko",
"zh-CN",
"zh-TW",
"hi",
"bn",
"ta",
"te",
"ml",
"mr",
"gu",
"kn",
"pa",
"ne",
"si",
"my",
"id",
"th",
"vi",
"ms",
"tl",
"km",
"lo",
"sw",
"am",
"ha",
"yo",
"ig",
"zu",
"xh",
"af",
"az",
"kk",
"uz",
"ky",
"tg",
"mn",
"ka",
"hy"
],
"enumTitles": [
"English",
"Spanish",
"French",
"German",
"Italian",
"Portuguese",
"Dutch",
"Polish",
"Swedish",
"Norwegian",
"Danish",
"Finnish",
"Czech",
"Greek",
"Hungarian",
"Romanian",
"Bulgarian",
"Croatian",
"Slovak",
"Slovenian",
"Estonian",
"Latvian",
"Lithuanian",
"Irish",
"Icelandic",
"Maltese",
"Russian",
"Ukrainian",
"Belarusian",
"Serbian",
"Bosnian",
"Macedonian",
"Albanian",
"Arabic",
"Turkish",
"Hebrew",
"Persian",
"Urdu",
"Kurdish",
"Japanese",
"Korean",
"Chinese (Simplified)",
"Chinese (Traditional)",
"Hindi",
"Bengali",
"Tamil",
"Telugu",
"Malayalam",
"Marathi",
"Gujarati",
"Kannada",
"Punjabi",
"Nepali",
"Sinhala",
"Burmese",
"Indonesian",
"Thai",
"Vietnamese",
"Malay",
"Tagalog",
"Khmer",
"Lao",
"Swahili",
"Amharic",
"Hausa",
"Yoruba",
"Igbo",
"Zulu",
"Xhosa",
"Afrikaans",
"Azerbaijani",
"Kazakh",
"Uzbek",
"Kyrgyz",
"Tajik",
"Mongolian",
"Georgian",
"Armenian"
],
"prefill": "en",
"title": "Language",
"type": "string"
},
"market": {
"default": "US",
"description": "Country or region used to localize suggestions.",
"editor": "select",
"enum": [
"US",
"GB",
"CA",
"AU",
"NZ",
"IE",
"DE",
"FR",
"ES",
"IT",
"NL",
"BE",
"AT",
"CH",
"PT",
"GR",
"CZ",
"PL",
"SE",
"NO",
"DK",
"FI",
"HU",
"RO",
"BG",
"HR",
"SK",
"SI",
"EE",
"LV",
"LT",
"LU",
"MT",
"CY",
"IS",
"LI",
"MC",
"AD",
"SM",
"JP",
"KR",
"CN",
"TW",
"HK",
"MO",
"IN",
"PK",
"BD",
"LK",
"NP",
"AF",
"ID",
"TH",
"VN",
"PH",
"MY",
"SG",
"BN",
"MM",
"KH",
"LA",
"TL",
"BR",
"MX",
"AR",
"CL",
"CO",
"PE",
"VE",
"EC",
"BO",
"PY",
"UY",
"GT",
"CR",
"PA",
"DO",
"PR",
"CU",
"SV",
"HN",
"NI",
"JM",
"TT",
"BB",
"RU",
"TR",
"UA",
"BY",
"KZ",
"UZ",
"AZ",
"AM",
"GE",
"MD",
"RS",
"BA",
"MK",
"AL",
"ME",
"XK",
"ZA",
"NG",
"EG",
"MA",
"DZ",
"TN",
"KE",
"GH",
"ET",
"UG",
"TZ",
"RW",
"ZW",
"SN",
"CI",
"CM",
"MZ",
"AO",
"ZM",
"AE",
"SA",
"IL",
"QA",
"KW",
"BH",
"OM",
"JO",
"LB",
"SY",
"IQ",
"IR",
"YE",
"PS"
],
"enumTitles": [
"United States",
"United Kingdom",
"Canada",
"Australia",
"New Zealand",
"Ireland",
"Germany",
"France",
"Spain",
"Italy",
"Netherlands",
"Belgium",
"Austria",
"Switzerland",
"Portugal",
"Greece",
"Czechia",
"Poland",
"Sweden",
"Norway",
"Denmark",
"Finland",
"Hungary",
"Romania",
"Bulgaria",
"Croatia",
"Slovakia",
"Slovenia",
"Estonia",
"Latvia",
"Lithuania",
"Luxembourg",
"Malta",
"Cyprus",
"Iceland",
"Liechtenstein",
"Monaco",
"Andorra",
"San Marino",
"Japan",
"South Korea",
"China",
"Taiwan",
"Hong Kong",
"Macao",
"India",
"Pakistan",
"Bangladesh",
"Sri Lanka",
"Nepal",
"Afghanistan",
"Indonesia",
"Thailand",
"Vietnam",
"Philippines",
"Malaysia",
"Singapore",
"Brunei",
"Myanmar",
"Cambodia",
"Laos",
"Timor-Leste",
"Brazil",
"Mexico",
"Argentina",
"Chile",
"Colombia",
"Peru",
"Venezuela",
"Ecuador",
"Bolivia",
"Paraguay",
"Uruguay",
"Guatemala",
"Costa Rica",
"Panama",
"Dominican Republic",
"Puerto Rico",
"Cuba",
"El Salvador",
"Honduras",
"Nicaragua",
"Jamaica",
"Trinidad and Tobago",
"Barbados",
"Russia",
"Turkey",
"Ukraine",
"Belarus",
"Kazakhstan",
"Uzbekistan",
"Azerbaijan",
"Armenia",
"Georgia",
"Moldova",
"Serbia",
"Bosnia and Herzegovina",
"North Macedonia",
"Albania",
"Montenegro",
"Kosovo",
"South Africa",
"Nigeria",
"Egypt",
"Morocco",
"Algeria",
"Tunisia",
"Kenya",
"Ghana",
"Ethiopia",
"Uganda",
"Tanzania",
"Rwanda",
"Zimbabwe",
"Senegal",
"Cote d'Ivoire",
"Cameroon",
"Mozambique",
"Angola",
"Zambia",
"United Arab Emirates",
"Saudi Arabia",
"Israel",
"Qatar",
"Kuwait",
"Bahrain",
"Oman",
"Jordan",
"Lebanon",
"Syria",
"Iraq",
"Iran",
"Yemen",
"Palestine"
],
"prefill": "US",
"title": "Country or region",
"type": "string"
},
"maxItems": {
"default": 5000,
"description": "Global cap on suggestion rows across all seeds and sources.",
"maximum": 50000,
"minimum": 1,
"prefill": 3,
"title": "Maximum rows",
"type": "integer"
},
"maxLength": {
"description": "Drop suggestions longer than this many characters.",
"maximum": 500,
"minimum": 1,
"title": "Maximum length",
"type": "integer"
},
"maxQueriesPerSeed": {
"default": 300,
"description": "Cap on autocomplete requests per seed and source. Exact stays one request.",
"maximum": 1000,
"minimum": 1,
"prefill": 300,
"title": "Maximum queries per seed",
"type": "integer"
},
"maxSuggestionsPerSeed": {
"default": 2000,
"description": "Cap on rows kept for each seed after the expansion plan runs.",
"maximum": 10000,
"minimum": 1,
"prefill": 3,
"title": "Maximum suggestions per seed",
"type": "integer"
},
"minLength": {
"description": "Drop suggestions shorter than this many characters.",
"maximum": 200,
"minimum": 1,
"title": "Minimum length",
"type": "integer"
},
"minWordCount": {
"default": 0,
"description": "Drop suggestions with fewer words than this.",
"maximum": 20,
"minimum": 0,
"prefill": 0,
"title": "Minimum word count",
"type": "integer"
},
"mode": {
"default": "exact",
"description": "How far to expand each seed. Exact is one request; All runs every working expansion axis.",
"editor": "select",
"enum": [
"all",
"exact",
"alphabet",
"questions",
"modifiers",
"prepositions",
"comparisons",
"related"
],
"enumTitles": [
"All expansions",
"Exact seed",
"Alphabet (suffix + prefix, a-z + 0-9)",
"Questions (locale-aware, prefix + suffix)",
"Video modifiers (shorts, video, tutorial, ...)",
"Prepositions",
"Comparisons",
"Related (trailing space, wildcard, review, ...)"
],
"prefill": "exact",
"title": "Expansion mode",
"type": "string"
},
"mustContainSeed": {
"default": false,
"description": "Keep only suggestions that contain the seed keyword.",
"prefill": false,
"title": "Must contain seed",
"type": "boolean"
},
"onlyQuestions": {
"default": false,
"description": "Keep only suggestions that look like questions.",
"prefill": false,
"title": "Only questions",
"type": "boolean"
},
"queries": {
"default": [
"web scraping"
],
"description": "Keywords or phrases to expand with YouTube autocomplete. Short 1-3 word seeds work best.",
"editor": "stringList",
"items": {
"type": "string"
},
"maxItems": 1000,
"minItems": 1,
"prefill": [
"web scraping"
],
"title": "Seed queries",
"type": "array"
},
"source": {
"default": "youtube",
"description": "YouTube search, YouTube Music, or both. YouTube Music is a separate music-biased source.",
"editor": "select",
"enum": [
"youtube",
"youtubeMusic",
"both"
],
"enumTitles": [
"YouTube search",
"YouTube Music",
"Both sources"
],
"prefill": "youtube",
"title": "Suggestion source",
"type": "string"
}
},
"required": [
"queries"
],
"schemaVersion": 1,
"title": "YouTube Search Suggestions Scraper Input",
"type": "object"
}
Output schema
Published result links and storage locations. This schema is not an exhaustive contract for every field in a dataset record.
| Field | Type | Required | Description |
|---|---|---|---|
suggestions | string | optional | Dataset containing all scraped YouTube autocomplete suggestion rows. |
Download the published output schema
View complete JSON
{
"actorOutputSchemaVersion": 1,
"description": "Autocomplete suggestion rows with seed, expansion type, rank, locale, source, search URL and channel/topic metadata when available.",
"properties": {
"suggestions": {
"description": "Dataset containing all scraped YouTube autocomplete suggestion rows.",
"template": "{{links.apiDefaultDatasetUrl}}/items",
"title": "YouTube suggestions",
"type": "string"
}
},
"title": "YouTube Search Suggestions Scraper Output"
}
Dataset schema
Published dataset views and any declared field definitions. A view can select only a subset of the returned record fields.
Download the published dataset schema
View complete JSON
{
"actorSpecification": 1,
"views": {
"overview": {
"display": {
"component": "table",
"properties": {}
},
"title": "YouTube suggestions",
"transformation": {
"fields": [
"suggestion",
"seed",
"type",
"rank",
"locale",
"source",
"suggestionType",
"searchUrl"
]
}
}
}
}
Key-value schema
Published key-value store definitions, when provided by this build.
This definition is not present in the default published build. See the published README for available documentation.
Published README
Read the full published documentation
YouTube Search Suggestions Scraper
Discover the phrases YouTube puts in its search box. Enter one or more seed queries and collect the platform's live autocomplete suggestions as clean, ranked JSON or CSV rows — with optional alphabet, question, modifier and related-search expansion for keyword research, video planning and audience research.
No YouTube account, API key, cookies or user-supplied proxy is needed. The actor reads YouTube's public autocomplete response and chooses a working connection automatically.
What this actor does
- Live YouTube suggestions: each exact seed query returns up to 14 suggestions, the same list the signed-out YouTube search box shows.
- Eight expansion modes:
exact,alphabet(suffix and prefix, letters and digits),questions,modifiers,prepositions,comparisons,related, andall(the union). - Optional recursion: re-query the best suggestions to depth 1 or 2 for deeper long-tail coverage.
- Locale targeting: 134 countries and 78 languages, with localized question and modifier words for 19 languages.
- Channel/topic cards: when YouTube attaches a creator or topic card to a suggestion, its name, description or handle, image, channel ID and entity URL are included when supplied.
- Filters and caps: length, word count, question-only, contains-seed, exclude terms, per-seed and global row caps.
- Per-seed deduplication: repeated phrases are merged with a best rank and an appearance count. Optional cross-seed deduplication.
- Empty fields are omitted: records only contain values that are actually populated.
Output per suggestion
| Field | Description |
|---|---|
recordType |
suggestion for a suggestion row, status when a seed produced nothing. |
id |
Stable 16-character ID for the source, seed, suggestion and locale. |
suggestion |
The exact phrase YouTube autocomplete returned. |
seed |
The seed query that produced this row. |
inputQuery |
Alias of seed, kept for older integrations. |
query |
The exact expansion query that produced the best rank. |
type |
suggestion, alphabet, question, modifier, preposition, comparison, related or recursive. |
rank |
Best 1-based position across every query that returned the phrase. |
appearances |
Number of expansion queries that returned the phrase. |
depth |
0 for the base plan, 1-2 for recursion. |
parentQuery |
The query that led to a recursive row. |
language, market, locale |
Requested language, country and combined locale. |
source |
youtube or youtubeMusic. |
suggestionType |
query, channel or topic. |
subTypes |
YouTube's raw numeric suggestion codes, when present. |
entityId, entityName, entityDescription |
Channel/topic card identity, name and description or handle. |
entityImageUrl, entityUrl |
Card image and source-provided entity link, when present. |
channelId, channelHandle, channelUrl |
Channel card details, when present. |
wordCount, isQuestion, containsSeed |
Derived text signals. |
searchUrl |
Ready-to-open YouTube or YouTube Music search URL. |
scrapedAt |
ISO-8601 UTC timestamp. |
When a seed returns no rows, the actor emits one status row instead: recordType (status), status, seed, query, language, market, source and suggestionCount (0). Status values are no_suggestions, suggestions_unavailable, invalid_query and blocked. An unavailable YouTube Music response is reported as suggestions_unavailable for the seed.
Input
| Field | Type | Default | Description |
|---|---|---|---|
queries |
array | ["web scraping"] |
Seed keywords or phrases. 1-3 word seeds work best. |
mode |
string | exact |
all, exact, alphabet, questions, modifiers, prepositions, comparisons or related. |
source |
string | youtube |
youtube, youtubeMusic or both. |
language |
string | en |
Language code used to localize suggestions. |
market |
string | US |
Country or region code used to localize suggestions. |
maxItems |
integer | 5000 |
Global cap on suggestion rows. |
maxSuggestionsPerSeed |
integer | 2000 |
Rows kept per seed after the expansion plan. |
maxQueriesPerSeed |
integer | 300 |
Autocomplete requests per seed and source. |
expansionDepth |
integer | 0 |
0 = selected mode only; 1-2 = re-query the best suggestions. |
dedupeAcrossSeeds |
boolean | false |
Keep one row when a phrase appears for several seeds. Per-seed dedupe is always on. |
minLength |
integer | – | Drop shorter suggestions. |
maxLength |
integer | – | Drop longer suggestions. |
containsKeyword |
string | – | Keep suggestions containing this text; prefix with ! to exclude it. |
excludeTerms |
array | [] |
Drop suggestions containing any of these terms. |
minWordCount |
integer | 0 |
Drop suggestions with fewer words. |
onlyQuestions |
boolean | false |
Keep only question-shaped suggestions. |
mustContainSeed |
boolean | false |
Keep only suggestions that contain the seed. |
includeEntityCards |
boolean | true |
Keep channel/topic cards and their metadata. |
includeSearchUrl |
boolean | true |
Add a ready-to-open search URL to every row. |
Old tasks that use keywords, maxSuggestions, deduplicateSuggestions or country keep working; those legacy keys are mapped to the new fields automatically.
Examples
Example: exact suggestions for one seed
{
"queries": ["web scraping"],
"mode": "exact",
"language": "en",
"market": "US",
"maxItems": 20
}
Example: full keyword expansion
{
"queries": ["coffee", "minecraft"],
"mode": "all",
"expansionDepth": 1,
"maxItems": 5000
}
Example: Spanish questions with channel cards
{
"queries": ["café"],
"mode": "questions",
"language": "es",
"market": "ES",
"includeEntityCards": true
}
Example: YouTube Music suggestions
{
"queries": ["lofi hip hop"],
"source": "youtubeMusic",
"mode": "exact",
"maxItems": 20
}
Example: long-tail ideas that mention the seed
{
"queries": ["running shoes"],
"mode": "all",
"mustContainSeed": true,
"minWordCount": 3,
"maxItems": 1000
}
Use cases
- YouTube SEO and content planning — turn one topic into the phrases viewers actually type.
- Keyword research — compare suggestions across markets and languages.
- Title and script ideas — collect question and long-tail variants for a niche.
- Creator discovery — surface channel cards YouTube attaches to short brand seeds.
- Trend monitoring — schedule a run and diff
suggestionorrankbetween snapshots. - YouTube Music research — read the separate music-biased suggestion list for artists, genres and moods.
FAQ
Does this require a YouTube account, API key or cookies?
No. It reads YouTube's public search-box suggestions and works signed out.
How many suggestions does one query return?
YouTube returns up to 14 suggestions per query. There is no pagination and no parameter that raises that ceiling.
Why are some suggestions missing or different?
Autocomplete is personalized by language, country, current trends and the request location, and YouTube can change it at any time. The actor records the requested locale but cannot guarantee a specific list.
Can I get search volume or competition metrics?
No. YouTube autocomplete does not publish search volume, CPC or difficulty. Those numbers come from separate paid keyword or search-results products.
Why does a long seed return nothing?
Autocomplete completes prefixes, so four- and five-word seeds often return few or no suggestions. Use a 1-3 word seed, or use alphabet mode to expand around a long seed.
What are channel and topic cards?
Some suggestions carry a creator or topic card with a name, handle, image, channel ID or entity link. The actor includes those fields when YouTube supplies them. Set includeEntityCards to false if you only want plain query suggestions.
How does deduplication work?
Duplicate phrases inside one seed are merged into one row with the best rank and an appearances count. Cross-seed duplicates are kept by default so each seed's list stays complete; set dedupeAcrossSeeds to true for one row per phrase across the whole run.
What is the YouTube Music source?
YouTube Music has its own music-biased suggestion list. It typically returns 6-10 suggestions per query and can return none for some seeds or locales; it is not a replacement for the main YouTube search box. Use source: "youtubeMusic" for music research or both to collect both lists.
Does this support YouTube TV suggestions?
No. YouTube TV does not expose a separate public suggestion list; it uses the same search suggestions as YouTube.
Do I need to set up a proxy?
No. The actor chooses a working connection to YouTube automatically. Just fill in the input and run it.
This is a third-party actor that reads publicly available YouTube autocomplete data. It is not affiliated with, endorsed by or sponsored by YouTube or Google.
Python quickstart
Use a schema-derived input and the Python standard library to start a run. An Apify account and token are required for execution.
Source build Fuf8WidkcEKo6eqVe. Documentation is regenerated from the default published build; private drafts are not included.