{"openapi":"3.1.0","info":{"title":"BestSERP","description":"Google search results as clean JSON: web, images, news, videos, shopping, places and maps.\n\nAuthenticate with your API key in the `X-API-KEY` header (or `Authorization: Bearer <key>`).\nEach request costs 1 credit per page of results; failed and busy requests are refunded.\nRequests not finished within `timeout` answer `202` with a `requestId`: poll `GET /requests/{requestId}`.\nErrors look like `{\"error\": {\"code\": \"...\", \"message\": \"...\"}, \"requestId\": \"...\"}`.\n","version":"2.0.0"},"paths":{"/search":{"post":{"tags":["Search"],"summary":"Web search","description":"Organic Google results, plus the page's video carousel (`videos`) and Top stories (`news`) when present.","operationId":"search_search","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{},"example":{"searchParameters":{"q":"best running shoes","gl":"us","hl":"en","type":"search","num":10,"page":1,"engine":"google"},"organic":[{"position":1,"title":"The 10 Best Running Shoes of 2026","link":"https://www.example.com/best-running-shoes","snippet":"We tested 60 pairs to find the best running shoes for every runner…","displayedLink":"https://www.example.com › gear","source":"Example","domain":"example.com","favicon":"https://www.google.com/s2/favicons?domain=example.com&sz=64"}],"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","credits":1,"cached":false,"linksPending":true,"unresolvedLinks":0,"durationMs":2100}}}},"202":{"description":"Not finished within `timeout` (or `async: true`): poll `pollUrl`","content":{"application/json":{"example":{"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","status":"pending","pollUrl":"/requests/5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11"}}}},"400":{"description":"invalid_request, unknown_parameter, unsupported_parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"401":{"description":"missing_api_key, invalid_api_key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"403":{"description":"account_suspended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"429":{"description":"rate_limited (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"502":{"description":"search_failed: blocked or timed out; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"503":{"description":"busy: no capacity right now; retry after Retry-After; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["q"],"properties":{"q":{"type":"string","minLength":1,"maxLength":256,"description":"Search query"},"gl":{"type":"string","default":"us","description":"Country (2-letter code)"},"hl":{"type":"string","default":"en","description":"Interface language"},"num":{"type":"integer","default":10,"enum":[10,20,30,40,50],"description":"Results per page; each 10 costs 1 credit"},"page":{"type":"integer","default":1,"minimum":1,"maximum":5,"description":"Page to return (page x num/10 ≤ 5); pages 1..page are fetched and charged"},"tbs":{"type":"string","enum":["qdr:h","qdr:d","qdr:w","qdr:m","qdr:y"],"description":"Recency filter (also accepted: `timeRange`: hour|day|week|month|year)"},"resolveLinks":{"type":"boolean","default":true,"description":"Replace Google redirect links with final URLs (see `linksPending`)"},"autocorrect":{"type":"boolean","description":"Accepted for compatibility; no effect"},"noCache":{"type":"boolean","default":false,"description":"Skip the 1-hour result cache"},"async":{"type":"boolean","default":false,"description":"Answer 202 at once; poll GET /requests/{requestId}"},"timeout":{"type":"number","default":60,"minimum":1,"maximum":120,"description":"Seconds to wait before answering 202"}},"additionalProperties":false},"example":{"q":"best running shoes","gl":"us","hl":"en","num":10}}}}},"get":{"tags":["Search"],"summary":"Web search (GET)","description":"Organic Google results, plus the page's video carousel (`videos`) and Top stories (`news`) when present. Same as the POST endpoint, with the parameters in the query string.","operationId":"search_search_get","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{},"example":{"searchParameters":{"q":"best running shoes","gl":"us","hl":"en","type":"search","num":10,"page":1,"engine":"google"},"organic":[{"position":1,"title":"The 10 Best Running Shoes of 2026","link":"https://www.example.com/best-running-shoes","snippet":"We tested 60 pairs to find the best running shoes for every runner…","displayedLink":"https://www.example.com › gear","source":"Example","domain":"example.com","favicon":"https://www.google.com/s2/favicons?domain=example.com&sz=64"}],"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","credits":1,"cached":false,"linksPending":true,"unresolvedLinks":0,"durationMs":2100}}}},"202":{"description":"Not finished within `timeout` (or `async: true`): poll `pollUrl`","content":{"application/json":{"example":{"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","status":"pending","pollUrl":"/requests/5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11"}}}},"400":{"description":"invalid_request, unknown_parameter, unsupported_parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"401":{"description":"missing_api_key, invalid_api_key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"403":{"description":"account_suspended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"429":{"description":"rate_limited (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"502":{"description":"search_failed: blocked or timed out; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"503":{"description":"busy: no capacity right now; retry after Retry-After; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}}},"parameters":[{"name":"q","in":"query","required":true,"description":"Search query","schema":{"type":"string","minLength":1,"maxLength":256}},{"name":"gl","in":"query","required":false,"description":"Country (2-letter code)","schema":{"type":"string","default":"us"}},{"name":"hl","in":"query","required":false,"description":"Interface language","schema":{"type":"string","default":"en"}},{"name":"num","in":"query","required":false,"description":"Results per page; each 10 costs 1 credit","schema":{"type":"integer","default":10,"enum":[10,20,30,40,50]}},{"name":"page","in":"query","required":false,"description":"Page to return (page x num/10 ≤ 5); pages 1..page are fetched and charged","schema":{"type":"integer","default":1,"minimum":1,"maximum":5}},{"name":"tbs","in":"query","required":false,"description":"Recency filter (also accepted: `timeRange`: hour|day|week|month|year)","schema":{"type":"string","enum":["qdr:h","qdr:d","qdr:w","qdr:m","qdr:y"]}},{"name":"resolveLinks","in":"query","required":false,"description":"Replace Google redirect links with final URLs (see `linksPending`)","schema":{"type":"boolean","default":true}},{"name":"autocorrect","in":"query","required":false,"description":"Accepted for compatibility; no effect","schema":{"type":"boolean"}},{"name":"noCache","in":"query","required":false,"description":"Skip the 1-hour result cache","schema":{"type":"boolean","default":false}},{"name":"async","in":"query","required":false,"description":"Answer 202 at once; poll GET /requests/{requestId}","schema":{"type":"boolean","default":false}},{"name":"timeout","in":"query","required":false,"description":"Seconds to wait before answering 202","schema":{"type":"number","default":60,"minimum":1,"maximum":120}}]}},"/images":{"post":{"tags":["Search"],"summary":"Image search","description":"Google Images results with full-size image URLs.","operationId":"search_images","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{},"example":{"searchParameters":{"q":"golden retriever","gl":"us","hl":"en","type":"images","pages":1,"engine":"google"},"images":[{"position":1,"title":"Golden retriever puppy","imageUrl":"https://images.example.com/golden.jpg","imageWidth":1200,"imageHeight":800,"thumbnailUrl":"https://encrypted-tbn0.gstatic.com/images?q=tbn:x","source":"Example Pets","domain":"example.com","link":"https://example.com/golden-retriever"}],"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","credits":1,"cached":false,"linksPending":false,"unresolvedLinks":0,"durationMs":2100}}}},"202":{"description":"Not finished within `timeout` (or `async: true`): poll `pollUrl`","content":{"application/json":{"example":{"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","status":"pending","pollUrl":"/requests/5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11"}}}},"400":{"description":"invalid_request, unknown_parameter, unsupported_parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"401":{"description":"missing_api_key, invalid_api_key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"403":{"description":"account_suspended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"429":{"description":"rate_limited (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"502":{"description":"search_failed: blocked or timed out; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"503":{"description":"busy: no capacity right now; retry after Retry-After; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["q"],"properties":{"q":{"type":"string","minLength":1,"maxLength":256,"description":"Search query"},"gl":{"type":"string","default":"us","description":"Country (2-letter code)"},"hl":{"type":"string","default":"en","description":"Interface language"},"pages":{"type":"integer","default":1,"minimum":1,"maximum":5,"description":"Result pages / scroll loads to fetch; each costs 1 credit"},"tbs":{"type":"string","enum":["qdr:h","qdr:d","qdr:w","qdr:m","qdr:y"],"description":"Recency filter (also accepted: `timeRange`: hour|day|week|month|year)"},"autocorrect":{"type":"boolean","description":"Accepted for compatibility; no effect"},"noCache":{"type":"boolean","default":false,"description":"Skip the 1-hour result cache"},"async":{"type":"boolean","default":false,"description":"Answer 202 at once; poll GET /requests/{requestId}"},"timeout":{"type":"number","default":60,"minimum":1,"maximum":120,"description":"Seconds to wait before answering 202"}},"additionalProperties":false},"example":{"q":"golden retriever","gl":"us","hl":"en"}}}}},"get":{"tags":["Search"],"summary":"Image search (GET)","description":"Google Images results with full-size image URLs. Same as the POST endpoint, with the parameters in the query string.","operationId":"search_images_get","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{},"example":{"searchParameters":{"q":"golden retriever","gl":"us","hl":"en","type":"images","pages":1,"engine":"google"},"images":[{"position":1,"title":"Golden retriever puppy","imageUrl":"https://images.example.com/golden.jpg","imageWidth":1200,"imageHeight":800,"thumbnailUrl":"https://encrypted-tbn0.gstatic.com/images?q=tbn:x","source":"Example Pets","domain":"example.com","link":"https://example.com/golden-retriever"}],"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","credits":1,"cached":false,"linksPending":false,"unresolvedLinks":0,"durationMs":2100}}}},"202":{"description":"Not finished within `timeout` (or `async: true`): poll `pollUrl`","content":{"application/json":{"example":{"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","status":"pending","pollUrl":"/requests/5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11"}}}},"400":{"description":"invalid_request, unknown_parameter, unsupported_parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"401":{"description":"missing_api_key, invalid_api_key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"403":{"description":"account_suspended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"429":{"description":"rate_limited (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"502":{"description":"search_failed: blocked or timed out; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"503":{"description":"busy: no capacity right now; retry after Retry-After; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}}},"parameters":[{"name":"q","in":"query","required":true,"description":"Search query","schema":{"type":"string","minLength":1,"maxLength":256}},{"name":"gl","in":"query","required":false,"description":"Country (2-letter code)","schema":{"type":"string","default":"us"}},{"name":"hl","in":"query","required":false,"description":"Interface language","schema":{"type":"string","default":"en"}},{"name":"pages","in":"query","required":false,"description":"Result pages / scroll loads to fetch; each costs 1 credit","schema":{"type":"integer","default":1,"minimum":1,"maximum":5}},{"name":"tbs","in":"query","required":false,"description":"Recency filter (also accepted: `timeRange`: hour|day|week|month|year)","schema":{"type":"string","enum":["qdr:h","qdr:d","qdr:w","qdr:m","qdr:y"]}},{"name":"autocorrect","in":"query","required":false,"description":"Accepted for compatibility; no effect","schema":{"type":"boolean"}},{"name":"noCache","in":"query","required":false,"description":"Skip the 1-hour result cache","schema":{"type":"boolean","default":false}},{"name":"async","in":"query","required":false,"description":"Answer 202 at once; poll GET /requests/{requestId}","schema":{"type":"boolean","default":false}},{"name":"timeout","in":"query","required":false,"description":"Seconds to wait before answering 202","schema":{"type":"number","default":60,"minimum":1,"maximum":120}}]}},"/news":{"post":{"tags":["Search"],"summary":"News search","description":"Google News tab results with source and publish time.","operationId":"search_news","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{},"example":{"searchParameters":{"q":"electric vehicles","gl":"us","hl":"en","type":"news","num":10,"page":1,"engine":"google"},"news":[{"position":1,"title":"EV sales hit a new record","link":"https://news.example.com/ev-record","snippet":"Electric vehicle sales rose 30% year over year…","date":"2 hours ago","publishedAt":"2026-11-14T08:00:00+00:00","source":"Example News","domain":"news.example.com"}],"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","credits":1,"cached":false,"linksPending":true,"unresolvedLinks":0,"durationMs":2100}}}},"202":{"description":"Not finished within `timeout` (or `async: true`): poll `pollUrl`","content":{"application/json":{"example":{"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","status":"pending","pollUrl":"/requests/5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11"}}}},"400":{"description":"invalid_request, unknown_parameter, unsupported_parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"401":{"description":"missing_api_key, invalid_api_key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"403":{"description":"account_suspended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"429":{"description":"rate_limited (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"502":{"description":"search_failed: blocked or timed out; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"503":{"description":"busy: no capacity right now; retry after Retry-After; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["q"],"properties":{"q":{"type":"string","minLength":1,"maxLength":256,"description":"Search query"},"gl":{"type":"string","default":"us","description":"Country (2-letter code)"},"hl":{"type":"string","default":"en","description":"Interface language"},"num":{"type":"integer","default":10,"enum":[10,20,30,40,50],"description":"Results per page; each 10 costs 1 credit"},"page":{"type":"integer","default":1,"minimum":1,"maximum":5,"description":"Page to return (page x num/10 ≤ 5); pages 1..page are fetched and charged"},"tbs":{"type":"string","enum":["qdr:h","qdr:d","qdr:w","qdr:m","qdr:y"],"description":"Recency filter (also accepted: `timeRange`: hour|day|week|month|year)"},"resolveLinks":{"type":"boolean","default":true,"description":"Replace Google redirect links with final URLs (see `linksPending`)"},"includeThumbnails":{"type":"boolean","default":false,"description":"Include inline base64 thumbnails (~20 KB each)"},"autocorrect":{"type":"boolean","description":"Accepted for compatibility; no effect"},"noCache":{"type":"boolean","default":false,"description":"Skip the 1-hour result cache"},"async":{"type":"boolean","default":false,"description":"Answer 202 at once; poll GET /requests/{requestId}"},"timeout":{"type":"number","default":60,"minimum":1,"maximum":120,"description":"Seconds to wait before answering 202"}},"additionalProperties":false},"example":{"q":"electric vehicles","gl":"us","hl":"en","num":10}}}}},"get":{"tags":["Search"],"summary":"News search (GET)","description":"Google News tab results with source and publish time. Same as the POST endpoint, with the parameters in the query string.","operationId":"search_news_get","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{},"example":{"searchParameters":{"q":"electric vehicles","gl":"us","hl":"en","type":"news","num":10,"page":1,"engine":"google"},"news":[{"position":1,"title":"EV sales hit a new record","link":"https://news.example.com/ev-record","snippet":"Electric vehicle sales rose 30% year over year…","date":"2 hours ago","publishedAt":"2026-11-14T08:00:00+00:00","source":"Example News","domain":"news.example.com"}],"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","credits":1,"cached":false,"linksPending":true,"unresolvedLinks":0,"durationMs":2100}}}},"202":{"description":"Not finished within `timeout` (or `async: true`): poll `pollUrl`","content":{"application/json":{"example":{"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","status":"pending","pollUrl":"/requests/5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11"}}}},"400":{"description":"invalid_request, unknown_parameter, unsupported_parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"401":{"description":"missing_api_key, invalid_api_key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"403":{"description":"account_suspended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"429":{"description":"rate_limited (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"502":{"description":"search_failed: blocked or timed out; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"503":{"description":"busy: no capacity right now; retry after Retry-After; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}}},"parameters":[{"name":"q","in":"query","required":true,"description":"Search query","schema":{"type":"string","minLength":1,"maxLength":256}},{"name":"gl","in":"query","required":false,"description":"Country (2-letter code)","schema":{"type":"string","default":"us"}},{"name":"hl","in":"query","required":false,"description":"Interface language","schema":{"type":"string","default":"en"}},{"name":"num","in":"query","required":false,"description":"Results per page; each 10 costs 1 credit","schema":{"type":"integer","default":10,"enum":[10,20,30,40,50]}},{"name":"page","in":"query","required":false,"description":"Page to return (page x num/10 ≤ 5); pages 1..page are fetched and charged","schema":{"type":"integer","default":1,"minimum":1,"maximum":5}},{"name":"tbs","in":"query","required":false,"description":"Recency filter (also accepted: `timeRange`: hour|day|week|month|year)","schema":{"type":"string","enum":["qdr:h","qdr:d","qdr:w","qdr:m","qdr:y"]}},{"name":"resolveLinks","in":"query","required":false,"description":"Replace Google redirect links with final URLs (see `linksPending`)","schema":{"type":"boolean","default":true}},{"name":"includeThumbnails","in":"query","required":false,"description":"Include inline base64 thumbnails (~20 KB each)","schema":{"type":"boolean","default":false}},{"name":"autocorrect","in":"query","required":false,"description":"Accepted for compatibility; no effect","schema":{"type":"boolean"}},{"name":"noCache","in":"query","required":false,"description":"Skip the 1-hour result cache","schema":{"type":"boolean","default":false}},{"name":"async","in":"query","required":false,"description":"Answer 202 at once; poll GET /requests/{requestId}","schema":{"type":"boolean","default":false}},{"name":"timeout","in":"query","required":false,"description":"Seconds to wait before answering 202","schema":{"type":"number","default":60,"minimum":1,"maximum":120}}]}},"/videos":{"post":{"tags":["Search"],"summary":"Video search","description":"Google Videos tab results with duration and channel.","operationId":"search_videos","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{},"example":{"searchParameters":{"q":"python asyncio tutorial","gl":"us","hl":"en","type":"videos","num":10,"page":1,"engine":"google"},"videos":[{"position":1,"title":"Python asyncio in 20 minutes","link":"https://www.youtube.com/watch?v=abc","duration":"20:14","channel":"Example Channel","platform":"YouTube","date":"3 weeks ago"}],"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","credits":1,"cached":false,"linksPending":false,"unresolvedLinks":0,"durationMs":2100}}}},"202":{"description":"Not finished within `timeout` (or `async: true`): poll `pollUrl`","content":{"application/json":{"example":{"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","status":"pending","pollUrl":"/requests/5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11"}}}},"400":{"description":"invalid_request, unknown_parameter, unsupported_parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"401":{"description":"missing_api_key, invalid_api_key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"403":{"description":"account_suspended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"429":{"description":"rate_limited (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"502":{"description":"search_failed: blocked or timed out; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"503":{"description":"busy: no capacity right now; retry after Retry-After; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["q"],"properties":{"q":{"type":"string","minLength":1,"maxLength":256,"description":"Search query"},"gl":{"type":"string","default":"us","description":"Country (2-letter code)"},"hl":{"type":"string","default":"en","description":"Interface language"},"num":{"type":"integer","default":10,"enum":[10,20,30,40,50],"description":"Results per page; each 10 costs 1 credit"},"page":{"type":"integer","default":1,"minimum":1,"maximum":5,"description":"Page to return (page x num/10 ≤ 5); pages 1..page are fetched and charged"},"tbs":{"type":"string","enum":["qdr:h","qdr:d","qdr:w","qdr:m","qdr:y"],"description":"Recency filter (also accepted: `timeRange`: hour|day|week|month|year)"},"includeThumbnails":{"type":"boolean","default":false,"description":"Include inline base64 thumbnails (~20 KB each)"},"autocorrect":{"type":"boolean","description":"Accepted for compatibility; no effect"},"noCache":{"type":"boolean","default":false,"description":"Skip the 1-hour result cache"},"async":{"type":"boolean","default":false,"description":"Answer 202 at once; poll GET /requests/{requestId}"},"timeout":{"type":"number","default":60,"minimum":1,"maximum":120,"description":"Seconds to wait before answering 202"}},"additionalProperties":false},"example":{"q":"python asyncio tutorial","gl":"us","hl":"en","num":10}}}}},"get":{"tags":["Search"],"summary":"Video search (GET)","description":"Google Videos tab results with duration and channel. Same as the POST endpoint, with the parameters in the query string.","operationId":"search_videos_get","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{},"example":{"searchParameters":{"q":"python asyncio tutorial","gl":"us","hl":"en","type":"videos","num":10,"page":1,"engine":"google"},"videos":[{"position":1,"title":"Python asyncio in 20 minutes","link":"https://www.youtube.com/watch?v=abc","duration":"20:14","channel":"Example Channel","platform":"YouTube","date":"3 weeks ago"}],"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","credits":1,"cached":false,"linksPending":false,"unresolvedLinks":0,"durationMs":2100}}}},"202":{"description":"Not finished within `timeout` (or `async: true`): poll `pollUrl`","content":{"application/json":{"example":{"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","status":"pending","pollUrl":"/requests/5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11"}}}},"400":{"description":"invalid_request, unknown_parameter, unsupported_parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"401":{"description":"missing_api_key, invalid_api_key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"403":{"description":"account_suspended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"429":{"description":"rate_limited (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"502":{"description":"search_failed: blocked or timed out; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"503":{"description":"busy: no capacity right now; retry after Retry-After; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}}},"parameters":[{"name":"q","in":"query","required":true,"description":"Search query","schema":{"type":"string","minLength":1,"maxLength":256}},{"name":"gl","in":"query","required":false,"description":"Country (2-letter code)","schema":{"type":"string","default":"us"}},{"name":"hl","in":"query","required":false,"description":"Interface language","schema":{"type":"string","default":"en"}},{"name":"num","in":"query","required":false,"description":"Results per page; each 10 costs 1 credit","schema":{"type":"integer","default":10,"enum":[10,20,30,40,50]}},{"name":"page","in":"query","required":false,"description":"Page to return (page x num/10 ≤ 5); pages 1..page are fetched and charged","schema":{"type":"integer","default":1,"minimum":1,"maximum":5}},{"name":"tbs","in":"query","required":false,"description":"Recency filter (also accepted: `timeRange`: hour|day|week|month|year)","schema":{"type":"string","enum":["qdr:h","qdr:d","qdr:w","qdr:m","qdr:y"]}},{"name":"includeThumbnails","in":"query","required":false,"description":"Include inline base64 thumbnails (~20 KB each)","schema":{"type":"boolean","default":false}},{"name":"autocorrect","in":"query","required":false,"description":"Accepted for compatibility; no effect","schema":{"type":"boolean"}},{"name":"noCache","in":"query","required":false,"description":"Skip the 1-hour result cache","schema":{"type":"boolean","default":false}},{"name":"async","in":"query","required":false,"description":"Answer 202 at once; poll GET /requests/{requestId}","schema":{"type":"boolean","default":false}},{"name":"timeout","in":"query","required":false,"description":"Seconds to wait before answering 202","schema":{"type":"number","default":60,"minimum":1,"maximum":120}}]}},"/shopping":{"post":{"tags":["Search"],"summary":"Shopping search","description":"Google Shopping products with price and rating.","operationId":"search_shopping","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{},"example":{"searchParameters":{"q":"mechanical keyboard","gl":"us","hl":"en","type":"shopping","pages":1,"engine":"google"},"shopping":[{"position":1,"title":"Example K2 Mechanical Keyboard","source":"Example Store","price":"$89.99","priceValue":89.99,"rating":4.6,"ratingCount":1820,"delivery":"Free delivery"}],"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","credits":1,"cached":false,"linksPending":false,"unresolvedLinks":0,"durationMs":2100}}}},"202":{"description":"Not finished within `timeout` (or `async: true`): poll `pollUrl`","content":{"application/json":{"example":{"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","status":"pending","pollUrl":"/requests/5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11"}}}},"400":{"description":"invalid_request, unknown_parameter, unsupported_parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"401":{"description":"missing_api_key, invalid_api_key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"403":{"description":"account_suspended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"429":{"description":"rate_limited (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"502":{"description":"search_failed: blocked or timed out; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"503":{"description":"busy: no capacity right now; retry after Retry-After; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["q"],"properties":{"q":{"type":"string","minLength":1,"maxLength":256,"description":"Search query"},"gl":{"type":"string","default":"us","description":"Country (2-letter code)"},"hl":{"type":"string","default":"en","description":"Interface language"},"pages":{"type":"integer","default":1,"minimum":1,"maximum":5,"description":"Result pages / scroll loads to fetch; each costs 1 credit"},"includeThumbnails":{"type":"boolean","default":false,"description":"Include inline base64 thumbnails (~20 KB each)"},"autocorrect":{"type":"boolean","description":"Accepted for compatibility; no effect"},"noCache":{"type":"boolean","default":false,"description":"Skip the 1-hour result cache"},"async":{"type":"boolean","default":false,"description":"Answer 202 at once; poll GET /requests/{requestId}"},"timeout":{"type":"number","default":60,"minimum":1,"maximum":120,"description":"Seconds to wait before answering 202"}},"additionalProperties":false},"example":{"q":"mechanical keyboard","gl":"us","hl":"en"}}}}},"get":{"tags":["Search"],"summary":"Shopping search (GET)","description":"Google Shopping products with price and rating. Same as the POST endpoint, with the parameters in the query string.","operationId":"search_shopping_get","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{},"example":{"searchParameters":{"q":"mechanical keyboard","gl":"us","hl":"en","type":"shopping","pages":1,"engine":"google"},"shopping":[{"position":1,"title":"Example K2 Mechanical Keyboard","source":"Example Store","price":"$89.99","priceValue":89.99,"rating":4.6,"ratingCount":1820,"delivery":"Free delivery"}],"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","credits":1,"cached":false,"linksPending":false,"unresolvedLinks":0,"durationMs":2100}}}},"202":{"description":"Not finished within `timeout` (or `async: true`): poll `pollUrl`","content":{"application/json":{"example":{"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","status":"pending","pollUrl":"/requests/5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11"}}}},"400":{"description":"invalid_request, unknown_parameter, unsupported_parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"401":{"description":"missing_api_key, invalid_api_key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"403":{"description":"account_suspended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"429":{"description":"rate_limited (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"502":{"description":"search_failed: blocked or timed out; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"503":{"description":"busy: no capacity right now; retry after Retry-After; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}}},"parameters":[{"name":"q","in":"query","required":true,"description":"Search query","schema":{"type":"string","minLength":1,"maxLength":256}},{"name":"gl","in":"query","required":false,"description":"Country (2-letter code)","schema":{"type":"string","default":"us"}},{"name":"hl","in":"query","required":false,"description":"Interface language","schema":{"type":"string","default":"en"}},{"name":"pages","in":"query","required":false,"description":"Result pages / scroll loads to fetch; each costs 1 credit","schema":{"type":"integer","default":1,"minimum":1,"maximum":5}},{"name":"includeThumbnails","in":"query","required":false,"description":"Include inline base64 thumbnails (~20 KB each)","schema":{"type":"boolean","default":false}},{"name":"autocorrect","in":"query","required":false,"description":"Accepted for compatibility; no effect","schema":{"type":"boolean"}},{"name":"noCache","in":"query","required":false,"description":"Skip the 1-hour result cache","schema":{"type":"boolean","default":false}},{"name":"async","in":"query","required":false,"description":"Answer 202 at once; poll GET /requests/{requestId}","schema":{"type":"boolean","default":false}},{"name":"timeout","in":"query","required":false,"description":"Seconds to wait before answering 202","schema":{"type":"number","default":60,"minimum":1,"maximum":120}}]}},"/places":{"post":{"tags":["Search"],"summary":"Places search","description":"Local results (the Places tab) with rating and address.","operationId":"search_places","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{},"example":{"searchParameters":{"q":"coffee shop hanoi","gl":"us","hl":"en","type":"places","pages":1,"engine":"google"},"places":[{"position":1,"title":"Example Coffee","address":"12 Example St, Hanoi","category":"Coffee shop","rating":4.6,"ratingCount":1800,"hours":"Open · Closes 10 PM","latitude":21.03,"longitude":105.85,"placeId":"ChIJexample","cid":"1234567890"}],"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","credits":1,"cached":false,"linksPending":false,"unresolvedLinks":0,"durationMs":2100}}}},"202":{"description":"Not finished within `timeout` (or `async: true`): poll `pollUrl`","content":{"application/json":{"example":{"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","status":"pending","pollUrl":"/requests/5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11"}}}},"400":{"description":"invalid_request, unknown_parameter, unsupported_parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"401":{"description":"missing_api_key, invalid_api_key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"403":{"description":"account_suspended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"429":{"description":"rate_limited (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"502":{"description":"search_failed: blocked or timed out; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"503":{"description":"busy: no capacity right now; retry after Retry-After; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["q"],"properties":{"q":{"type":"string","minLength":1,"maxLength":256,"description":"Search query"},"gl":{"type":"string","default":"us","description":"Country (2-letter code)"},"hl":{"type":"string","default":"en","description":"Interface language"},"pages":{"type":"integer","default":1,"minimum":1,"maximum":5,"description":"Result pages / scroll loads to fetch; each costs 1 credit"},"includeThumbnails":{"type":"boolean","default":false,"description":"Include inline base64 thumbnails (~20 KB each)"},"autocorrect":{"type":"boolean","description":"Accepted for compatibility; no effect"},"noCache":{"type":"boolean","default":false,"description":"Skip the 1-hour result cache"},"async":{"type":"boolean","default":false,"description":"Answer 202 at once; poll GET /requests/{requestId}"},"timeout":{"type":"number","default":60,"minimum":1,"maximum":120,"description":"Seconds to wait before answering 202"}},"additionalProperties":false},"example":{"q":"coffee shop hanoi","gl":"us","hl":"en"}}}}},"get":{"tags":["Search"],"summary":"Places search (GET)","description":"Local results (the Places tab) with rating and address. Same as the POST endpoint, with the parameters in the query string.","operationId":"search_places_get","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{},"example":{"searchParameters":{"q":"coffee shop hanoi","gl":"us","hl":"en","type":"places","pages":1,"engine":"google"},"places":[{"position":1,"title":"Example Coffee","address":"12 Example St, Hanoi","category":"Coffee shop","rating":4.6,"ratingCount":1800,"hours":"Open · Closes 10 PM","latitude":21.03,"longitude":105.85,"placeId":"ChIJexample","cid":"1234567890"}],"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","credits":1,"cached":false,"linksPending":false,"unresolvedLinks":0,"durationMs":2100}}}},"202":{"description":"Not finished within `timeout` (or `async: true`): poll `pollUrl`","content":{"application/json":{"example":{"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","status":"pending","pollUrl":"/requests/5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11"}}}},"400":{"description":"invalid_request, unknown_parameter, unsupported_parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"401":{"description":"missing_api_key, invalid_api_key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"403":{"description":"account_suspended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"429":{"description":"rate_limited (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"502":{"description":"search_failed: blocked or timed out; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"503":{"description":"busy: no capacity right now; retry after Retry-After; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}}},"parameters":[{"name":"q","in":"query","required":true,"description":"Search query","schema":{"type":"string","minLength":1,"maxLength":256}},{"name":"gl","in":"query","required":false,"description":"Country (2-letter code)","schema":{"type":"string","default":"us"}},{"name":"hl","in":"query","required":false,"description":"Interface language","schema":{"type":"string","default":"en"}},{"name":"pages","in":"query","required":false,"description":"Result pages / scroll loads to fetch; each costs 1 credit","schema":{"type":"integer","default":1,"minimum":1,"maximum":5}},{"name":"includeThumbnails","in":"query","required":false,"description":"Include inline base64 thumbnails (~20 KB each)","schema":{"type":"boolean","default":false}},{"name":"autocorrect","in":"query","required":false,"description":"Accepted for compatibility; no effect","schema":{"type":"boolean"}},{"name":"noCache","in":"query","required":false,"description":"Skip the 1-hour result cache","schema":{"type":"boolean","default":false}},{"name":"async","in":"query","required":false,"description":"Answer 202 at once; poll GET /requests/{requestId}","schema":{"type":"boolean","default":false}},{"name":"timeout","in":"query","required":false,"description":"Seconds to wait before answering 202","schema":{"type":"number","default":60,"minimum":1,"maximum":120}}]}},"/maps":{"post":{"tags":["Search"],"summary":"Maps search","description":"Google Maps places with coordinates, place id and CID.","operationId":"search_maps","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{},"example":{"searchParameters":{"q":"pho restaurant hanoi","gl":"us","hl":"en","type":"maps","pages":1,"engine":"google"},"places":[{"position":1,"title":"Example Coffee","address":"12 Example St, Hanoi","category":"Coffee shop","rating":4.6,"ratingCount":1800,"hours":"Open · Closes 10 PM","latitude":21.03,"longitude":105.85,"placeId":"ChIJexample","cid":"1234567890"}],"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","credits":1,"cached":false,"linksPending":false,"unresolvedLinks":0,"durationMs":2100}}}},"202":{"description":"Not finished within `timeout` (or `async: true`): poll `pollUrl`","content":{"application/json":{"example":{"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","status":"pending","pollUrl":"/requests/5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11"}}}},"400":{"description":"invalid_request, unknown_parameter, unsupported_parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"401":{"description":"missing_api_key, invalid_api_key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"403":{"description":"account_suspended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"429":{"description":"rate_limited (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"502":{"description":"search_failed: blocked or timed out; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"503":{"description":"busy: no capacity right now; retry after Retry-After; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["q"],"properties":{"q":{"type":"string","minLength":1,"maxLength":256,"description":"Search query"},"gl":{"type":"string","default":"us","description":"Country (2-letter code)"},"hl":{"type":"string","default":"en","description":"Interface language"},"pages":{"type":"integer","default":1,"minimum":1,"maximum":5,"description":"Result pages / scroll loads to fetch; each costs 1 credit"},"autocorrect":{"type":"boolean","description":"Accepted for compatibility; no effect"},"noCache":{"type":"boolean","default":false,"description":"Skip the 1-hour result cache"},"async":{"type":"boolean","default":false,"description":"Answer 202 at once; poll GET /requests/{requestId}"},"timeout":{"type":"number","default":60,"minimum":1,"maximum":120,"description":"Seconds to wait before answering 202"}},"additionalProperties":false},"example":{"q":"pho restaurant hanoi","gl":"us","hl":"en"}}}}},"get":{"tags":["Search"],"summary":"Maps search (GET)","description":"Google Maps places with coordinates, place id and CID. Same as the POST endpoint, with the parameters in the query string.","operationId":"search_maps_get","security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Results","content":{"application/json":{"schema":{},"example":{"searchParameters":{"q":"pho restaurant hanoi","gl":"us","hl":"en","type":"maps","pages":1,"engine":"google"},"places":[{"position":1,"title":"Example Coffee","address":"12 Example St, Hanoi","category":"Coffee shop","rating":4.6,"ratingCount":1800,"hours":"Open · Closes 10 PM","latitude":21.03,"longitude":105.85,"placeId":"ChIJexample","cid":"1234567890"}],"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","credits":1,"cached":false,"linksPending":false,"unresolvedLinks":0,"durationMs":2100}}}},"202":{"description":"Not finished within `timeout` (or `async: true`): poll `pollUrl`","content":{"application/json":{"example":{"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","status":"pending","pollUrl":"/requests/5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11"}}}},"400":{"description":"invalid_request, unknown_parameter, unsupported_parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"401":{"description":"missing_api_key, invalid_api_key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"403":{"description":"account_suspended","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"429":{"description":"rate_limited (see Retry-After)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"502":{"description":"search_failed: blocked or timed out; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"503":{"description":"busy: no capacity right now; retry after Retry-After; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}}},"parameters":[{"name":"q","in":"query","required":true,"description":"Search query","schema":{"type":"string","minLength":1,"maxLength":256}},{"name":"gl","in":"query","required":false,"description":"Country (2-letter code)","schema":{"type":"string","default":"us"}},{"name":"hl","in":"query","required":false,"description":"Interface language","schema":{"type":"string","default":"en"}},{"name":"pages","in":"query","required":false,"description":"Result pages / scroll loads to fetch; each costs 1 credit","schema":{"type":"integer","default":1,"minimum":1,"maximum":5}},{"name":"autocorrect","in":"query","required":false,"description":"Accepted for compatibility; no effect","schema":{"type":"boolean"}},{"name":"noCache","in":"query","required":false,"description":"Skip the 1-hour result cache","schema":{"type":"boolean","default":false}},{"name":"async","in":"query","required":false,"description":"Answer 202 at once; poll GET /requests/{requestId}","schema":{"type":"boolean","default":false}},{"name":"timeout","in":"query","required":false,"description":"Seconds to wait before answering 202","schema":{"type":"number","default":60,"minimum":1,"maximum":120}}]}},"/requests/{requestId}":{"get":{"tags":["Requests"],"summary":"Poll a request","description":"Result of a request answered `202` (or any earlier request): `202` while pending, then the same\nbody as the search endpoint. Only the account that made the request can read it.","operationId":"get_request","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"requestId","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Requestid"}}],"responses":{"200":{"description":"Finished: same body as the search endpoint","content":{"application/json":{"schema":{},"example":{"searchParameters":{"q":"best running shoes","gl":"us","hl":"en","type":"search","num":10,"page":1,"engine":"google"},"organic":[{"position":1,"title":"The 10 Best Running Shoes of 2026","link":"https://www.example.com/best-running-shoes","snippet":"We tested 60 pairs to find the best running shoes for every runner…","displayedLink":"https://www.example.com › gear","source":"Example","domain":"example.com","favicon":"https://www.google.com/s2/favicons?domain=example.com&sz=64"}],"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","credits":1,"cached":false,"linksPending":true,"unresolvedLinks":0,"durationMs":2100}}}},"202":{"description":"Not finished within `timeout` (or `async: true`): poll `pollUrl`","content":{"application/json":{"example":{"requestId":"5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11","status":"pending","pollUrl":"/requests/5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"502":{"description":"search_failed: blocked or timed out; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"503":{"description":"busy: no capacity right now; retry after Retry-After; credits refunded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}},"requestId":{"type":"string","format":"uuid"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/account":{"get":{"tags":["Account"],"summary":"Credit balance","description":"Credit balance of the account that owns the key, with its live grants (soonest expiry first).","operationId":"account_account_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"ApiKeyAuth":[]}]}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","description":"Your API key (dashboard > API Keys). `Authorization: Bearer <key>` works too.","in":"header","name":"X-API-KEY"}}},"tags":[{"name":"Search","description":"One endpoint per Google vertical"},{"name":"Requests","description":"Poll requests answered 202"},{"name":"Account","description":"Credit balance"}]}