Facebook Events Search
Facebookイベントは公開のイベント情報で、イベント名、日程テキスト、開始日時、開催場所、参加状況のシグナル、カバー画像、オンライン開催・終了済みのステータスを含みます。これらのレコードは、イベントの発見、日程のモニタリング、会場のリサーチ、参加状況の比較に活用できます。
Facebook Events Search API の主な機能
- キーワードによるイベント発見テキストクエリを使って、トピック、アクティビティ、組織、場所に関連する公開Facebookイベントのレコードを検索します。
- イベントの基本情報と日程一致したレコードについて、イベントID、イベント名、公開URL、日程テキスト、正規化された開始日時を返します。
- 開催場所とイベント状態場所ID、場所名、オンライン開催のステータス、終了済みのステータスを保持し、会場と時期のコンテキストを区別できます。
- 参加状況とカバー画像のフィールド表示中の「興味あり」「参加予定」「参加済み」の人数と、存在する場合は公開カバー画像への参照を含めます。
Facebook Events Search API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
query | 必須 | 公開Facebookイベントの検索に使う、空でないキーワードクエリです。 |
results_limit | 任意 | 取得するイベントレコードの最大数です。7〜2,000の範囲で指定でき、デフォルトは100です。 |
Facebook Events Search API の使い方
キーワードを非同期タスクとして送信し、タスクIDをポーリングして、正規化されたイベントレコードをカーソルページネーションで読み取ります。
- 空でないキーワードクエリを用意し、必要に応じて7〜2,000の範囲で results_limit を指定します。
- query と results_limit を /v1/facebook/events-search に POST します。
- status が succeeded になるまで /v1/tasks/{task_id} をポーリングします。
- /v1/tasks/{task_id}?limit=50 を読み取り、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}'
# Poll GET /v1/tasks/{task_id}, then read /v1/tasks/{task_id}?limit=50 and use data.results.Facebook Events Search API の主なユースケース
- トピック別のイベント発見: 絞り込んだクエリとイベント名、公開URL、日程テキストを使って、関連する公開イベントの一覧を作成します。
- 日程のモニタリング: 収集を実行するたびに、正規化された開始日時、日程テキスト、イベントID、終了済みのステータスを比較します。
- 会場と開催形式のリサーチ: 一致したイベントを場所ID、場所名、オンライン開催のステータスで整理し、イベントがどこでどのように告知されているかを調べます。
- 表示中の参加状況の比較: イベント名や開始日時とあわせて、イベントレコード間で「興味あり」「参加予定」「参加済み」の人数を比較します。
Facebook Events Search API 活用のヒント
- 幅広いクエリで無関係なイベントレコードが返る場合は、具体的なトピック、アクティビティ、組織、場所を表す語句を使用してください。
- 必要なカバー範囲に応じて results_limit を7〜2,000の範囲で設定してください。省略した場合はデフォルトの100件が取得されます。
- 検索を繰り返して結果を統合する際は、同じイベントを二重に数えないよう、イベントIDまたは公開URLを使用してください。
- レコードをアプリケーションにマッピングする際は、場所、カバー画像、参加人数、イベント状態のフィールドを任意項目として扱ってください。
関連API
Facebook Events Search API 以外に別の種類の公開Facebookデータが必要な場合は、これらのAPIをご利用ください。
- Facebook Pages API — 公開Facebookページのプロフィール、連絡先、画像、表示中のユーザー評価を取得します。
- Facebook Posts API — 対応するFacebook URLから、公開投稿、メディア、リアクション、コメント、シェアを取得します。
- Facebook Comments API — 投稿URLから、公開コメント、投稿者、エンゲージメント、メディア、元のリンクを取得します。
- Facebook Video Transcript API — 既知の公開動画投稿またはリールのURLから、取得可能な文字起こしテキストと形式を抽出します。
- Facebook Event Details API — 既知の公開イベントURLから、正規化されたメタデータ、日程、場所、メディア、表示中のエンゲージメントを取得します。
- Facebook Profile Events API — プロフィールまたはページのURLに関連する公開イベントを、名前、日程、場所、メディア、表示中の指標、取得元の情報とともに取得します。