{"openapi":"3.1.0","info":{"title":"gsearch.dev Google Search API","version":"v1","description":"Search Google and receive ordered organic results as structured JSON, with country, language, and page targeting. gsearch.dev combines multiple search providers and in-house search scrapers behind one stable API. This sourcing model helps us keep prices low. At its full 300,000-credit monthly allowance, the annual Platform plan works out to $0.58 per 1,000 search credits. One returned page uses one credit.","contact":{"name":"gsearch.dev support","email":"support@gsearch.dev"},"termsOfService":"https://gsearch.dev/terms"},"servers":[{"url":"https://gsearch.dev"}],"externalDocs":{"description":"Google Search API documentation and code examples","url":"https://gsearch.dev/docs"},"tags":[{"name":"Search","description":"Run a localized Google text search and return structured organic results."}],"paths":{"/api/v1/search":{"post":{"tags":["Search"],"operationId":"searchGoogle","summary":"Search Google","description":"Runs a text search using the requested country, language, starting page, and page count. Each page in a successful response uses one search credit. If any page fails, the request returns an error without a partial response or credit charge.","security":[{"ApiKeyAuth":[]},{"BearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"},"example":{"q":"Ada Lovelace","gl":"us","hl":"en","page":1,"pages":3}}}},"responses":{"200":{"description":"The search completed successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"},"example":{"searchParameters":{"q":"Ada Lovelace","type":"search","gl":"us","hl":"en","page":1,"pages":3},"organic":[{"title":"Ada Lovelace | Biography, Computer, and Facts","link":"https://example.com/ada-lovelace","snippet":"A concise result snippet returned as structured text.","position":1}],"engine":"google","cached":false,"resultCount":1,"pagesReturned":3,"creditsUsed":3,"requestId":"4a7c43b4-19e5-4ecf-a2f8-7d734f7ac731"}}}},"400":{"description":"The request body is missing, malformed, or contains an invalid value. Possible codes: INVALID_SEARCH_REQUEST or INVALID_JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"The request does not include a valid API key or account session. Possible codes: AUTH_REQUIRED or INVALID_CREDENTIALS.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"402":{"description":"The account does not have enough credits for every requested page. Possible codes: CREDITS_EXHAUSTED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"413":{"description":"The JSON request body is larger than the accepted limit. Possible codes: REQUEST_BODY_TOO_LARGE.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"415":{"description":"The request does not use supported UTF-8 JSON content. Possible codes: UNSUPPORTED_MEDIA_TYPE.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"429":{"description":"The account request limit, requested-page limit, search IP safety limit, or global API limit was reached. Possible codes: API_PLAN_RATE_LIMITED, API_PLAN_PAGE_RATE_LIMITED, API_SEARCH_IP_RATE_LIMITED, or RATE_LIMITED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"500":{"description":"The request failed because of an unexpected service error. Possible codes: INTERNAL_ERROR.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"502":{"description":"The search could not return a valid response. Possible codes: PROVIDER_UNAVAILABLE or PROVIDER_INVALID_RESPONSE.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"503":{"description":"The search service is temporarily unavailable. Possible codes: SERVICE_UNAVAILABLE.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"504":{"description":"The search did not finish before the request deadline. Possible codes: PROVIDER_TIMEOUT.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"default":{"description":"The request could not be completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"An API key created in the gsearch.dev account area."},"BearerAuth":{"type":"http","scheme":"bearer","description":"The same API key sent as an Authorization Bearer token."}},"schemas":{"SearchRequest":{"type":"object","additionalProperties":false,"required":["q"],"properties":{"q":{"type":"string","minLength":1,"maxLength":300,"pattern":"\\S","description":"The text to search for. Leading and trailing whitespace is removed."},"gl":{"type":"string","enum":["af","al","dz","as","ad","ao","ai","aq","ag","ar","am","aw","au","at","az","bs","bh","bd","bb","by","be","bz","bj","bm","bt","bo","ba","bw","bv","br","io","bn","bg","bf","bi","kh","cm","ca","cv","ky","cf","td","cl","cn","cx","cc","co","km","cg","cd","ck","cr","ci","hr","cu","cy","cz","dk","dj","dm","do","ec","eg","sv","gq","er","ee","et","fk","fo","fj","fi","fr","gf","pf","tf","ga","gm","ge","de","gh","gi","gr","gl","gd","gp","gu","gt","gn","gw","gy","ht","hm","va","hn","hk","hu","is","in","id","ir","iq","ie","il","it","jm","jp","jo","kz","ke","ki","kp","kr","kw","kg","la","lv","lb","ls","lr","ly","li","lt","lu","mo","mk","mg","mw","my","mv","ml","mt","mh","mq","mr","mu","yt","mx","fm","md","mc","mn","ms","ma","mz","mm","na","nr","np","nl","an","nc","nz","ni","ne","ng","nu","nf","mp","no","om","pk","pw","ps","pa","pg","py","pe","ph","pn","pl","pt","pr","qa","re","ro","ru","rw","sh","kn","lc","pm","vc","ws","sm","st","sa","sn","rs","sc","sl","sg","sk","si","sb","so","za","gs","es","lk","sd","sr","sj","sz","se","ch","sy","tw","tj","tz","th","tl","tg","tk","to","tt","tn","tr","tm","tc","tv","ug","ua","ae","gb","us","um","uy","uz","vu","ve","vn","vg","vi","wf","eh","ye","zm","zw"],"default":"us","description":"The country code used to localize results."},"hl":{"type":"string","enum":["en","bg","de","fr","es"],"default":"en","description":"The language code used for the search interface and results."},"page":{"type":"integer","minimum":1,"maximum":100,"default":1,"description":"The first result page to request."},"pages":{"type":"integer","minimum":1,"maximum":100,"default":1,"description":"The number of consecutive pages to return. The final page cannot exceed 100. Each page uses one credit."}}},"SearchParameters":{"type":"object","additionalProperties":false,"required":["q","type","gl","hl","page"],"properties":{"q":{"type":"string"},"type":{"type":"string","const":"search"},"gl":{"type":"string","enum":["af","al","dz","as","ad","ao","ai","aq","ag","ar","am","aw","au","at","az","bs","bh","bd","bb","by","be","bz","bj","bm","bt","bo","ba","bw","bv","br","io","bn","bg","bf","bi","kh","cm","ca","cv","ky","cf","td","cl","cn","cx","cc","co","km","cg","cd","ck","cr","ci","hr","cu","cy","cz","dk","dj","dm","do","ec","eg","sv","gq","er","ee","et","fk","fo","fj","fi","fr","gf","pf","tf","ga","gm","ge","de","gh","gi","gr","gl","gd","gp","gu","gt","gn","gw","gy","ht","hm","va","hn","hk","hu","is","in","id","ir","iq","ie","il","it","jm","jp","jo","kz","ke","ki","kp","kr","kw","kg","la","lv","lb","ls","lr","ly","li","lt","lu","mo","mk","mg","mw","my","mv","ml","mt","mh","mq","mr","mu","yt","mx","fm","md","mc","mn","ms","ma","mz","mm","na","nr","np","nl","an","nc","nz","ni","ne","ng","nu","nf","mp","no","om","pk","pw","ps","pa","pg","py","pe","ph","pn","pl","pt","pr","qa","re","ro","ru","rw","sh","kn","lc","pm","vc","ws","sm","st","sa","sn","rs","sc","sl","sg","sk","si","sb","so","za","gs","es","lk","sd","sr","sj","sz","se","ch","sy","tw","tj","tz","th","tl","tg","tk","to","tt","tn","tr","tm","tc","tv","ug","ua","ae","gb","us","um","uy","uz","vu","ve","vn","vg","vi","wf","eh","ye","zm","zw"]},"hl":{"type":"string","enum":["en","bg","de","fr","es"]},"page":{"type":"integer","minimum":1,"maximum":100}}},"PagedSearchParameters":{"type":"object","additionalProperties":false,"required":["q","type","gl","hl","page","pages"],"properties":{"q":{"type":"string"},"type":{"type":"string","const":"search"},"gl":{"type":"string","enum":["af","al","dz","as","ad","ao","ai","aq","ag","ar","am","aw","au","at","az","bs","bh","bd","bb","by","be","bz","bj","bm","bt","bo","ba","bw","bv","br","io","bn","bg","bf","bi","kh","cm","ca","cv","ky","cf","td","cl","cn","cx","cc","co","km","cg","cd","ck","cr","ci","hr","cu","cy","cz","dk","dj","dm","do","ec","eg","sv","gq","er","ee","et","fk","fo","fj","fi","fr","gf","pf","tf","ga","gm","ge","de","gh","gi","gr","gl","gd","gp","gu","gt","gn","gw","gy","ht","hm","va","hn","hk","hu","is","in","id","ir","iq","ie","il","it","jm","jp","jo","kz","ke","ki","kp","kr","kw","kg","la","lv","lb","ls","lr","ly","li","lt","lu","mo","mk","mg","mw","my","mv","ml","mt","mh","mq","mr","mu","yt","mx","fm","md","mc","mn","ms","ma","mz","mm","na","nr","np","nl","an","nc","nz","ni","ne","ng","nu","nf","mp","no","om","pk","pw","ps","pa","pg","py","pe","ph","pn","pl","pt","pr","qa","re","ro","ru","rw","sh","kn","lc","pm","vc","ws","sm","st","sa","sn","rs","sc","sl","sg","sk","si","sb","so","za","gs","es","lk","sd","sr","sj","sz","se","ch","sy","tw","tj","tz","th","tl","tg","tk","to","tt","tn","tr","tm","tc","tv","ug","ua","ae","gb","us","um","uy","uz","vu","ve","vn","vg","vi","wf","eh","ye","zm","zw"]},"hl":{"type":"string","enum":["en","bg","de","fr","es"]},"page":{"type":"integer","minimum":1,"maximum":100},"pages":{"type":"integer","minimum":1,"maximum":100}}},"OrganicResult":{"type":"object","additionalProperties":false,"required":["title","link","snippet","position"],"properties":{"title":{"type":"string"},"link":{"type":"string","format":"uri"},"snippet":{"type":"string"},"position":{"type":"integer","minimum":1}}},"LegacySearchResponse":{"type":"object","additionalProperties":false,"required":["searchParameters","organic","engine","cached","resultCount","requestId"],"properties":{"searchParameters":{"$ref":"#/components/schemas/SearchParameters"},"organic":{"type":"array","items":{"$ref":"#/components/schemas/OrganicResult"}},"engine":{"type":"string","const":"google"},"cached":{"type":"boolean","const":false,"deprecated":true,"description":"Deprecated compatibility field. Always false."},"resultCount":{"type":"integer","minimum":0},"requestId":{"type":"string","format":"uuid"}}},"PagedSearchResponse":{"type":"object","additionalProperties":false,"required":["searchParameters","organic","engine","cached","resultCount","pagesReturned","creditsUsed","requestId"],"properties":{"searchParameters":{"$ref":"#/components/schemas/PagedSearchParameters"},"organic":{"type":"array","items":{"$ref":"#/components/schemas/OrganicResult"}},"engine":{"type":"string","const":"google"},"cached":{"type":"boolean","const":false,"deprecated":true,"description":"Deprecated compatibility field. Always false."},"resultCount":{"type":"integer","minimum":0},"pagesReturned":{"type":"integer","minimum":1,"maximum":100},"creditsUsed":{"type":"integer","minimum":0,"maximum":100,"description":"The number of account credits used by this response."},"requestId":{"type":"string","format":"uuid"}}},"SearchResponse":{"oneOf":[{"$ref":"#/components/schemas/LegacySearchResponse"},{"$ref":"#/components/schemas/PagedSearchResponse"}],"description":"Single-page requests that omit pages keep the original v1 response. Requests with pages include pagination and credit metadata."},"ApiErrorResponse":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string","format":"uuid"}}}}}}}}