Google Maps Reviews API: Get More Than 5 Reviews With next_token

Published October 29, 2026

You call the Google Maps reviews endpoint, count the rows and get exactly five. That looks like the complaint behind so many searches: the Google Places API returns five reviews per place, and the rest of the history is out of reach. Before you go shopping for a headless-browser scraper, stop counting rows and read the key after them. The rows are a page. That key is a cursor.

The first page holds five reviews and a cursor

The five came from the request. The business-reviews operation takes a limit whose documented default is 20, and my validation call asked for limit=5. It returned five review objects and a next_token string. A page size and a ceiling are different things, and this response only shows the first. What Google's own Places endpoint does is outside this page; this one hands you a pointer to more.

Diagnose your own place before writing a loop. Export the place as BUSINESS_ID; it is a google_id copied from a search row, as covered below. Create the platform key in the dashboard and substitute it for the placeholder.

curl --get 'https://api.opendata-api.com/api/project/google-maps-extractor/business-reviews' \
  --data-urlencode 'key=YOUR_API_KEY' \
  --data-urlencode "business_id=$BUSINESS_ID" \
  --data-urlencode 'limit=5' \
  --output page1.json

Then read the shape locally. This prints the cursor's length, never the cursor.

import json

with open("page1.json", encoding="utf-8") as handle:
    gateway = json.load(handle)
body = gateway["data"]
token = body.get("next_token")
print("rows:", len(body["data"]))
print("cursor length:", len(token) if isinstance(token, str) else None)
print("echoed inputs:", sorted(body["request_params"]))

On the validation call this reported five rows, a 68-character cursor and ['business_id', 'limit']. That was page one only, so nothing here claims how deep a real history goes.

The cursor leaves as next_token and returns as next_page_token

The response names the cursor next_token. The request parameter is next_page_token. Read one and send the other, and a loop that parses correctly can still go wrong: a service that ignores a query parameter it does not recognise answers every call with page one. I did not send the wrong name to see what this gateway does, so treat that as a risk to design against, not a measured result.

body = gateway["data"]                  # inner reviews response
cursor = body.get("next_token")         # response key
params["next_page_token"] = cursor      # request key

Each response has three layers to pass: the HTTP status, the gateway code, then the status inside data. The cursor itself is opaque, so do not slice, decode or log it. Your platform key rides in the same query string, which is why the script below never prints a URL.

Pin business_id, country, lang and sort_by for the whole walk

A cursor continues one query. The documentation says to send it back with business_id and the other inputs unchanged. What the service does with a cursor paired with another place or order is untested here, so the script never allows it: the parameter dict is built once, outside the loop, and only next_page_token is added. Pin limit too, and mind the spelling: this operation takes lang, while the search and details operations take language.

The ID comes from a search row. Rows from locate-and-search and search-nearby carry google_id, place_id and cid, and reviews accept the 0x...:0x... Google Maps ID, the numeric CID or the ChIJ place ID. Finding places from a city name is the subject of the nearby search guide.

Stop on a missing token, a repeated page or a page cap

A walk needs three exits, because each catches a different failure.

  • No usable cursor. next_token is missing, null, empty or not a string, or data is empty. A last page was not observed, so every one of those ends the walk.
  • A repeated page. Fingerprint each page as the tuple of its review id values. A fingerprint seen before means the loop is re-reading, for example page one served again because the cursor went out under the wrong name. Stop and report it.
  • A page cap. max_pages bounds a walk that keeps returning fresh cursors. Each page is one request that spends platform credits, so the cap is also a spending limit.

Return the reason with the rows. A walk that ended on the cap is not a complete export, and a failure at any status layer is an error, not the end of the history.

Newest first: read until the first review you already hold

Monitoring a competitor is the opposite of an export: you want what is new since the last run. If reviews arrive newest first, read from the top and stop at the first id already in your database. Everything below it is older and already stored, so a normal poll costs one request.

The rule is only as good as the order. sort_by controls it, but the documentation lists no accepted values and I tested none, so the script reads the value from an environment variable and checks the result. timestamp is Unix seconds (time is text such as "4 months ago"), and on a newest-first page it never increases from one row to the next. My unsorted test page failed that check: its five timestamps sat 20, 0, 45, 68 and 83 days after the oldest. Try a candidate value on a limit=5 request, read the timestamps, and only then schedule polls.

Two guard rails belong in the poll. Keep a small page cap, since an empty database would otherwise walk the whole history. And save new rows only after the walk finishes: a poll that stored page one and crashed before page two would hide the older new reviews behind the stored anchor.

One script: backfill once, then poll for new reviews

backfill walks up to 50 pages and de-duplicates by review id; poll stops at the first stored review and prints low-rated newcomers. Set API_KEY and BUSINESS_ID in the environment, plus GMAPS_SORT_BY once you have proved a newest-first value. GMAPS_COUNTRY and GMAPS_LANG are optional.

import os
import sqlite3
import sys

import requests

URL = "https://api.opendata-api.com/api/project/google-maps-extractor/business-reviews"
API_KEY = os.environ["API_KEY"]  # platform key: never hard-code or print it

# Built once and reused for every page of a walk.
BASE = {"business_id": os.environ["BUSINESS_ID"], "limit": 20}
for name in ("country", "lang", "sort_by"):
    value = os.environ.get("GMAPS_" + name.upper())
    if value:
        BASE[name] = value


def fetch_page(session, cursor=None):
    params = {**BASE, "key": API_KEY}
    if cursor:
        params["next_page_token"] = cursor  # request name differs from the response key
    try:
        response = session.get(URL, params=params, timeout=30)
    except requests.RequestException as exc:
        raise RuntimeError(f"transport failure: {type(exc).__name__}") from None
    if response.status_code != 200:
        raise RuntimeError(f"HTTP {response.status_code}")
    gateway = response.json()
    body = gateway.get("data")
    if gateway.get("code") != 200 or not isinstance(body, dict) or body.get("status") is not True:
        raise RuntimeError(f"business failure: {gateway.get('message')}")
    return body


def newest_first(rows):
    stamps = [row["timestamp"] for row in rows]
    return all(a >= b for a, b in zip(stamps, stamps[1:]))


def walk(session, seen, max_pages, stop_at_seen):
    fresh, fingerprints, cursor = [], set(), None
    for _ in range(max_pages):
        body = fetch_page(session, cursor)
        rows = body["data"]
        if not rows:
            return fresh, "no rows"
        if stop_at_seen and not newest_first(rows):
            raise RuntimeError("page is not newest first; check GMAPS_SORT_BY")
        fingerprint = tuple(row["id"] for row in rows)
        if fingerprint in fingerprints:
            return fresh, "repeated page"
        fingerprints.add(fingerprint)
        for row in rows:
            if row["id"] in seen:
                if stop_at_seen:
                    return fresh, "reached a stored review"
                continue
            seen.add(row["id"])
            fresh.append(row)
        cursor = body.get("next_token")  # response key
        if not isinstance(cursor, str) or not cursor:
            return fresh, "no next_token"
    return fresh, "page cap"


def main(mode):
    db = sqlite3.connect("reviews.db")
    db.execute("CREATE TABLE IF NOT EXISTS reviews "
               "(id TEXT PRIMARY KEY, ts INTEGER, rating INTEGER, text TEXT, url TEXT)")
    seen = {row[0] for row in db.execute("SELECT id FROM reviews")}
    poll = mode == "poll"
    with requests.Session() as session:
        fresh, reason = walk(session, seen, 3 if poll else 50, stop_at_seen=poll)
    # Save only after the walk: a crash between pages must not hide older new reviews.
    db.executemany("INSERT OR IGNORE INTO reviews VALUES (?, ?, ?, ?, ?)",
                   [(r["id"], r["timestamp"], r["rating"], r["text"], r["url"]) for r in fresh])
    db.commit()
    print(f"{mode}: {len(fresh)} new reviews, stopped on: {reason}")
    if poll:
        for row in fresh:
            if row["rating"] is not None and row["rating"] <= 2:
                print("low rating:", row["rating"], row["url"])


if __name__ == "__main__":
    if sys.argv[1:] not in (["backfill"], ["poll"]):
        sys.exit("usage: python reviews.py backfill|poll")
    main(sys.argv[1])

Run python reviews.py backfill once, then schedule python reviews.py poll. Stopping on "no next_token" or "reached a stored review" is normal; "repeated page" and "page cap" deserve a look.