{"openapi":"3.0.3","info":{"title":"Google API","version":"1.0.0","description":"Google web search, knowledge panels, query suggestions and dictionary lookups with stable schemas.","contact":{"email":"support@endpointry.com"},"termsOfService":"https://endpointry.com/legal/terms"},"servers":[{"url":"https://api.endpointry.com/v1/google"}],"tags":[{"name":"Google API","description":"Google web search, knowledge panels, query suggestions and dictionary lookups with stable schemas."}],"components":{"schemas":{"ResponseMeta":{"type":"object","properties":{"request_id":{"type":"string","example":"req_9f2c4a1b8d3e0f6a7c5b9d1e"},"as_of":{"type":"string","format":"date-time","description":"When this snapshot of the data was taken (UTC)."},"cache":{"type":"string","enum":["HIT","MISS"]},"pagination":{"$ref":"#/components/schemas/PaginationMeta"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/ResponseWarning"}}},"required":["request_id"]},"PaginationMeta":{"type":"object","properties":{"page":{"type":"integer"},"next_cursor":{"type":"string","nullable":true},"next_offset":{"type":"integer","nullable":true},"next_page":{"type":"integer","nullable":true},"limit":{"type":"integer"},"returned":{"type":"integer"},"total":{"type":"integer"}}},"ResponseWarning":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"}},"required":["code","detail"]},"GoogleWebSearchResult":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/GoogleSearchResult"}}},"required":["results"]},"GoogleSearchResult":{"type":"object","properties":{"position":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Absolute rank across the whole result set, starting at 1."},"url":{"type":"string","format":"uri"},"domain":{"type":"string"},"title":{"type":"string"},"snippet":{"type":"string","nullable":true},"published_at":{"type":"string","nullable":true,"format":"date-time","description":"Publication date when the source exposes one, otherwise null."}},"required":["position","url","domain","title","snippet","published_at"]},"Problem":{"type":"object","properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string"},"detail":{"type":"string"},"request_id":{"type":"string"}},"required":["type","title","status","code","request_id"]},"GoogleRankMatch":{"type":"object","properties":{"position":{"type":"integer","minimum":0,"exclusiveMinimum":true,"example":2,"description":"Absolute rank across the whole result set, starting at 1."},"url":{"type":"string","format":"uri","example":"https://www.pipedrive.com/en/crm/compare/crm-tool"},"title":{"type":"string","example":"Compare CRM Tools"}},"required":["position","url","title"]},"GoogleKnowledgePanel":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string","nullable":true,"description":"Short type descriptor, e.g. \"Software company\"."},"description":{"type":"object","nullable":true,"properties":{"text":{"type":"string"},"source_url":{"type":"string","nullable":true,"format":"uri"},"source_name":{"type":"string","nullable":true}},"required":["text","source_url","source_name"]},"image":{"type":"object","nullable":true,"properties":{"url":{"type":"string","format":"uri"},"width":{"type":"integer","nullable":true},"height":{"type":"integer","nullable":true},"page_url":{"type":"string","nullable":true,"format":"uri"}},"required":["url","width","height","page_url"]},"attributes":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"values":{"type":"array","items":{"type":"string"}}},"required":["label","values"]},"description":"Structured facts, e.g. Founded → [\"2021\"]."}},"required":["name","label","description","image","attributes"]},"GoogleAutocompleteResult":{"type":"object","properties":{"suggestions":{"type":"array","items":{"$ref":"#/components/schemas/GoogleSuggestion"}},"spelling_suggestion":{"type":"string","nullable":true,"description":"Corrected query when the input looks misspelled, otherwise null."}},"required":["suggestions","spelling_suggestion"]},"GoogleSuggestion":{"type":"object","properties":{"position":{"type":"integer","minimum":0,"exclusiveMinimum":true},"keyword":{"type":"string","description":"The full suggested query, as plain text."},"keyword_html":{"type":"string","description":"Same suggestion with <b> around the completed portion, for UI highlighting."},"entity":{"type":"object","nullable":true,"properties":{"title":{"type":"string"},"label":{"type":"string","nullable":true},"image_url":{"type":"string","nullable":true,"format":"uri"}},"required":["title","label","image_url"],"description":"Set when the suggestion maps to a known entity."}},"required":["position","keyword","keyword_html","entity"]},"DictionaryResult":{"type":"object","properties":{"word":{"type":"string"},"syllables":{"type":"string","nullable":true,"example":"ser·en·dip·i·ty","description":"The word split into syllables, when the source provides it."},"etymology":{"type":"string","nullable":true,"example":"1754: coined by Horace Walpole…","description":"Word origin, when available."},"pronunciations":{"type":"array","items":{"$ref":"#/components/schemas/Pronunciation"}},"entries":{"type":"array","items":{"$ref":"#/components/schemas/DictionaryEntry"},"description":"One entry per part of speech, in the order the source ranks them."}},"required":["word","syllables","etymology","pronunciations","entries"]},"Pronunciation":{"type":"object","properties":{"text":{"type":"string","example":"ˌserənˈdipədē"},"notation":{"type":"string","nullable":true,"example":"respell","description":"The transcription system used, when the source states one."},"audio_url":{"type":"string","nullable":true,"format":"uri","description":"Spoken pronunciation, when available."}},"required":["text","notation","audio_url"]},"DictionaryEntry":{"type":"object","properties":{"part_of_speech":{"type":"string","example":"noun"},"inflections":{"type":"array","items":{"$ref":"#/components/schemas/Inflection"}},"definitions":{"type":"array","items":{"$ref":"#/components/schemas/Definition"}}},"required":["part_of_speech","inflections","definitions"]},"Inflection":{"type":"object","properties":{"label":{"type":"string","example":"plural noun"},"text":{"type":"string","example":"serendipities"}},"required":["label","text"]},"Definition":{"type":"object","properties":{"text":{"type":"string"},"synonyms":{"type":"array","items":{"type":"string"}},"examples":{"type":"array","items":{"type":"string"}}},"required":["text","synonyms","examples"]}},"parameters":{}},"paths":{"/web-search":{"get":{"operationId":"google.web-search","summary":"Search the web","description":"Returns ranked web results, exactly `per_page` per response (up to 10) until the result set ends. Pagination continues while results remain — typically 100–250 per query — and stops with `meta.pagination.next_page: null`. Each result carries its absolute position, so ranking is stable across pages. Results reflect a globally neutral locale; country and language targeting are not yet available.","tags":["Google API"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"example":"best crm software","description":"The search query."},"required":true,"description":"The search query.","name":"query","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"default":1,"example":1,"description":"Page number, starting at 1."},"required":false,"description":"Page number, starting at 1.","name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":10,"default":10,"example":10,"description":"Results per page (1–10). Every page is full until the result set ends."},"required":false,"description":"Results per page (1–10). Every page is full until the result set ends.","name":"per_page","in":"query"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/GoogleWebSearchResult"}},"required":["meta","data"]}}}},"default":{"description":"Error response (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/rank":{"get":{"operationId":"google.rank","summary":"Check a domain's rank","description":"Reports where a domain ranks for a query, scanning the whole measured result set — typically 100–250 results. Returns the best position, every appearance of the domain with its exact page, and `results_scanned` so a `null` position always names the set it was measured against. Shares its snapshot with `/web-search`, so a check right after a search costs nothing extra. Results reflect a globally neutral locale; country and language targeting are not yet available.","tags":["Google API"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"example":"best crm software","description":"The search query (keyword) to check rankings in."},"required":true,"description":"The search query (keyword) to check rankings in.","name":"query","in":"query"},{"schema":{"type":"string","minLength":4,"maxLength":253,"pattern":"^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$/i","example":"pipedrive.com","description":"The domain to look for, without scheme or path."},"required":true,"description":"The domain to look for, without scheme or path.","name":"domain","in":"query"},{"schema":{"type":"string","enum":["exact","subdomains"],"default":"subdomains","example":"subdomains","description":"`subdomains` counts the domain and everything under it; `exact` counts only the domain itself (www is always treated as the domain)."},"required":false,"description":"`subdomains` counts the domain and everything under it; `exact` counts only the domain itself (www is always treated as the domain).","name":"mode","in":"query"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"type":"object","properties":{"query":{"type":"string","example":"best crm software"},"domain":{"type":"string","example":"pipedrive.com"},"mode":{"type":"string","enum":["exact","subdomains"]},"position":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true,"example":2,"description":"Best position the domain holds — the first entry of `matches`, surfaced as the headline answer. `null` means the domain is not in the measured result set."},"matches":{"type":"array","items":{"$ref":"#/components/schemas/GoogleRankMatch"},"description":"Every appearance of the domain, in rank order."},"results_scanned":{"type":"integer","example":187,"description":"How many results the verdict is based on — the full measured result set for the query, typically 100–250. A null position means \"not in these\", never more."}},"required":["query","domain","mode","position","matches","results_scanned"]}},"required":["meta","data"]}}}},"default":{"description":"Error response (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/knowledge-panel":{"get":{"operationId":"google.knowledge-panel","summary":"Get the knowledge panel for a query","description":"Returns structured entity data — name, type, summary, image and attributes — for queries that resolve to a known entity. Returns `404 NOT_FOUND` when the query has no panel. Sharing a warm result set with `/web-search`, so a lookup after a search is served from cache.","tags":["Google API"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"example":"anthropic","description":"The entity or topic to look up."},"required":true,"description":"The entity or topic to look up.","name":"query","in":"query"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/GoogleKnowledgePanel"}},"required":["meta","data"]}}}},"default":{"description":"Error response (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/autocomplete":{"get":{"operationId":"google.autocomplete","summary":"Get query suggestions","description":"Returns the suggestions Google offers for a partial query, in rank order, plus a spelling correction when the input looks misspelled. Each suggestion is provided as plain text and with highlight markup, and carries entity details when the suggestion maps to one. Useful for keyword research and search-as-you-type experiences.","tags":["Google API"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":256,"example":"best crm","description":"Partial query to complete."},"required":true,"description":"Partial query to complete.","name":"query","in":"query"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/GoogleAutocompleteResult"}},"required":["meta","data"]}}}},"default":{"description":"Error response (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/dictionary":{"get":{"operationId":"google.dictionary","summary":"Look up a word","description":"Returns the dictionary entry for an English word: syllabification, phonetic pronunciations with audio, etymology, and one entry per part of speech with its inflections, numbered senses, synonyms and usage examples. Returns `404 NOT_FOUND` when the word has no entry. Definitions are stable, so responses are cached for 24 hours.","tags":["Google API"],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":64,"example":"serendipity","description":"The word or phrase to define."},"required":true,"description":"The word or phrase to define.","name":"word","in":"query"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/DictionaryResult"}},"required":["meta","data"]}}}},"default":{"description":"Error response (RFC 9457 problem+json)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}}}