guide
How to get Google Maps reviews by API, not just the first five
If you have built anything on top of Google reviews, you have met the limit: the Places API returns at most five reviews for a place. Five is enough to show a star rating on a store page. It is not enough for sentiment analysis, reputation monitoring or a study of a competitor's customers. This guide shows how to pull a place's reviews as structured JSON with the ScrapeNest API, how to run large pulls as background jobs, and how to budget the credits.
Why the Places API stops at five
Google's Place Details documentation says the reviews field returns "up to five user-submitted Review objects". There is no page token for more, so the official API cannot give you a place's review history.
The ScrapeNest Google Maps reviews endpoint returns a place's reviews as one JSON list instead. POST /v1/scrape/google-maps/reviews returns up to 10,000 reviews per request, with duplicates removed and the newest first.
Before you start
- Create a ScrapeNest account. The free plan includes 1,000 credits a month and needs no card. Verify your email address, then mint an API key on the dashboard; a key on an unverified account gets
403 email_not_verified. - Install the SDK for your language:
pip install scrapenestfor Python 3.9 or later, ornpm install scrapenestfor Node.js 18 or later. Both are at version 0.5.2. Plain HTTP works too, so each step below also has a curl version. - Keep the key out of your code. The examples read it from the
SCRAPENEST_API_KEYenvironment variable.
Step 1: name the place
You do not have to look up an ID first. The place_id field takes the place's name and city, such as "Katz's Delicatessen, New York". It also accepts any Google Maps URL of the place, a maps.app.goo.gl share link, a ChIJ… place ID, or the 0x…:0x… ID that appears in Maps URLs.
When a name matches more than one place, the call is refused with 409 place_ambiguous, free of charge, and the message lists the candidates with their place IDs. Send the ID of the one you meant. Every successful response carries the resolved place_id, so store it and skip the name lookup on later pulls.
Step 2: pull a few hundred reviews
For pulls of up to a few hundred reviews, the synchronous call is the simplest. In Python:
import os
from scrapenest import Client
client = Client(os.environ["SCRAPENEST_API_KEY"])
res = client.maps_reviews("Katz's Delicatessen, New York", max_reviews=200)
print(res.name, res.rating, res.review_count, res.place_id)
for review in res.reviews:
print(review.posted_at_iso, review.rating, review.author_name)
print((review.text or "")[:200])
print(len(res.reviews), "reviews,", res.credits_charged, "credits")
The same call in TypeScript:
import { ScrapeNest } from "scrapenest";
const client = new ScrapeNest({ apiKey: process.env.SCRAPENEST_API_KEY ?? "" });
const res = await client.mapsReviews({
place_id: "Katz's Delicatessen, New York",
max_reviews: 200,
});
for (const review of res.reviews) {
console.log(review.posted_at_iso, review.rating, review.text?.slice(0, 200));
}
And with curl:
curl -X POST https://scrapenest.dev/v1/scrape/google-maps/reviews \
-H "Authorization: Bearer $SCRAPENEST_API_KEY" \
-H "Content-Type: application/json" \
-d '{"place_id": "Eiffel Tower, Paris", "max_reviews": 200}'
The synchronous endpoint streams its response, so the HTTP status line goes out before the work is done, and an error arrives inside a 200 response as {"error": {...}, "http_status": <status>}. The SDKs spot this and raise a typed error. With plain HTTP, check for an error key before you read reviews.
Step 3: run large pulls as background jobs
Above roughly 700 reviews, use the async variant, POST /v1/scrape/google-maps/reviews/async. It takes the same body, answers at once with 202 Accepted and a run_id, and does the work in the background. You then poll GET /v1/scrape/runs/{run_id} until the status is completed, failed or cancelled. A completed run's result holds the same body the synchronous call returns.
run = client.maps_reviews_async("Eiffel Tower, Paris", max_reviews=5000)
final = client.wait_for_run(run.run_id, poll_interval=10, timeout=1800)
if final.status == "completed":
reviews = final.result["reviews"]
print(len(reviews), "reviews,", final.credits_charged, "credits")
else:
print(final.status, final.error_code, final.error_message)
wait_for_run gives up after 300 seconds unless you pass a longer timeout, and raises TimeoutError when it does. The job keeps running on the server either way, so you can collect it later with client.get_run(run_id), or stop it with client.cancel_run(run_id). In TypeScript the same calls are mapsReviewsAsync, waitForRun, getRun and cancelRun:
const run = await client.mapsReviewsAsync({ place_id: "Eiffel Tower, Paris", max_reviews: 5000 });
const final = await client.waitForRun(run.run_id, { pollInterval: 10_000, timeout: 1_800_000 });
console.log(final.status, final.credits_charged);
With curl, submit the job, then poll the run:
RUN=$(curl -s -X POST https://scrapenest.dev/v1/scrape/google-maps/reviews/async \
-H "Authorization: Bearer $SCRAPENEST_API_KEY" \
-H "Content-Type: application/json" \
-d '{"place_id": "Eiffel Tower, Paris", "max_reviews": 5000}' | jq -r .run_id)
curl -s https://scrapenest.dev/v1/scrape/runs/$RUN \
-H "Authorization: Bearer $SCRAPENEST_API_KEY" | jq '{status, progress, credits_charged}'
Polling is free, but it counts toward your rate limit, so every 10 to 15 seconds is plenty for a big Maps run. While a large run is in progress, its record carries a progress object with current, target and detail that you can show as a progress bar. Runs expire after seven days.
Step 4: read the results
Each review comes back with these fields:
review_idandreview_urlratingfrom 1 to 5, andtextauthor_name,author_id,author_profile_urlandauthor_avatar_urlposted_atin Unix seconds,posted_at_iso, andrelative_timesuch as "2 weeks ago"language,helpful_count,photosandowner_reply
Treat text, photos and owner_reply as optional: a rating-only review has no text, and most reviews have no photos and no reply from the owner. Some reviews carry a date worked out from Google's relative label rather than an exact timestamp.
The place itself comes with name, address, rating, review_count, google_maps_url and star_histogram, which holds five counts from one star to five stars. Two details matter when you store the data:
- Reviews always come back newest first, whatever you send in
sort; that field is kept only for backward compatibility. Incremental syncs are simple as a result: keep the newestreview_idyou have, and on the next pull stop reading when you reach it. review_countis the total Google publishes for the place. On a busy place it is often much higher than the number of reviews Google makes reachable. Count thereviewsarray to see what you received, and read thenotefield for the reason.
How many reviews you can get
max_reviews accepts 1 to 10,000 and defaults to 200. What comes back depends on what Google exposes for the place. A place with a few hundred reviews usually returns all of them. On very large places Google exposes only part of the list, and on places with tens of thousands of reviews the practical ceiling is about 10,000 unique reviews per request. You are billed for the reviews returned, not the number you asked for.
What a pull costs
Reviews are billed in blocks of 50: 100 credits for each block of 50 reviews returned, rounded up, and a flat 40 credits when 50 or fewer come back.
| Reviews returned | Credits |
|---|---|
| 1 to 50 | 40 |
| 200 | 400 |
| 500 | 1,000 |
| 1,000 | 2,000 |
| 5,000 | 10,000 |
| 10,000 | 20,000 |
The free plan's 1,000 monthly credits cover one 500-review pull, or 25 pulls of 50 reviews or fewer. Paid plans start at $29 a month for 200,000 credits; see pricing. Repeating a request inside its cache window bills 1 credit. Pulls of 2,000 reviews or fewer are cached for an hour by default, and larger pulls are not cached unless you set cache_ttl_seconds.
Large requests are checked against your balance before they start. If returning every review you asked for would take the account past its overage limit, the call is refused with 402 insufficient_credits; lower max_reviews or top up.
Errors worth handling
409 place_ambiguous: the name matched several places. Pick one of the listed IDs.place_not_found,place_id_unresolvableandplace_id_format: the place could not be resolved. Try the place's Google Maps URL instead of its name. If a known place keeps resolving to the wrong location, send its current Maps URL inplace_url.- A failed async run ends with
status: "failed"pluserror_codeanderror_message. The run-level codestalledmeans the run used up its time budget; resubmit, or ask for fewer reviews.
The reviews reference and the run error table list every code.
Reviews from an AI assistant
The same data is a tool in the ScrapeNest MCP server. In Claude, Cursor or ChatGPT, ask something like "What do the newest Google reviews of Katz's Delicatessen complain about?" The maps_reviews tool takes the place name, waits about a minute, and hands back a run_id for poll_run if the pull is still going. One MCP call asks for at most 2,000 reviews; larger pulls go through the REST API.
Handle review data with care
Reviews are written by real people and include their names and profile links. Keep only the fields you need, and follow the data-protection rules that apply to you and your users.