POST /maps
Google Maps API
The BestSERP Google Maps API runs a search on Google Maps and returns the places it lists as JSON: name, address, category, rating, review count, opening status, latitude and longitude, place ID and CID. Use it to map businesses, enrich location data or check local rankings without a Google Cloud project.
Last updated:
Key takeaways
- /maps returns places with title, address, category, rating, ratingCount and more.
- Target any country with gl and any language with hl; city-level location is not supported yet.
- 1 credit per page of results ($0.50 per 1,000 after 3,000 free); failed searches are refunded.
- POST a JSON body or GET with the same parameters; the key goes in the X-API-KEY header.
Try the Google Maps API
Pick a suggested query to see a saved response, or type your own for a live search (3 free per day).
Loading the live demo
Send a request
POST a JSON body to
https://api.bestserp.com/maps with your key in the X-API-KEY header. Replace YOUR_API_KEY and run.curl -X POST 'https://api.bestserp.com/maps' \
-H 'X-API-KEY: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"q":"pho restaurant hanoi"}'Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
qrequired | string | Search query (1–256 characters). | |
gl | string | us | Country, 2-letter code (us, gb, vn, de…). The search runs from an IP in that country when one is free, else from another one (see ipCountry). |
hl | string | en | Interface language (en, vi, de…). |
pages | integer | 1 | Result pages or scroll loads to fetch, 1–5. Each costs 1 credit. |
noCache | boolean | false | Skip the 1-hour result cache (5 minutes for news). |
async | boolean | false | Answer 202 immediately with a requestId to poll. |
timeout | number | 60 | Seconds to wait before answering 202 (1–120). |
autocorrect | boolean | Accepted for compatibility; no effect. |
Response fields
Results are in
places. Empty fields are left out.places[]
| Field | Meaning |
|---|---|
position | Rank of the place, from 1. |
title | Business or place name. |
address | Address as shown. |
category | Type of place as shown, e.g. Coffee shop. |
rating | Average rating out of 5. |
ratingCount | Number of reviews. |
priceLevel | Price range as shown, e.g. $$. |
hours | Opening status as shown, e.g. Open · Closes 10 PM. |
snippet | Short description or review excerpt, when shown. |
latitude | Latitude in decimal degrees. |
longitude | Longitude in decimal degrees. |
placeId | Google place ID. |
cid | Google Maps customer ID (CID). |
link | Link shown for the place in the listing, when there is one. |
thumbnailUrl | Thumbnail as an inline data: URI, only with includeThumbnails: true (about 20 KB each). |
Every response
| Field | Meaning |
|---|---|
searchParameters | Your request after validation, with defaults filled in (q, gl, hl, type, page or pages...). |
requestId | ID of this request. Poll GET /requests/{requestId} for async requests and for final links. |
credits | Credits charged for this request (refunded automatically if it fails). |
cached | true when the answer came from the recent-result cache (1 hour, 5 minutes for news). |
linksPending | true while Google redirect links are being replaced by final URLs; poll the request to get them. |
unresolvedLinks | Links that are still Google redirects: they work, but are not the final URL. |
durationMs | Time the search took, in milliseconds. |
ipCountry | Country of the IP the search ran from (same code as gl). Another country than gl when no IP there was free: the search runs anyway instead of waiting. Missing when unknown. |
Sample response
A trimmed response for "pho restaurant hanoi". Your results reflect Google at the time of the request.
{
"searchParameters": {
"q": "pho restaurant hanoi",
"gl": "us",
"hl": "en",
"type": "maps",
"pages": 1,
"engine": "google"
},
"places": [
{
"position": 1,
"title": "Pho Lantern",
"address": "12 Hang Bac, Hoan Kiem, Hanoi",
"category": "Pho restaurant",
"rating": 4.7,
"ratingCount": 2140,
"priceLevel": "$",
"hours": "Open · Closes 10 PM",
"latitude": 21.0341,
"longitude": 105.8519,
"placeId": "ChIJlanternCoffee01",
"cid": "4893217750012345678",
"link": "https://maps.google.com/?cid=4893217750012345678"
},
{
"position": 2,
"title": "Pho Bat Dan 49",
"address": "64 Luong Van Can, Hoan Kiem, Hanoi",
"category": "Pho restaurant",
"rating": 4.5,
"ratingCount": 3890,
"priceLevel": "$",
"hours": "Open · Closes 11 PM",
"latitude": 21.0322,
"longitude": 105.8511,
"placeId": "ChIJnoteCafeHanoi02",
"cid": "1185342209876543210",
"link": "https://maps.google.com/?cid=1185342209876543210"
},
{
"position": 3,
"title": "Pho Thin Lo Duc",
"address": "152 Trieu Viet Vuong, Hai Ba Trung, Hanoi",
"category": "Pho restaurant",
"rating": 4.4,
"ratingCount": 980,
"priceLevel": "$",
"hours": "Closed · Opens 7 AM",
"latitude": 21.0145,
"longitude": 105.8497,
"placeId": "ChIJcongCorner00003",
"cid": "7734001122334455667",
"link": "https://maps.google.com/?cid=7734001122334455667"
}
],
"requestId": "5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11",
"credits": 1,
"cached": false,
"linksPending": false,
"unresolvedLinks": 0,
"durationMs": 3120
}What you can build
Store locators and maps
Plot businesses of a category on your own map with their coordinates.
Local rank tracking
Record the order of places Google Maps shows for your keywords.
Local rank tracking guideData enrichment
Match your records to Google place IDs, ratings and categories.
Current limits
What this API does not do yet, so you can decide before you build on it.
- Returns the places of the Maps results list, not their detail pages: no phone numbers, review text or photo galleries.
- The search area follows the query and gl. Map coordinates, zoom level and radius are not supported yet.
- Up to 5 scroll loads (pages) per request; each costs 1 credit.
- Targeting is by country (gl) and interface language (hl). City-level location is not supported yet: a request with location is refused with an explicit error.
- Results are what a desktop browser sees. There is no mobile SERP option yet.
- 60 searches per minute per account by default; ask on Telegram for more.
Pricing: 1 credit per page of results, 3,000 free credits, then $0.50 per 1,000. See pricing
Frequently asked questions
What is the difference with the Places API?
Places returns Google's local results for a query; Maps runs the query on Google Maps itself. Both return the same fields, but which places are listed, and in what order, can differ.
Can I search around coordinates?
Not yet. Put the area in the query ("hotel bali") and set gl to the country.
How many places does a request return?
What Google Maps loads for one scroll of the list. Set pages up to 5 to load more; each load costs 1 credit.
Can I use the coordinates on my own map?
The API returns latitude and longitude for each place; check the terms of the map provider you display them on.
Other Google APIs
- Google Search APIOrganic results with titles, links and snippets, plus the video carousel and Top stories.
- Google Images APIImage results with full-size image URLs, dimensions and the page that hosts each image.
- Google News APINews articles with source, publish time and site icon, from the Google News tab.
- Google Videos APIVideo results with duration, channel and platform.
- Google Shopping APIProducts with price, numeric price, discount, delivery and rating.
- Google Places APILocal businesses with rating, category, address and opening hours.
Start with 3,000 free searches
No credit card. Sign in with Google, create a key, send your first request.