Blog / API guides

Google Maps Reviews API: Parameters, Requests and Cost

9 Jul 2026Perceptlayer8 min read

To get Google Maps reviews as JSON, call GET /v1/google-maps/reviews with a business_id. You get that ID from the business_id field of a Simple Search result, so the whole path is two requests.

This guide walks both steps with real requests, then covers the parameters on the Reviews and Review endpoints and what the calls cost. It also shows a trimmed excerpt of a recorded Reviews response, so you can see the fields you'll parse, including the review_id the single-review endpoint needs.

Where does the business_id come from?

Reviews are looked up by a place's business_id, not by its name. Search for the place with Simple Search and read business_id from each item in the response. Simple Search needs only query, so a search like "restaurants in new york" is enough to get IDs for the places it finds.

Here is the request:

curl "https://api.perceptlayer.com/v1/google-maps/simple-search?query=restaurants+in+new+york" \
  -H "X-API-Key: $API_KEY"

The response is a JSON object with an items array. This is an excerpt of a recorded response, trimmed with …:

{
  "items": [
    {
      "name": "Lulla NYC",
      "review_count": 1571,
      "rating": 4.8,
      "business_id": "0x89c259bf22ca32bd:0x35d818a560181b20",
      "subtypes": [
        "Italian restaurant",
        "Restaurant"
      ],
      "full_address": "113 W 24th St, New York, NY 10011, United States",
      "place_id": "ChIJvTLKIr9ZwokRIBsYYKUY2DU=",
      …
    }
  ]
}

Each item also carries rating and review_count, so you can rank places before you spend a call on their reviews. Use business_id, the value with the 0x…:0x… shape, for the next step. place_id is a different identifier.

Sign-in details are in the authentication docs. If you don't have a key yet, get a free API key.

How do you request reviews for a place?

Pass the business_id you got from Simple Search to the Reviews endpoint. It's a GET request to /v1/google-maps/reviews, and the key goes in the X-API-Key header like every other call. The only required parameter is business_id, so the shortest working request is one query string value and one header.

curl "https://api.perceptlayer.com/v1/google-maps/reviews?business_id=0x89c259bf22ca32bd:0x35d818a560181b20" \
  -H "X-API-Key: $API_KEY"

Here's the same two-step flow in Python. It picks Lulla NYC out of the Simple Search items by its business_id, rather than taking the first item, which in the recorded response is a different place. It then loops over the Reviews items and prints rating, review_id and timestamp, three fields from the recorded response:

import os
import requests

BASE = "https://api.perceptlayer.com/v1/google-maps"
HEADERS = {"X-API-Key": os.environ["API_KEY"]}

search = requests.get(
    f"{BASE}/simple-search",
    params={"query": "restaurants in new york"},
    headers=HEADERS,
    timeout=30,
)
search.raise_for_status()
TARGET_ID = "0x89c259bf22ca32bd:0x35d818a560181b20"
place = next(
    (i for i in search.json()["items"] if i["business_id"] == TARGET_ID),
    None,
)
if place is None:
    raise SystemExit(f"{TARGET_ID} not in the Simple Search items; use another business_id")
print(place["name"], place["rating"], place["review_count"])

reviews = requests.get(
    f"{BASE}/reviews",
    params={"business_id": place["business_id"]},
    headers=HEADERS,
    timeout=30,
)
reviews.raise_for_status()
for review in reviews.json()["items"]:
    print(review["rating"], review["review_id"], review["timestamp"])

Two calls, two credits.

What does the Reviews response look like?

The response is a JSON object with an items array, one object per review. This excerpt is from a recorded response for a different business_id than the one above (0x60188b88b7d8f7ab:0x2133080e9923eaac). It's trimmed with …, and the reviewer's name and profile links are left out:

{
  "items": [
    {
      "review_source": "Google",
      "review_id": "Ci9DQUlRQUNvZENodHljRjlvT25kVUxXTmpaamhNWjFac016WTVSMjlqUVRCb1VYYxAB",
      "rating": 5,
      "timestamp": 1779471094452,
      …
      "author_review_count": 262,
      "author_photo_count": 660,
      "review_text": [
        "A must do! Easy access via …"
      ],
      "review_language": [
        "en"
      ],
      "review_link": "https://www.google.com/maps/reviews/data=!4m8!14m7!1m6!2m5!1sCi9DQUlRQUNvZENodHljRjlvT25kVUxXTmpaamhNWjFac016WTVSMjlqUVRCb1VYYxAB",
      "images": [
        …
      ],
      "is_google_review": true
    },
    …
  ]
}

Each item has a rating, a timestamp and a review_id, plus review_text and review_language, which are both arrays. Items also carry author fields (name, profile link, review and photo counts) and an images array. Treat the author fields as personal data.

Which parameters does the Reviews endpoint take?

GET /v1/google-maps/reviews takes one required parameter, business_id, and seven optional ones: page, pages, search, sort, limit, hl and gl. The sort value must be 1, 2, 3 or 4, and search is capped at 100 characters. The table below lists each parameter with its type and any limits from the catalogue.

The catalogue records types and limits only. It doesn't say what 1 to 4 mean for sort, what page or pages select, what hl and gl accept, give defaults, or state how many reviews a call returns, so we won't guess at any of that. Run a call in the playground on the Google Maps API page to see the effect of each value on your own place before you rely on it.

Combining parameters is a matter of adding query string values. The request below is a syntax example only. We have no recorded response for it, and the values are placeholders that show how the parameters fit together, not a claim about what they return:

curl -G "https://api.perceptlayer.com/v1/google-maps/reviews" \
  --data-urlencode "business_id=0x89c259bf22ca32bd:0x35d818a560181b20" \
  --data-urlencode "search=pasta" \
  --data-urlencode "sort=2" \
  --data-urlencode "limit=20" \
  --data-urlencode "hl=en" \
  -H "X-API-Key: $API_KEY"

It passes search=pasta, sort=2, limit=20 and hl=en along with the place's business_id, all within the documented types and limits. What sort=2 orders by and how many reviews limit=20 yields are not documented, so check both on your own place.

To find out what each sort value does, call Reviews four times with the same business_id and sort set to 1, 2, 3 and 4. Compare the order of rating and timestamp across the items. For page and limit, repeat the call with and without them and count the items each time. Each test call is 1 credit.

How do you fetch a single review?

Use GET /v1/google-maps/review when you already know the review you want. It needs two parameters, review_id (up to 100 characters) and business_id, and nothing else.

curl "https://api.perceptlayer.com/v1/google-maps/review?review_id=$REVIEW_ID&business_id=0x89c259bf22ca32bd:0x35d818a560181b20" \
  -H "X-API-Key: $API_KEY"

The review ID comes from the Reviews response: each object in items carries a review_id, as in the excerpt above. So the chain is Reviews, then Review. Call Reviews with a business_id, read items[].review_id, and pass that value with the same business_id to Review. The Review endpoint page has the parameters and a playground link. Two related endpoints cover other angles on the same data. Contributor Reviews takes a contributor_id and looks at reviews from the reviewer's side, and Business Details takes a business_id for the place's own record.

What does a Google Maps reviews call cost?

Each call to Reviews or Review costs 1 credit when it succeeds, as shown on the endpoint. A failed call costs nothing and returns X-Credits-Used: 0. Credits come from a free monthly grant or a prepaid pack, with no subscription and no seats. The credits docs explain billing.

Larger packs run from 5,000,000 up to 50,000,000 credits. The free tier needs a verified email and no credit card. Purchased credits last 12 months. See pricing for what credits cost.

Here is the arithmetic for a realistic job. Say you want reviews for 300 places. One Simple Search call finds places, and one Reviews call per place fetches reviews:

• 300 Reviews calls × 1 credit = 300 credits.
• Add N Simple Search calls to find the places, at 1 credit each. N depends on how many places each search returns.
• Total: 300 + N credits. Even with N in the dozens, that sits well inside the free 1,000.

Repeat that four times a month and you'd use at least 4 × 300 = 1,200 credits before counting searches, which is over the free grant. The Starter pack's 10,000 credits covers it with room to spare, and pricing shows what a pack costs.

One caveat. These figures assume one Reviews call per place. Every separate call is 1 credit. The catalogue doesn't say whether a request with pages above 1 costs more, so run one with the value you plan to use, compare your credit balance before and after, then scale the estimate.

How does this compare with the official Places API?

Google's own Places API fits some jobs better. Its Place resource documents the reviews field as a "list of reviews about this place, sorted by relevance. A maximum of 5 reviews can be returned" (Google Maps Platform, Place resource reference, 2026). If five reviews per place is enough, and you want Google's billing and terms directly, use it. The Place Details documentation lists the reviews field among the fields you can request.

Reach for the Reviews endpoint when you want the search, sort, limit and pages parameters, or the same key and JSON conventions as the rest of the catalogue. Run a call on one of your own places and compare the items you get back with the cap above before you choose.

Data is collected from publicly available sources and returned as found at the time of the call. Reviews are written by individuals, so treat reviewer names and text as personal data in your own storage and follow the rules that apply to you.

What happens when a request fails?

A failed request comes back with an HTTP status and a JSON body shaped as {"error": {"code", "message", "request_id"}}. The code tells you whether to fix the request or retry it. Failed calls cost nothing. The codes you're most likely to meet here:

The full list is in the errors docs. Log the request_id with every failure so you can trace it later.

Next step: get a free key, run the Simple Search call above, and paste the business_id into the Reviews call in the playground. Related guides: Zillow listings as JSON is another walk-through in the same format, and the API guides category has the rest.

google mapsreviewslocal businessapi