{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Autocomplete Scraper — Keyword Suggestions & Ideas",
    "description": "Google Autocomplete scraper and API for keyword research: hundreds of long-tail ideas and questions per seed keyword, in any country, from Web, YouTube and Shopping suggestions, with optional Google Trends scores. Pay per seed plus a small start fee, no platform fees.",
    "version": "1.0",
    "x-build-id": "imhIZ4e1oCudW7FZg"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/aaronoptimus~google-autocomplete-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-aaronoptimus-google-autocomplete-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/aaronoptimus~google-autocomplete-scraper/runs": {
      "post": {
        "operationId": "runs-sync-aaronoptimus-google-autocomplete-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/aaronoptimus~google-autocomplete-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-aaronoptimus-google-autocomplete-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "required": [
          "seedKeywords"
        ],
        "properties": {
          "seedKeywords": {
            "title": "Seed keywords",
            "type": "array",
            "description": "Keywords to expand, one per line (a line like \"coffee maker, espresso machine\" counts as two seeds; \"1,000 calorie meal\" stays one). Each seed is sent to Google Autocomplete with letters, question words and other modifiers, and every distinct suggestion becomes one keyword idea. Up to 1,000 seeds per run.",
            "items": {
              "type": "string"
            }
          },
          "countries": {
            "title": "Countries",
            "type": "array",
            "description": "2-letter country codes (US, GB, DE, IN...), one per line or comma-separated. Google suggests different completions per country. Each seed is expanded (and charged) once per country. Up to 50.",
            "items": {
              "type": "string",
              "pattern": "^[\\s,]*[A-Za-z]{2}([\\s,]+[A-Za-z]{2})*[\\s,]*$"
            },
            "default": [
              "US"
            ]
          },
          "language": {
            "title": "Language",
            "pattern": "^\\s*[a-zA-Z]{2,3}([-_][a-zA-Z0-9]{2,4})?\\s*$",
            "type": "string",
            "description": "Language code of the searches, e.g. en, de, es, fr, pt-BR, ja. Question words and prepositions are built in for en, es, de, fr, pt, it and nl; other languages use the English ones (and letters a–z), so they return fewer ideas.",
            "default": "en"
          },
          "sources": {
            "title": "Search type",
            "type": "array",
            "description": "Which Google search box to read: Web search, YouTube search or Google Shopping. Pick several to get each. Each seed is expanded (and charged) once per search type.",
            "items": {
              "type": "string",
              "enum": [
                "web",
                "youtube",
                "shopping"
              ],
              "enumTitles": [
                "Google Web search",
                "YouTube search",
                "Google Shopping"
              ]
            },
            "default": [
              "web"
            ]
          },
          "expandAlphabet": {
            "title": "Letters a–z after the seed",
            "type": "boolean",
            "description": "\"coffee maker a\", \"coffee maker b\"... (26 queries). The main source of long-tail ideas.",
            "default": true
          },
          "expandQuestions": {
            "title": "Question words before the seed",
            "type": "boolean",
            "description": "\"how coffee maker\", \"why coffee maker\"... Finds the questions people ask (great for FAQ and blog topics).",
            "default": true
          },
          "expandPrepositions": {
            "title": "Prepositions after the seed",
            "type": "boolean",
            "description": "\"coffee maker for\", \"coffee maker with\", \"coffee maker near\"...",
            "default": true
          },
          "expandComparisons": {
            "title": "Comparison words after the seed",
            "type": "boolean",
            "description": "\"coffee maker vs\", \"coffee maker or\", \"coffee maker alternative\"... Finds competitor and comparison keywords.",
            "default": true
          },
          "expandNumbers": {
            "title": "Digits 0–9 after the seed",
            "type": "boolean",
            "description": "\"coffee maker 1\", \"coffee maker 2\"... Useful for product sizes, models and years (10 more queries).",
            "default": false
          },
          "expandAlphabetPrefix": {
            "title": "Letters a–z before the seed",
            "type": "boolean",
            "description": "\"a coffee maker\", \"b coffee maker\"... Finds words that come before your seed (26 more queries).",
            "default": false
          },
          "customModifiers": {
            "title": "Your own modifiers",
            "type": "array",
            "description": "Extra words to try, e.g. \"review\", \"price\" or \"best {seed} for\". Without {seed} the word is added after the seed. Up to 100.",
            "items": {
              "type": "string"
            }
          },
          "expandTopIdeas": {
            "title": "Also expand the top ideas (second level)",
            "minimum": 0,
            "maximum": 50,
            "type": "integer",
            "description": "Run the same full expansion on the best N ideas of each seed to dig deeper. Each one is charged as one more seed expansion, only when ideas it found are in your results. 0 = off.",
            "default": 0
          },
          "maxIdeasPerSeed": {
            "title": "Maximum ideas per seed",
            "minimum": 0,
            "type": "integer",
            "description": "Keep only the best N ideas of each seed (by rank). 0 = keep all. Doesn't change the price.",
            "default": 0
          },
          "onlyIdeasContainingSeed": {
            "title": "Only ideas that contain every word of the seed",
            "type": "boolean",
            "description": "Drops suggestions like \"what espresso machine is best\" for the seed \"coffee maker\".",
            "default": false
          },
          "excludeWords": {
            "title": "Exclude ideas containing",
            "type": "array",
            "description": "Words or phrases to drop, e.g. competitor brands or \"free\". Matched as whole words, ignoring case.",
            "items": {
              "type": "string"
            }
          },
          "onlyIntents": {
            "title": "Only these kinds of ideas",
            "type": "array",
            "description": "Keep only ideas tagged with at least one of these intents, e.g. just questions for an FAQ. Empty = keep all. (Website suggestions also need \"Keep website suggestions\" on.)",
            "items": {
              "type": "string",
              "enum": [
                "question",
                "comparison",
                "commercial",
                "local",
                "navigational"
              ],
              "enumTitles": [
                "Questions (how, what, why...)",
                "Comparisons (vs, or, alternative)",
                "Commercial (best, price, buy, review...)",
                "Local (near me, nearby...)",
                "Websites"
              ]
            }
          },
          "dropVariants": {
            "title": "Drop near-duplicate wordings",
            "type": "boolean",
            "description": "Keep only the best-ranked wording when ideas differ just by word order, a plural or small words (\"camping coffee maker\" vs \"coffee makers for camping\"). Off = keep them all, each pointing to its main wording in variantOf.",
            "default": false
          },
          "dedupeAcrossSeeds": {
            "title": "Remove ideas already found for an earlier seed",
            "type": "boolean",
            "description": "With several related seeds, each idea appears only once per country and search type: under the first seed that found it. Doesn't change the price.",
            "default": false
          },
          "includeNavigational": {
            "title": "Keep website suggestions",
            "type": "boolean",
            "description": "Google sometimes suggests a website address (e.g. https://www.amazon.com/). Off = drop them.",
            "default": false
          },
          "addTrendsScore": {
            "title": "Add Google Trends scores",
            "type": "boolean",
            "description": "Look up the top ideas of each seed on Google Trends: how popular each is compared with the seed (100 = as popular as the seed), on a 0–100 scale shared by the scored ideas, whether it's rising or falling, and a link to check it. Charged per idea that has Trends data; ideas too small for Google Trends to measure are free.",
            "default": false
          },
          "trendsMaxIdeasPerSeed": {
            "title": "Ideas to score per seed",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "How many of the top ideas of each seed get a Trends score (near-duplicate wordings of an idea already scored are skipped). Caps the Trends cost per seed.",
            "default": 20
          },
          "trendsTimeRange": {
            "title": "Trends period",
            "enum": [
              "today 1-m",
              "today 3-m",
              "today 12-m",
              "today 5-y"
            ],
            "type": "string",
            "description": "Period the Trends score and trend direction cover.",
            "default": "today 12-m"
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Apify Proxy spreads requests over many IP addresses so Google doesn't slow them down. The default works for most runs.",
            "default": {
              "useApifyProxy": true
            }
          },
          "useResidentialFallback": {
            "title": "Switch to residential proxies if Google throttles",
            "type": "boolean",
            "description": "If Google keeps refusing requests, all requests switch to Apify residential proxy automatically. No extra cost to you.",
            "default": true
          },
          "maxConcurrency": {
            "title": "Parallel requests",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "How many autocomplete requests run at once. Lower it if you see many retries.",
            "default": 6
          },
          "maxRetries": {
            "title": "Retries per request",
            "minimum": 0,
            "maximum": 15,
            "type": "integer",
            "description": "Each retry uses a fresh IP address.",
            "default": 6
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}