POST /api/v1/search

Google Maps 抓取 API

按关键词和地点查找商户。在同一个 JSON 响应中接收最多 20 条结构化商户记录,可直接用于您的应用或研究工作流。

请求示例

完整的接口约定请参见 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 密钥保存在服务器端;为新任务使用新的幂等键,并在原请求不变的重试中保留同一幂等键。

响应

示例 JSON
{
  "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 以不变的请求体重试。测试凭据返回模拟数据,不消耗您的正式额度。

结构化商户数据

从 Maps 搜索到可用记录。

从响应中读取 data.businesses。每个商户将其列表字段归入 place 之下;字段可用性取决于来源。

01

商户标识与位置

使用商户名称、类别、格式化地址、坐标和 Maps URL 来组织本地商户数据集。

02

联系方式与声誉

读取可用的电话号码、网站、评分和评价数。启用 extra 后,可请求电子邮箱和社交联系方式补全。

03

标识符与观测日期

保留 place.dataId 以查询评价和照片。检查 place.observedAt 和 contactsCheckedAt,了解数据的观测时间。

让缺失和较旧的数据保持可见

不可用字段可能为 null 或空值,信息补全也可能报告 not_found 或 failed。某条记录并不保证对应的电子邮箱或网站存在。Maps 详情可以在保留原始观测时间戳的情况下复用最多 730 天;使用记录前请评估其新鲜度。

了解数据新鲜度 →

一个聚焦的请求

选择查询、页码和补全选项。

在 Authorization 头中携带服务器端 API 密钥,发送 JSON 请求体。只有 q 是必填的。

Google Maps Search API 参数
参数要求用途
q必填商户关键词和地点,例如“西雅图的咖啡店”。长度为 2–200 个字符。
page默认:11 到 10 之间的页码。每次请求最多返回 20 家商户。
ll可选形如 @47.6062,-122.3321,12z 的 Maps 视口,用于引导搜索位置。
hl默认:en搜索使用的语言代码。
gl可选用于限定查询的两位国家/地区代码,不是严格的地理过滤器。
extra默认:false设为 true 以请求可用的电子邮箱和社交联系方式补全。这可能会更耗时。

响应会在 data.params 中回显规范化后的参数。data.total 统计的是本次响应中的商户数,而不是 Google Maps 上的商户总数。当您的工作流需要更多结果时,请明确选择其他页码。

构建您的第一个集成

一个请求,一个有用的下一步。

Search API 是同步的:直接从 HTTP 响应中读取结果。

01

创建您的 API 密钥

在 API 工作区创建具有 scrapes:write 权限的密钥。将密钥存放在服务器环境中,并在请求中发送 Authorization: Bearer。

打开 API 密钥
02

搜索一个有边界的区域

选择一个类别和地点,请求第 1 页,并检查返回的列表字段。做市场对比时,针对要比较的各个区域分别发起搜索。

03

跟随地点标识符

将匹配商户的 place.dataId 作为 fid,获取评价页或相册页。这些是独立的请求,各自返回记录。

探索 Reviews API

为真实请求做规划

页面可预测,限额明确。

用量与可用性

每个成功的正式搜索页消耗一个 API 请求单位,包括空结果。REST 和 MCP 共享 API 额度。在线抓取工具和浏览器扩展的订阅有独立额度。速率限制、凭据、服务容量和来源可用性仍然适用。

对比 API 套餐 →

超时与重试

请在 HTTP 客户端中允许最多 180 秒。超时可能留下正在处理且已预留请求单位的任务。使用完全相同的请求体和 Idempotency-Key 重试该请求。在开始新尝试前,请先查看错误详情和可重试性。

了解重试机制 →

继续您的工作流

使用同一批商户数据的更多方式。

01

评价与相册数据

使用地点的 feature ID 获取公开评价或照片和视频元数据。

探索相册数据
02

连接 MCP 客户端

让兼容的 AI 客户端使用您的 API 凭据发现搜索、评价和照片工具。

设置 MCP
03

安装 Agent Skill

为您的智能体提供工作流说明、操作参考和用于 Google Maps 研究的 REST 备用方案。

探索该技能

常见问题

Google Maps 抓取 API 返回什么?

返回一个 JSON 封装,包含 data.businesses、data.total、规范化后的 data.params、request_id 和 schema_version。商户记录包含可用的列表字段,如名称、地址、类别、联系信息、评分和 Maps 标识符。

我可以在 Python 或 JavaScript 中使用该 API 吗?

可以。端点接受标准的 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 权益和可用的服务容量,成功的正式调用会消耗请求单位。

迈出下一步

构建您的第一次 Google Maps 搜索。

创建 API 密钥,选择一个查询和地点,并在同一响应中读取结构化商户数据。