Dataspryva

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.

FieldTypeRequiredDescription
queriesarrayrequiredKeywords or phrases to expand with YouTube autocomplete. Short 1-3 word seeds work best.
modestringoptionalHow far to expand each seed. Exact is one request; All runs every working expansion axis.
sourcestringoptionalYouTube search, YouTube Music, or both. YouTube Music is a separate music-biased source.
Show all input fields
FieldTypeRequiredDescription
queriesarrayrequiredKeywords or phrases to expand with YouTube autocomplete. Short 1-3 word seeds work best.
modestringoptionalHow far to expand each seed. Exact is one request; All runs every working expansion axis.
sourcestringoptionalYouTube search, YouTube Music, or both. YouTube Music is a separate music-biased source.
languagestringoptionalLanguage used to localize suggestions.
marketstringoptionalCountry or region used to localize suggestions.
maxItemsintegeroptionalGlobal cap on suggestion rows across all seeds and sources.
maxSuggestionsPerSeedintegeroptionalCap on rows kept for each seed after the expansion plan runs.
maxQueriesPerSeedintegeroptionalCap on autocomplete requests per seed and source. Exact stays one request.
expansionDepthintegeroptional0 = selected mode only. 1-2 re-query the best suggestions for deeper long-tail coverage.
dedupeAcrossSeedsbooleanoptionalKeep one row when the same suggestion appears for more than one seed. Per-seed duplicates are always removed.
minLengthintegeroptionalDrop suggestions shorter than this many characters.
maxLengthintegeroptionalDrop suggestions longer than this many characters.
containsKeywordstringoptionalKeep suggestions containing this text. Prefix with ! to exclude it instead.
excludeTermsarrayoptionalDrop suggestions containing any of these terms.
minWordCountintegeroptionalDrop suggestions with fewer words than this.
onlyQuestionsbooleanoptionalKeep only suggestions that look like questions.
mustContainSeedbooleanoptionalKeep only suggestions that contain the seed keyword.
includeEntityCardsbooleanoptionalKeep channel and topic suggestions, with their entity metadata, when YouTube returns them.
includeSearchUrlbooleanoptionalAdd 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.

FieldTypeRequiredDescription
suggestionsstringoptionalDataset 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, and all (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 suggestion or rank between 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.

Open the step-by-step Python guide →

Source build Fuf8WidkcEKo6eqVe. Documentation is regenerated from the default published build; private drafts are not included.