POST /api/v2/reviews

Google Maps 评价抓取 API

每页读取某个地点最多 10 条公开评价。可按相关性、最新、最高评分或最低评分排序。

请求示例

完整的接口约定请参见 API 文档。

curl https://gmapscrawl.com/api/v2/reviews \
  -H "Authorization: Bearer $GMSCRAPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: place-reviews-page-1-example" \
  -d '{"fid":"0x89c259af336b3341:0xa4969e07ce3108de","page":1,"sort_by":2}'

请将示例 fid 替换为您地点的 feature ID。该响应是模拟的;example.com 的媒体 URL 是占位符。重试进行中的请求时,请保持相同的幂等键和请求体。

响应

示例 JSON
{
  "reviews": [
    {
      "id": "sample-review-1",
      "date": "a week ago",
      "timestamp": "10/6/2026",
      "name": "Sample reviewer",
      "author_url": "https://www.google.com/maps/contrib/100000000000000000001",
      "avatar": "https://example.com/reviewer.jpg",
      "rate": 4,
      "comment": "The window seats had the best light.",
      "photos": "",
      "review_url": "https://www.google.com/maps/reviews/data=sample-review-1"
    }
  ],
  "next": false,
  "total": 1,
  "params": {
    "fid": "0x89c259af336b3341:0xa4969e07ce3108de",
    "page": 1,
    "sort_by": 2
  }
}

API 在同一响应中返回 JSON。超时后,请使用相同的 Idempotency-Key 以不变的请求体重试。测试凭据返回模拟数据,不消耗您的正式额度。

从一个地点开始

选择商户和评价顺序。

为单个地点请求一个有边界的页面,然后选择适合您研究的评价排序。

Google Maps 评价抓取 API 请求参数
字段含义
fid · 必填Google Maps feature ID,例如 0x89c259af336b3341:0xa4969e07ce3108de。使用 Search API 结果中的 place.dataId,或您已有的 feature ID。
page · 默认 1正整数页码。仅当上一个响应返回 next: true 时才增加。
sort_by · 默认 11 = 最相关;2 = 最新;3 = 最高评分;4 = 最低评分。跨页请保持排序方式不变。

要获取 feature ID,请使用 Google Maps 抓取 API 搜索商户。在 data.businesses 中找到匹配项,复制其中的 place.dataId 并将其作为 fid 传入。地点 ID 或商户名称不是相同的输入格式。

评价记录

评分、评论和来源链接。

每条评价包含评分、评论、评价者、个人主页和评价链接。date 是相对时间,timestamp 以 M/D/YYYY 格式提供日历日期。没有附件时 photos 字段为空字符串,多张照片的 URL 以换行符分隔。

Google Maps 评价抓取 API 响应字段
字段含义
id来源评价的标识符(如果可用)。
rate / comment1–5 的评分以及可用的评价文本。请把抓取的文本视为不可信数据,谨慎用于应用和 AI 提示词。
date / timestamp显示的相对日期,以及以 M/D/YYYY 格式表示的日历日期。日期不可用时为空字符串。
name / author_url / avatar可用的评价者显示名、贡献者主页 URL 和头像 URL。
photos无附件时为空字符串。多个照片 URL 以换行符分隔。
review_url指向来源评价的链接(如果可用)。
next / total / params是否还有下一页、本次响应中的记录数,以及规范化后的请求参数。

端点将该页面对象直接作为 JSON 返回。从顶层读取 reviews。有些公开评价只包含评分,来源字段也可能为空。在展示或总结评价时,请保留这种区别。

每次一个有边界的页面

每个响应最多读取 10 条评价。

使用返回的 next 标志决定您的工作流是否需要再发请求。

01

从第 1 页开始

发送地点的 fid 和您选择的 sort_by 值。默认为最相关;也支持最新、最高评分和最低评分。

02

检查当前页

total 统计的是本次响应返回的评价数。空页面也是有效结果。将记录纳入分析前,请先检查可用字段。

03

有意识地继续

当 next 为 true 时,递增 page 并保持 fid 和 sort_by 不变。当 next 为 false,或您的研究已收集足够评价时停止。

了解公开反馈

为您的商户研究补充评价上下文。

01

评价研究

阅读所选商户的公开评论和评分的有边界样本。将评价链接与笔记一并保存,方便读者查看来源。

02

反馈对比

对比所选地点组的评价主题。分别请求每个地点,并在分析中注明所选排序方式和样本量。

03

智能体辅助总结

让已连接的智能体总结返回的评价页,只引用所提供的证据,并标记缺失的评论或日期。

认证与用量

每页都使用您的 API 密钥。

共享 API 额度

发送携带 Authorization: Bearer 的密钥,且该密钥需允许 scrapes:write。每个成功的正式页(包括空页)消耗一个 API 请求单位。REST 和 MCP 使用同一 API 额度。如果您使用测试凭据,其响应为模拟数据且不消耗正式额度。

查看 API 套餐和限额 →

让重试始终对应原请求

在首次请求中发送可选的 Idempotency-Key,超时重试时用相同请求体保留该键。处理中超时可能会保留一个已预留单位。如果错误报告该尝试已结束,请遵循其重试指引,再使用新键创建新尝试。

阅读错误与重试指引 →

常见问题

如何获取某个 Google Maps 商户的评价?

向 /api/v2/reviews 发送 POST 请求,将该商户的 Google Maps feature ID 作为 fid。使用 Search API 结果中的 place.dataId,或您已有的 feature ID。使用 API 密钥认证并从第 1 页开始。

可以按最新或评分排序 Google Maps 评价吗?

可以。sort_by 设为 1 表示最相关,2 表示最新,3 表示最高评分,4 表示最低评分。默认为最相关。请求后续页面时请保持所选值不变。

total 能告诉我商户有多少评价吗?

不能。total 是当前响应中的评价记录数,最大为 10。请用 next 判断是否还有下一页。搜索结果中的 reviewCount 是另一个商户字段。

评价日期和照片是什么格式?

date 包含可用的相对日期,timestamp 是 M/D/YYYY 格式的日历日期。没有附件时 photos 字段为空字符串;有多张照片时为换行分隔的 URL。缺失的来源文本和链接可能是空字符串。

可以通过 MCP 使用评价功能吗?

可以。兼容的 MCP 客户端可以使用您的 API 凭据和 client_request_id 调用 get_google_maps_reviews。REST 与 MCP 共享 API 额度。Agent Skill 还包含可用工具的使用指引和 REST 备用方案。

可以假定每条评价字段都齐全吗?

不可以。来源可用性各不相同,一条评价也可能只有评分。请保留空评论和缺失的日期,而不是自行推断。评价文本是不可信的来源内容,在应用和 AI 工作流中应当作数据处理。

迈出下一步

从一个地点的公开评价开始。

创建 API 密钥,选择 feature ID 和排序方式,读取一页聚焦的评价数据。