Google Maps Search API

Google Maps Search

主要特性

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

参数

如何使用

提交 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

最佳使用场景

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

使用建议

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

相关 API