Facebook Marketplace Location Search API

Facebook Marketplace Location Search

主要特性

• 按地点名称解析位置提交城市、地区、街区或地点名称，并获取该次查询返回的全部 Marketplace 位置候选。
• 同名地点判别字段结合候选名称、说明文字、地址、城市、邮编和经纬度，区分名称相同或相近的地点。
• 可追溯的标准化候选每条候选记录保留 Facebook 位置 ID、原始 search query 和采集时间，便于复核并重复使用所选地点。

参数

如何使用

提交一个地点名称 query，跟踪异步任务，并读取该次查询返回的标准化位置候选。

1. 准备一个非空的城市、地区、街区或地点名称 query。
2. 将 query 提交到 /v1/facebook-marketplace/location-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/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