Facebook Profile Events
Facebook Profile Events 是与个人资料或 Page 关联的公开活动条目，包含名称、描述、地点、开始与结束时间、媒体和可见指标。活动日程与来源上下文可用于丰富主办方日历、研究活动清单和比较不同 Page 的活动安排。
主要特性
- 个人资料与 Page 活动列表从一个或多个已提交的 Facebook 个人资料或 Page URL 采集关联的公开活动条目。
- 活动身份与日程返回活动 ID、公开 URL、名称、描述、地点以及标准化的开始和结束时间。
- 媒体与可见指标保留每个活动附带的标准化公开图片或视频引用以及常见可见指标。
- 标准化来源上下文为每条标准化记录附加已提交的来源 URL，并在同一来源列表内按活动 ID 或 URL 去重。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
urls | 必填 | 一个或多个位于 facebook.com、www.facebook.com 或 m.facebook.com 的个人资料或 Page URL。 |
results_limit | 可选 | 每个输入 URL 最多采集的活动记录数，范围为 20 到 2,000，默认为 100。 |
如何使用
把个人资料或 Page URL 作为异步任务提交，轮询 task ID，完成后再用 cursor 分页读取标准化活动记录。
- 准备一个或多个 Facebook 个人资料或 Page URL，并按需为每个 URL 设置 20 到 2,000 之间的 results_limit。
- 向 /v1/facebook/profile-events POST urls 和可选的 results_limit。
- 轮询 /v1/tasks/{task_id}，直到状态变为 succeeded。
- 通过 /v1/tasks/{task_id}?limit=50 读取 data.results，并在 results.has_more 为 true 时继续传 results.next_cursor。
curl -X POST "https://api.socq.ai/v1/facebook/profile-events" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.facebook.com/NASA"],"results_limit":20}'
# 轮询 GET /v1/tasks/{task_id}，再读取 /v1/tasks/{task_id}?limit=50，并使用 data.results。最佳使用场景
- 丰富主办方日历： 使用活动名称、描述、地点和开始与结束时间，丰富由已知公开主办方 Page 构建的日历。
- 跨 Page 活动清单： 按 input_url 整理标准化活动 ID 和 URL，比较选定个人资料或 Page 的公开活动条目。
- 活动详情采集队列： 使用返回的活动 URL 构建去重队列，供后续获取更完整的活动详情。
- 公开日程报告： 组合日程字段、媒体引用和可见指标，生成与已跟踪公开来源关联的活动报告。
使用建议
- 提交能公开活动列表的个人资料或 Page 目标；仅通过主机校验并不能确认 Facebook URL 是合适的活动来源。
- 设置 results_limit 时同时考虑输入 URL 数量，因为数量上限和预估的按结果费用会分别应用于每个 URL。
- 当同一活动可能关联多个已提交来源时，合并结果应按活动 ID 或公开 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 Event Details API — 通过已知公开活动 URL 采集标准化元数据、日程、地点、媒体和可见互动指标。
- Facebook Profile Photos API — 从个人资料或 Page URL 采集公开照片，返回说明文字、作者上下文、互动指标、图片元数据和来源引用。
- Facebook Profiles API — 通过已知 Facebook URL 查询公开个人资料或主页，返回身份信息、简介、头像、可见计数和输入上下文。
- Facebook Reels API — 从个人资料或 Page URL 采集公开 Reels，返回说明文字、作者上下文、视频元数据、可见互动和来源引用。