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