> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# LinkedIn 広告ライブラリ API

> 競合の広告を LinkedIn 広告ライブラリから JSON で分析します。キーワード、広告主、費用の支払者で広告を検索し、広告 1 件を開いて、ライブラリが公開する支払者、インプレッション、到達した国を受け取ります。

LinkedIn 広告ライブラリを非同期 task API で読み取り、競合がビジネスパーソンに向けてどんな広告を出しているかを JSON で受け取ります。ADS は独立したエンジンです。`taskType` `ADS` に `platform` `linkedin_ad_library` を送り、`action` で読み取る対象を選びます。広告ライブラリを選ぶには、[広告ライブラリの比較](https://docs.querying.ai/ja/engines/ad-libraries.md)を参照してください。

* `search`(デフォルト)は、`query` のキーワード、`advertiserName` の広告主名、`payer` の費用の支払者、またはそれらの組み合わせで広告を一覧します。広告ごとに広告主、形式、タイトル、本文、メディアがあり、レスポンスの末尾には返した広告をまとめた `summary` が付きます。
* `ad` は広告 1 件を開きます。広告主、費用の支払者、ランディングページに加え、ライブラリが公開している場合は掲載期間、インプレッション、到達した国、ターゲティングを返します。

ライブラリには広告主の検索がないため、`action` `advertisers` は `400 VALIDATION_ERROR` で拒否されます。競合は検索の `advertiserName` で探します。

検索は返した**広告 30 件ごとに 0.5 クレジット**です。`ad` は 0.5 クレジットです。

## リクエスト

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "linkedin_ad_library", "query": "webinar", "country": "ALL", "limit": 30 } }'
```

task を送信したら、`GET /v1/async/task/{id}` をポーリングするか、webhook で受け取ります。参照: [非同期 task](https://docs.querying.ai/ja/concepts/async-tasks.md)。ライブラリが読み取り速度を制限するため、広告 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` は変更できます。

## 検索レスポンスの例

```json theme={"theme":"css-variables"}
{
  "platform": "linkedin_ad_library",
  "action": "search",
  "country": "ALL",
  "query": "webinar",
  "totalCount": null,
  "returnedCount": 30,
  "hasMore": true,
  "nextCursor": "eyJ2IjoxLCJoIjoielVmY24wUlRHU0hSWHYwYSIsImMiOiIxNjk4Mjc2MTc2LTE3OTUyMTAzMTIxMzkiLCJzIjo2LCJwIjozMH0",
  "libraryUrl": "https://www.linkedin.com/ad-library/search?keyword=webinar&countries=ALL",
  "ads": [
    {
      "position": 1,
      "libraryId": "1698500736",
      "libraryUrl": "https://www.linkedin.com/ad-library/detail/1698500736",
      "advertiserId": null,
      "advertiserName": "Rescale",
      "isActive": null,
      "startDate": null,
      "endDate": null,
      "activeDays": null,
      "platforms": ["LINKEDIN"],
      "format": "IMAGE",
      "title": "How engineering teams get AI agents past the pilot",
      "body": "Most engineering teams have tried AI agents. Far fewer have moved them past the pilot. Watch Kairos Power and Oak Ridge …",
      "ctaText": null,
      "ctaType": null,
      "linkUrl": null,
      "landingDomain": null,
      "utm": null,
      "payer": null,
      "impressions": null,
      "targeting": null,
      "reachedCountries": null,
      "images": [
        "https://media.licdn.com/dms/image/v2/D5610AQFdah1Z0xeBuQ/image-shrink_1280/B56aH7HH6kH4AY-/0/1795214311284/Fall2026-Showcase_LinkedIn_6A_Webinar-on-demand_1200x1200png"
      ],
      "videos": [],
      "advertiserLogoUrl": "https://media.licdn.com/dms/image/v2/D560BAQFsh4MOa0Ohiw/company-logo_100_100/B56Z4dQLnEIQAQ-/0/1778607242071/rescale_logo",
      "advertiserType": null,
      "advertiserUrl": null,
      "bodyTruncated": true,
      "creativeType": "SPONSORED_STATUS_UPDATE"
    }
  ],
  "summary": {
    "ads": 30,
    "activeAds": 0,
    "advertisers": [
      { "advertiserName": "Rescale", "ads": 5 }
    ],
    "formats": { "ARTICLE": 1, "CAROUSEL": 1, "IMAGE": 24, "SPOTLIGHT": 2, "VIDEO": 2 },
    "platforms": { "LINKEDIN": 30 },
    "ctaTypes": {},
    "landingDomains": [],
    "utmCampaigns": [],
    "launchesByWeek": [],
    "longestRunning": [],
    "oldestStartDate": null,
    "newestStartDate": null,
    "medianActiveDays": null
  }
}
```

* レスポンスは `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>` から得られます。

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "ADS", "payload": { "platform": "linkedin_ad_library", "action": "ad", "libraryId": "1638962914" } }'
```

```json theme={"theme":"css-variables"}
{
  "platform": "linkedin_ad_library",
  "action": "ad",
  "libraryId": "1638962914",
  "ad": {
    "libraryId": "1638962914",
    "libraryUrl": "https://www.linkedin.com/ad-library/detail/1638962914",
    "advertiserId": "85881048",
    "advertiserName": "Samsung Germany",
    "isActive": null,
    "startDate": "2026-11-11",
    "endDate": "2026-11-22",
    "activeDays": 12,
    "platforms": ["LINKEDIN"],
    "format": "VIDEO",
    "title": "Smart arbeiten mit der Galaxy Z-Serie",
    "body": "Mails mobil checken, aber für die eigentliche Arbeit genervt an den Laptop wechseln? Das bremst den Workflow.\n\nSpar dir den Medienbruch mit der neuen Galaxy Z-Serie und nutze die maximale Flexibilität unserer faltbaren Smartphones:\n\n📱 Z Fold8 Ultra: 8-Zoll-…",
    "ctaText": "Learn more",
    "ctaType": null,
    "linkUrl": "https://www.samsung.com/de/smartphones/galaxy-z-fold8/",
    "landingDomain": "samsung.com",
    "utm": null,
    "payer": "Starcom Germany GmbH",
    "impressions": { "min": 50000, "max": 100000 },
    "targeting": {
      "language": { "exclude": null, "include": ["English"] },
      "location": { "exclude": null, "include": ["Germany"] },
      "parameters": [
        { "excluded": false, "parameter": "Audience", "targeted": false }
      ]
    },
    "reachedCountries": ["DE"],
    "images": [],
    "videos": [
      {
        "bitrate": 12005128,
        "files": [
          {
            "bitrate": 12005128,
            "type": "video/mp4",
            "url": "https://dms.licdn.com/playlist/vid/v2/D4E10AQHs0oH-zSWScA/progressive-servable-video/B4EaHKwT54IoAg-/0/1794403027272"
          }
        ],
        "previewUrl": "https://media.licdn.com/dms/image/v2/D4E10AQHs0oH-zSWScA/videocover-high/B4EaHKwT54IoBQ-/0/1794403028674",
        "url": "https://dms.licdn.com/playlist/vid/v2/D4E10AQHs0oH-zSWScA/progressive-servable-video/B4EaHKwT54IoAg-/0/1794403027272"
      }
    ],
    "advertiserLogoUrl": "https://media.licdn.com/dms/image/v2/D4E0BAQEL38Z5ttMZXw/company-logo_100_100/company-logo_100_100/0/1692353831724/samsung_germany_logo",
    "advertiserType": "company",
    "advertiserUrl": "https://www.linkedin.com/company/85881048",
    "bodyTruncated": false,
    "creativeType": "SPONSORED_VIDEO"
  },
  "advertiser": {
    "advertiserId": "85881048",
    "advertiserName": "Samsung Germany",
    "logoUrl": "https://media.licdn.com/dms/image/v2/D4E0BAQEL38Z5ttMZXw/company-logo_100_100/company-logo_100_100/0/1692353831724/samsung_germany_logo",
    "type": "company",
    "url": "https://www.linkedin.com/company/85881048"
  },
  "transparency": {
    "impressions": { "min": 50000, "max": 100000 },
    "impressionsText": "50k-100k",
    "reachByCountry": [
      { "country": "Germany", "countryCode": "DE", "share": 100, "shareText": "100%" }
    ]
  },
  "variants": null
}
```

* `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 クレジットです。完了したリクエストだけが課金されます。

## 関連

* [広告ライブラリの比較](https://docs.querying.ai/ja/engines/ad-libraries.md)
* [Meta 広告ライブラリ](https://docs.querying.ai/ja/engines/meta-ad-library.md)
* [エンジン一覧](https://docs.querying.ai/ja/engines/overview.md)
* [クレジットと上限](https://docs.querying.ai/ja/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.