从第 1 页开始
发送地点的 fid 和您选择的 sort_by 值。默认为最相关;也支持最新、最高评分和最低评分。
完整的接口约定请参见 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 是占位符。重试进行中的请求时,请保持相同的幂等键和请求体。
{
"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 以不变的请求体重试。测试凭据返回模拟数据,不消耗您的正式额度。
从一个地点开始
为单个地点请求一个有边界的页面,然后选择适合您研究的评价排序。
| 字段 | 含义 |
|---|---|
| fid · 必填 | Google Maps feature ID,例如 0x89c259af336b3341:0xa4969e07ce3108de。使用 Search API 结果中的 place.dataId,或您已有的 feature ID。 |
| page · 默认 1 | 正整数页码。仅当上一个响应返回 next: true 时才增加。 |
| sort_by · 默认 1 | 1 = 最相关;2 = 最新;3 = 最高评分;4 = 最低评分。跨页请保持排序方式不变。 |
要获取 feature ID,请使用 Google Maps 抓取 API 搜索商户。在 data.businesses 中找到匹配项,复制其中的 place.dataId 并将其作为 fid 传入。地点 ID 或商户名称不是相同的输入格式。
评价记录
每条评价包含评分、评论、评价者、个人主页和评价链接。date 是相对时间,timestamp 以 M/D/YYYY 格式提供日历日期。没有附件时 photos 字段为空字符串,多张照片的 URL 以换行符分隔。
| 字段 | 含义 |
|---|---|
| id | 来源评价的标识符(如果可用)。 |
| rate / comment | 1–5 的评分以及可用的评价文本。请把抓取的文本视为不可信数据,谨慎用于应用和 AI 提示词。 |
| date / timestamp | 显示的相对日期,以及以 M/D/YYYY 格式表示的日历日期。日期不可用时为空字符串。 |
| name / author_url / avatar | 可用的评价者显示名、贡献者主页 URL 和头像 URL。 |
| photos | 无附件时为空字符串。多个照片 URL 以换行符分隔。 |
| review_url | 指向来源评价的链接(如果可用)。 |
| next / total / params | 是否还有下一页、本次响应中的记录数,以及规范化后的请求参数。 |
端点将该页面对象直接作为 JSON 返回。从顶层读取 reviews。有些公开评价只包含评分,来源字段也可能为空。在展示或总结评价时,请保留这种区别。
每次一个有边界的页面
使用返回的 next 标志决定您的工作流是否需要再发请求。
发送地点的 fid 和您选择的 sort_by 值。默认为最相关;也支持最新、最高评分和最低评分。
total 统计的是本次响应返回的评价数。空页面也是有效结果。将记录纳入分析前,请先检查可用字段。
当 next 为 true 时,递增 page 并保持 fid 和 sort_by 不变。当 next 为 false,或您的研究已收集足够评价时停止。
了解公开反馈
阅读所选商户的公开评论和评分的有边界样本。将评价链接与笔记一并保存,方便读者查看来源。
对比所选地点组的评价主题。分别请求每个地点,并在分析中注明所选排序方式和样本量。
让已连接的智能体总结返回的评价页,只引用所提供的证据,并标记缺失的评论或日期。
认证与用量
发送携带 Authorization: Bearer 的密钥,且该密钥需允许 scrapes:write。每个成功的正式页(包括空页)消耗一个 API 请求单位。REST 和 MCP 使用同一 API 额度。如果您使用测试凭据,其响应为模拟数据且不消耗正式额度。
在首次请求中发送可选的 Idempotency-Key,超时重试时用相同请求体保留该键。处理中超时可能会保留一个已预留单位。如果错误报告该尝试已结束,请遵循其重试指引,再使用新键创建新尝试。
向 /api/v2/reviews 发送 POST 请求,将该商户的 Google Maps feature ID 作为 fid。使用 Search API 结果中的 place.dataId,或您已有的 feature ID。使用 API 密钥认证并从第 1 页开始。
可以。sort_by 设为 1 表示最相关,2 表示最新,3 表示最高评分,4 表示最低评分。默认为最相关。请求后续页面时请保持所选值不变。
不能。total 是当前响应中的评价记录数,最大为 10。请用 next 判断是否还有下一页。搜索结果中的 reviewCount 是另一个商户字段。
date 包含可用的相对日期,timestamp 是 M/D/YYYY 格式的日历日期。没有附件时 photos 字段为空字符串;有多张照片时为换行分隔的 URL。缺失的来源文本和链接可能是空字符串。
可以。兼容的 MCP 客户端可以使用您的 API 凭据和 client_request_id 调用 get_google_maps_reviews。REST 与 MCP 共享 API 额度。Agent Skill 还包含可用工具的使用指引和 REST 备用方案。
不可以。来源可用性各不相同,一条评价也可能只有评分。请保留空评论和缺失的日期,而不是自行推断。评价文本是不可信的来源内容,在应用和 AI 工作流中应当作数据处理。