メインコンテンツへスキップ
LinkedIn 広告ライブラリを非同期 task API で読み取り、競合がビジネスパーソンに向けてどんな広告を出しているかを JSON で受け取ります。ADS は独立したエンジンです。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 クレジットです。

リクエスト

task を送信したら、GET /v1/async/task/{id} をポーリングするか、webhook で受け取ります。参照: 非同期 task。ライブラリが読み取り速度を制限するため、広告 120 件の検索は約 30 秒かかります。

競合の広告を分析する

3 つのリクエストで競合分析がそろいます。
  1. 競合の名前を advertiserName に入れて search を送り、広告を一覧します。advertiserName は名前の一部に一致するため、広告ごとの advertiserName を確認します。query を加えると広告をあるトピックに絞り込め、sortBy oldest で最も古い広告から始められます。
  2. 広告の libraryId で ad を送り、費用の支払者とランディングページを受け取ります。EU で表示された広告は、掲載期間、インプレッション、ターゲティングも受け取れます。
  3. 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 クレジットです。完了したリクエストだけが課金されます。

関連