Facebook Ad Transcript
Facebook広告の文字起こしとは、広告ライブラリの対象に紐づく音声のテキストレコードのことで、ソースURL、テキスト、言語、形式、収集日時、任意のショートコードのコンテキストを含みます。これらのレコードは、メッセージのレビュー、キーワードのインデックス化、言語に応じた処理、ソースに紐づくアーカイブに活用できます。
Facebook Ad Transcript API の主な機能
- 広告ライブラリURLの一括指定対応するFacebookホストの広告ライブラリURLを受け付け、重複しない各URLを独立した文字起こし対象として処理します。
- ソースに紐づく音声テキスト空でない文字起こしテキストを、送信したソースURLと、ソースIDがない場合はURLをフォールバックとする識別子とともに返します。
- 言語と形式のコンテキスト正規化レコードに、null になり得るソース言語、plaintext または WebVTT の形式、収集日時、任意のショートコードを含めます。
- 取得できたレコードのみを保存選択した広告対象から空でない文字起こしが得られた場合にのみ結果を保存するため、成功したタスクでも送信したURLより少ないレコードが返ることがあります。
Facebook Ad Transcript API のパラメータ
| パラメータ | 必須 | 説明 |
|---|---|---|
urls | 必須 | 対応するFacebookホスト上の広告ライブラリURLです。カンマまたは改行で区切り、各パスには /ads/library を含める必要があります。 |
Facebook Ad Transcript API の使い方
Facebook広告ライブラリのURLを送信します。空でない文字起こしテキストがある対象のみが結果になるため、返されたソースURLを入力と照合してください。
- ホストが facebook.com、www.facebook.com、m.facebook.com のいずれかで、パスに /ads/library を含むFacebook広告ライブラリのURLを1つ以上用意します。
- urls を /v1/facebook/ad-transcript に POST し、返された task_id を保存します。
- タスクが成功または失敗するまで /v1/tasks/{task_id} をポーリングします。
- data.results.items を読み取り、results.has_more が true の場合は results.next_cursor を指定して次のページをリクエストします。
curl -X POST "https://api.socq.ai/v1/facebook/ad-transcript" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.facebook.com/ads/library/?id=123456789012345"]}'
# Poll GET /v1/tasks/{task_id}
# Continue with GET /v1/tasks/{task_id}?limit=50&cursor={next_cursor}Facebook Ad Transcript API の主なユースケース
- 広告メッセージのレビュー: ソースに紐づく文字起こしテキストを読み、選定した公開広告の対象間で使われている話し言葉の表現を比較します。
- 広告音声の検索インデックス: テキストをレコードID、ソースURL、収集日時、ショートコードのコンテキストとともにインデックス化し、既知の広告の文字起こしを話された語句で検索できるようにします。
- 文字起こし処理の振り分け: language と format のフィールドを使って、plaintext と WebVTT のレコードを適切なテキスト処理、字幕処理、言語処理のパイプラインに振り分けます。
Facebook Ad Transcript API 活用のヒント
- 対応するFacebookホストを使用し、すべてのURLパスに /ads/library を残してください。それ以外のホストやパスはリクエストの検証で失敗します。
- コレクターが除去するのは完全に一致する重複文字列のみのため、同じ対象が異なるクエリ文字列で現れる場合は、まとめて送信する前に広告ライブラリのURLを正規化してください。
- 成功後は返された url の値を送信したリストと照合し、未対応の広告や空でない文字起こしが得られなかった対象もワークフロー上で把握できるようにしてください。
- format に応じて解析処理を分岐し、language と extra.shortcode は null になり得る値として扱ってください。created_at は予約フィールドで、現在は null を返します。
- 大量のURLが、指定した結果ページの上限を超える複数ページにまたがる場合は、results.has_more が true の間 results.next_cursor をたどってください。
関連API
Facebook Ad Transcript API 以外に別の種類の公開Facebookデータが必要な場合は、これらのAPIをご利用ください。
- Facebook Pages API — 公開Facebookページのプロフィール、連絡先、画像、表示中のユーザー評価を取得します。
- Facebook Posts API — 対応するFacebook URLから、公開投稿、メディア、リアクション、コメント、シェアを取得します。
- Facebook Video Transcript API — 既知の公開動画投稿またはリールのURLから、取得可能な文字起こしテキストと形式を抽出します。
- Facebook Group Posts API — FacebookグループのURLから公開投稿を取得します。並び順やグループごとの取得上限を指定でき、投稿者情報、動画メディア、表示中のエンゲージメントを返します。
- Facebook Profile Photos API — プロフィールまたはページのURLから、公開写真をキャプション、投稿者情報、エンゲージメント、画像メタデータ、取得元の参照情報とともに取得します。
- Facebook Reels API — プロフィールまたはページのURLから、公開リールをキャプション、投稿者情報、動画メタデータ、表示中のエンゲージメント、取得元の参照情報とともに取得します。