API Reference
Four endpoints for Google Maps data: search places, get the details of one place, read all of its reviews and convert any identifier or Google Maps link. Every response is JSON with the same envelope.
https://api.scrapemapsapi.com/v1
X-API-Key header (or Authorization: Bearer)
Response format
Every successful response is {"data": ..., "meta": {...}}; lists also have pagination. meta.credits_used is what the call cost and meta.cached tells whether it was served from our cache. Only HTTP 200 responses are billed.
| Header | Description |
|---|---|
| X-Credits-Used | Credits charged for this call |
| X-Credits-Remaining | Credits left on your account after this call |
| X-Cache | HIT when served from cache, MISS otherwise |
| X-Processing-Time | Processing time in milliseconds |
Search places
/v1/places/search1 credit per call (up to 20 places)Text search on Google Maps, optionally biased to an area. Returns up to 20 places per page.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
qrequired | string | What to search, e.g. "trattoria in Florence" or "dentist near Brooklyn". Up to 300 characters. |
language | string | Language of the results, e.g. en, it, pt-BR. Default en. |
region | string | Two-letter country code that biases the results, e.g. us, it. Default us. |
lat | number | Latitude of the area centre (with lng). |
lng | number | Longitude of the area centre (with lat). |
radius_km | number | Radius of the area in km, up to 100 (with lat/lng). |
limit | integer | Places per page, 1–20. Default 20. |
cursor | string | pagination.next_cursor of the previous page. |
Example Request
curl "https://api.scrapemapsapi.com/v1/places/search?q=trattoria%20in%20Florence®ion=it&lat=43.7696&lng=11.2558&radius_km=2&limit=1" \
-H "X-API-Key: key_your_api_key"Example Response
{
"data": [
{
"id": "ChIJ8cLgoQNUKhMReGlaTjwrH40",
"ids": {
"place_id": "ChIJ8cLgoQNUKhMReGlaTjwrH40",
"cid": "10168894021638449528",
"feature_id": "0x132a5403a1e0c2f1:0x8d1f2b3c4e5a6978",
"google_maps_url": "https://www.google.com/maps?cid=10168894021638449528"
},
"name": "Trattoria Da Neri",
"categories": [
"Tuscan restaurant",
"Italian restaurant"
],
"address": {
"formatted": "Via dei Neri, 42/r, 50122 Firenze FI, Italy",
"street": "Via dei Neri, 42/r",
"postal_code": "50122",
"city": "Firenze",
"region": "Toscana",
"country_code": "IT"
},
"location": {
"lat": 43.7681,
"lng": 11.258
},
"rating": 4.6,
"review_count": 2843,
"phone": "055 123 4567",
"website": "https://www.trattoriadaneri.example",
"status": "operational"
}
],
"pagination": {
"next_cursor": "eyJvIjoyMCwicSI6InRyYXR0b3JpYSJ9",
"has_more": true
},
"meta": {
"credits_used": 1,
"cached": false,
"query": "trattoria in Florence",
"language": "en",
"region": "it"
}
}Place details
/v1/places/{place}1 creditFull details of one place: address, coordinates, contacts, opening hours, attributes, photos and booking links.
Parameters
| Parameter | Type | Description |
|---|---|---|
placerequired | string | Place ID (ChIJ…), CID (decimal, as in maps?cid=) or feature ID (0x…:0x…). To start from a Google Maps URL, call resolve first. |
language | string | Language of the results, e.g. en, it, pt-BR. Default en. |
region | string | Two-letter country code that biases the results, e.g. us, it. Default us. |
Example Request
curl "https://api.scrapemapsapi.com/v1/places/ChIJ8cLgoQNUKhMReGlaTjwrH40?language=en" \
-H "X-API-Key: key_your_api_key"Example Response
{
"data": {
"id": "ChIJ8cLgoQNUKhMReGlaTjwrH40",
"ids": {
"place_id": "ChIJ8cLgoQNUKhMReGlaTjwrH40",
"cid": "10168894021638449528",
"feature_id": "0x132a5403a1e0c2f1:0x8d1f2b3c4e5a6978",
"google_maps_url": "https://www.google.com/maps?cid=10168894021638449528"
},
"name": "Trattoria Da Neri",
"categories": [
"Tuscan restaurant",
"Italian restaurant"
],
"address": {
"formatted": "Via dei Neri, 42/r, 50122 Firenze FI, Italy",
"street": "Via dei Neri, 42/r",
"postal_code": "50122",
"city": "Firenze",
"region": "Toscana",
"country_code": "IT"
},
"location": {
"lat": 43.7681,
"lng": 11.258
},
"rating": 4.6,
"review_count": 2843,
"phone": "055 123 4567",
"website": "https://www.trattoriadaneri.example",
"status": "operational",
"local_name": null,
"phone_international": "+39 055 123 4567",
"plus_code": "8FMHQ753+6V",
"timezone": "Europe/Rome",
"description": "Family-run trattoria near Santa Croce serving bistecca alla fiorentina and handmade pasta.",
"opening_hours": {
"weekly": [
{
"day": "monday",
"closed": false,
"open_24h": false,
"periods": [
{
"open": "12:00",
"close": "15:00"
},
{
"open": "19:00",
"close": "22:30"
}
],
"text": "12:00–15:00, 19:00–22:30"
},
{
"day": "tuesday",
"closed": true,
"open_24h": false,
"periods": [],
"text": "Closed"
}
],
"status_text": "Open · Closes 3 pm"
},
"attributes": {
"Service options": [
"Dine-in",
"Takeaway"
],
"Accessibility": [
"Wheelchair-accessible entrance"
]
},
"photos": [
{
"url": "https://lh5.googleusercontent.com/p/AF1QipExample=w800-h600",
"width": 800,
"height": 600
}
],
"booking_links": [
{
"url": "https://www.thefork.example/trattoria-da-neri",
"domain": "thefork.example"
}
],
"knowledge_graph_id": "/g/11c1q8_example"
},
"meta": {
"credits_used": 1,
"cached": true,
"language": "en"
}
}Reviews
/v1/places/{place}/reviews1 credit per call (up to 20 reviews)All reviews of a place, not just five: page through them with cursors, sort them and get them translated.
Parameters
| Parameter | Type | Description |
|---|---|---|
placerequired | string | Place ID (ChIJ…), CID (decimal, as in maps?cid=) or feature ID (0x…:0x…). To start from a Google Maps URL, call resolve first. |
sort | string | relevant (default), newest, highest or lowest. |
language | string | Language of dates and translation target: reviews in other languages get a translated_text. Default en. |
original_language | string | Only reviews originally written in this language, e.g. it. Each call reads one page of the feed, so a filtered page can hold fewer reviews than limit, even none, with a next_cursor to continue. |
limit | integer | Reviews per page, 1–20 (one page of the review feed). Default 20. |
cursor | string | pagination.next_cursor of the previous page. |
author.id (a keyed hash), so you can group reviews by author without processing names, photos or profile links. This keeps your use of the data simpler under the GDPR.Every page is one call: 1 credit for 20 reviews, 7 reviews or an empty page alike. 1,000 reviews take 50 calls.
Example Request
curl "https://api.scrapemapsapi.com/v1/places/ChIJ8cLgoQNUKhMReGlaTjwrH40/reviews?sort=newest&limit=20&language=en" \
-H "X-API-Key: key_your_api_key"Example Response
{
"data": [
{
"id": "Ci9DQUlRQUNvZENodHljRjlvT2xKVVpXdzNXbGhzTFhWT1VrRjFUVTQ0VUVsdVZXYxAB",
"rating": 5,
"published_at": "2026-11-14T19:42:10Z",
"relative_date": "a week ago",
"language": "it",
"text": "Bistecca perfetta e servizio gentilissimo. Prenotate!",
"translated_text": "Perfect steak and very kind service. Book ahead!",
"author": {
"id": "a_5f2c9e1b7d43"
},
"owner_response": {
"text": "Grazie mille, vi aspettiamo presto!",
"translated_text": "Thank you so much, see you soon!",
"relative_date": "6 days ago"
},
"photos": [],
"details": {
"Price per person": "€30–40",
"Food": "5",
"Service": "5",
"Atmosphere": "4"
},
"source": "Google"
}
],
"pagination": {
"next_cursor": "CAESBkVnSUlDZw",
"has_more": true
},
"meta": {
"credits_used": 1,
"cached": false,
"place_id": "ChIJ8cLgoQNUKhMReGlaTjwrH40",
"cid": "10168894021638449528",
"sort": "newest",
"language": "en",
"original_language": null
}
}Resolve identifiers and URLs
/v1/places/resolve1 creditTurns any place ID, CID, feature ID or Google Maps URL (including maps.app.goo.gl short links) into all identifiers of the place.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
inputrequired | string | An identifier or a Google Maps URL, including maps.app.goo.gl short links and bare CIDs. |
Example Request
curl "https://api.scrapemapsapi.com/v1/places/resolve?input=https%3A%2F%2Fmaps.app.goo.gl%2Fx7Qp2Nf9TzVb8LkE6" \
-H "X-API-Key: key_your_api_key"Example Response
{
"data": {
"place_id": "ChIJ8cLgoQNUKhMReGlaTjwrH40",
"cid": "10168894021638449528",
"feature_id": "0x132a5403a1e0c2f1:0x8d1f2b3c4e5a6978",
"google_maps_url": "https://www.google.com/maps?cid=10168894021638449528"
},
"meta": {
"credits_used": 1,
"cached": false
}
}Pagination with cursors
Search and reviews return a pagination object. When has_more is true, pass next_cursor as the cursor parameter of the same request to get the next page. On the last page next_cursor is null. Cursors are opaque: do not build or edit them, and keep the other parameters unchanged while paging.
import requests
url = "https://api.scrapemapsapi.com/v1/places/ChIJ8cLgoQNUKhMReGlaTjwrH40/reviews"
headers = {"X-API-Key": "key_your_api_key"}
params = {"sort": "newest", "limit": 100}
reviews = []
while True:
page = requests.get(url, headers=headers, params=params, timeout=60).json()
reviews.extend(page["data"])
if not page["pagination"]["has_more"]:
break
params["cursor"] = page["pagination"]["next_cursor"]
print(len(reviews), "reviews")Objects
Place
Search returns the summary fields; details add the fields marked "Details only". Fields Google does not publish for signed-out visitors (popular times, price level) are not part of the schema.
| Field | Type | Description |
|---|---|---|
id | string | null | Place ID (ChIJ…), the primary identifier. |
ids | object | place_id, cid, feature_id and google_maps_url of the place. |
name | string | Name of the place, in the requested language when Google has it. |
categories | string[] | Categories, the main one first (e.g. "Tuscan restaurant"). |
address | object | formatted, street, postal_code, city, region, country_code. |
location | object | lat and lng. |
rating | number | null | Average rating, 1 to 5. |
review_count | integer | null | Number of reviews on Google Maps. |
phone | string | null | Phone number in local format. |
website | string | null | Website of the business. |
status | string | null | operational, temporarily_closed or permanently_closed; null when unknown. |
local_name | string | null | Details only. Name in the local language, if different. |
phone_international | string | null | Details only. Phone number in international format. |
plus_code | string | null | Details only. Open Location Code. |
timezone | string | null | Details only. IANA time zone, e.g. Europe/Rome. |
description | string | null | Details only. Description written by the owner. |
opening_hours | object | null | Details only. weekly: one entry per day (day, closed, open_24h, periods of open/close HH:MM, text), plus status_text. |
attributes | object | Details only. Feature groups, e.g. {"Accessibility": [...]}. |
photos | object[] | Details only. url, width, height. |
booking_links | object[] | Details only. Reservation and ordering links (url, domain). |
knowledge_graph_id | string | null | Details only. Google Knowledge Graph ID. |
Review
| Field | Type | Description |
|---|---|---|
id | string | Stable review ID. |
rating | integer | null | Stars, 1 to 5. |
published_at | string | null | Publication time, ISO 8601 in UTC. |
relative_date | string | null | Date as Google displays it, e.g. "a week ago" (localized). |
language | string | null | Original language of the review. |
text | string | null | Original text. Null for rating-only reviews. |
translated_text | string | null | Google translation into the requested language, when it differs. |
author | object | Only a pseudonymous, stable id. Names, photos and profile links are never returned. |
owner_response | object | null | Reply of the owner: text, translated_text, relative_date. |
photos | object[] | Photos attached to the review. |
details | object | Structured answers, e.g. {"Price per person": "€30–40", "Food": "5"}. |
source | string | null | Review platform, normally "Google". |
Errors
Errors use the envelope {"detail": {"error": "code", "message": "..."}} and are never billed.
| Status | Error Code | Description |
|---|---|---|
| 400 | invalid_place_id | The place parameter is not a valid place ID, CID or feature ID |
| 400 | invalid_cursor | The cursor is malformed or belongs to another query |
| 400 | invalid_location | Only one of lat and lng was given |
| 401 | missing_api_key | No API key in the request |
| 401 | invalid_api_key | Unknown or disabled API key |
| 402 | insufficient_credits | Not enough credits for this call |
| 404 | place_not_found | The place does not exist on Google Maps |
| 422 | (list) | A parameter is missing or out of range; detail is a list of invalid parameters |
| 429 | rate_limit_exceeded | Too many requests: wait for Retry-After seconds |
| 429 | insufficient_credits_retry_later | Repeated calls without credits: the key is paused, top up |
| 500 | internal_server_error | Unexpected error: retry once, then contact support |
| 502 | upstream_error | Google answered with an error: retry later |
| 502 | proxy_error | A short link could not be followed (resolve): retry later |
| 503 | upstream_unavailable | Google Maps is temporarily unreachable: retry in a minute |
See Error Handling for every code and how to retry.