Facebook Marketplace Item API

Facebook Marketplace Item

主要特性

• 已知商品 URL 输入处理 facebook.com、www.facebook.com、m.facebook.com 或 web.facebook.com 下以 /marketplace/item/{numeric_id} 开头的公开路径，采集范围只覆盖提交的商品。
• 标准化商品详情在公开来源提供时返回商品身份、标题、说明文字、卖家、价格、位置、图片、属性、配送值、时间和可用状态字段。
• 批量独立处理分别处理每个有效 URL，且每个 URL 最多返回一条商品记录；某个商品不可用时，其余输入仍会继续处理。
• 明确的公开数据边界卖家、位置、媒体、属性、配送和状态字段由公开来源决定；来源未提供时保留为空，不生成占位详情。

参数

如何使用

提交已知公开 Marketplace 商品 URL，跟踪异步任务，再通过 cursor 分页读取标准化商品记录。

1. 准备一个或多个路径以 /marketplace/item/{numeric_id} 开头的公开 Facebook Marketplace URL。
2. 将链接作为 urls 提交到 /v1/facebook-marketplace/item，并保存 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/item" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.facebook.com/marketplace/item/1656586118821988/"]}'

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

最佳使用场景

• 补全选定搜索结果： 使用商品说明文字、卖家字段、更多媒体、属性、配送值和详细位置上下文，补充选定的 Marketplace 搜索结果。
• 复查价格与可用状态： 对已知商品 URL 比较标准化价格、划线价、状态说明以及 live、pending、sold、shipping、buy-now 和 messaging 标记。
• 比较选定商品属性： 对明确的公开商品列表整理标题、分类、成色属性、位置、配送类型、价格和媒体。
• 保存商品时间点快照： 保存商品身份、来源 URL、公开内容、状态字段、created_at 和 collected_at，供后续比较。

使用建议

• 提交前校验每个 host 和 /marketplace/item/{numeric_id} 路径，并删除完全重复的 URL 字符串；任一无效 URL 会使整个请求被拒绝，而重复字符串只处理一次。
• 返回记录少于输入 URL 时不要补造缺失商品；不可用或未找到的商品会被跳过，其余有效 URL 继续处理。
• 将卖家身份、坐标、说明文字、媒体、属性、配送值、创建时间和公开状态标记作为由来源决定的可空字段处理。
• 同时保存 extra.input_url 和 collected_at，让每条商品记录保留输入 URL 与采集时间。
• 成功结果超过当前结果页时，应在 has_more 为 true 的情况下继续使用 next_cursor，不要只读取第一页。

相关 API