--- title: "Google Maps Reviews API: Parameters, Requests and Cost" description: "Call GET /v1/google-maps/reviews with a business_id from Simple Search. Every parameter, the sort values 1 to 4, and the cost: 1 credit per call." url: https://perceptlayer.com/blog/google-maps-reviews-api-parameters --- [Blog](https://perceptlayer.com/blog) / [API guides](https://perceptlayer.com/blog/category/api-guides) # Google Maps Reviews API: Parameters, Requests and Cost 9 Jul 2026 Perceptlayer 8 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. ## Key takeaways - `business_id` is the only required parameter on `/v1/google-maps/reviews`. Simple Search items carry it, for example `0x89c259bf22ca32bd:0x35d818a560181b20`. - Reviews accepts `page`, `pages`, `search`, `sort`, `limit`, `hl` and `gl`. `sort` takes one of 1, 2, 3 or 4, and `search` is capped at 100 characters. - `/v1/google-maps/review` fetches a single review and needs both `review_id` and `business_id`. - Each call costs 1 credit, so the free 1,000 monthly credits cover 1,000 calls. ## 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: ```bash 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 `…`: ```json { "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](https://docs.perceptlayer.com/authentication). If you don't have a key yet, [get a free API key](https://perceptlayer.com/signup). ## 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. ```bash 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: ```python 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: ```json { "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. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `business_id` | string | yes | From Simple Search, e.g. `0x89c259bf22ca32bd:0x35d818a560181b20` | | `page` | string | no | Up to 512 characters | | `pages` | integer | no | | | `search` | string | no | Up to 100 characters | | `sort` | integer | no | One of 1, 2, 3, 4 | | `limit` | integer | no | | | `hl` | string | no | | | `gl` | string | no | | 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](https://perceptlayer.com/apis/google-maps) 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: ```bash 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. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `review_id` | string | yes | Up to 100 characters | | `business_id` | string | yes | From Simple Search | ```bash 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](https://perceptlayer.com/apis/google-maps/review) has the parameters and a playground link. Two related endpoints cover other angles on the same data. [Contributor Reviews](https://perceptlayer.com/apis/google-maps/contributor-reviews) takes a `contributor_id` and looks at reviews from the reviewer's side, and [Business Details](https://perceptlayer.com/apis/google-maps/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](https://docs.perceptlayer.com/credits) explain billing. | Plan | Credits | Reviews calls at 1 credit | | --- | --- | --- | | Free | 1,000 every month | 1,000 | | Starter | 10,000 | 10,000 | | Build | 50,000 | 50,000 | | Growth | 200,000 | 200,000 | | Pro | 500,000 | 500,000 | | Scale | 1,000,000 | 1,000,000 | 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](https://perceptlayer.com/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](https://perceptlayer.com/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](https://developers.google.com/maps/documentation/places/web-service/reference/rest/v1/places), 2026). If five reviews per place is enough, and you want Google's billing and terms directly, use it. The [Place Details documentation](https://developers.google.com/maps/documentation/places/web-service/place-details) 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: | Code | Status | What to do | | --- | --- | --- | | `invalid_api_key` | 401 | Check the `X-API-Key` header | | `insufficient_credits` | 402 | Top up or wait for the monthly grant | | `not_found` | 404 | Check the `business_id` came from Simple Search | | `invalid_parameters` | 422 | Check types and limits, e.g. `sort` is 1 to 4 | | `rate_limited` | 429 | Back off and retry; see [rate limits](https://docs.perceptlayer.com/rate-limits) | | `source_error` | 502 | Retry the call | | `temporarily_unavailable` | 503 | Retry the call | The full list is in the [errors docs](https://docs.perceptlayer.com/errors). 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](https://perceptlayer.com/blog/zillow-listings-api-json) is another walk-through in the same format, and the [API guides category](https://perceptlayer.com/blog/category/api-guides) has the rest. ## APIs in this post - [Google Maps **1 credit per call** · 10 endpoints](https://perceptlayer.com/apis/google-maps) ## Frequently asked questions ### Do I need a Google account or Google Cloud project? No Google credentials appear in the request. You send an `X-API-Key` header with a Perceptlayer key, which starts with `sk_live_`. Verify an email address and you get 1,000 free credits every month, with no credit card. ### How much does it cost to pull reviews for 1,000 places? One Reviews call per place is 1,000 calls at 1 credit each, so 1,000 credits. That fits inside the free monthly 1,000 only if you make no other calls. Beyond the free grant, the Starter pack's 10,000 credits cover it ten times over; [pricing](https://perceptlayer.com/pricing) has what credits cost. ### Can I filter reviews by keyword or sort them? Yes. Reviews takes `search` (a string of up to 100 characters) and `sort` (an integer, one of 1, 2, 3, 4). ### How do I get more than one page of reviews? Reviews has `page` (a string, up to 512 characters), `pages` (an integer) and `limit` (an integer). Try them on one place in the playground and check how many credits the request used before you build a loop. ### Does a failed request use credits? No. A failed call returns an error body with a `code`, `message` and `request_id`. A 429 or 503 response you receive wasn't charged, and it carries a `Retry-After` header with the seconds to wait. One exception: requests have no idempotency key, so if a reply is lost (a client timeout), the call may have succeeded and been billed. Check `X-Credits-Remaining` before you retry those. google maps reviews local business api ## More from the blog 1. [API guides](https://perceptlayer.com/blog/category/api-guides) 15 Sept 2026 Perceptlayer 7 min read ## [Google Maps Directions API Alternative: Routes as JSON](https://perceptlayer.com/blog/google-maps-directions-api-alternative) One GET to /v1/google-maps/directions returns a route as JSON for 1 credit. Parameters, a 15,000-route cost example and Google's per-request rates. 2. [API guides](https://perceptlayer.com/blog/category/api-guides) 18 Aug 2026 Perceptlayer 8 min read ## [Google Maps Business Data API: Search Places as JSON](https://perceptlayer.com/blog/google-maps-business-data-api) One GET to simple-search returns places as JSON: name, rating, review\_count, address, phone and business\_id. Parameters, a real response, 1 credit per call. 3. [API guides](https://perceptlayer.com/blog/category/api-guides) 7 Aug 2026 Updated 26 Oct 2026 Perceptlayer 6 min read ## [Yelp Reviews API: Business Search and Reviews as JSON](https://perceptlayer.com/blog/yelp-reviews-api-json) Three Yelp endpoints return search results, business details and reviews as JSON, 1 credit per call. Parameters, a real response and a cost example.