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 の使い方
キーワードと広告サンプルを定めるフィルターを送信し、完了した非同期タスクから正規化されたレコードをすべて読み取ります。
- 空でない query を1つ用意し、必要に応じて一致方式、広告の種類、国、ステータス、メディア、並び順、期間、結果件数の上限を選びます。
- リクエストを /v1/facebook-ad-library/search に POST し、返された task_id を保存します。
- タスクが成功するか失敗を返すまで /v1/tasks/{task_id} をポーリングします。
- 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 trueFacebook 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ではなく取得できない公開データとして扱ってください。
関連API
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、表示中のシグナルの各フィールドを返します。