メインコンテンツへスキップ
Meta 広告ライブラリを非同期タスク API で検索し、JSON で受け取ります。taskType ADS に platform meta_ad_library を指定し、query にキーワードを、または pageId に広告主の Facebook ページ ID を入れます。検索は受け取った広告 30 件ごとに 0.5 クレジットです。広告主の名前からページ ID を探すには action advertisers を送ります。

リクエスト

タスクを送信したあと、GET /v1/async/task/{id} をポーリングするか Webhook で受け取ります。非同期タスクを参照してください。広告 30 件の検索はたいてい数秒で、広告 500 件の検索は 1 分ほどで完了します。

パラメータ

  • action: search(デフォルト)、または名前で広告主を探す advertisers。
  • query: キーワード。広告の本文に含まれる語を順序を問わず探します。pageId がない場合は必須です。
  • pageId: 広告主の数字の Facebook ページ ID(例: 266556540473351)。その広告主の広告を集め、query と組み合わせるとその中から検索します。
  • country: 広告が掲載された国の 2 文字のコード、またはすべての国を表す ALL。デフォルトは US です。
  • activeStatus: active(デフォルト)、inactive、all。
  • limit: 広告 1-500 件。デフォルトは 30 です。
  • cursor: 前のレスポンスの nextCursor。その続きの広告を受け取ります。
  • searchType: keyword_unordered(デフォルト)または keyword_exact_phrase。
  • adType: all(デフォルト)、political_and_issue_ads、housing_ads、employment_ads、financial_products_and_services_ads。
  • mediaType: all(デフォルト)、image、meme、image_and_meme、video、none。
  • publisherPlatforms: facebook、instagram、audience_network、messenger、whatsapp、threads のうち 1 つ以上。配列かカンマ区切りのテキストで送ります。
  • contentLanguages: 2 文字の言語コードを 1 つ以上。
  • startDate、endDate: YYYY-MM-DD。2 つの日付のあいだに表示された広告を残します。
  • sortBy: impressions_high_to_low(デフォルト)または most_recent。impressions_low_to_high は adType political_and_issue_ads でのみ使えます。ライブラリがこの順に並べるのはその広告だけです。
ライブラリで検索できない値は 400 VALIDATION_ERROR で拒否され、details がそのフィールドを示します。

続きの広告を受け取る

受け取る広告がまだあるレスポンスには nextCursor が付きます。同じ検索でこの値を cursor として送ると、次の広告を再び limit 件まで受け取ります。position は前のレスポンスから続き、ライブラリに広告がなくなると nextCursor は null になります。
カーソルはそれを返した検索でのみ使えます。query、pageId、country、activeStatus、フィルターが異なると 400 VALIDATION_ERROR で拒否され、limit は変えられます。カーソルは先に読んだ広告が多いほど長くなり、広告 1,000 件の後で約 14 KB になるため、長さ制限のないテキストとして保存します。ライブラリは同じ広告を 2 回表示することがあるため、後のレスポンスに同じ広告が再び含まれることがあります。重複は libraryId で見分けます。

広告主を探す

action advertisers は、広告ライブラリの検索ボックスが候補に出すように、名前が query に合う広告主の Facebook ページを返します。選んだ広告主の pageId でその広告を検索します。
広告主ごとに position、pageId、name、category、likeCount、verified(Meta の青い認証バッジ)、country(Meta がページの国を示す場合。例: グローバルブランドの英国ページ)、pageAlias、profileUrl、pictureUrl、instagramUsername、instagramFollowerCount、instagramVerified、広告ライブラリでその広告主の広告を開く libraryUrl があります。keywords はライブラリがその名前に提案する検索語です。ライブラリはページに書かれた名前で探すため、Shokz は Shokz のページを見つけ、샥즈 は見つけません。合うページがなければ空の advertisers で完了します。広告主の検索は query と country だけを受け取り、0.5 クレジットです。

レスポンス例

結果フィールド

  • レスポンスは platform、action、country、query または pageId、activeStatus と、指定したフィルターをそのまま返します。
  • totalCount はライブラリが数えた条件に合う広告の数で、大きな検索ではライブラリが丸めます。returnedCount は ads の広告の数、hasMore はライブラリにまだ広告があれば true で nextCursor で続きを受け取れ、libraryUrl は同じ検索を広告ライブラリで開きます。
  • 広告ごとに position、libraryId、libraryUrl、isActive、startDate と endDate(UTC の日付)、platforms、versions(このクリエイティブと本文を使う広告の数)、format(IMAGE、VIDEO、CAROUSEL、DCO、DPA、MULTI_IMAGES など)、body、title、caption、linkUrl、linkDescription、ctaText、ctaType、categories(POLITICAL や EMPLOYMENT など、ライブラリによる広告の分類)が含まれます。
  • 広告主は pageId、pageName、pageProfileUrl、pageProfilePictureUrl、pageLikeCount、pageCategories です。社会問題、選挙、政治に関する広告には広告費を支払った主体の byline と disclaimerLabel が、有料パートナーシップの広告にはパートナーのページの brandedContent が加わります。
  • メディアは images(url、resizedUrl)、videos(hdUrl、sdUrl、previewImageUrl)、cards です。cards はカルーセル広告やカタログ広告のカードで、カードごとに title、body、linkUrl、caption、linkDescription、ctaText、ctaType、imageUrl、resizedImageUrl、video があります。ダイナミック広告のほかの本文、リンク、画像、動画は extraTexts、extraLinks、extraImages、extraVideos に入ります。
  • メディアの URL は数日で期限が切れる Meta の CDN リンクです。必要なファイルは保存してください。
  • カタログ広告(DPA、DCO)の本文には、{{product.name}} のようなライブラリのプレースホルダーがそのまま残ります。
  • spend、currency、impressions、reach は、ライブラリが公開する広告にだけあります。社会問題、選挙、政治に関する広告と、EU で表示された広告です。
  • 条件に合う広告がない検索は、空の ads と totalCount 0 で完了します。

料金

検索は開始時に limit で指定した広告 30 件ごとに 0.5 クレジットを確保し、受け取った広告 30 件ごとに 0.5 クレジットを課金します。最低 0.5 クレジットです。デフォルトの検索(広告 30 件)は 0.5 クレジットで、limit 500 の検索は 8.5 クレジットを確保します。広告主の検索は 0.5 クレジットです。課金は完了したリクエストにのみ適用されます。

関連