Facebook Marketplace Location Search
Facebook Marketplace 位置候选以名称、说明文字、地址、城市、邮编和地理坐标标识一个地点。结合这些字段可以消除同名地点歧义、选择商品搜索中心，并为本地商品研究构建可复用的地点选择器。
主要特性
- 按地点名称解析位置提交城市、地区、街区或地点名称，并获取该次查询返回的全部 Marketplace 位置候选。
- 同名地点判别字段结合候选名称、说明文字、地址、城市、邮编和经纬度，区分名称相同或相近的地点。
- 可追溯的标准化候选每条候选记录保留 Facebook 位置 ID、原始 search query 和采集时间，便于复核并重复使用所选地点。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
query | 必填 | 必填的非空城市、地区、街区或地点名称，例如 Austin。 |
如何使用
提交一个地点名称 query，跟踪异步任务，并读取该次查询返回的标准化位置候选。
- 准备一个非空的城市、地区、街区或地点名称 query。
- 将 query 提交到 /v1/facebook-marketplace/location-search，并保存返回的 task_id。
- 轮询 /v1/tasks/{task_id}，直到任务成功或失败。
- 读取 data.results.items；has_more 为 true 时继续使用 next_cursor。
curl -X POST "https://api.socq.ai/v1/facebook-marketplace/location-search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"Austin"}'
# 轮询 GET /v1/tasks/{task_id}
# 读取 data.results.items；has_more 为 true 时继续使用 next_cursor最佳使用场景
- 解析商品搜索中心： 选择候选的经纬度，为 Facebook Marketplace Search 提供所需的地理搜索中心。
- 消除同名地点歧义： 在名称相近的候选中对比说明文字、城市、邮编、地址和坐标，再确定目标地点。
- 构建可复用地点选择器： 保存位置 ID、显示名称、地点类型和坐标，供后续本地商品 query 通过选择器复用。
使用建议
- 短地点名称可能对应多个地区时，在 query 中加入地区或街区上下文。
- 接受同名候选前，对比说明文字、城市、邮编、地址和经纬度。
- 不要提交 results_limit，因为地点查询会保存该 query 返回的全部候选。
- has_more 为 true 时继续使用 next_cursor，避免遗漏任务结果分页中的候选。
- 结果为空表示当前 query 未解析到候选，不能据此判断该地区不支持 Marketplace。
相关 API
需要其他类型的 Facebook Marketplace 公开数据时，可以使用以下 API。
- Facebook Marketplace Search API — 按关键词和坐标搜索公开 Marketplace 商品，返回价格、位置、媒体、分类、配送与状态上下文。
- Facebook Marketplace Item API — 通过已知商品 URL 采集详细公开 Marketplace 商品，返回卖家、价格、位置、媒体、属性、配送和可用状态字段。