{"openapi":"3.1.0","info":{"title":"CrawlerData API","version":"1.0.0","description":"Google Shopping (products, sellers, product details) and Google Search, Images, News, Local and Autocomplete results as JSON. Submit a job to POST /v1/jobs. The live queue returns the result in the same response; fast and regular are asynchronous (poll GET /v1/jobs/{jobId} or receive a webhook). Failed jobs cost 0 credits. Also available as an MCP server at POST /mcp.","contact":{"name":"CrawlerData","email":"contact@crawlerdata.com","url":"https://crawlerdata.com"},"termsOfService":"https://crawlerdata.com/legal/terms","x-logo":{"url":"https://crawlerdata.com/favicon.svg"}},"externalDocs":{"description":"Docs","url":"https://app.crawlerdata.com/docs"},"servers":[{"url":"https://api.crawlerdata.com"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Jobs","description":"Submit and fetch scraping jobs"},{"name":"SerpApi-compatible","description":"SerpApi parameters and response format: switch by changing the base URL"}],"paths":{"/v1/jobs":{"post":{"tags":["Jobs"],"operationId":"submitJob","summary":"Run a Google Shopping or Google Search request","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/GoogleShoppingSearchRequest"},{"$ref":"#/components/schemas/GoogleShoppingProductRequest"},{"$ref":"#/components/schemas/GoogleShoppingProductInfoRequest"},{"$ref":"#/components/schemas/GoogleSearchRequest"},{"$ref":"#/components/schemas/GoogleImagesRequest"},{"$ref":"#/components/schemas/GoogleNewsRequest"},{"$ref":"#/components/schemas/GoogleLocalRequest"},{"$ref":"#/components/schemas/GoogleAutocompleteRequest"}],"discriminator":{"propertyName":"endpoint"}},"example":{"endpoint":"google-shopping-search","params":{"query":"wireless headphones","country":"us"},"queue":"live"}}}},"responses":{"200":{"description":"Live job finished (completed or failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"202":{"description":"Async job queued","content":{"application/json":{"schema":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/Job"},"message":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"402":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/v1/jobs/{jobId}":{"get":{"tags":["Jobs"],"operationId":"getJob","summary":"Get a job and its result","parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The job, with its result once completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobResponse"}}}},"404":{"$ref":"#/components/responses/Error"}}}},"/search.json":{"get":{"tags":["SerpApi-compatible"],"operationId":"serpApiSearch","summary":"SerpApi-compatible search (GET /search also works)","description":"Takes SerpApi query parameters and returns SerpApi-shaped JSON (search_metadata, search_parameters, organic_results, shopping_results, news_results, ...), built only from the data our endpoints return. Runs one live job, billed like POST /v1/jobs (1 credit; failed searches are free). Parameters SerpApi has that we cannot apply (num, google_domain, safe, ...) are ignored.","security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"parameters":[{"name":"engine","in":"query","schema":{"type":"string","enum":["google","google_shopping","google_news","google_images","google_local","google_autocomplete"],"default":"google"}},{"name":"q","in":"query","required":true,"schema":{"type":"string","maxLength":500}},{"name":"gl","in":"query","schema":{"type":"string","enum":["us","gb","uk","ca","au","de","fr","nl","it","es","pt","be","at","ch","se","no","dk","fi","ie","pl","cz","il","ae","in","jp","kr","sg","mx","br","nz","za","tr"],"default":"us"},"description":"Country"},{"name":"hl","in":"query","schema":{"type":"string","default":"en"},"description":"Language, e.g. en (a regional code such as en-GB uses its language part)"},{"name":"device","in":"query","schema":{"type":"string","enum":["desktop","mobile"],"default":"desktop"},"description":"engine=google only"},{"name":"location","in":"query","schema":{"type":"string"},"description":"Search from a city, region or postal code: a Google canonical location name, e.g. \"Austin, Texas, United States\". Without a country name the gl country is added; without gl the country of the location is used."},{"name":"uule","in":"query","schema":{"type":"string"},"description":"Advanced: a raw Google uule value, instead of location"},{"name":"start","in":"query","schema":{"type":"integer","minimum":0,"maximum":180},"description":"Result offset: a multiple of 10 up to 90 (google, google_news) or of 20 up to 180 (google_local)"},{"name":"tbm","in":"query","schema":{"type":"string","enum":["nws","isch","shop","lcl"]},"description":"engine=google only: news, images, shopping or local results"}],"responses":{"200":{"description":"SerpApi-shaped results","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/SerpApiError"},"401":{"$ref":"#/components/responses/SerpApiError"},"402":{"$ref":"#/components/responses/SerpApiError"},"429":{"$ref":"#/components/responses/SerpApiError"},"502":{"$ref":"#/components/responses/SerpApiError"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from the dashboard (sk_...)"},"apiKeyQuery":{"type":"apiKey","in":"query","name":"api_key","description":"The same API key as a query parameter (SerpApi style, /search.json only)"}},"schemas":{"GoogleShoppingSearchRequest":{"type":"object","description":"Google Shopping search: products with price, merchant, rating and product_id. 1 credit.","required":["endpoint","params"],"properties":{"endpoint":{"type":"string","enum":["google-shopping-search"]},"params":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":500},"country":{"type":"string","description":"Two-letter country code. Defaults to \"us\", or to the country of location.","enum":["us","gb","uk","ca","au","de","fr","nl","it","es","pt","be","at","ch","se","no","dk","fi","ie","pl","cz","il","ae","in","jp","kr","sg","mx","br","nz","za","tr"]},"language":{"type":"string","pattern":"^[a-zA-Z]{2}$","default":"en"},"page":{"type":"integer","default":1},"location":{"type":"string","minLength":2,"maxLength":200,"description":"Search from a city, region or postal code: a Google canonical location name, \"City,Region,Country\" (Google Ads geotarget format), e.g. \"Austin,Texas,United States\". When country is omitted it is taken from the location."},"uule":{"type":"string","pattern":"^[aw][+ ][A-Za-z0-9+/_=-]{4,1000}$","description":"Advanced: a raw Google uule value, sent as is. Use location instead unless you already have uule values."}},"required":["query"],"additionalProperties":false},"queue":{"$ref":"#/components/schemas/Queue"},"postbackUrl":{"type":"string","format":"uri","description":"Webhook that receives the result (fast and regular queues)."}}},"GoogleShoppingProductRequest":{"type":"object","description":"Google Shopping sellers: every seller's offer for a product_id. 1 credit per 10 sellers returned (min 1).","required":["endpoint","params"],"properties":{"endpoint":{"type":"string","enum":["google-shopping-product"]},"params":{"type":"object","properties":{"product_id":{"type":"string","minLength":1,"maxLength":100},"country":{"type":"string","default":"us","enum":["us","gb","uk","ca","au","de","fr","nl","it","es","pt","be","at","ch","se","no","dk","fi","ie","pl","cz","il","ae","in","jp","kr","sg","mx","br","nz","za","tr"]},"language":{"type":"string","pattern":"^[a-zA-Z]{2}$","default":"en"}},"required":["product_id"],"additionalProperties":false},"queue":{"$ref":"#/components/schemas/Queue"},"postbackUrl":{"type":"string","format":"uri","description":"Webhook that receives the result (fast and regular queues)."}}},"GoogleShoppingProductInfoRequest":{"type":"object","description":"Google Shopping product details: description, specs, images, rating. 1 credit.","required":["endpoint","params"],"properties":{"endpoint":{"type":"string","enum":["google-shopping-product-info"]},"params":{"type":"object","properties":{"product_id":{"type":"string","minLength":1,"maxLength":100},"country":{"type":"string","default":"us","enum":["us","gb","uk","ca","au","de","fr","nl","it","es","pt","be","at","ch","se","no","dk","fi","ie","pl","cz","il","ae","in","jp","kr","sg","mx","br","nz","za","tr"]},"language":{"type":"string","pattern":"^[a-zA-Z]{2}$","default":"en"}},"required":["product_id"],"additionalProperties":false},"queue":{"$ref":"#/components/schemas/Queue"},"postbackUrl":{"type":"string","format":"uri","description":"Webhook that receives the result (fast and regular queues)."}}},"GoogleSearchRequest":{"type":"object","description":"Google web search results. 1 credit.","required":["endpoint","params"],"properties":{"endpoint":{"type":"string","enum":["google-search"]},"params":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":500},"country":{"type":"string","description":"Two-letter country code. Defaults to \"us\", or to the country of location.","enum":["us","gb","uk","ca","au","de","fr","nl","it","es","pt","be","at","ch","se","no","dk","fi","ie","pl","cz","il","ae","in","jp","kr","sg","mx","br","nz","za","tr"]},"language":{"type":"string","pattern":"^[a-zA-Z]{2}$","default":"en"},"device":{"type":"string","enum":["desktop","mobile"],"default":"desktop"},"page":{"type":"integer","minimum":1,"maximum":10,"default":1},"location":{"type":"string","minLength":2,"maxLength":200,"description":"Search from a city, region or postal code: a Google canonical location name, \"City,Region,Country\" (Google Ads geotarget format), e.g. \"Austin,Texas,United States\". When country is omitted it is taken from the location."},"uule":{"type":"string","pattern":"^[aw][+ ][A-Za-z0-9+/_=-]{4,1000}$","description":"Advanced: a raw Google uule value, sent as is. Use location instead unless you already have uule values."}},"required":["query"],"additionalProperties":false},"queue":{"$ref":"#/components/schemas/Queue"},"postbackUrl":{"type":"string","format":"uri","description":"Webhook that receives the result (fast and regular queues)."}}},"GoogleImagesRequest":{"type":"object","description":"Google Images results. 1 credit.","required":["endpoint","params"],"properties":{"endpoint":{"type":"string","enum":["google-images"]},"params":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":500},"country":{"type":"string","description":"Two-letter country code. Defaults to \"us\", or to the country of location.","enum":["us","gb","uk","ca","au","de","fr","nl","it","es","pt","be","at","ch","se","no","dk","fi","ie","pl","cz","il","ae","in","jp","kr","sg","mx","br","nz","za","tr"]},"language":{"type":"string","pattern":"^[a-zA-Z]{2}$","default":"en"},"page":{"type":"integer","default":1},"location":{"type":"string","minLength":2,"maxLength":200,"description":"Search from a city, region or postal code: a Google canonical location name, \"City,Region,Country\" (Google Ads geotarget format), e.g. \"Austin,Texas,United States\". When country is omitted it is taken from the location."},"uule":{"type":"string","pattern":"^[aw][+ ][A-Za-z0-9+/_=-]{4,1000}$","description":"Advanced: a raw Google uule value, sent as is. Use location instead unless you already have uule values."}},"required":["query"],"additionalProperties":false},"queue":{"$ref":"#/components/schemas/Queue"},"postbackUrl":{"type":"string","format":"uri","description":"Webhook that receives the result (fast and regular queues)."}}},"GoogleNewsRequest":{"type":"object","description":"Google News results. 1 credit.","required":["endpoint","params"],"properties":{"endpoint":{"type":"string","enum":["google-news"]},"params":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":500},"country":{"type":"string","description":"Two-letter country code. Defaults to \"us\", or to the country of location.","enum":["us","gb","uk","ca","au","de","fr","nl","it","es","pt","be","at","ch","se","no","dk","fi","ie","pl","cz","il","ae","in","jp","kr","sg","mx","br","nz","za","tr"]},"language":{"type":"string","pattern":"^[a-zA-Z]{2}$","default":"en"},"page":{"type":"integer","minimum":1,"maximum":10,"default":1},"location":{"type":"string","minLength":2,"maxLength":200,"description":"Search from a city, region or postal code: a Google canonical location name, \"City,Region,Country\" (Google Ads geotarget format), e.g. \"Austin,Texas,United States\". When country is omitted it is taken from the location."},"uule":{"type":"string","pattern":"^[aw][+ ][A-Za-z0-9+/_=-]{4,1000}$","description":"Advanced: a raw Google uule value, sent as is. Use location instead unless you already have uule values."}},"required":["query"],"additionalProperties":false},"queue":{"$ref":"#/components/schemas/Queue"},"postbackUrl":{"type":"string","format":"uri","description":"Webhook that receives the result (fast and regular queues)."}}},"GoogleLocalRequest":{"type":"object","description":"Google local business results. 1 credit.","required":["endpoint","params"],"properties":{"endpoint":{"type":"string","enum":["google-local"]},"params":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":500},"country":{"type":"string","description":"Two-letter country code. Defaults to \"us\", or to the country of location.","enum":["us","gb","uk","ca","au","de","fr","nl","it","es","pt","be","at","ch","se","no","dk","fi","ie","pl","cz","il","ae","in","jp","kr","sg","mx","br","nz","za","tr"]},"language":{"type":"string","pattern":"^[a-zA-Z]{2}$","default":"en"},"page":{"type":"integer","minimum":1,"maximum":10,"default":1},"location":{"type":"string","minLength":2,"maxLength":200,"description":"Search from a city, region or postal code: a Google canonical location name, \"City,Region,Country\" (Google Ads geotarget format), e.g. \"Austin,Texas,United States\". When country is omitted it is taken from the location."},"uule":{"type":"string","pattern":"^[aw][+ ][A-Za-z0-9+/_=-]{4,1000}$","description":"Advanced: a raw Google uule value, sent as is. Use location instead unless you already have uule values."}},"required":["query"],"additionalProperties":false},"queue":{"$ref":"#/components/schemas/Queue"},"postbackUrl":{"type":"string","format":"uri","description":"Webhook that receives the result (fast and regular queues)."}}},"GoogleAutocompleteRequest":{"type":"object","description":"Google search suggestions. 1 credit.","required":["endpoint","params"],"properties":{"endpoint":{"type":"string","enum":["google-autocomplete"]},"params":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":500},"country":{"type":"string","default":"us","enum":["us","gb","uk","ca","au","de","fr","nl","it","es","pt","be","at","ch","se","no","dk","fi","ie","pl","cz","il","ae","in","jp","kr","sg","mx","br","nz","za","tr"]},"language":{"type":"string","pattern":"^[a-zA-Z]{2}$","default":"en"}},"required":["query"],"additionalProperties":false},"queue":{"$ref":"#/components/schemas/Queue"},"postbackUrl":{"type":"string","format":"uri","description":"Webhook that receives the result (fast and regular queues)."}}},"Queue":{"type":"string","enum":["live","fast","regular"],"default":"fast","description":"live = synchronous; fast/regular = asynchronous. Same price."},"Job":{"type":"object","properties":{"id":{"type":"string"},"endpoint":{"type":"string","enum":["google-shopping-search","google-shopping-product","google-shopping-product-info","google-search","google-images","google-news","google-local","google-autocomplete"]},"queue":{"$ref":"#/components/schemas/Queue"},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"params":{"type":"object"},"credits":{"type":"integer","description":"Credits charged (0 when failed)"},"latencyMs":{"type":["integer","null"]},"error":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}},"JobResponse":{"type":"object","properties":{"job":{"$ref":"#/components/schemas/Job"},"result":{"type":["object","null"],"description":"Structured result; shape depends on the endpoint (see the docs)."}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"}}}}}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"SerpApiError":{"description":"Error, SerpApi style","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}}}