facebook-ad-library/
search

キーワードとフィルターでFacebook広告ライブラリの公開広告を検索し、広告主、クリエイティブのテキスト、メディア、配信、表示中の指標を正規化されたレコードとして返します。

Facebook Ad Library Search API

キーワードで広告検索
クリエイティブと配信の情報
公開広告データ
結果1件あたり0.5クレジット
準備完了
準備完了

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

README

SocQ 編集 · 更新

Facebook Ad Library Search

Facebook広告ライブラリ検索の結果は、キーワードに一致した公開広告で、広告主のページ情報、クリエイティブのテキストとメディア、配信日、掲載プラットフォーム、国、表示中の指標を含みます。これらのレコードは、クリエイティブの発見、広告主の調査、配信中広告のモニタリング、同じ条件で繰り返し実行するクエリ間の比較に活用できます。

Facebook Ad Library Search API の主な機能

  • キーワード一致とフレーズ一致空でない query を1つ指定して検索し、語順を問わないキーワード一致か完全なフレーズ一致かを選んで、対象となる公開広告の条件を制御します。
  • 検索フィルターと並び順広告の種類、国、配信ステータス、メディアの種類、期間、対応するインプレッション順または関連度順で結果を絞り込みます。
  • 正規化された広告と広告主のレコード広告アーカイブID、公開ソースURL、広告主のページ情報、クリエイティブのタイトル、本文、取得日時を一貫したレコードで返します。
  • クリエイティブ・配信・公開情報取得可能な画像や動画、開始日時と終了日時、配信中かどうかの状態、掲載プラットフォーム、国、CTAの詳細、リンク先、表示中の指標を保持します。
  • 上限付きで重複を除外した取得20〜2,000件の結果をリクエストでき、取得可能な結果ページ全体で重複するアーカイブIDや公開広告URLは1回だけ保存されます。

Facebook Ad Library Search API のパラメータ

パラメータ必須説明
query必須必須。公開広告の検索に使用する、空でないキーワードまたはフレーズです。
results_limit任意保存する重複のない広告の最大件数です。デフォルトは100で、20〜2,000の整数を指定できます。
search_type任意キーワードの一致方式です。デフォルトは keyword_unordered で、語順まで一致させる必要がある場合は keyword_exact_phrase を使用します。
ad_type任意広告カテゴリのフィルターです。デフォルトは all で、political_and_issue_ads に限定することもできます。
country任意国のフィルターです。ALL または2文字の国コードを指定します。送信したコードは大文字に正規化されます。
status任意配信ステータスのフィルターです。デフォルトは ACTIVE で、ALL、ACTIVE、INACTIVE を指定できます。
media_type任意クリエイティブのメディアのフィルターです。ALL、IMAGE、VIDEO、MEME、IMAGE_AND_MEME、NONE を指定でき、デフォルトは ALL です。
sort_by任意結果の並び順です。デフォルトは total_impressions で、relevancy_monthly_grouped も指定できます。
start_date任意任意。YYYY-MM-DD 形式のインプレッション期間の開始日です。
end_date任意任意。YYYY-MM-DD 形式のインプレッション期間の終了日です。start_date より前の日付は指定できません。

Facebook Ad Library Search API の使い方

キーワードと広告サンプルを定めるフィルターを送信し、完了した非同期タスクから正規化されたレコードをすべて読み取ります。

  1. 空でない query を1つ用意し、必要に応じて一致方式、広告の種類、国、ステータス、メディア、並び順、期間、結果件数の上限を選びます。
  2. リクエストを /v1/facebook-ad-library/search に POST し、返された task_id を保存します。
  3. タスクが成功するか失敗を返すまで /v1/tasks/{task_id} をポーリングします。
  4. data.results.items を読み取り、has_more が true の間は next_cursor をたどって続きを取得します。
curl -X POST "https://api.socq.ai/v1/facebook-ad-library/search" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"running shoes","results_limit":100,"country":"US","status":"ACTIVE","media_type":"VIDEO","search_type":"keyword_unordered"}'

# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is true

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

  • キーワード起点の広告発見: 送信したクエリ、広告ID、クリエイティブのテキスト、広告主名、公開URLを使って、一致する公開広告をソースまでたどれるセットとしてまとめます。
  • クリエイティブと形式の比較: 一致したレコード間で、クリエイティブのタイトル、本文、画像、動画、表示形式、CTAの値、リンク先、掲載プラットフォームを比較します。
  • 配信中広告のモニタリング: 定めたクエリを繰り返し実行し、観測ごとに広告ID、配信中かどうかの状態、開始日時と終了日時、掲載プラットフォーム、取得日時を比較します。
  • 広告主候補の調査: 広告主のページID、名前、別名、URL、表示中のページのいいね数、一致したクリエイティブを使って、重点的に追跡調査するページを特定します。

Facebook Ad Library Search API 活用のヒント

  • 語順に意味がある場合は keyword_exact_phrase を、広告によってフレーズの語順が異なる可能性がある場合は keyword_unordered を使用してください。
  • 保存するサンプルの焦点がぼやけないよう、results_limit を増やす前に国、ステータス、メディア、広告の種類、期間のフィルターを適用してください。
  • results_limit は取得件数の上限として扱い、保存されたすべてのレコードを読み取るには has_more が false になるまでタスク結果のカーソルをたどってください。
  • 繰り返し実行した結果は広告アーカイブIDまたは公開広告URLで重複を除外し、観測時のコンテキストとして extra.search_query と collected_at を保持してください。
  • リーチ、広告費、ページのいいね数、終了日、メディア、CTA、国の値がない場合は、0ではなく取得できない公開データとして扱ってください。

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

  • Facebook Ad Library Company Search API — 企業名またはページ名から広告主ページの候補を検索し、ページID、分類、画像、表示中のオーディエンス、連携するInstagramのシグナルを返します。
  • Facebook Ad Library Company Ads API — 広告主のページID 1件について公開広告を取得し、クリエイティブ、配信、市場、メディア、CTA、表示中のシグナルの各フィールドを返します。
  • Facebook Ad Library Ad API — 広告ライブラリの公開広告1件をURLから取得し、クリエイティブ、広告主、メディア、配信、CTA、表示中のシグナルの各フィールドを返します。

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

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

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

Facebook Ad Library Search APIは、空でないキーワードまたはフレーズと任意の検索フィルターから公開広告を取得するAPIです。正規化された広告ID、広告主のページ情報、クリエイティブのテキストとメディア、配信のフィールド、表示中の指標を返します。

query は必須です。そのほか、results_limit、sort_by、search_type、ad_type、country、status、media_type、start_date、end_date を指定できます。

keyword_unordered は元の語順を問わずにクエリの単語に一致し、keyword_exact_phrase はフレーズの語順を保ったまま一致します。デフォルトは keyword_unordered です。

正規化された結果には、広告と広告主の情報、クリエイティブのテキスト、画像や動画、配信日と状態、掲載プラットフォーム、国、CTAとリンク先のフィールド、ページのいいね数、リーチ、広告費の情報、取得日時が含まれる場合があります。公開されていない公開フィールドは空のままになります。

キーワードに一致する公開広告がない場合や、選択した国、ステータス、メディア、広告の種類、期間のフィルターによって取得可能なレコードがすべて除外される場合があります。公開ソースの状況によって、完了したタスクが空になることもあります。

results_limit は保存する重複のない広告の最大件数で、デフォルトは100、20〜2,000の整数を指定できます。完了後は、保存されたすべてのタスク結果ページを読み取るため、has_more が true の間は next_cursor をたどってください。

返された正規化広告1件につき0.5 SocQクレジットです。結果が空の場合は結果の料金はかかりません。