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.

Base URL

https://api.scrapemapsapi.com/v1

Authentication

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.

HeaderDescription
X-Credits-UsedCredits charged for this call
X-Credits-RemainingCredits left on your account after this call
X-CacheHIT when served from cache, MISS otherwise
X-Processing-TimeProcessing time in milliseconds

Place details

GET/v1/places/{place}1 credit

Full details of one place: address, coordinates, contacts, opening hours, attributes, photos and booking links.

Parameters

ParameterTypeDescription
placerequiredstringPlace ID (ChIJ…), CID (decimal, as in maps?cid=) or feature ID (0x…:0x…). To start from a Google Maps URL, call resolve first.
languagestringLanguage of the results, e.g. en, it, pt-BR. Default en.
regionstringTwo-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

GET/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

ParameterTypeDescription
placerequiredstringPlace ID (ChIJ…), CID (decimal, as in maps?cid=) or feature ID (0x…:0x…). To start from a Google Maps URL, call resolve first.
sortstringrelevant (default), newest, highest or lowest.
languagestringLanguage of dates and translation target: reviews in other languages get a translated_text. Default en.
original_languagestringOnly 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.
limitintegerReviews per page, 1–20 (one page of the review feed). Default 20.
cursorstringpagination.next_cursor of the previous page.
Privacy by design. Review authors are identified only by a pseudonymous, stable 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

GET/v1/places/resolve1 credit

Turns 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

ParameterTypeDescription
inputrequiredstringAn 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.

Python
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.

FieldTypeDescription
idstring | nullPlace ID (ChIJ…), the primary identifier.
idsobjectplace_id, cid, feature_id and google_maps_url of the place.
namestringName of the place, in the requested language when Google has it.
categoriesstring[]Categories, the main one first (e.g. "Tuscan restaurant").
addressobjectformatted, street, postal_code, city, region, country_code.
locationobjectlat and lng.
ratingnumber | nullAverage rating, 1 to 5.
review_countinteger | nullNumber of reviews on Google Maps.
phonestring | nullPhone number in local format.
websitestring | nullWebsite of the business.
statusstring | nulloperational, temporarily_closed or permanently_closed; null when unknown.
local_namestring | nullDetails only. Name in the local language, if different.
phone_internationalstring | nullDetails only. Phone number in international format.
plus_codestring | nullDetails only. Open Location Code.
timezonestring | nullDetails only. IANA time zone, e.g. Europe/Rome.
descriptionstring | nullDetails only. Description written by the owner.
opening_hoursobject | nullDetails only. weekly: one entry per day (day, closed, open_24h, periods of open/close HH:MM, text), plus status_text.
attributesobjectDetails only. Feature groups, e.g. {"Accessibility": [...]}.
photosobject[]Details only. url, width, height.
booking_linksobject[]Details only. Reservation and ordering links (url, domain).
knowledge_graph_idstring | nullDetails only. Google Knowledge Graph ID.

Review

FieldTypeDescription
idstringStable review ID.
ratinginteger | nullStars, 1 to 5.
published_atstring | nullPublication time, ISO 8601 in UTC.
relative_datestring | nullDate as Google displays it, e.g. "a week ago" (localized).
languagestring | nullOriginal language of the review.
textstring | nullOriginal text. Null for rating-only reviews.
translated_textstring | nullGoogle translation into the requested language, when it differs.
authorobjectOnly a pseudonymous, stable id. Names, photos and profile links are never returned.
owner_responseobject | nullReply of the owner: text, translated_text, relative_date.
photosobject[]Photos attached to the review.
detailsobjectStructured answers, e.g. {"Price per person": "€30–40", "Food": "5"}.
sourcestring | nullReview platform, normally "Google".

Errors

Errors use the envelope {"detail": {"error": "code", "message": "..."}} and are never billed.

StatusError CodeDescription
400invalid_place_idThe place parameter is not a valid place ID, CID or feature ID
400invalid_cursorThe cursor is malformed or belongs to another query
400invalid_locationOnly one of lat and lng was given
401missing_api_keyNo API key in the request
401invalid_api_keyUnknown or disabled API key
402insufficient_creditsNot enough credits for this call
404place_not_foundThe place does not exist on Google Maps
422(list)A parameter is missing or out of range; detail is a list of invalid parameters
429rate_limit_exceededToo many requests: wait for Retry-After seconds
429insufficient_credits_retry_laterRepeated calls without credits: the key is paused, top up
500internal_server_errorUnexpected error: retry once, then contact support
502upstream_errorGoogle answered with an error: retry later
502proxy_errorA short link could not be followed (resolve): retry later
503upstream_unavailableGoogle Maps is temporarily unreachable: retry in a minute

See Error Handling for every code and how to retry.