商户标识与位置
使用商户名称、类别、格式化地址、坐标和 Maps URL 来组织本地商户数据集。
完整的接口约定请参见 API 文档。
curl https://gmapscrawl.com/api/v1/search \
-H "Authorization: Bearer $GMSCRAPER_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: seattle-coffee-search-001" \
-d '{"q":"coffee shops in Seattle","page":1,"extra":false}'示例为空响应。正式搜索会返回可用的商户。请将 API 密钥保存在服务器端;为新任务使用新的幂等键,并在原请求不变的重试中保留同一幂等键。
{
"data": {
"total": 0,
"params": {
"q": "coffee shops in Seattle",
"page": 1,
"hl": "en",
"extra": false
},
"businesses": []
},
"request_id": "req_example",
"schema_version": "2026-09-22"
}API 在同一响应中返回 JSON。超时后,请使用相同的 Idempotency-Key 以不变的请求体重试。测试凭据返回模拟数据,不消耗您的正式额度。
结构化商户数据
从响应中读取 data.businesses。每个商户将其列表字段归入 place 之下;字段可用性取决于来源。
使用商户名称、类别、格式化地址、坐标和 Maps URL 来组织本地商户数据集。
读取可用的电话号码、网站、评分和评价数。启用 extra 后,可请求电子邮箱和社交联系方式补全。
保留 place.dataId 以查询评价和照片。检查 place.observedAt 和 contactsCheckedAt,了解数据的观测时间。
不可用字段可能为 null 或空值,信息补全也可能报告 not_found 或 failed。某条记录并不保证对应的电子邮箱或网站存在。Maps 详情可以在保留原始观测时间戳的情况下复用最多 730 天;使用记录前请评估其新鲜度。
了解数据新鲜度 →一个聚焦的请求
在 Authorization 头中携带服务器端 API 密钥,发送 JSON 请求体。只有 q 是必填的。
| 参数 | 要求 | 用途 |
|---|---|---|
| q | 必填 | 商户关键词和地点,例如“西雅图的咖啡店”。长度为 2–200 个字符。 |
| page | 默认:1 | 1 到 10 之间的页码。每次请求最多返回 20 家商户。 |
| ll | 可选 | 形如 @47.6062,-122.3321,12z 的 Maps 视口,用于引导搜索位置。 |
| hl | 默认:en | 搜索使用的语言代码。 |
| gl | 可选 | 用于限定查询的两位国家/地区代码,不是严格的地理过滤器。 |
| extra | 默认:false | 设为 true 以请求可用的电子邮箱和社交联系方式补全。这可能会更耗时。 |
响应会在 data.params 中回显规范化后的参数。data.total 统计的是本次响应中的商户数,而不是 Google Maps 上的商户总数。当您的工作流需要更多结果时,请明确选择其他页码。
构建您的第一个集成
Search API 是同步的:直接从 HTTP 响应中读取结果。
在 API 工作区创建具有 scrapes:write 权限的密钥。将密钥存放在服务器环境中,并在请求中发送 Authorization: Bearer。
打开 API 密钥选择一个类别和地点,请求第 1 页,并检查返回的列表字段。做市场对比时,针对要比较的各个区域分别发起搜索。
将匹配商户的 place.dataId 作为 fid,获取评价页或相册页。这些是独立的请求,各自返回记录。
探索 Reviews API为真实请求做规划
每个成功的正式搜索页消耗一个 API 请求单位,包括空结果。REST 和 MCP 共享 API 额度。在线抓取工具和浏览器扩展的订阅有独立额度。速率限制、凭据、服务容量和来源可用性仍然适用。
对比 API 套餐 →请在 HTTP 客户端中允许最多 180 秒。超时可能留下正在处理且已预留请求单位的任务。使用完全相同的请求体和 Idempotency-Key 重试该请求。在开始新尝试前,请先查看错误详情和可重试性。
了解重试机制 →返回一个 JSON 封装,包含 data.businesses、data.total、规范化后的 data.params、request_id 和 schema_version。商户记录包含可用的列表字段,如名称、地址、类别、联系信息、评分和 Maps 标识符。
可以。端点接受标准的 HTTP POST 请求,使用 JSON 和 Bearer 认证。上面的示例使用了 Python 标准库和服务器端 JavaScript fetch。任何能发送这些请求头和请求体的 HTTP 客户端都可以集成。
一个搜索页返回 0 到 20 家商户。page 参数接受 1 到 10。每个成功的正式页(包括空页)消耗一个 API 请求单位;一次搜索并不保证每页都有 20 家商户。
可以。从商户记录中复制 place.dataId,并将其作为 fid 传给独立的 Reviews 或 Photos API。这些端点每次请求返回一个有边界的页面。API 概览页链接了每个端点的字段、示例和分页规则。
不是。将 extra 设为 true 以请求可用的联系方式补全。网站、邮箱和社交主页都可能缺失。请检查 enrichmentState 和 fieldStates,并在您的应用中明确标记不可用数据。
如果您有测试凭据,其响应是模拟的,不消耗正式 API 额度。请将这些结果标记为模拟数据。正式密钥需要有效的 API 权益和可用的服务容量,成功的正式调用会消耗请求单位。