google-maps/
search

按 query 和 location 搜索公开 Google Maps 地点,返回标准化名称、分类、地址、联系方式、评分、评价数、URL 和坐标。

Google Maps Search API

query 与 location 输入
可选地理上下文
请求 1–2,000 条结果
标准化地点记录
每条结果 0.15 积分
等待提交
等待提交

填写参数并发送请求,任务状态和标准化结果会显示在这里。

README

由 SocQ 维护 · 更新于

Google Maps Search

Google Maps Search 将商家、分类或地点 query 与必填 location 转换为结构化公开地点记录。每条结果都使用与 provider 无关的 PlaceItem schema,因此可用的身份、地址、联系信息、评分、评价数和坐标字段可以直接进入研究与数据补全系统,客户端无需绑定来源特有字段。

Google Maps Search API 主要特性

  • 按 query 与 location 发现地点将 coffee 等必填非空 query 与 New York, NY 等必填 location 组合,发现匹配的公开地点。
  • 可选地理控制需要更明确的地理上下文时,可增加 country、成对的 latitude 与 longitude,以及 zoom_level;未提供的选填字段不会被推断补齐。
  • 标准化地点身份与联系方式在字段可用时,以稳定 PlaceItem 结构返回 ID、来源 URL、名称、分类、地址、公开电话、网站和采集时间。
  • 评分与地理坐标为每条地点记录保留可用的评分、评价数、城市、地区、国家、纬度和经度,并安全处理来源未提供的字段。

Google Maps Search API 参数

参数必填描述
query必填必填的非空地点、商家或分类搜索词。
location必填必填的非空可读搜索区域,例如城市、地区或地址。两个坐标都省略时,runtime 会将它与 query 组合用于发现。
country可选可选的非空国家名称或代码,作为地理上下文传递。
latitude可选可选纬度,范围为 -90 到 90,必须与 longitude 同时提供。
longitude可选可选经度,范围为 -180 到 180,必须与 latitude 同时提供。
zoom_level可选可选的地图缩放级别整数,范围为 0 到 21。
results_limit可选保存地点记录的数量上限;默认值为 100,可设置为 1 到 2,000 的整数。

如何使用 Google Maps Search API

提交 query 与 location,跟踪异步任务,再通过 cursor 分页读取标准化地点记录。

  1. 准备非空 query 和 location;可选增加 country、坐标、zoom_level,以及 1 到 2,000 的 results_limit。
  2. 将请求 POST 到 /v1/google-maps/search,并保存返回的 task_id。
  3. 轮询 /v1/tasks/{task_id},直到任务成功或返回失败。
  4. 读取 data.results.items;has_more 为 true 时,将 next_cursor 继续传给任务接口。
curl -X POST "https://api.socq.ai/v1/google-maps/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"coffee","location":"New York, NY","country":"US","results_limit":3}'

# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items;has_more 为 true 时继续使用 next_cursor

Google Maps Search API 最佳使用场景

  • 发现本地商家: 在指定城市、街区或地址区域内,构建匹配某个分类或服务的数量受控公开商家列表。
  • 补全地点数据: 为 CRM 或研究队列中的地点候选补充可用名称、分类、地址、电话、网站与坐标。
  • 市场与覆盖研究: 比较不同独立地理搜索所采集的地点数量、分类、评分和评价规模。
  • 准备地点候选清单: 使用公开 URL、联系字段、评分上下文与坐标,筛选需要进一步核对或获取详情的地点。

Google Maps Search API 使用建议

  • 使用明确的分类或商家搜索词,并在 location 中填写清楚的城市、街区或地址;模糊组合可能产生宽泛或有歧义的匹配。
  • 只有在地理上下文可靠时才发送 country、坐标或 zoom_level;latitude 与 longitude 必须成对提供,并分别保持在规定范围内。
  • 让 results_limit 接近实际需要的记录数。它控制采集上限,而任务 GET 的 limit 控制单次响应返回多少条已存储记录。
  • 已存储结果超过首个任务响应页时,持续使用 next_cursor,直到 has_more 为 false。
  • 将说明、联系字段、评分、评价数和坐标作为选填公开数据处理,并保留 collected_at 以便进行时点对比。

除了 Google Maps Search API,需要其他类型的 Google Maps 公开数据时,可以使用以下 API。

探索其他平台

还可以将 Google Maps 数据与其他已支持社交平台的公开数据结合使用。

Google Maps Search API — 常见问题

Google Maps Search API 是一个通过必填 query 和 location 发现公开地点的异步接口。它以与 provider 无关的 PlaceItem 记录返回可用身份、分类、地址、联系方式、评分、评价数、URL 和地理字段。

query 和 location 都是必填非空字符串。country、latitude、longitude、zoom_level 和 results_limit 是选填字段。

需要。当前请求契约只接受成对坐标。可以同时省略两个字段,让 runtime 组合 location 与 query;也可以同时提供 -90 到 90 的 latitude 和 -180 到 180 的 longitude。

results_limit 是采集上限,不保证一定返回相同数量。来源可能只返回较少的公开匹配,并且公开身份相同的记录在同一任务中只存储一次。

公开地点结果可能缺少说明、分类、地址、电话、网站、评分、评价数、URL 或部分 location 字段。客户端应安全处理 null,而不是将其视为任务失败。

每条已存储地点记录消耗 0.15 SocQ 积分。预扣按 results_limit 计算,省略时按 100 条计算;任务成功后按实际已存储结果数结算,空结果集不产生结果费用。