Google Maps API reference

googlemaps.suggest

Get Google Maps' suggestions for the start of a search, with the place's ID and coordinates when the suggestion is a place.

Google Maps Suggest Places API: overview and live sample

At a glance

Endpoint ID: googlemaps.suggest
Price: 1 credit per call; failed calls are free
Runs for up to: 30 seconds
Request: POST /execute; Run an endpoint
MCP tool when pinned: googlemaps__suggest; Pin tools
OpenAPI: openapi.json; Download

Request

Send the endpoint ID as capability and its fields as input. Set UPSCRAPE_API_KEY to your key first.

curl --request POST \  --url https://data.upscrape.com/execute \  --header "Authorization: Bearer $UPSCRAPE_API_KEY" \  --header "Content-Type: application/json" \  --header "Prefer: wait=30" \  --data '{  "capability": "googlemaps.suggest",  "input": {    "query": "coffee shops near"  }}'

import jsonimport osimport requestspayload = json.loads(r'''{  "capability": "googlemaps.suggest",  "input": {    "query": "coffee shops near"  }}''')response = requests.post(    "https://data.upscrape.com/execute",    headers={        "Authorization": f"Bearer {os.environ['UPSCRAPE_API_KEY']}",        "Content-Type": "application/json",        "Prefer": "wait=30",    },    json=payload,)response.raise_for_status()print(json.dumps(response.json(), indent=2))

const response = await fetch("https://data.upscrape.com/execute", {  method: "POST",  headers: {    "Authorization": `Bearer ${process.env.UPSCRAPE_API_KEY}`,    "Content-Type": "application/json",    "Prefer": "wait=30",  },  body: JSON.stringify({  "capability": "googlemaps.suggest",  "input": {    "query": "coffee shops near"  }}),});if (!response.ok) {  throw new Error(`Upscrape request failed: ${response.status}`);}console.log(JSON.stringify(await response.json(), null, 2));

Input

Field	Type	Required	What it does	Example
`query`	string	yes	Partial query, e.g. 'coffee shops near'.	coffee shops near
`country`	string	no	Two-letter country code for the gl parameter (default 'us'). Default: `us`.
`lang`	string	no	Language code such as 'en' or 'en-US' (default 'en'). Default: `en`.
`lat`	number	no	Optional latitude for geo-bias (use with lng). From -90 to 90.
`lng`	number	no	Optional longitude for geo-bias (use with lat). From -180 to 180.
`zoom`	integer	no	Map zoom level for bias (default 12; higher = tighter area). From 10 to 18.

Response

A finished call answers with HTTP 200; the data is in results[0].data, and billing.credits_charged is what it cost. A call still running after the wait answers 202: see jobs and results.

This is results[0].data from a real run:

results[0].data

{  "suggestions": [    {      "text": "coffee shops near me",      "kind": "query"    },    {      "text": "coffee shops near me open now",      "kind": "query"    }  ]}

Fields

Field	Type	Example
`suggestions[].text`	string	coffee shops near me
`suggestions[].kind`	string	query
`suggestions`	array	3 records

If a call fails

A failed call costs nothing. The response carries an error.code you can branch on; Errors and retries lists every code and which ones to retry.

Other Google Maps endpoints

Something missing or unclear? Ask the team that builds the Google Maps endpoints.