facebook-ad-library/
ad

広告URLからFacebook広告ライブラリの公開広告を1件取得し、クリエイティブのテキスト、広告主情報、メディア、配信期間、表示中の指標を正規化されたレコードとして返します。

Facebook Ad Library Ad API

広告ライブラリのURL
クリエイティブと広告主の情報
公開されている配信指標
結果1件あたり0.6クレジット
準備完了
準備完了

パラメータを入力してリクエストを送信してください。タスクのステータスと正規化された結果がここに表示されます。

README

SocQ 編集 · 更新

Facebook Ad Library Ad

Facebook広告ライブラリの広告は、クリエイティブのテキスト、広告主情報、メディア、CTA、配信期間、配信中かどうかのステータス、取得可能なリーチや広告費の指標を含む公開の広告レコードです。これらのフィールドは、選択した広告の情報補完、クリエイティブの確認、公開配信状況のモニタリング、特定時点での比較に活用できます。

Facebook Ad Library Ad API の主な機能

  • 広告ライブラリURLからの直接取得数値の id クエリパラメータを含む公開 /ads/library URLを1件指定すると、正規化された広告レコードを最大1件取得します。
  • クリエイティブと広告主の情報公開されている場合、広告アーカイブID、クリエイティブのタイトルと本文、広告主のFacebookページ情報、公開ページURL、CTA、リンク先を返します。
  • 配信状況と表示中の指標公開レコードで提供されている場合、開始日時と終了日時、配信中かどうかのステータス、掲載プラットフォーム、国の情報、ページのいいね数、リーチ、通貨、広告費を保持します。
  • 正規化された複数カードのメディア標準フィールドには取得可能なスナップショットまたは1枚目のカードのテキストを使用し、スナップショットと各カードにある画像・動画のアセットは重複を除外します。すべてのバリエーションを網羅した一覧ではありません。

Facebook Ad Library Ad API のパラメータ

パラメータ必須説明
url必須必須。公開Facebook広告ライブラリの広告URLです。正規の https://www.facebook.com/ads/library/?id={numeric_id} 形式を使用してください。1回のリクエストで指定できるURLは1件です。

Facebook Ad Library Ad API の使い方

公開広告ライブラリのURLを1件送信し、非同期タスクを追跡して、標準の結果エンベロープから正規化された広告レコードを読み取ります。

  1. パスが /ads/library で、クエリに数値の id を含む公開Facebook広告ライブラリのURLを1件用意します。
  2. url を /v1/facebook-ad-library/ad に送信し、返された task_id を控えます。
  3. タスクが成功するか失敗を返すまで /v1/tasks/{task_id} をポーリングします。
  4. data.results.items を読み取ります。このエンドポイントが返すレコードは最大1件のため、通常 next_cursor は null、has_more は false のままです。
curl -X POST "https://api.socq.ai/v1/facebook-ad-library/ad" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.facebook.com/ads/library/?id=702369045530963"}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items; this operation returns at most one item

Facebook Ad Library Ad API の主なユースケース

  • 選択した広告の情報補完: アーカイブID、広告主情報、クリエイティブのタイトル、本文、メディア、CTA、リンク先URL、入力URLを使って、既存の広告レコードを補完します。
  • クリエイティブアセットとリンク先の確認: 既知の広告について、重複を除外した画像・動画の参照を、表示形式、CTAのテキスト、CTAの種類、公開リンク先とあわせて確認します。
  • 公開配信状況の確認: 配信中かどうかのステータス、開始日時と終了日時、掲載プラットフォーム、国の値、取得可能なリーチや広告費のフィールドを使って、公開されている配信状況を分析します。
  • 特定時点の広告スナップショットの保存: クリエイティブ、広告主、配信、表示中の指標、入力URL、collected_at のフィールドを保存し、同じ既知の広告をあとで比較できるようにします。

Facebook Ad Library Ad API 活用のヒント

  • パスが厳密に /ads/library で、数値の id クエリパラメータを含む広告ライブラリのURLを送信してください。ページURL、ページID、投稿URL、広告IDのみの入力は受け付けません。
  • 送信したURLが構文上有効な場合、レコードのない succeeded タスクは、広告が利用できない、または見つからないという有効な結果として扱ってください。
  • リーチ、広告費、ページのいいね数、メディア、end_at、広告主のプロフィールURL、CTA、国の値は任意の公開フィールドとして扱い、欠けている値を0に変換しないでください。
  • 複数のカードやクリエイティブを持つ広告では、正規化された name と text を代表的なフィールドとして使用し、重複を除外したメディアリストはバリエーションごとの完全な一覧とはみなさずに確認してください。

Facebook Ad Library Ad API 以外に別の種類の公開Facebook Ad Libraryデータが必要な場合は、これらのAPIをご利用ください。

  • Facebook Ad Library Search API — キーワードで公開広告を検索します。一致方法、広告、国、ステータス、メディア、並び順、日付、取得件数上限を指定できます。
  • Facebook Ad Library Company Search API — 企業名またはページ名から広告主ページの候補を検索し、ページID、分類、画像、表示中のオーディエンス、連携するInstagramのシグナルを返します。
  • Facebook Ad Library Company Ads API — 広告主のページID 1件について公開広告を取得し、クリエイティブ、配信、市場、メディア、CTA、表示中のシグナルの各フィールドを返します。

他のプラットフォームを見る

Facebook Ad Libraryのデータを、対応する他のソーシャルプラットフォームの公開データと組み合わせられます。

Facebook Ad Library Ad API — よくある質問

Facebook Ad Library Ad APIは、送信した広告ライブラリのURLから公開広告を1件取得するAPIです。正規化されたクリエイティブのテキスト、広告主情報、メディア、配信期間、CTA、取得可能な公開指標を返します。

正規の https://www.facebook.com/ads/library/?id={numeric_id} 形式の公開URLを1件送信してください。パスは /ads/library で、id クエリパラメータは数値である必要があります。

レコードには、広告アーカイブIDとURL、クリエイティブのタイトルと本文、広告主のページのフィールド、メディア、配信日とステータス、掲載プラットフォーム、国の値、CTAの詳細、リンク先URL、ページのいいね数、リーチ、通貨、広告費、取得時の情報が含まれる場合があります。

構文上有効なURLでも、利用できない、または見つからない公開広告を指している場合があります。その場合、タスクはプレースホルダーの結果を作成せずに成功することがあります。

正規化された name と text には取得可能なスナップショットまたは1枚目のカードの値が使われ、media にはスナップショットと各カードにある重複のないアセットが含まれます。このレコードは、すべてのクリエイティブのバリエーションを網羅した一覧ではありません。

正常に返された広告レコード1件につき0.6 SocQクレジットです。結果が返らなかったタスクには結果の料金はかかりません。