taskType ADS に platform linkedin_ad_library を送り、action で読み取る対象を選びます。広告ライブラリを選ぶには、広告ライブラリの比較を参照してください。
search(デフォルト)は、queryのキーワード、advertiserNameの広告主名、payerの費用の支払者、またはそれらの組み合わせで広告を一覧します。広告ごとに広告主、形式、タイトル、本文、メディアがあり、レスポンスの末尾には返した広告をまとめたsummaryが付きます。adは広告 1 件を開きます。広告主、費用の支払者、ランディングページに加え、ライブラリが公開している場合は掲載期間、インプレッション、到達した国、ターゲティングを返します。
action advertisers は 400 VALIDATION_ERROR で拒否されます。競合は検索の advertiserName で探します。
検索は返した広告 30 件ごとに 0.5 クレジットです。ad は 0.5 クレジットです。
リクエスト
GET /v1/async/task/{id} をポーリングするか、webhook で受け取ります。参照: 非同期 task。ライブラリが読み取り速度を制限するため、広告 120 件の検索は約 30 秒かかります。
競合の広告を分析する
3 つのリクエストで競合分析がそろいます。- 競合の名前を
advertiserNameに入れてsearchを送り、広告を一覧します。advertiserNameは名前の一部に一致するため、広告ごとのadvertiserNameを確認します。queryを加えると広告をあるトピックに絞り込め、sortByoldestで最も古い広告から始められます。 - 広告の
libraryIdでadを送り、費用の支払者とランディングページを受け取ります。EU で表示された広告は、掲載期間、インプレッション、ターゲティングも受け取れます。 payerでsearchを送り、代理店や企業が費用を支払った広告を、どのページが出していても一覧します。
パラメーター
action:search(デフォルト)、ad。query: 広告の本文に含まれるキーワード。searchにはquery、advertiserName、payerのいずれかが必要です。advertiserName: 名前。広告主名の一部に一致します(例:samsung)。payer: 費用を支払った主体の名前。名前の一部に一致します(例:Starcom)。libraryId: 広告の数字の ID(例:1638962914)。adでは必須です。country: 広告が掲載された国の 2 文字コード、またはすべての国を表すALL(デフォルト)。startDate、endDate:YYYY-MM-DD。一緒に送り、直近 1 年以内にします。2 つの日付の間に表示された広告を残します。sortBy:newest(デフォルト)またはoldest。limit: 広告 1〜120 件。デフォルトは 30 です。cursor: 前のレスポンスのnextCursor。その後の広告を続けて受け取ります。
search は libraryId を除く上のすべてのフィールドを読み取り、ad は libraryId だけを読み取ります。Meta 広告ライブラリのフィルター(pageId、pageIds、activeStatus、searchType、adType、mediaType、publisherPlatforms、contentLanguages)、ライブラリが検索できない値、アクションが読み取らないフィールドは 400 VALIDATION_ERROR で拒否され、details がそのフィールドを示します。
広告をさらに取得する
読み取る広告がさらにある場合、レスポンスにnextCursor が付きます。同じ検索にこの値を cursor として送ると、次の広告を再び limit 件まで受け取れます。ライブラリにこれ以上広告がなければ nextCursor は null です。カーソルは、それを返した検索でのみ使えます。query、advertiserName、payer、country、日付範囲や sortBy が異なる場合は 400 VALIDATION_ERROR で拒否され、limit は変更できます。
検索レスポンスの例
- レスポンスは
platform、action、country、query、advertiserName、payer、sortBy、および受け取った日付をそのまま返します。returnedCountはadsの広告数、hasMoreはライブラリにさらに広告があればtrueでnextCursorで続きを取得し、libraryUrlは同じ検索を広告ライブラリで開きます。ライブラリが件数を示さないため、totalCountはnullです。 - 広告は 1 枚のカードとして返り、
position、libraryId、libraryUrl、advertiserName、advertiserLogoUrl、creativeType(例:SPONSORED_STATUS_UPDATE、SPONSORED_VIDEO)、format、title、body、images、videos(動画のポスターはpreviewUrl)、platforms(LINKEDIN)があります。formatはIMAGE、VIDEO、CAROUSEL、DOCUMENT、ARTICLE、MESSAGE、JOB、SPOTLIGHT、FOLLOW_COMPANYのいずれかです。 - メッセージ広告と Thought Leader 広告には
memberが含まれます。メッセージの送信者、または広告が宣伝する投稿の作成者で、nameとurlを持ち、adも同じ形で返します。それ以外の広告ではmemberはnullです。 - カードには本文の先頭 120 文字が入り、本文がそれより長い場合は
bodyTruncatedがtrueです。adは本文の全文を返します。 advertiserId、payer、startDate、endDate、activeDays、linkUrl、landingDomain、impressions、targeting、ctaText、utmはカードではnullです。adがライブラリにある値を埋めます。ライブラリは広告がまだ掲載中かどうかを示さないため、isActiveはnullです。summaryはこのレスポンスの広告を数えます。ads、advertisers(広告が最も多い 10 件:advertiserName、ads)、formats、platformsです。カードに日付がないため、日付のフィールド(oldestStartDate、newestStartDate、medianActiveDays、launchesByWeek、longestRunning)は空またはnullのままです。- 条件に合う広告がない検索は、空の
adsと広告0件のsummaryで完了します。
ライブラリが保管する範囲
- すべての広告のクリエイティブ、広告主、費用の支払者が、すべての国で取得できます。
- 掲載期間、インプレッションの範囲、国別のインプレッションの割合、ターゲティングは、EU で表示された広告でのみ取得できます。
- ライブラリは広告を約 12 か月保管し、日付フィルターは直近 1 年のみ受け付けます。
広告 1 件を開く
action ad は、送った libraryId の広告を開きます。検索結果、または広告ライブラリのアドレス /ad-library/detail/<libraryId> から得られます。
adは、全文を含む検索カードのフィールドに加えて、advertiserId、advertiserUrl、advertiserType(companyまたはperson)、payer(広告の費用を支払った主体)、linkUrl、landingDomain、ctaText、startDate、endDate、activeDays、impressions、targeting、reachedCountriesを持ちます。impressionsはライブラリが公開する範囲(min、max)です。targetingは、広告主が含めた、または除外した言語と地域(language、location)と、ターゲティングのパラメーター(parameters:parameter、targeted、excluded)を並べます。EU で表示されなかった広告(例: Adobe の広告1698237666)では、日付、impressions、targeting、reachedCountriesがnullです。支払者と広告主はすべての広告にあります。videosは動画ごとにurl(最もビットレートが高いファイル)、files(すべての mp4:url、type、bitrate)、previewUrlを並べます。カルーセル広告はcards(title、imageUrl)を、ドキュメント広告はdocument(タイトル、ページ数、ページの表紙)を加えます。advertiserは広告の背後にあるページです。advertiserId、advertiserName、url、type、logoUrlがあります。- EU で表示されなかった広告の
transparencyはnullです。EU で表示された広告ではimpressions、impressionsText(50k-100kのようにライブラリが示すテキスト)、reachByCountryを持ちます。これは EU 外を含む、各国のインプレッションの割合(country、countryCode、share、shareText)です。 variantsは、ライブラリが複数表示する場合に広告の他のバージョンを並べ、そうでなければnullです。- クリエイティブのメディア URL は何年も開いたままです。カルーセルカードの URL は約 1 週間後、広告主のロゴは約 2 週間半後に失効します。必要なファイルは保存してください。
- ライブラリに広告がない
libraryIdはPAGE_UNAVAILABLEで失敗します。
料金
検索は開始時に、limit が要求した広告 30 件ごとに 0.5 クレジットを保留し、返した広告 30 件ごとに 0.5 クレジットを課金します(最低 0.5 クレジット)。デフォルトの検索(広告 30 件)は 0.5 クレジットで、limit 120 の検索は 2 クレジットを保留します。ad は 0.5 クレジットです。完了したリクエストだけが課金されます。