Facebook Event Details
Facebook Event Detailsは、すでにわかっているイベントURLを直接照会するエンドポイントです。/events/ を含む公開FacebookのURLを1つ以上送信すると、取得可能な場合はイベントID、正規URL、イベント名、説明、開始・終了日時、開催場所、公開メディア、表示中の指標、収集時のコンテキストを取得できます。
Facebook Event Details API の主な機能
- イベントURLの直接照会キーワード、カテゴリ、都市、日付による検索を行わずに、既知の公開FacebookイベントURLを解決します。
- 正規化されたイベントのメタデータID、正規URL、イベント名、説明、収集タイムスタンプのフィールドを、安定したイベント形式で返します。
- 日程と開催場所のコンテキストソースで表示されている場合は、正規化された開始・終了日時と公開されている開催場所の値を取得します。
- メディアと表示中の指標イベントで取得可能な場合は、正規化された公開メディアと、一般的なエンゲージメントや反応の指標を含めます。
Facebook Event Details API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
urls | 必須 | 必須。公開FacebookイベントURLの配列です。対応ホストは facebook.com、www.facebook.com、m.facebook.com で、各パスに /events/ を含める必要があります。 |
Facebook Event Details API の使い方
イベントURLを非同期タスクとして送信し、タスクIDをポーリングして、正規化されたイベントレコードを読み取ります。
- パスに /events/ を含む、facebook.com、www.facebook.com、m.facebook.com の公開URLを1つ以上用意します。
- urls を /v1/facebook/event-details に POST します。
- status が succeeded になるまで /v1/tasks/{task_id} をポーリングします。
- /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/"]}'
# Poll GET /v1/tasks/{task_id}, then read /v1/tasks/{task_id}?limit=50 and use data.results.items.Facebook Event Details API の主なユースケース
- イベントのメタデータ補完: 保存済みのイベントURLに、正規化されたID、イベント名、説明、開催場所、日時、メディア、表示中の指標を追加します。
- カレンダーへの取り込み: 取得できたイベント名、開始・終了日時、説明、開催場所、ソースURLをカレンダーのパイプラインにマッピングします。
- 主催者と会場のリサーチ: 既存のイベントURLリストについて、公開されている説明、開催場所、日程、メディア、反応のシグナルを確認します。
- 既知イベントの更新: 保存済みのイベントURLを再実行し、ソースで現在取得可能な公開フィールドを最新の状態に更新します。
Facebook Event Details API 活用のヒント
- Facebookページのイベント一覧や、events というパス要素を含むだけの別のFacebook URLではなく、正規のイベント詳細URLを使用してください。
- ソース側の公開状況はイベントによって異なるため、イベント名、説明、開催場所、日程、メディア、指標は任意項目として扱ってください。
- 複数URLのリクエストで結果を照合する際は extra.input_url を保持してください。送信した1つのURLから生成されるイベントレコードは最大1件です。
- 非公開、削除済み、制限付き、ログイン必須のイベントでは、イベントレコードが返されないままタスクが完了することがあります。
関連API
Facebook Event Details API 以外に別の種類の公開Facebookデータが必要な場合は、これらのAPIをご利用ください。
- Facebook Pages API — 公開Facebookページのプロフィール、連絡先、画像、表示中のユーザー評価を取得します。
- Facebook Posts API — 対応するFacebook URLから、公開投稿、メディア、リアクション、コメント、シェアを取得します。
- Facebook Comments API — 投稿URLから、公開コメント、投稿者、エンゲージメント、メディア、元のリンクを取得します。
- Facebook Video Transcript API — 既知の公開動画投稿またはリールのURLから、取得可能な文字起こしテキストと形式を抽出します。
- Facebook Events Search API — キーワードで公開イベントを検索し、日程、場所、参加状況、カバーメディア、イベントの状態の各フィールドを返します。
- Facebook Profile Events API — プロフィールまたはページのURLに関連する公開イベントを、名前、日程、場所、メディア、表示中の指標、取得元の情報とともに取得します。