{ "info": { "title": "SerpData", "version": "1.0.0", "description": "Google search results as JSON." }, "servers": [ { "url": "https://api.serpdata.dev" } ], "security": [ { "apiKey": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key" } } }, "openapi": "3.1.1", "paths": { "/google/search/web": { "get": { "operationId": "search", "summary": "Google web results. Add mode=rich for the full page.", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The search query. OR can appear at most once; a query with two or more is rejected." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "mode", "in": "query", "required": false, "schema": { "enum": [ "simple", "rich" ], "type": "string", "default": "simple", "description": "simple (default) returns organic results only. rich also returns People Also Ask, top stories, the local pack, shopping, images, videos and related searches. It does not return a knowledge panel." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "gl", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-zA-Z]{2}$", "description": "Two-letter country code, such as gb. Required when uule is set; choose the country containing that location." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "uule", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 2048, "pattern": "^w\\+CAIQIC[A-Za-z0-9+/_-]+={0,2}$", "description": "Canonical-name Google UULE starting with w+. Biases results toward a city in either mode. Requires matching gl; coordinate-form a+ values are not supported." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "start", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "number" } ], "description": "Offset into Google's results, a multiple of 10 up to 90. Each page holds ten results." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "hl", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,3})?$", "description": "Google's interface language, such as en, de or pt-BR. It sets the page's labels and can change which results rank." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "lr", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^lang_[a-zA-Z]{2}(-[a-zA-Z]{2})?(\\|lang_[a-zA-Z]{2}(-[a-zA-Z]{2})?){0,9}$", "description": "Only return pages written in these languages, such as lang_de. Join up to ten with |, as in lang_de|lang_fr." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "tbs", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^(qdr:[hdwmy][0-9]{0,4}|cdr:1,cd_min:[0-9]{1,2}\\/[0-9]{1,2}\\/[0-9]{4}(,cd_max:[0-9]{1,2}\\/[0-9]{1,2}\\/[0-9]{4})?|cdr:1,cd_max:[0-9]{1,2}\\/[0-9]{1,2}\\/[0-9]{4})$", "description": "Date filter. qdr:d is the past day: use h, d, w, m or y for hour, day, week, month or year, with an optional count, as in qdr:m6. For a custom range, send cdr:1,cd_min:1/31/2026,cd_max:3/1/2026 (month/day/year); either end may be left out." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "filter", "in": "query", "required": false, "schema": { "enum": [ "0", "1" ], "type": "string", "description": "0 also returns the similar results Google normally hides. 1, the default, hides them." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cr", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^country[a-zA-Z]{2}(\\|country[a-zA-Z]{2}){0,9}$", "description": "Only return pages from these countries, such as countryDE. Join up to ten with |, as in countryDE|countryAT. Unlike gl, which localizes results, this excludes pages from other countries." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "safe", "in": "query", "required": false, "schema": { "enum": [ "active", "off" ], "type": "string", "description": "active turns on SafeSearch, which hides explicit results. off turns it off." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "nfpr", "in": "query", "required": false, "schema": { "enum": [ "0", "1" ], "type": "string", "description": "1 searches for the query exactly as typed, instead of Google's spelling correction." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "cookie_policy", "in": "query", "required": false, "schema": { "enum": [ "oldest", "random", "newest", "rested" ], "type": "string", "description": "Internal tuning knob: which eligible Google cookie to lease for this search." }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "searchParameters": { "type": "object", "properties": { "q": { "type": "string" }, "type": { "type": "string" }, "engine": { "type": "string" }, "gl": { "type": "string" }, "uule": { "type": "string" }, "hl": { "type": "string" }, "lr": { "type": "string" }, "tbs": { "type": "string" }, "filter": { "type": "string" }, "cr": { "type": "string" }, "safe": { "type": "string" }, "nfpr": { "type": "string" } }, "required": [ "q", "type", "engine" ], "additionalProperties": {} }, "organic": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "link": { "type": "string" }, "snippet": { "type": "string", "default": "" }, "subtitle": { "type": "string" }, "ratingSuffix": { "type": "string" }, "position": { "type": "number" }, "rating": { "type": "number", "minimum": 0, "maximum": 5 }, "reviewCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "duration": { "type": "number", "minimum": 0 }, "date": { "type": "string" }, "source": { "type": "string" }, "channel": { "type": "string" }, "imageUrl": { "type": "string" }, "thumbnail": { "type": "string" }, "sitelinks": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "href": { "type": "string" }, "style": { "enum": [ "chip", "more", "expanded" ], "type": "string" }, "description": { "type": "string" } }, "required": [ "title", "href" ], "additionalProperties": {} } } }, "required": [ "title", "link", "position" ], "additionalProperties": {} } }, "latencyMs": { "type": "number", "minimum": 0, "description": "Measured API handler duration; excludes cold initialization and client transport." }, "peopleAlsoAsk": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" } }, "required": [ "question" ], "additionalProperties": {} } }, "relatedSearches": { "type": "array", "items": { "type": "string" } }, "topStories": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "link": { "type": "string" }, "source": { "type": "string", "default": "" }, "date": { "type": "string", "default": "" }, "thumbnail": { "type": "string", "default": "" } }, "required": [ "title", "link" ], "additionalProperties": {} } }, "places": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "rating": { "type": "number", "minimum": 0, "maximum": 5 }, "reviewCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "snippet": { "type": "string", "default": "" }, "thumbnail": { "type": "string", "default": "" }, "links": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "href": { "type": "string" } }, "required": [ "label", "href" ] }, "default": [] } }, "required": [ "title" ], "additionalProperties": {} } }, "videos": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "link": { "type": "string" }, "duration": { "type": "number", "minimum": 0 }, "ariaLabel": { "type": "string", "default": "" }, "thumbnail": { "type": "string", "default": "" } }, "required": [ "title", "link" ], "additionalProperties": {} } }, "shopping": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "price": { "type": "string", "default": "" }, "source": { "type": "string", "default": "" }, "rating": { "type": "number", "minimum": 0, "maximum": 5 }, "reviewCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "link": { "type": "string", "default": "" }, "sponsored": { "type": "boolean", "default": false }, "thumbnail": { "type": "string", "default": "" } }, "required": [ "title" ], "additionalProperties": {} } }, "components": { "type": "object", "properties": { "blockOrder": { "type": "array", "items": { "type": "object", "properties": { "type": { "enum": [ "localPack", "topStories", "shopping", "images", "inlineVideo", "shortVideos", "videos", "peopleAlsoAsk", "organicResult", "relatedSearches" ], "type": "string" }, "index": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } } }, "aiOverview": { "anyOf": [ { "type": "object", "properties": { "content": { "type": "string" } } }, { "type": "null" } ] }, "peopleAlsoAsk": { "type": "array", "items": { "type": "string" } }, "localPack": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "rating": { "type": "number", "minimum": 0, "maximum": 5 }, "reviewCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "text": { "type": "string" }, "price": { "type": "string" }, "category": { "type": "string" }, "details": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "highlight": { "type": "object", "properties": { "text": { "type": "string" }, "color": { "type": "string" } } }, "icon": { "type": "string" }, "reviewIcon": { "type": "boolean" } } } }, "thumbnail": { "type": "string" }, "links": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "href": { "type": "string" } } } } } } }, "localMap": { "anyOf": [ { "type": "object", "properties": { "src": { "type": "string" }, "alt": { "type": "string" } } }, { "type": "null" } ] }, "localMorePlaces": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string" }, "href": { "type": "string" } } }, { "type": "null" } ], "default": null }, "topStoriesMore": { "type": "object", "properties": { "label": { "type": "string" }, "href": { "type": "string" } } }, "newsSections": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "subtitle": { "type": "string" }, "customizeLabel": { "type": "string" }, "indices": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "visibleCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "more": { "type": "object", "properties": { "label": { "type": "string" }, "href": { "type": "string" } } } } } }, "videosMore": { "type": "object", "properties": { "label": { "type": "string" }, "href": { "type": "string" } } }, "shortVideosMore": { "type": "object", "properties": { "label": { "type": "string" }, "href": { "type": "string" } } }, "shoppingTitle": { "type": "string" }, "shoppingSections": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "headingOverflow": { "type": "boolean" }, "indices": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "layout": { "const": "grid" } } } }, "relatedSearches": { "type": "array", "items": { "type": "string" } }, "images": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "source": { "type": "string" }, "link": { "type": "string" }, "thumbnail": { "type": "string" } } } }, "inlineVideo": { "anyOf": [ { "type": "object", "properties": { "previewUrl": { "type": "string" }, "keyMoments": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "time": { "type": "string" }, "link": { "type": "string" } } } }, "title": { "type": "string" }, "source": { "type": "string" }, "meta": { "type": "string" }, "snippet": { "type": "string" }, "duration": { "type": "number", "minimum": 0 }, "link": { "type": "string" }, "thumbnail": { "type": "string" } } }, { "type": "null" } ] }, "shortVideos": { "type": "array", "items": { "type": "object", "properties": { "previewUrl": { "type": "string" }, "title": { "type": "string" }, "source": { "type": "string" }, "duration": { "type": "number", "minimum": 0 }, "link": { "type": "string" }, "thumbnail": { "type": "string" } } } }, "topStories": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "source": { "type": "string" }, "age": { "type": "string" }, "layout": { "enum": [ "compact", "large" ], "type": "string" }, "groupTitle": { "type": "string" }, "isLive": { "type": "boolean" }, "link": { "type": "string" }, "thumbnail": { "type": "string" } } } }, "videos": { "type": "array", "items": { "type": "object", "properties": { "summary": { "type": "string" }, "keyMoments": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "time": { "type": "string" }, "link": { "type": "string" } } } }, "previewUrl": { "type": "string" }, "title": { "type": "string" }, "ariaLabel": { "type": "string" }, "isLive": { "type": "boolean" }, "source": { "type": "string", "default": "" }, "date": { "type": "string", "default": "" }, "duration": { "type": "number", "minimum": 0 }, "link": { "type": "string" }, "thumbnail": { "type": "string" } } } }, "shopping": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "price": { "type": "string" }, "merchant": { "type": "string" }, "merchantIcon": { "type": "string" }, "merchantMore": { "type": "string" }, "originalPrice": { "type": "string" }, "usualPrice": { "type": "string" }, "priceBadge": { "type": "string" }, "unitPrice": { "type": "string" }, "delivery": { "type": "string" }, "rating": { "type": "number", "minimum": 0, "maximum": 5 }, "reviewCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "link": { "type": "string" }, "sponsored": { "type": "boolean" }, "text": { "type": "string" }, "thumbnail": { "type": "string" } } } } } }, "credits": { "type": "number" }, "creditsRemaining": { "type": "number" } }, "required": [ "searchParameters", "organic", "credits", "creditsRemaining" ], "additionalProperties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "BAD_REQUEST" }, "status": { "const": 400 }, "message": { "type": "string", "default": "A parameter is missing or the wrong shape. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "The key is missing, unknown, or revoked. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INSUFFICIENT_CREDITS" }, "status": { "const": 402 }, "message": { "type": "string", "default": "Your balance is lower than the request costs. Top up on the billing page." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such endpoint, or no place with that cid. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INTERNAL_SERVER_ERROR" }, "status": { "const": 500 }, "message": { "type": "string", "default": "Something failed on our side. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "502": { "description": "502", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UPSTREAM_ERROR" }, "status": { "const": 502 }, "message": { "type": "string", "default": "The source site refused the request. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "SERVICE_UNAVAILABLE" }, "status": { "const": 503 }, "message": { "type": "string", "default": "Capacity is temporarily exhausted. The credit is returned. Honor Retry-After." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "GATEWAY_TIMEOUT" }, "status": { "const": 504 }, "message": { "type": "string", "default": "The request outlived its deadline. The credit is returned and it can be retried." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/google/search/videos": { "post": { "operationId": "videos", "summary": "Google Videos results.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "minLength": 1, "description": "The search query. OR can appear at most once; a query with two or more is rejected." } }, "required": [ "q" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "searchParameters": { "type": "object", "properties": { "q": { "type": "string" }, "type": { "type": "string" }, "engine": { "type": "string" } }, "required": [ "q", "type", "engine" ], "additionalProperties": {} }, "videos": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "link": { "type": "string" }, "snippet": { "type": "string" }, "imageUrl": { "type": "string" }, "duration": { "type": "string" }, "source": { "type": "string" }, "channel": { "type": "string" }, "date": { "type": "string" }, "position": { "type": "number" } }, "required": [ "title", "link", "snippet", "imageUrl", "duration", "source", "channel", "date", "position" ], "additionalProperties": {} } }, "latencyMs": { "type": "number", "minimum": 0, "description": "Measured API handler duration; excludes cold initialization and client transport." }, "credits": { "type": "number" }, "creditsRemaining": { "type": "number" } }, "required": [ "searchParameters", "videos", "credits", "creditsRemaining" ], "additionalProperties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "BAD_REQUEST" }, "status": { "const": 400 }, "message": { "type": "string", "default": "A parameter is missing or the wrong shape. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "The key is missing, unknown, or revoked. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INSUFFICIENT_CREDITS" }, "status": { "const": 402 }, "message": { "type": "string", "default": "Your balance is lower than the request costs. Top up on the billing page." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such endpoint, or no place with that cid. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INTERNAL_SERVER_ERROR" }, "status": { "const": 500 }, "message": { "type": "string", "default": "Something failed on our side. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "502": { "description": "502", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UPSTREAM_ERROR" }, "status": { "const": 502 }, "message": { "type": "string", "default": "The source site refused the request. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "SERVICE_UNAVAILABLE" }, "status": { "const": 503 }, "message": { "type": "string", "default": "Capacity is temporarily exhausted. The credit is returned. Honor Retry-After." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "GATEWAY_TIMEOUT" }, "status": { "const": 504 }, "message": { "type": "string", "default": "The request outlived its deadline. The credit is returned and it can be retried." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/google/search/images": { "post": { "operationId": "images", "summary": "Google Images results.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "minLength": 1, "description": "The search query. OR can appear at most once; a query with two or more is rejected." } }, "required": [ "q" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "searchParameters": { "type": "object", "properties": { "q": { "type": "string" }, "type": { "type": "string" }, "engine": { "type": "string" } }, "required": [ "q", "type", "engine" ], "additionalProperties": {} }, "images": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "link": { "type": "string" }, "imageUrl": { "type": "string" }, "thumbnailUrl": { "type": "string", "default": "" }, "source": { "type": "string", "default": "" }, "imageWidth": { "type": "number", "default": 0 }, "imageHeight": { "type": "number", "default": 0 }, "thumbnailWidth": { "type": "number", "default": 0 }, "thumbnailHeight": { "type": "number", "default": 0 }, "position": { "type": "number" } }, "required": [ "title", "link", "imageUrl", "position" ], "additionalProperties": {} } }, "latencyMs": { "type": "number", "minimum": 0, "description": "Measured API handler duration; excludes cold initialization and client transport." }, "credits": { "type": "number" }, "creditsRemaining": { "type": "number" } }, "required": [ "searchParameters", "images", "credits", "creditsRemaining" ], "additionalProperties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "BAD_REQUEST" }, "status": { "const": 400 }, "message": { "type": "string", "default": "A parameter is missing or the wrong shape. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "The key is missing, unknown, or revoked. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INSUFFICIENT_CREDITS" }, "status": { "const": 402 }, "message": { "type": "string", "default": "Your balance is lower than the request costs. Top up on the billing page." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such endpoint, or no place with that cid. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INTERNAL_SERVER_ERROR" }, "status": { "const": 500 }, "message": { "type": "string", "default": "Something failed on our side. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "502": { "description": "502", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UPSTREAM_ERROR" }, "status": { "const": 502 }, "message": { "type": "string", "default": "The source site refused the request. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "SERVICE_UNAVAILABLE" }, "status": { "const": 503 }, "message": { "type": "string", "default": "Capacity is temporarily exhausted. The credit is returned. Honor Retry-After." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "GATEWAY_TIMEOUT" }, "status": { "const": 504 }, "message": { "type": "string", "default": "The request outlived its deadline. The credit is returned and it can be retried." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/google/search/news": { "post": { "operationId": "news", "summary": "Google News results.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "minLength": 1, "description": "The search query. OR can appear at most once; a query with two or more is rejected." } }, "required": [ "q" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "searchParameters": { "type": "object", "properties": { "q": { "type": "string" }, "type": { "type": "string" }, "engine": { "type": "string" } }, "required": [ "q", "type", "engine" ], "additionalProperties": {} }, "news": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "link": { "type": "string" }, "snippet": { "type": "string", "default": "" }, "date": { "type": "string", "default": "" }, "source": { "type": "string", "default": "" }, "imageUrl": { "type": "string", "default": "" }, "position": { "type": "number" } }, "required": [ "title", "link", "position" ], "additionalProperties": {} } }, "latencyMs": { "type": "number", "minimum": 0, "description": "Measured API handler duration; excludes cold initialization and client transport." }, "credits": { "type": "number" }, "creditsRemaining": { "type": "number" } }, "required": [ "searchParameters", "news", "credits", "creditsRemaining" ], "additionalProperties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "BAD_REQUEST" }, "status": { "const": 400 }, "message": { "type": "string", "default": "A parameter is missing or the wrong shape. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "The key is missing, unknown, or revoked. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INSUFFICIENT_CREDITS" }, "status": { "const": 402 }, "message": { "type": "string", "default": "Your balance is lower than the request costs. Top up on the billing page." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such endpoint, or no place with that cid. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INTERNAL_SERVER_ERROR" }, "status": { "const": 500 }, "message": { "type": "string", "default": "Something failed on our side. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "502": { "description": "502", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UPSTREAM_ERROR" }, "status": { "const": 502 }, "message": { "type": "string", "default": "The source site refused the request. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "SERVICE_UNAVAILABLE" }, "status": { "const": 503 }, "message": { "type": "string", "default": "Capacity is temporarily exhausted. The credit is returned. Honor Retry-After." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "GATEWAY_TIMEOUT" }, "status": { "const": 504 }, "message": { "type": "string", "default": "The request outlived its deadline. The credit is returned and it can be retried." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/google/search/shopping": { "post": { "operationId": "shopping", "summary": "Google Shopping results.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "minLength": 1, "description": "The search query. OR can appear at most once; a query with two or more is rejected." } }, "required": [ "q" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "searchParameters": { "type": "object", "properties": { "q": { "type": "string" }, "type": { "type": "string" }, "engine": { "type": "string" } }, "required": [ "q", "type", "engine" ], "additionalProperties": {} }, "shopping": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "source": { "type": "string", "default": "" }, "link": { "type": "string" }, "price": { "type": "string", "default": "" }, "rating": { "type": "number", "default": 0 }, "ratingCount": { "type": "number", "default": 0 }, "productId": { "type": "string", "default": "" }, "position": { "type": "number" } }, "required": [ "title", "link", "position" ], "additionalProperties": {} } }, "latencyMs": { "type": "number", "minimum": 0, "description": "Measured API handler duration; excludes cold initialization and client transport." }, "credits": { "type": "number" }, "creditsRemaining": { "type": "number" } }, "required": [ "searchParameters", "shopping", "credits", "creditsRemaining" ], "additionalProperties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "BAD_REQUEST" }, "status": { "const": 400 }, "message": { "type": "string", "default": "A parameter is missing or the wrong shape. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "The key is missing, unknown, or revoked. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INSUFFICIENT_CREDITS" }, "status": { "const": 402 }, "message": { "type": "string", "default": "Your balance is lower than the request costs. Top up on the billing page." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such endpoint, or no place with that cid. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INTERNAL_SERVER_ERROR" }, "status": { "const": 500 }, "message": { "type": "string", "default": "Something failed on our side. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "502": { "description": "502", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UPSTREAM_ERROR" }, "status": { "const": 502 }, "message": { "type": "string", "default": "The source site refused the request. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "SERVICE_UNAVAILABLE" }, "status": { "const": 503 }, "message": { "type": "string", "default": "Capacity is temporarily exhausted. The credit is returned. Honor Retry-After." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "GATEWAY_TIMEOUT" }, "status": { "const": 504 }, "message": { "type": "string", "default": "The request outlived its deadline. The credit is returned and it can be retried." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/google/maps/place": { "get": { "operationId": "place", "summary": "One business by its Google CID, place ID or feature ID: address, rating, hours, phone, category.", "parameters": [ { "name": "cid", "in": "query", "schema": { "type": "string", "minLength": 1, "description": "Google customer id, returned on every /places and /map result. Send one of cid, placeId or fid." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "placeId", "in": "query", "schema": { "type": "string", "minLength": 1, "description": "Google place ID, such as ChIJwc3zxvNdeUgR7U9zwP-ov3A, the kind the Google Places API returns. Use instead of cid." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "fid", "in": "query", "schema": { "type": "string", "minLength": 1, "description": "Google feature ID, such as 0x48795df3c6f3cdc1:0x70bfa8ffc0734fed, returned as fid on every /map result. Use instead of cid." }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "cid": { "type": "string" }, "fid": { "type": "string" }, "businessStatus": { "enum": [ "OPEN", "CLOSED" ], "type": "string" }, "postingRestricted": { "anyOf": [ { "const": true }, { "type": "null" } ] }, "address": { "type": "string" }, "sublocality": { "type": "string" }, "route": { "type": "string" }, "locality": { "type": "string" }, "postalCode": { "type": "string" }, "administrativeAreaLevel1": { "type": "string" }, "country": { "type": "string" }, "googlePlaceId": { "type": "string" }, "kgmid": { "type": "string" }, "website": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "aboutText": { "type": "string" }, "description": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "rating": { "type": "number" }, "ratingCount": { "type": "number" }, "phone": { "type": "string" }, "phoneE164": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "openingHours": { "anyOf": [ { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "type": "null" } ], "description": "Open intervals as flat [start, end, start, end, ...] pairs of minutes since Monday 00:00, for the days Google returned. Null when it returned no hours." }, "amenities": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "reviewsDistribution": { "type": "object", "properties": { "oneStar": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "twoStar": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "threeStar": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "fourStar": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "fiveStar": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "oneStar", "twoStar", "threeStar", "fourStar", "fiveStar" ], "additionalProperties": {}, "description": "How many reviews gave each star rating. Absent when Google did not send the breakdown." }, "reviewsTags": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "count": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "title" ], "additionalProperties": {} }, "description": "The topics Google shows above the reviews, with how many reviews mention each. Absent when Google showed none." }, "latencyMs": { "type": "number", "minimum": 0, "description": "Measured API handler duration; excludes cold initialization and client transport." }, "creditsRemaining": { "type": "number" } }, "required": [ "name", "cid", "fid", "businessStatus", "postingRestricted", "openingHours", "creditsRemaining" ], "additionalProperties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "BAD_REQUEST" }, "status": { "const": 400 }, "message": { "type": "string", "default": "A parameter is missing or the wrong shape. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "The key is missing, unknown, or revoked. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INSUFFICIENT_CREDITS" }, "status": { "const": 402 }, "message": { "type": "string", "default": "Your balance is lower than the request costs. Top up on the billing page." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such endpoint, or no place with that cid. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INTERNAL_SERVER_ERROR" }, "status": { "const": 500 }, "message": { "type": "string", "default": "Something failed on our side. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "502": { "description": "502", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UPSTREAM_ERROR" }, "status": { "const": 502 }, "message": { "type": "string", "default": "The source site refused the request. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "SERVICE_UNAVAILABLE" }, "status": { "const": 503 }, "message": { "type": "string", "default": "Capacity is temporarily exhausted. The credit is returned. Honor Retry-After." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "GATEWAY_TIMEOUT" }, "status": { "const": 504 }, "message": { "type": "string", "default": "The request outlived its deadline. The credit is returned and it can be retried." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/google/maps/place/reviews": { "get": { "operationId": "reviews", "summary": "Reviews for one business, page by page.", "parameters": [ { "name": "cid", "in": "query", "schema": { "type": "string", "minLength": 1, "description": "Google customer id, returned on every /places and /map result. Send one of cid, placeId or fid." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "placeId", "in": "query", "schema": { "type": "string", "minLength": 1, "description": "Google place ID, such as ChIJwc3zxvNdeUgR7U9zwP-ov3A, the kind the Google Places API returns. Use instead of cid." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "fid", "in": "query", "schema": { "type": "string", "minLength": 1, "description": "Google feature ID, such as 0x48795df3c6f3cdc1:0x70bfa8ffc0734fed, returned as fid on every /map result. Use instead of cid." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "pageToken", "in": "query", "schema": { "type": "string", "description": "The nextPageToken from a previous response." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "sort", "in": "query", "schema": { "enum": [ "relevant", "newest", "highest", "lowest" ], "type": "string", "default": "relevant", "description": "Review order: relevant (default, Google's own order), newest first, highest rating first, or lowest rating first. Keep the same sort when passing a pageToken." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "hl", "in": "query", "schema": { "type": "string", "pattern": "^[a-zA-Z]{2}$", "description": "Two-letter language code, such as de. Reviews in other languages come back with textTranslated in this language. Defaults to en." }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "cid": { "type": "string" }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "reviewId": { "type": "string" }, "authorName": { "type": "string" }, "authorId": { "type": "string" }, "rating": { "type": "number" }, "publishedAt": { "type": "string" }, "photos": { "type": "array", "items": { "type": "string" } }, "authorPhotoUrl": { "type": "string" }, "text": { "type": "string" }, "relativeTime": { "type": "string" }, "originalLanguage": { "type": "string", "description": "Language code of the review text, such as ja." }, "textTranslated": { "type": "string", "description": "The review translated into the requested hl, when it was written in another language." }, "translatedLanguage": { "type": "string", "description": "Language code of textTranslated." }, "isLocalGuide": { "type": "boolean", "description": "Whether the reviewer is a Google Local Guide." }, "reviewerReviewCount": { "type": "number", "description": "How many reviews the reviewer has written." }, "reviewerPhotoCount": { "type": "number", "description": "How many photos the reviewer has posted." }, "reviewUrl": { "type": "string", "description": "Link to the review on Google Maps." }, "ownerReply": { "type": "object", "properties": { "text": { "type": "string" }, "relativeTime": { "type": "string", "description": "When the owner replied, such as a year ago." }, "textTranslated": { "type": "string", "description": "The reply translated into the requested hl." } }, "required": [ "text" ], "description": "The business owner's reply, when there is one." }, "aspectRatings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" }, "description": "Star ratings the reviewer gave for parts of the visit, such as Food or Service." } }, "required": [ "reviewId", "authorName", "authorId", "rating", "publishedAt", "photos" ], "additionalProperties": {} } }, "nextPageToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latencyMs": { "type": "number", "minimum": 0, "description": "Measured API handler duration; excludes cold initialization and client transport." }, "creditsRemaining": { "type": "number" } }, "required": [ "cid", "reviews", "nextPageToken", "creditsRemaining" ], "additionalProperties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "BAD_REQUEST" }, "status": { "const": 400 }, "message": { "type": "string", "default": "A parameter is missing or the wrong shape. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "The key is missing, unknown, or revoked. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INSUFFICIENT_CREDITS" }, "status": { "const": 402 }, "message": { "type": "string", "default": "Your balance is lower than the request costs. Top up on the billing page." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such endpoint, or no place with that cid. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INTERNAL_SERVER_ERROR" }, "status": { "const": 500 }, "message": { "type": "string", "default": "Something failed on our side. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "502": { "description": "502", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UPSTREAM_ERROR" }, "status": { "const": 502 }, "message": { "type": "string", "default": "The source site refused the request. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "SERVICE_UNAVAILABLE" }, "status": { "const": 503 }, "message": { "type": "string", "default": "Capacity is temporarily exhausted. The credit is returned. Honor Retry-After." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "GATEWAY_TIMEOUT" }, "status": { "const": 504 }, "message": { "type": "string", "default": "The request outlived its deadline. The credit is returned and it can be retried." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/google/maps/place/photos": { "get": { "operationId": "photos", "summary": "Photos for one business.", "parameters": [ { "name": "cid", "in": "query", "schema": { "type": "string", "minLength": 1, "description": "Google customer id, returned on every /places and /map result. Send one of cid, placeId or fid." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "placeId", "in": "query", "schema": { "type": "string", "minLength": 1, "description": "Google place ID, such as ChIJwc3zxvNdeUgR7U9zwP-ov3A, the kind the Google Places API returns. Use instead of cid." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "fid", "in": "query", "schema": { "type": "string", "minLength": 1, "description": "Google feature ID, such as 0x48795df3c6f3cdc1:0x70bfa8ffc0734fed, returned as fid on every /map result. Use instead of cid." }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "cid": { "type": "string" }, "photos": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "hash": { "type": "string" }, "dimensions": { "anyOf": [ { "type": "array", "items": { "type": "number" } }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "categories": { "type": "array", "items": { "type": "number" } } }, "required": [ "url", "hash", "dimensions", "source", "categories" ], "additionalProperties": {} } }, "totalCount": { "type": "number" }, "found": { "type": "boolean" }, "latencyMs": { "type": "number", "minimum": 0, "description": "Measured API handler duration; excludes cold initialization and client transport." }, "creditsRemaining": { "type": "number" } }, "required": [ "cid", "photos", "totalCount", "found", "creditsRemaining" ], "additionalProperties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "BAD_REQUEST" }, "status": { "const": 400 }, "message": { "type": "string", "default": "A parameter is missing or the wrong shape. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "The key is missing, unknown, or revoked. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INSUFFICIENT_CREDITS" }, "status": { "const": 402 }, "message": { "type": "string", "default": "Your balance is lower than the request costs. Top up on the billing page." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such endpoint, or no place with that cid. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INTERNAL_SERVER_ERROR" }, "status": { "const": 500 }, "message": { "type": "string", "default": "Something failed on our side. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "502": { "description": "502", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UPSTREAM_ERROR" }, "status": { "const": 502 }, "message": { "type": "string", "default": "The source site refused the request. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "SERVICE_UNAVAILABLE" }, "status": { "const": 503 }, "message": { "type": "string", "default": "Capacity is temporarily exhausted. The credit is returned. Honor Retry-After." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "GATEWAY_TIMEOUT" }, "status": { "const": 504 }, "message": { "type": "string", "default": "The request outlived its deadline. The credit is returned and it can be retried." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/google/maps/area/places": { "get": { "operationId": "map", "summary": "Businesses inside a map viewport.", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "description": "The search query." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "lat", "in": "query", "required": true, "schema": { "type": "number", "description": "Latitude of the viewport's center." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "lng", "in": "query", "required": true, "schema": { "type": "number", "description": "Longitude of the viewport's center." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "zoom", "in": "query", "required": false, "schema": { "type": "number", "description": "Google Maps zoom level." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "number", "description": "Results to skip." }, "allowEmptyValue": true, "allowReserved": true }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "number", "description": "Results to return." }, "allowEmptyValue": true, "allowReserved": true } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "places": { "type": "array", "items": { "type": "object", "properties": { "cid": { "type": "string" }, "fid": { "type": "string" }, "name": { "type": "string" }, "rating": { "type": "number" }, "ratingCount": { "type": "number" }, "lat": { "type": "number" }, "lng": { "type": "number" }, "address": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "website": { "type": "string" }, "phone": { "type": "string" }, "neighborhood": { "type": "string" }, "placeId": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "primaryPhoto": { "type": "string" }, "photos": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "url" ], "additionalProperties": {} }, "description": "Full-size photos from the place's result card on Google Maps, without videos. Left out when Google sends none." } }, "required": [ "cid", "fid", "name" ], "additionalProperties": {} } }, "hasMore": { "type": "boolean" }, "latencyMs": { "type": "number", "minimum": 0, "description": "Measured API handler duration; excludes cold initialization and client transport." }, "creditsRemaining": { "type": "number" } }, "required": [ "places", "hasMore", "creditsRemaining" ], "additionalProperties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "BAD_REQUEST" }, "status": { "const": 400 }, "message": { "type": "string", "default": "A parameter is missing or the wrong shape. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "The key is missing, unknown, or revoked. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INSUFFICIENT_CREDITS" }, "status": { "const": 402 }, "message": { "type": "string", "default": "Your balance is lower than the request costs. Top up on the billing page." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such endpoint, or no place with that cid. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INTERNAL_SERVER_ERROR" }, "status": { "const": 500 }, "message": { "type": "string", "default": "Something failed on our side. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "502": { "description": "502", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UPSTREAM_ERROR" }, "status": { "const": 502 }, "message": { "type": "string", "default": "The source site refused the request. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "SERVICE_UNAVAILABLE" }, "status": { "const": 503 }, "message": { "type": "string", "default": "Capacity is temporarily exhausted. The credit is returned. Honor Retry-After." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "GATEWAY_TIMEOUT" }, "status": { "const": 504 }, "message": { "type": "string", "default": "The request outlived its deadline. The credit is returned and it can be retried." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/google/maps/search/places": { "post": { "operationId": "places", "summary": "Local business results for a query.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "minLength": 1, "description": "The search query." }, "lat": { "type": "number", "description": "Latitude of the viewport's center. Omit lat and lng to search nationally." }, "lng": { "type": "number", "description": "Longitude of the viewport's center." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Results to return, 1 to 200. Defaults to 20." } }, "required": [ "q" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "searchParameters": { "type": "object", "properties": { "q": { "type": "string" }, "type": { "type": "string" }, "engine": { "type": "string" } }, "required": [ "q", "type", "engine" ], "additionalProperties": {} }, "places": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "number" }, "title": { "type": "string" }, "address": { "type": "string", "default": "" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "rating": { "type": "number" }, "ratingCount": { "type": "number" }, "category": { "type": "string", "default": "" }, "phoneNumber": { "type": "string", "default": "" }, "website": { "type": "string", "default": "" }, "cid": { "type": "string" } }, "required": [ "position", "title", "cid" ], "additionalProperties": {} } }, "latencyMs": { "type": "number", "minimum": 0, "description": "Measured API handler duration; excludes cold initialization and client transport." }, "credits": { "type": "number" }, "creditsRemaining": { "type": "number" } }, "required": [ "searchParameters", "places", "credits", "creditsRemaining" ], "additionalProperties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "BAD_REQUEST" }, "status": { "const": 400 }, "message": { "type": "string", "default": "A parameter is missing or the wrong shape. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "The key is missing, unknown, or revoked. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INSUFFICIENT_CREDITS" }, "status": { "const": 402 }, "message": { "type": "string", "default": "Your balance is lower than the request costs. Top up on the billing page." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such endpoint, or no place with that cid. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INTERNAL_SERVER_ERROR" }, "status": { "const": 500 }, "message": { "type": "string", "default": "Something failed on our side. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "502": { "description": "502", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UPSTREAM_ERROR" }, "status": { "const": 502 }, "message": { "type": "string", "default": "The source site refused the request. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "SERVICE_UNAVAILABLE" }, "status": { "const": 503 }, "message": { "type": "string", "default": "Capacity is temporarily exhausted. The credit is returned. Honor Retry-After." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "GATEWAY_TIMEOUT" }, "status": { "const": 504 }, "message": { "type": "string", "default": "The request outlived its deadline. The credit is returned and it can be retried." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/google/trends": { "post": { "operationId": "trends", "summary": "Google Trends keyword comparisons, geographic breakdowns, related searches and Trending Now.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "mode": { "const": "keyword", "default": "keyword", "description": "Keyword analysis (default) or Trending Now country feed." }, "resolutions": { "type": "array", "maxItems": 4, "items": { "enum": [ "COUNTRY", "REGION", "CITY", "DMA" ], "type": "string" }, "default": [], "description": "Geographic breakdowns to fetch; empty uses Google’s default. DMA means US metro areas. Each resolution adds a Google request." }, "keywords": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Required in keyword mode; compare one to five keywords or topic IDs." }, "geo": { "type": "string", "pattern": "^(?:[A-Z]{2}(?:-[A-Z0-9]{1,3})?)?$", "default": "" }, "time": { "type": "string", "pattern": "^(?:now (?:1|4)-H|now [17]-d|today (?:1|3|12)-m|today 5-y|all|\\d{4}-\\d{2}-\\d{2} \\d{4}-\\d{2}-\\d{2})$", "default": "today 12-m" }, "category": { "type": "integer", "minimum": 0, "maximum": 4294967295, "default": 0 }, "property": { "enum": [ "", "images", "news", "youtube", "froogle" ], "type": "string", "default": "" }, "language": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Za-z]{2})?$", "default": "en-US" }, "timezone": { "type": "integer", "minimum": -840, "maximum": 840, "default": 0 }, "sections": { "type": "array", "minItems": 1, "maxItems": 4, "items": { "enum": [ "interestOverTime", "interestByRegion", "relatedQueries", "relatedTopics" ], "type": "string" }, "default": [ "interestOverTime", "interestByRegion", "relatedQueries", "relatedTopics" ] } }, "required": [ "keywords" ] }, { "type": "object", "properties": { "mode": { "const": "trending" }, "geo": { "type": "string", "pattern": "^[A-Z]{2}$", "default": "US", "description": "Trending Now country code." }, "language": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Za-z]{2})?$", "default": "en-US" }, "timezone": { "type": "integer", "minimum": -840, "maximum": 840, "default": 0 }, "hours": { "anyOf": [ { "const": 4 }, { "const": 24 }, { "const": 48 }, { "const": 168 } ], "default": 24 }, "categories": { "type": "array", "maxItems": 19, "items": { "anyOf": [ { "const": 1 }, { "const": 2 }, { "const": 3 }, { "const": 4 }, { "const": 5 }, { "const": 6 }, { "const": 7 }, { "const": 8 }, { "const": 9 }, { "const": 10 }, { "const": 11 }, { "const": 13 }, { "const": 14 }, { "const": 15 }, { "const": 16 }, { "const": 17 }, { "const": 18 }, { "const": 19 }, { "const": 20 } ] }, "default": [], "description": "Trending Now category IDs (different from Explore categories). Match any selected category; empty selects all." }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 } }, "required": [ "mode" ] } ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "searchParameters": { "anyOf": [ { "type": "object", "properties": { "mode": { "const": "keyword", "default": "keyword", "description": "Keyword analysis (default) or Trending Now country feed." }, "resolutions": { "type": "array", "maxItems": 4, "items": { "enum": [ "COUNTRY", "REGION", "CITY", "DMA" ], "type": "string" }, "default": [], "description": "Geographic breakdowns to fetch; empty uses Google’s default. DMA means US metro areas. Each resolution adds a Google request." }, "keywords": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": "Required in keyword mode; compare one to five keywords or topic IDs." }, "geo": { "type": "string", "pattern": "^(?:[A-Z]{2}(?:-[A-Z0-9]{1,3})?)?$", "default": "" }, "time": { "type": "string", "pattern": "^(?:now (?:1|4)-H|now [17]-d|today (?:1|3|12)-m|today 5-y|all|\\d{4}-\\d{2}-\\d{2} \\d{4}-\\d{2}-\\d{2})$", "default": "today 12-m" }, "category": { "type": "integer", "minimum": 0, "maximum": 4294967295, "default": 0 }, "property": { "enum": [ "", "images", "news", "youtube", "froogle" ], "type": "string", "default": "" }, "language": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Za-z]{2})?$", "default": "en-US" }, "timezone": { "type": "integer", "minimum": -840, "maximum": 840, "default": 0 }, "sections": { "type": "array", "minItems": 1, "maxItems": 4, "items": { "enum": [ "interestOverTime", "interestByRegion", "relatedQueries", "relatedTopics" ], "type": "string" }, "default": [ "interestOverTime", "interestByRegion", "relatedQueries", "relatedTopics" ] } }, "required": [ "keywords" ] }, { "type": "object", "properties": { "mode": { "const": "trending" }, "geo": { "type": "string", "pattern": "^[A-Z]{2}$", "default": "US", "description": "Trending Now country code." }, "language": { "type": "string", "pattern": "^[a-z]{2}(?:-[A-Za-z]{2})?$", "default": "en-US" }, "timezone": { "type": "integer", "minimum": -840, "maximum": 840, "default": 0 }, "hours": { "anyOf": [ { "const": 4 }, { "const": 24 }, { "const": 48 }, { "const": 168 } ], "default": 24 }, "categories": { "type": "array", "maxItems": 19, "items": { "anyOf": [ { "const": 1 }, { "const": 2 }, { "const": 3 }, { "const": 4 }, { "const": 5 }, { "const": 6 }, { "const": 7 }, { "const": 8 }, { "const": 9 }, { "const": 10 }, { "const": 11 }, { "const": 13 }, { "const": 14 }, { "const": 15 }, { "const": 16 }, { "const": 17 }, { "const": 18 }, { "const": 19 }, { "const": 20 } ] }, "default": [], "description": "Trending Now category IDs (different from Explore categories). Match any selected category; empty selects all." }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50 } }, "required": [ "mode" ] } ] }, "results": { "type": "array", "items": { "type": "object", "properties": { "section": { "enum": [ "interestOverTime", "interestByRegion", "relatedQueries", "relatedTopics", "trendingNow" ], "type": "string" }, "averages": { "type": "array", "items": { "type": "number" }, "description": "Google’s timeline averages, in comparison keyword order, when supplied." }, "resolution": { "anyOf": [ { "enum": [ "COUNTRY", "REGION", "CITY", "DMA" ], "type": "string" }, { "type": "null" } ] }, "widgetId": { "type": "string" }, "widgetRequest": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "status": { "enum": [ "ok", "unavailable" ], "type": "string" }, "data": { "anyOf": [ { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, { "type": "null" } ] } }, "required": [ "section", "widgetId", "status", "data" ] } }, "latencyMs": { "type": "number", "minimum": 0, "description": "Measured API handler duration; excludes cold initialization and client transport." }, "credits": { "type": "number" }, "creditsRemaining": { "type": "number" } }, "required": [ "searchParameters", "results", "credits", "creditsRemaining" ], "additionalProperties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "BAD_REQUEST" }, "status": { "const": 400 }, "message": { "type": "string", "default": "A parameter is missing or the wrong shape. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "The key is missing, unknown, or revoked. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INSUFFICIENT_CREDITS" }, "status": { "const": 402 }, "message": { "type": "string", "default": "Your balance is lower than the request costs. Top up on the billing page." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such endpoint, or no place with that cid. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INTERNAL_SERVER_ERROR" }, "status": { "const": 500 }, "message": { "type": "string", "default": "Something failed on our side. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "502": { "description": "502", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UPSTREAM_ERROR" }, "status": { "const": 502 }, "message": { "type": "string", "default": "The source site refused the request. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "SERVICE_UNAVAILABLE" }, "status": { "const": 503 }, "message": { "type": "string", "default": "Capacity is temporarily exhausted. The credit is returned. Honor Retry-After." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "GATEWAY_TIMEOUT" }, "status": { "const": 504 }, "message": { "type": "string", "default": "The request outlived its deadline. The credit is returned and it can be retried." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/google/autocomplete": { "post": { "operationId": "autocomplete", "summary": "The suggestions Google offers as a query is typed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "minLength": 1, "description": "The partial query." }, "gl": { "type": "string", "pattern": "^[a-zA-Z]{2}$", "description": "Two-letter country code, such as gb." }, "hl": { "type": "string", "pattern": "^[a-zA-Z]{2}$", "description": "Two-letter language code, such as en." } }, "required": [ "q" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "searchParameters": { "type": "object", "properties": { "q": { "type": "string" }, "type": { "type": "string" }, "engine": { "type": "string" }, "gl": { "type": "string" }, "hl": { "type": "string" } }, "required": [ "q", "type", "engine", "gl", "hl" ], "additionalProperties": {} }, "suggestions": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" } }, "required": [ "value" ], "additionalProperties": {} } }, "latencyMs": { "type": "number", "minimum": 0, "description": "Measured API handler duration; excludes cold initialization and client transport." }, "credits": { "type": "number" }, "creditsRemaining": { "type": "number" } }, "required": [ "searchParameters", "suggestions", "credits", "creditsRemaining" ], "additionalProperties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "BAD_REQUEST" }, "status": { "const": 400 }, "message": { "type": "string", "default": "A parameter is missing or the wrong shape. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "The key is missing, unknown, or revoked. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INSUFFICIENT_CREDITS" }, "status": { "const": 402 }, "message": { "type": "string", "default": "Your balance is lower than the request costs. Top up on the billing page." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such endpoint, or no place with that cid. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INTERNAL_SERVER_ERROR" }, "status": { "const": 500 }, "message": { "type": "string", "default": "Something failed on our side. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "502": { "description": "502", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UPSTREAM_ERROR" }, "status": { "const": 502 }, "message": { "type": "string", "default": "The source site refused the request. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "SERVICE_UNAVAILABLE" }, "status": { "const": 503 }, "message": { "type": "string", "default": "Capacity is temporarily exhausted. The credit is returned. Honor Retry-After." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "GATEWAY_TIMEOUT" }, "status": { "const": 504 }, "message": { "type": "string", "default": "The request outlived its deadline. The credit is returned and it can be retried." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } }, "/google/search/patents": { "post": { "operationId": "patents", "summary": "Google Patents results.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "minLength": 1, "description": "The search query." }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991, "description": "1-based page number." } }, "required": [ "q" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "searchParameters": { "type": "object", "properties": { "q": { "type": "string" }, "type": { "type": "string" }, "engine": { "type": "string" }, "page": { "type": "number" } }, "required": [ "q", "type", "engine", "page" ], "additionalProperties": {} }, "organic": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "link": { "type": "string" }, "snippet": { "type": "string" }, "priorityDate": { "type": "string" }, "filingDate": { "type": "string" }, "grantDate": { "type": "string" }, "publicationDate": { "type": "string" }, "inventor": { "type": "string" }, "assignee": { "type": "string" }, "publicationNumber": { "type": "string" }, "language": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "pdfUrl": { "type": "string" }, "figures": { "type": "array", "items": { "type": "object", "properties": { "imageUrl": { "type": "string" }, "thumbnailUrl": { "type": "string" } }, "additionalProperties": {} } } }, "required": [ "title", "link", "snippet", "figures" ], "additionalProperties": {} } }, "totalResults": { "type": "number" }, "latencyMs": { "type": "number", "minimum": 0, "description": "Measured API handler duration; excludes cold initialization and client transport." }, "credits": { "type": "number" }, "creditsRemaining": { "type": "number" } }, "required": [ "searchParameters", "organic", "totalResults", "credits", "creditsRemaining" ], "additionalProperties": {} } } } }, "400": { "description": "400", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "BAD_REQUEST" }, "status": { "const": 400 }, "message": { "type": "string", "default": "A parameter is missing or the wrong shape. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "401": { "description": "401", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UNAUTHORIZED" }, "status": { "const": 401 }, "message": { "type": "string", "default": "The key is missing, unknown, or revoked. Not charged." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "402": { "description": "402", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INSUFFICIENT_CREDITS" }, "status": { "const": 402 }, "message": { "type": "string", "default": "Your balance is lower than the request costs. Top up on the billing page." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "404": { "description": "404", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "NOT_FOUND" }, "status": { "const": 404 }, "message": { "type": "string", "default": "No such endpoint, or no place with that cid. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "INTERNAL_SERVER_ERROR" }, "status": { "const": 500 }, "message": { "type": "string", "default": "Something failed on our side. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "502": { "description": "502", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "UPSTREAM_ERROR" }, "status": { "const": 502 }, "message": { "type": "string", "default": "The source site refused the request. The credit is returned." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "503": { "description": "503", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "SERVICE_UNAVAILABLE" }, "status": { "const": 503 }, "message": { "type": "string", "default": "Capacity is temporarily exhausted. The credit is returned. Honor Retry-After." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } }, "504": { "description": "504", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "defined": { "const": true }, "code": { "const": "GATEWAY_TIMEOUT" }, "status": { "const": 504 }, "message": { "type": "string", "default": "The request outlived its deadline. The credit is returned and it can be retried." }, "data": {} }, "required": [ "defined", "code", "status", "message" ] }, { "type": "object", "properties": { "defined": { "const": false }, "code": { "type": "string" }, "status": { "type": "number" }, "message": { "type": "string" }, "data": {} }, "required": [ "defined", "code", "status", "message" ] } ] } } } } } } } } }