Google Maps

Search Google Maps places, or get one place by ID.

GET/api/v1/google/maps

Costs 1 credit per request; failed requests are refunded. Authentication, the search_metadata envelope and error codes are the same as for every endpoint (see the API reference). Try it in the playground.

Parameters

Request and search query

Parameter	Type	Description
`q`conditional	string	The business, category, address, or natural-language query to search. Required when type is search.Examples: coffee shops in Austin, dentist near Denver
`type`conditional	"search" \| "place"	Chooses a result search or an exact place response. Required for query and filter searches.Use place when sending an exact-place data sequence.

Geographic location

Parameter	Type	Description
`ll`	string	A complete viewport containing latitude, longitude, and either zoom or radius.Format: @lat,lon,14z or @lat,lon,5000m
`location`	string	A named geographic location resolved by the API. Cannot be combined with ll or lat/lon.Requires z or m.
`lat`	string	Latitude for a coordinate-based viewport. Must be supplied with lon and either z or m.
`lon`	string	Longitude for a coordinate-based viewport. Must be supplied with lat and either z or m.
`z`conditional	string	Google Maps zoom level for location or lat/lon geography.Accepted range: 3 through 30.Cannot be combined with m.
`m`conditional	string	Search radius in meters for location or lat/lon geography.Accepted range: 1 through 15,028,132.Cannot be combined with z.
`nearby`	boolean	Uses the supplied geography as a nearby-search scope.Requires ll, location, or a lat/lon pair.

Exact place

Parameter	Type	Description
`data`conditional	string	A Google Maps protobuf parameter sequence for search filters or an exact place.Maximum length: 8,192 characters.Exact-place data requires type=place.
`place_id`conditional	string	A Google place identifier used to resolve one exact place or request live foot traffic.Cannot be combined with data_cid or exact-place data on the primary Maps endpoint.It is the only required parameter on /api/google/maps/popular-times.Every response is fetched live. Places without published busy hours return HTTP 404 not_found and are not billed.
`data_cid`conditional	string	A decimal Google CID used to resolve one exact place.Cannot be combined with place_id or exact-place data.

Localization

Parameter	Type	Description
`hl`	string	Language used for Google Maps labels and returned text.Examples: en, es, fr, de
`gl`	string	Two-letter country code used for regional result localization.Examples: us, gb, ca, au
`google_domain`	string	Validated Google domain used for the request.Examples: google.com, google.co.uk, google.ca

Search filters

Parameter	Type	Description
`min_price`	string	Minimum price level for returned places.Must be non-negative and cannot exceed max_price.
`max_price`	string	Maximum price level for returned places.Must be non-negative and cannot be lower than min_price.
`min_rating`	string	Preferred minimum Google rating.Google treats this as a relevance preference.
`open_state`	"now" \| "24h"	Filters by the current open state.Cannot be combined with open_on_day or open_at_hour.
`open_on_day`	"mon" \| "tue" \| "wed" \| "thu" \| "fri" \| "sat" \| "sun"	Filters for places open on a specific day.
`open_at_hour`	string	Filters for places open at a specific hour using 24-hour time.Accepted range: 0 through 23.Requires open_on_day.

Pagination

Parameter	Type	Description
`start`	string	Native Maps result offset: 0, 20, 40, and so on. Each request returns up to 20 places and each successful request costs one credit.Use pagination.next when it is present instead of constructing the next request manually.

Response

A JSON object with search_metadata (request id, credits used and remaining) and the result groups the page returns. Groups and fields depend on the content of each page, so treat every field as optional.

Examples

cURL

curl "https://serpfast.com/api/v1/google/maps?q=787+Coffee+New+York&type=search&hl=en&gl=us" \
  -H "Authorization: Bearer $SERPFAST_KEY"

Node.js 18+

const params = new URLSearchParams({
  "q": "787 Coffee New York",
  "type": "search",
  "hl": "en",
  "gl": "us"
});
const res = await fetch(`https://serpfast.com/api/v1/google/maps?${params}`, {
  headers: { Authorization: `Bearer ${process.env.SERPFAST_KEY}` },
});
const data = await res.json();
console.log(data);

Python

import os, requests

params = {
  "q": "787 Coffee New York",
  "type": "search",
  "hl": "en",
  "gl": "us"
}
res = requests.get(
    "https://serpfast.com/api/v1/google/maps",
    params=params,
    headers={"Authorization": f"Bearer {os.environ['SERPFAST_KEY']}"},
    timeout=120,
)
print(res.json())