Places search (/places)
Reference for /places: places search parameters, response fields, code in 5 languages, GET and POST forms, and a sample response.
Updated View as Markdown
Local results (the Places tab): rating, address, category and opening hours. Results are in places. The product page is Google Places API.
Try in PlaygroundOpens the dashboard playground with this request filled in (sign in first).
Request
POST https://api.bestserp.com/places with a JSON body, or GET https://api.bestserp.com/places with the same parameters in the query string. The key goes in the X-API-KEY header either way (authentication).
POST
curl -X POST 'https://api.bestserp.com/places' \
-H 'X-API-KEY: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"q":"coffee shop hanoi"}'GET
curl -G 'https://api.bestserp.com/places' \
-H 'X-API-KEY: YOUR_API_KEY' \
--data-urlencode 'q=coffee shop hanoi'Parameters
Unknown parameters are refused (unknown_parameter), so a typo never goes unnoticed.
| 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. |
includeThumbnails | boolean | false | Include inline base64 thumbnails (~20 KB each). |
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
Empty fields are left out of each item.
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
200 OK
{
"searchParameters": {
"q": "coffee shop hanoi",
"gl": "us",
"hl": "en",
"type": "places",
"pages": 1,
"engine": "google"
},
"places": [
{
"position": 1,
"title": "Lantern Coffee Roasters",
"address": "12 Hang Bac, Hoan Kiem, Hanoi",
"category": "Coffee shop",
"rating": 4.7,
"ratingCount": 2140,
"priceLevel": "$",
"hours": "Open · Closes 10 PM",
"latitude": 21.0341,
"longitude": 105.8519,
"placeId": "ChIJlanternCoffee01",
"cid": "4893217750012345678"
},
{
"position": 2,
"title": "The Note Cafe",
"address": "64 Luong Van Can, Hoan Kiem, Hanoi",
"category": "Cafe",
"rating": 4.5,
"ratingCount": 3890,
"priceLevel": "$",
"hours": "Open · Closes 11 PM",
"latitude": 21.0322,
"longitude": 105.8511,
"placeId": "ChIJnoteCafeHanoi02",
"cid": "1185342209876543210"
},
{
"position": 3,
"title": "Cong Corner",
"address": "152 Trieu Viet Vuong, Hai Ba Trung, Hanoi",
"category": "Coffee shop",
"rating": 4.4,
"ratingCount": 980,
"priceLevel": "$",
"hours": "Closed · Opens 7 AM",
"latitude": 21.0145,
"longitude": 105.8497,
"placeId": "ChIJcongCorner00003",
"cid": "7734001122334455667"
}
],
"requestId": "5b0c8a52-3f0e-4d55-9a2a-0f3a8e2d1c11",
"credits": 1,
"cached": false,
"linksPending": false,
"unresolvedLinks": 0,
"durationMs": 2280
}Limits
- Returns the listing for the query, not each place's detail page: no phone numbers, review text or photo galleries.
- Put the city in the query ("pizza new york"): the search area follows the query and gl, coordinates or a radius are not supported.
- Photos are returned only as an optional thumbnail with includeThumbnails: true.
- 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.
Errors and their credit rules are on the errors page.