Facebook Event Details
Facebook Event Details 是面向已知活动 URL 的直接查询端点。提交一个或多个包含 /events/ 的 Facebook 公开 URL，可在字段可用时采集活动 ID、规范 URL、名称、描述、开始与结束时间、地点、公开媒体、可见指标和采集上下文。
主要特性
- 直接查询活动 URL通过已知 Facebook 公开活动 URL 获取详情，无需进行关键词、分类、城市或日期搜索。
- 标准化活动元数据以稳定活动结构返回身份、规范 URL、名称、描述和采集时间字段。
- 日程与地点上下文在来源公开相应字段时，采集标准化开始与结束时间以及公开地点值。
- 媒体与可见指标在可用时返回标准化公开媒体，以及活动常见互动或响应指标。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
urls | 必填 | 必填的 Facebook 公开活动 URL 数组。接受 facebook.com、www.facebook.com 和 m.facebook.com，且每个路径必须包含 /events/。 |
如何使用
把活动 URL 作为异步任务提交，轮询 task ID，完成后读取标准化活动记录。
- 准备一个或多个 facebook.com、www.facebook.com 或 m.facebook.com 的公开 URL，路径必须包含 /events/。
- 向 /v1/facebook/event-details POST urls。
- 轮询 /v1/tasks/{task_id}，直到状态变为 succeeded。
- 通过 /v1/tasks/{task_id}?limit=50 读取 data.results.items，并在 results.has_more 为 true 时继续传 results.next_cursor。
curl -X POST "https://api.socq.ai/v1/facebook/event-details" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.facebook.com/events/123456789012345/"]}'
# 轮询 GET /v1/tasks/{task_id}，再读取 /v1/tasks/{task_id}?limit=50，并使用 data.results.items。最佳使用场景
- 活动元数据补全： 为已保存活动 URL 补充标准化身份、名称、描述、地点、时间、媒体和可见指标。
- 日历数据导入： 把可用的活动名称、开始与结束时间、描述、地点和来源 URL 映射到日历数据管线。
- 举办方与场地研究： 针对现有活动 URL 清单，查看公开描述、地点、日程、媒体和响应信号。
- 已知活动信息刷新： 重新提交已保存的活动 URL，刷新来源当前公开且可用的字段。
使用建议
- 优先使用单个活动的规范详情 URL，不要提交主页活动列表或仅碰巧包含 events 路径段的其他 Facebook URL。
- 名称、描述、地点、日程、媒体和指标的可见性因活动而异，请按可空字段处理。
- 处理多 URL 请求时保留 extra.input_url，以便结果回溯到输入；每个输入 URL 最多产生一条活动记录。
- 私密、已删除、受限或需要登录的活动可能在任务完成后不返回活动记录。
相关 API
需要其他类型的 Facebook 公开数据时，可以使用以下 API。
- Facebook Pages API — 获取公开 Page 资料、联系方式、图片和可见受众评分。
- Facebook Posts API — 从受支持的 Facebook URL 采集公开帖子、媒体、表情回应、评论数和分享数。
- Facebook Comments API — 从帖子 URL 采集公开评论、作者、互动、媒体和来源链接。
- Facebook Video Transcript API — 从已知的公开视频帖子或 Reel URL 提取可用字幕文本和格式。
- Facebook Group Posts API — 从 Facebook 群组 URL 采集公开帖子，可选择排序并设置每个群组的数量上限，返回作者、视频媒体和可见互动信息。
- Facebook Events Search API — 按关键词搜索公开活动，返回日程、地点、出席指标、封面媒体和活动状态字段。
- Facebook Ad Transcript API — 从 Facebook Ad Library URL 提取可用口播文本、语言、格式和来源上下文。
- Facebook Comment Replies API — 使用已知评论的 feedback ID 和 expansion token 获取公开回复，返回文本、作者标识、互动指标和父级上下文。
- Facebook Company Reviews API — 采集公开 Page 评价，返回评价文本、评价者链接、评分、点赞数、时间和公司上下文。
- Facebook Profile Events API — 从个人资料或 Page URL 采集关联的公开活动，返回名称、日程、地点、媒体、可见指标和来源上下文。
- Facebook Profile Photos API — 从个人资料或 Page URL 采集公开照片，返回说明文字、作者上下文、互动指标、图片元数据和来源引用。
- Facebook Profiles API — 通过已知 Facebook URL 查询公开个人资料或主页，返回身份信息、简介、头像、可见计数和输入上下文。
- Facebook Reels API — 从个人资料或 Page URL 采集公开 Reels，返回说明文字、作者上下文、视频元数据、可见互动和来源引用。