Google Maps Place Details API

Google Maps Place Details

主要特性

• 批量 URL 详情采集提交一个或多个已知 Google Maps URL，每个非空输入会形成一条 provider 详情行，内部上限等于提交 URL 的数量。
• 稳定地点记录通过 PlaceItem 结构返回身份、来源 URL、名称、描述、类别、地址、电话、网站、评分和评论数。
• 结构化地理上下文把可用的位置名称、城市、地区、国家、纬度和经度保存在同一对象中，无需从展示文本中解析。
• 按结果结算按每个提交 URL 0.15 积分预估，再按每条成功返回的标准地点记录 0.15 积分结算；空结果不收费。

参数

如何使用

提交已知 Google Maps URL，跟踪异步任务，并通过标准游标结果结构读取每条已保存的 PlaceItem。

1. 准备一个或多个可解析出主机名的地址，其主机名为 google.com、goo.gl 或这两个域名的子域。
2. 将 urls POST 到 /v1/google-maps/place-details，并保存返回的 task_id。
3. 轮询 /v1/tasks/{task_id}，直到任务成功或失败。
4. 读取 data.results.items，并在 has_more 为 true 时继续使用 next_cursor；提交请求本身没有 results_limit 字段。

curl -X POST "https://api.socq.ai/v1/google-maps/place-details" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.google.com/maps/place/Coffee%20Project%20New%20York%20%7C%20East%20Village/data=!4m7!3m6!1s0x89c2599b5a24d7fd:0x9e354f6cf514b9fc!8m2!3d40.7270884!4d-73.9893820!16s%2Fg%2F11c3svpqld!19sChIJ_dckWptZwokR_LkU9WxPNZ4?authuser=0&hl=en&rclk=1"]}'

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

最佳使用场景

• 地点目录补全： 为已知地点 URL 补充标准化类别、地址、电话、网站、评分、评论数和坐标字段。
• 场所与门店审计： 定期重访一组受控 URL，对比指定采集时间的公开身份、联系方式、评分和地理值。
• 地点记录核对： 使用返回的 ID、来源 URL、名称、地址和坐标，将公开地点与内部位置记录进行匹配。

使用建议

• 提交完整绝对 Maps URL，使解析器能够取得受支持的主机名；没有协议的裸主机名不会在运行时解析器中产生 hostname。
• 不要添加 Place ID、Google API key、field mask 或 results_limit，因为它们都不是该 SocQ 请求契约的字段。
• 把每个 URL 视为一条详情候选，而不是保证返回一条结果；不可用或无法标准化的来源行可能导致结果少于 URL。
• 保留可空的电话、网站、评分、评论数、描述、发布时间和 location 成员，不要编造默认值。
• has_more 为 true 时继续读取 next_cursor，因为游标分页作用于已保存任务结果，而 provider 上限来自 URL 数量。

相关 API