Facebook Marketplace Search API

Facebook Marketplace Search

主要特性

• 按关键词与地理位置搜索商品将一个非空 query 与必填经纬度组合，并可通过半径、价格、排序、配送、成色、发布时间和可用状态筛选公开商品。
• 结构化商品与价格记录以一致结构返回商品 ID、公开 URL、标题、可用说明文字、价格数值、币种、格式化价格和划线价。
• 位置、媒体与分类上下文每条结果保留可用的位置标签、城市、州、图片引用、分类 ID、attributes、配送类型和发布时间说明。
• 公开搜索卡片字段边界保留公开卖家字段以及 live、pending、sold、shipping、buy-now 和 messaging 状态；搜索卡片未提供的详情保持为空。

参数

如何使用

提交关键词、地理中心与可选商品筛选条件，跟踪异步任务，再通过 cursor 分页读取标准化商品记录。

1. 准备非空 query、-90 到 90 的 latitude、-180 到 180 的 longitude，以及需要的可选筛选条件。
2. 将请求 POST 到 /v1/facebook-marketplace/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/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"bike","latitude":30.2677,"longitude":-97.7475,"results_limit":100}'

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

最佳使用场景

• 比较本地商品报价： 结合相似公开商品的标准化价格、币种、标题、query 上下文和位置，比较指定搜索区域内的报价。
• 研究区域库存与分类： 使用分类 ID、attributes、配送类型、可用状态、图片和位置上下文，构建数量受控的本地商品数据集。
• 生成可重复的市场快照： 保留商品 ID、价格、状态字段、search_query 和 collected_at，比较同一搜索在不同时间独立采集的结果。
• 准备商品详情候选： 通过公开商品 URL、标题、价格、图片和可用状态，筛选需要进一步获取 item 详情的记录。

使用建议

• 当搜索从地点名称而不是坐标开始时，先通过 Location Search 解析并核对候选，再提交 latitude 与 longitude。
• 提交前校验经纬度范围，确保 radius_km 大于 0、价格非负，并保证 min_price 不大于 max_price。
• 存储结果超过首个响应页时持续使用 next_cursor，直到 has_more 为 false；results_limit 控制采集上限，不是任务响应分页大小。
• 重复快照应以商品 ID 为键并保留 collected_at，因为同一任务只保存一次重复 ID，公开商品也可能变化或消失。
• 将说明文字、卖家字段、精确坐标、attributes 和创建时间作为选填值处理；需要更深公开详情时，将返回的商品 URL 交给 Marketplace Item。

相关 API