openapi: 3.0.0 info: title: Google Maps Autocomplete API description: | The Google Maps Autocomplete API returns the suggestions the Google Maps search box shows for partial text, biased to the map area set with ll. Query suggestions are search phrases. Place suggestions are businesses, landmarks, addresses, streets, areas or transit stations, or coordinates or a plus code typed in q. All but streets, coordinates and plus codes carry identifiers. **Cross-linking**: Pass a query suggestion's `value` as the `q` parameter of the Google Maps API to search for it. Pass a place suggestion's `data_id` or `place_id` to the Google Maps Place, Google Maps Reviews or Google Maps Photos API to fetch the place's details, reviews or photos. version: 1.0.0 servers: - url: https://www.searchapi.io/api/v1 paths: /search: get: summary: Google Maps Autocomplete security: - ApiKeyAuth: [] - ApiKeyQuery: [] parameters: - name: engine in: query required: true description: Search engine identifier schema: type: string enum: ["google_maps_autocomplete"] default: "google_maps_autocomplete" - name: q in: query required: true description: The partial text typed into the Google Maps search box (e.g. pizz), up to 30 words. schema: type: string maxLength: 100 - name: ll in: query required: false description: >- The map area the suggestions are biased to, formatted as @latitude,longitude,zoom (e.g. @40.7484,-73.9857,14z) with a zoom level, where Google Maps zooms from 3z (the whole world) to 21z (the closest view), or @latitude,longitude,meters (e.g. @40.7484,-73.9857,5886m) with the height of the visible map in meters, where Google Maps shows about 50m at the closest view and about 15000000m for the whole world. Without ll, the map centres on a major city of the gl country, New York for the default us. schema: type: string pattern: "^@[-+]?(?:90(?:[.,]0+)?|[0-8]?[0-9](?:[.,][0-9]+)?),[-+]?(?:180(?:[.,]0+)?|1[0-7][0-9](?:[.,][0-9]+)?|[0-9]{1,2}(?:[.,][0-9]+)?),[0-9]{1,8}(?:[.,][0-9]+)?[zm]$" - name: cp in: query required: false description: >- Position of the text cursor within q, counted in characters from the start, up to the length of q. Google Maps completes the word at the cursor, and the rest of q narrows the suggestions. By default, and at 0, the cursor is at the end of q. schema: type: integer minimum: 0 maximum: 100 - name: hl in: query required: false description: The interface language of the search. schema: type: string default: "en" enum: ["af", "ak", "sq", "am", "ar", "hy", "az", "eu", "be", "bem", "bn", "bh", "xx-bork", "bs", "br", "bg", "km", "ca", "chr", "ny", "zh-cn", "zh-tw", "co", "hr", "cs", "da", "nl", "xx-elmer", "en", "eo", "et", "ee", "fo", "tl", "fi", "fr", "fy", "gaa", "gl", "ka", "de", "el", "kl", "gn", "gu", "xx-hacker", "ht", "ha", "haw", "iw", "hi", "hu", "is", "ig", "id", "ia", "ga", "it", "ja", "jw", "kn", "kk", "rw", "rn", "xx-klingon", "kg", "ko", "kri", "ku", "ckb", "ky", "lo", "la", "lv", "ln", "lt", "loz", "lg", "ach", "mk", "mg", "my", "ms", "ml", "mt", "mv", "mi", "mr", "mfe", "mo", "mn", "sr-me", "ne", "pcm", "nso", "no", "nn", "oc", "or", "om", "ps", "fa", "xx-pirate", "pl", "pt", "pt-br", "pt-pt", "pa", "qu", "ro", "rm", "nyn", "ru", "gd", "sr", "sh", "st", "tn", "crs", "sn", "sd", "si", "sk", "sl", "so", "es", "es-419", "su", "sw", "sv", "tg", "ta", "tt", "te", "th", "ti", "to", "lua", "tum", "tr", "tk", "tw", "ug", "uk", "ur", "uz", "vu", "vi", "cy", "wo", "xh", "yi", "yo", "zu"] - name: gl in: query required: false description: The country of the search. schema: type: string default: "us" enum: ["af", "al", "dz", "as", "ad", "ao", "ai", "aq", "ag", "ar", "am", "aw", "au", "at", "az", "bs", "bh", "bd", "bb", "by", "be", "bz", "bj", "bm", "bt", "bo", "ba", "bw", "bv", "br", "io", "bn", "bg", "bf", "bi", "kh", "cm", "ca", "cv", "ky", "cf", "td", "cl", "cn", "cx", "cc", "co", "km", "cg", "cd", "ck", "cr", "ci", "hr", "cu", "cy", "cz", "dk", "dj", "dm", "do", "ec", "eg", "sv", "gq", "er", "ee", "et", "fk", "fo", "fj", "fi", "fr", "gf", "pf", "tf", "ga", "gm", "ge", "de", "gh", "gi", "gr", "gl", "gd", "gp", "gu", "gt", "gn", "gw", "gy", "ht", "hm", "va", "hn", "hk", "hu", "is", "in", "id", "ir", "iq", "ie", "il", "it", "jm", "jp", "jo", "kz", "ke", "ki", "kp", "kr", "kw", "kg", "la", "lv", "lb", "ls", "lr", "ly", "li", "lt", "lu", "mo", "mk", "mg", "mw", "my", "mv", "ml", "mt", "mh", "mq", "mr", "mu", "yt", "mx", "fm", "md", "mc", "mn", "ms", "ma", "mz", "mm", "na", "nr", "np", "nl", "nc", "nz", "ni", "ne", "ng", "nu", "nf", "mp", "no", "om", "pk", "pw", "ps", "pa", "pg", "py", "pe", "ph", "pn", "pl", "pt", "pr", "qa", "re", "ro", "ru", "rw", "sh", "kn", "lc", "pm", "vc", "ws", "sm", "st", "sa", "sn", "rs", "sc", "sl", "sg", "sk", "si", "sb", "so", "za", "gs", "es", "lk", "sd", "sr", "sj", "sz", "se", "ch", "sy", "tw", "tj", "tz", "th", "tl", "tg", "tk", "to", "tt", "tn", "tr", "tm", "tc", "tv", "ug", "ua", "ae", "uk", "gb", "us", "um", "uy", "uz", "vu", "ve", "vn", "vg", "vi", "wf", "eh", "ye", "zm", "zw", "gg", "je", "im", "me"] responses: '200': description: Successful response. content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication Error. The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server Error. Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- Timeout, or Google Maps could not return suggestions for this query. The body is a bare {"error": ...} rather than a search response, and the search is not billed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"' ApiKeyQuery: type: apiKey in: query name: api_key description: Pass API key as query parameter schemas: SearchResponse: type: object properties: search_metadata: $ref: '#/components/schemas/SearchMetadata' search_parameters: $ref: '#/components/schemas/SearchParameters' suggestions: type: array description: The suggestions in the order the Google Maps search box shows them. items: $ref: '#/components/schemas/Suggestion' error: type: string description: Message returned with a 200, and billed, when Google Maps has no suggestions for the query. Suggestion: type: object required: [value, type] properties: value: type: string description: The full suggestion text, a search phrase or a place name with its location line. type: type: string enum: ["query", "place"] description: Whether the suggestion is a search phrase or a specific place. thumbnail: type: string description: Image shown next to a query suggestion, such as a chain's logo. title: type: string description: Name of the place. subtitle: type: string description: Location line the Google Maps search box shows after the place name (e.g. West 55th Street, New York, NY), often shorter than the full address. gps_coordinates: $ref: '#/components/schemas/GpsCoordinates' data_id: type: string description: Google Maps data ID of the place, accepted by the Google Maps Place, Reviews and Photos APIs. place_id: type: string description: Google place ID of the place, accepted by the Google Maps Place, Reviews and Photos APIs. country_code: type: string description: Two-letter code of the country the place is in. GpsCoordinates: type: object required: [latitude, longitude] properties: latitude: type: number format: double description: Latitude of the place. longitude: type: number format: double description: Longitude of the place. SearchMetadata: type: object required: [status, created_at] properties: id: type: string description: Unique identifier for the search request status: type: string description: Status of the search request created_at: type: string format: date-time description: Timestamp when the search was created request_time_taken: type: number description: Time taken to make the request in seconds parsing_time_taken: type: number description: Time taken to parse the results in seconds total_time_taken: type: number description: Total time taken for the search in seconds request_url: type: string description: Google Maps search for q at the map area the suggestions are biased to html_url: type: string description: URL to view HTML results json_url: type: string description: URL to view JSON results SearchParameters: type: object properties: engine: type: string description: Search engine identifier q: type: string description: Text autocompleted ll: type: string description: Map area the suggestions are biased to cp: type: string description: Position of the text cursor within q hl: type: string description: Interface language of the search gl: type: string description: Country of the search ErrorResponse: type: object required: [error] properties: error: type: string description: Error message describing what went wrong