Google Maps 评论接口只返回 5 条?用 next_token 翻页拿全评论

发布于 2026年10月29日

一页刚好 5 条评论,不少人马上下结论:和官方 Places API 一样,每个地点最多只能拿 5 条,要全量就得去爬地图页面。对 business-reviews 来说,这个结论多半下早了。官方 Place Details 的 5 条是封顶;这里的 5 只是一页的条数——我们的测试请求带了 limit=5,data 里正好 5 条,响应里同时还有一个字符串 next_token。页大小和上限是两件事,游标就是下一页的入口。真正的坑在命名上:游标出来叫 next_token,传回去却要叫 next_page_token。

第一页只有 5 条评论,但后面还有

先用最小的请求确认现象,不要一上来写循环。business_id 来自商家搜索结果:只有城市名时用 locate-and-search,query 写成 attorney in Philadelphia, PA, USA 这样;已有经纬度时用 search-nearby。每一行都带 google_id(形如 0x…:0x…)、place_id、cid,还有 phone、website_url、working_hours,电话、网站和营业时间在这一步就能收到。文档说这三种标识都能当 business_id,测试调用用的是 0x 形式,下面也用它,取值是文档里的示例 ID。

curl --get 'https://api.opendata-api.com/api/project/google-maps-extractor/business-reviews' \
  --data-urlencode 'key=YOUR_API_KEY' \
  --data-urlencode 'business_id=0x80c2c621d7d91b49:0x5e3e80cfbddfba70' \
  --data-urlencode 'limit=5'

把 YOUR_API_KEY 换成自己的平台密钥,放在服务端环境变量里。复制示例不会自动发请求,执行一次才算一次调用。响应按三层读:HTTP 状态、网关外层的 code(200 才继续)、里面那层的 status(为 true)。HTTP 非 2xx 是传输或鉴权问题;code 不是 200 先看 message;status 不是 true,是评论接口自己报告没成功。任何一层失败都不要读成「这家店没有评论」,监控脚本最怕的就是把失败当成平静。

网关外层  code / message / data
└─ data   status / request_id / data[] / next_token / request_params
   └─ data[]  本页评论:id、rating、text、timestamp、user_name、owner_response_* ……

limit 默认 20,上限文档没写,我们也没测过,所以别指望一次要个很大的 limit 就能拿全。文档的说法是还有更多评论时才返回 token,有 token 就接着翻。照片是同一个 business_id 的另一条线:先用 business-photos-categories 看分类,再把分类交给 business-photos 的 category。

游标出来叫 next_token,传回去要叫 next_page_token

位置字段名
响应里(data.next_token)next_token
下一次请求的查询参数next_page_token

循环里最顺手的写法是 params["next_token"] = token:键读对了,名字发错了。传错的参数名会被拒绝还是被忽略,文档没写,我们也没试过。如果是被忽略,后果是静默的——每一轮都拿回第一页,循环看上去一直在工作,重复评论却越攒越多。拿到重复评论时先查两处:游标有没有放进 next_page_token,整轮的其他参数有没有被改动。诊断很便宜:第二次请求把游标放进 next_page_token,对比两页的评论 id,交集应当为空。

curl --get 'https://api.opendata-api.com/api/project/google-maps-extractor/business-reviews' \
  --data-urlencode 'key=YOUR_API_KEY' \
  --data-urlencode 'business_id=0x80c2c621d7d91b49:0x5e3e80cfbddfba70' \
  --data-urlencode 'limit=5' \
  --data-urlencode 'next_page_token=<上一页 data.next_token 的原值>'

游标按不透明字符串处理:不截断、不手工转义(交给 HTTP 库编码)、不去拆解。它和密钥一样,别写进公开日志、截图或工单。它能保持多久有效,我们没有验证,所以别存下来隔天接着翻;想续读就从第一页重新走,或者用后面的「遇到已入库就停」。

整轮翻页固定 business_id、country、lang 和 sort_by

文档没说游标是否绑定了商家和排序,那就按「绑定」来用:一轮翻页里只有 next_page_token 在变,business_id、country、lang、sort_by,连同 limit,从头到尾不动。中途换了 sort_by,你无从知道游标是接着旧顺序走还是按新顺序重排,漏读和重复都不会报错。

  • 评论接口的语言参数叫 lang,同一个项目里 locate-and-search、search-nearby、business-details 叫 language。别用一个通用语言字段转发给所有操作。
  • country、lang、sort_by 的可选值文档都没有列举,测试调用也没传过。要用,先发小请求确认一个值。
  • 想要最新优先,没有现成的已知取值可抄:试一个值,看返回的 timestamp(Unix 秒)是不是逐条递减,确认后再写进脚本。别用 time 判断先后,它是「4 个月前」这类相对文字。

三种停止条件:没有 token、整页重复、达到页数上限

最后一页长什么样(字段缺失、null 还是空串),我们没有观察到,所以不赌具体形态。

  • 没有可用 token:next_token 不是非空字符串就停。这是唯一能说「走到头了」的信号。
  • 整页重复:把每页评论的 id 拼起来算个指纹,同一个指纹第二次出现,说明游标没往前走——参数名传错了,或者游标在兜圈子。用内容而不是 token 字符串做指纹,是因为不管游标为什么没推进,只要读到的是同一页,指纹就一样。零星重复的 id 只做去重,不停;整页重复才是硬停。
  • 页数上限:每页是一次计费调用,max_pages 同时是成本上限和失控循环的最后一道闸。碰到上限只能说「没读完」。

搜索结果行里的 reviews_count 可以当对照,差得很远就记一笔。它和能翻到的条数是否同一口径,我们没有验证,不当停止条件。脚本最后会打印停止原因,只有 no_token 才表示走到了游标的尽头。

按最新排序:读到已入库的评论就停

监控竞品新差评,没必要每次都从头翻到底。顺序固定成最新优先之后,规则很短:从第一页往下读,遇到第一条已经入库的评论就停,后面的都比它旧。

  • 以评论 id 为键入库,不用 time 文字或作者名去重。
  • 第一页的 timestamp 不是递减,脚本直接拒绝轮询,不去猜。这条规则只在顺序可靠时成立。
  • 平时一次轮询只要一页:没有新评论时第一条就命中已入库,有几条新的,也会在同一页里撞上已入库的那条。一次涌进超过一页的新评论,才会翻到第二页。
  • 新评论里 rating 不高于 2 的单独标出来当差评预警。店家回复在 owner_response_* 字段,我们的样本里它们全是 null,使用前先判空。
  • 如果你观察到被编辑过的旧评论会排到前面,一条命中就停可能太激进,可以改成连续命中 3 条再停。我们没见到这种情况,不必一开始就加。

轮询频率按业务定,差评预警按小时或每天一次都够;平时一次轮询只花一次调用,真正的成本在回填。第一次运行时库是空的,没有「已入库」可命中,同一套代码就当回填用:关掉「遇到已入库就停」,只靠三种停止条件收尾。

完整脚本:先回填历史,再定时增量

先设置 OPENDATA_API_KEY;回填不需要 REVIEWS_SORT_BY,轮询需要一个你验证过的最新优先取值。运行一次 python reviews_walk.py backfill '<business_id>',之后用 cron 定时跑 python reviews_walk.py poll '<business_id>'。回填最多 30 页、每页 20 条,轮询最多 3 页,数字写在 main() 里,按需要改。评论数很大的商家,回填会以 page_cap 收尾,这时历史是不完整的,脚本如实打印,不标成完成;想读更深就调高那个 30 再跑一次,已入库的评论会被跳过,但游标不能隔天续翻,前面的页要重新读一遍并重新计费。三层失败在脚本里各自抛错,不会被悄悄当成「没有新评论」,报错信息也不带完整 URL,避免把密钥写进日志。

"""Walk Google Maps reviews: backfill once, then poll newest-first for new ones."""
import hashlib
import os
import sqlite3
import sys

import requests

BASE = "https://api.opendata-api.com/api/project/google-maps-extractor"
API_KEY = os.environ["OPENDATA_API_KEY"]          # never print or commit this
SORT_BY = os.environ.get("REVIEWS_SORT_BY", "")   # a value you verified as newest-first
FIXED = {                                         # identical on every page of one walk
    "country": os.environ.get("REVIEWS_COUNTRY", ""),
    "lang": os.environ.get("REVIEWS_LANG", ""),
    "sort_by": SORT_BY,
    "limit": 20,
}


def fetch_page(business_id, token=""):
    params = {"key": API_KEY, "business_id": business_id,
              "next_page_token": token, **FIXED}   # response says next_token, request says next_page_token
    params = {k: v for k, v in params.items() if v}
    try:
        resp = requests.get(f"{BASE}/business-reviews", params=params, timeout=30)
    except requests.RequestException as exc:
        raise RuntimeError(type(exc).__name__) from None   # the message would carry the key
    if not resp.ok:                                   # layer 1: HTTP
        raise RuntimeError(f"HTTP {resp.status_code}")
    gateway = resp.json()
    if gateway.get("code") != 200:                    # layer 2: gateway envelope
        raise RuntimeError(f"gateway: {gateway.get('message')}")
    body = gateway.get("data") or {}
    if body.get("status") is not True:                # layer 3: endpoint status
        raise RuntimeError("endpoint status is not true")
    return body


def fingerprint(rows):
    return hashlib.sha1("|".join(str(r.get("id")) for r in rows).encode()).hexdigest()


def newest_first(rows):
    stamps = [r.get("timestamp") for r in rows]
    return all(isinstance(t, (int, float)) for t in stamps) and stamps == sorted(stamps, reverse=True)


def walk(business_id, db, stop_at_seen, max_pages):
    new, token, seen_pages = [], "", set()
    for page_no in range(1, max_pages + 1):
        body = fetch_page(business_id, token)
        rows = body.get("data") or []
        if not rows:
            return new, "empty_page"
        page_id = fingerprint(rows)
        if page_id in seen_pages:
            return new, "repeated_page"               # the cursor did not advance
        seen_pages.add(page_id)
        if stop_at_seen and page_no == 1 and not newest_first(rows):
            raise RuntimeError("page one is not newest-first; refusing to poll")
        for row in rows:
            known = db.execute("SELECT 1 FROM reviews WHERE business_id=? AND id=?",
                               (business_id, row["id"])).fetchone()
            if known:
                if stop_at_seen:
                    db.commit()
                    return new, "reached_known_review"
                continue                              # backfill: skip, keep walking
            db.execute("INSERT INTO reviews VALUES (?, ?, ?, ?, ?, ?)",
                       (business_id, row["id"], row.get("timestamp"), row.get("rating"),
                        row.get("user_name"), row.get("text")))
            new.append(row)
        db.commit()
        token = body.get("next_token")
        if not isinstance(token, str) or not token:
            return new, "no_token"
    return new, "page_cap"


def main():
    mode, business_id = sys.argv[1], sys.argv[2]      # backfill|poll <business_id>
    if mode == "poll" and not SORT_BY:
        sys.exit("set REVIEWS_SORT_BY to a newest-first value you verified")
    db = sqlite3.connect("reviews.db")
    db.execute("CREATE TABLE IF NOT EXISTS reviews (business_id TEXT, id TEXT, ts INTEGER,"
               " rating INTEGER, user_name TEXT, text TEXT, PRIMARY KEY (business_id, id))")
    poll = mode == "poll"
    new, why = walk(business_id, db, stop_at_seen=poll, max_pages=3 if poll else 30)
    print(f"{mode}: {len(new)} new, stopped on {why}")   # only no_token reached the end
    for row in new if poll else []:
        if (row.get("rating") or 5) <= 2:
            print("LOW", row["rating"], row.get("user_name"), (row.get("text") or "")[:80])


if __name__ == "__main__":
    main()

单次调用费用见定价。