Facebook Events Search
Facebook Events 是公开活动条目，包含名称、日程文字、开始时间、地点、出席信号、封面图片以及线上或已结束状态。这些记录可用于发现活动、监测日程、研究举办地点和比较出席情况。
主要特性
- 按关键词发现活动通过文本 query 查找与主题、活动类型、组织或地点相关的 Facebook 公开活动记录。
- 活动身份与日程为匹配记录返回活动 ID、名称、公开 URL、日程文字和标准化开始时间。
- 地点与活动状态保留地点 ID、地点名称、线上活动状态和已结束状态，便于区分举办形式与时间背景。
- 出席指标与封面字段返回公开可见的感兴趣、参加和参加过人数，并在存在时提供公开封面图片引用。
参数
| 参数 | 必填 | 描述 |
|---|---|---|
query | 必填 | 用于搜索 Facebook 公开活动的非空关键词 query。 |
results_limit | 可选 | 最多采集的活动记录数，范围为 7 到 2,000，默认为 100。 |
如何使用
把关键词作为异步任务提交，轮询 task ID，完成后再用 cursor 分页读取标准化活动记录。
- 准备非空关键词 query，并按需设置 7 到 2,000 之间的 results_limit。
- 向 /v1/facebook/events-search POST query 和 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/events-search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"technology conference","results_limit":20}'
# 轮询 GET /v1/tasks/{task_id}，再读取 /v1/tasks/{task_id}?limit=50，并使用 data.results。最佳使用场景
- 按主题发现活动： 结合具体 query、活动名称、公开 URL 和日程文字，整理相关 Facebook 公开活动清单。
- 活动日程监测： 在多次采集结果之间比较标准化开始时间、日程文字、活动 ID 和已结束状态。
- 地点与形式研究： 按地点 ID、地点名称和线上状态整理匹配活动，研究活动展示的举办地点与形式。
- 可见出席情况比较： 结合活动名称和开始时间，比较不同活动记录的感兴趣、参加和参加过人数。
使用建议
- 当宽泛 query 返回无关活动时，改用具体的主题、活动类型、组织或地点短语。
- 按所需覆盖范围把 results_limit 设为 7 到 2,000；省略时默认请求 100 条记录。
- 合并多次搜索结果时使用活动 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 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 Events API — 从个人资料或 Page URL 采集关联的公开活动，返回名称、日程、地点、媒体、可见指标和来源上下文。
- Facebook Profile Photos API — 从个人资料或 Page URL 采集公开照片，返回说明文字、作者上下文、互动指标、图片元数据和来源引用。
- Facebook Profiles API — 通过已知 Facebook URL 查询公开个人资料或主页，返回身份信息、简介、头像、可见计数和输入上下文。
- Facebook Reels API — 从个人资料或 Page URL 采集公开 Reels，返回说明文字、作者上下文、视频元数据、可见互动和来源引用。