> ## 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.

# TikTok 広告 API

> TikTok の競合広告を JSON で分析します。TikTok 広告ライブラリで、広告主がヨーロッパ、英国、スイス、トルコ、ブラジルで掲載する広告をインプレッションとターゲティングとともに検索し、Creative Center で国別のトップ広告を読み取ります。

TikTok の広告ソースを非同期 task API で読み取り、JSON で受け取ります。ADS は独立したエンジンです。`taskType` `ADS` に 2 つのプラットフォームのいずれかを送り、`action` で読み取る対象を選びます。広告ライブラリを選ぶには、[広告ライブラリの比較](https://docs.querying.ai/ja/engines/ad-libraries.md)を参照してください。

* `tiktok_ad_library` は TikTok 広告ライブラリ(Commercial Content Library)を読み取ります。EU と EEA の国、英国、スイス、トルコ、ブラジルの 34 地域で表示された広告を一覧します。広告ごとに最初と最後に表示された日とインプレッションの範囲があり、`ad` はランディングページ、費用の支払者、ターゲティング、国、年齢、性別ごとのインプレッションを加えます。競合のすべての広告を見るときに使います。
* `tiktok_creative_center` は TikTok Creative Center のトップ広告を読み取ります。米国、韓国、日本を含む 28 か国で、直近 7 日、30 日、180 日に最も成果が出た広告を、クリック率、いいね、業種とともに一覧します。市場でどのクリエイティブが効いているかを見るときに使います。

検索は、どちらのプラットフォームでも返した**広告 30 件ごとに 0.5 クレジット**です。`advertisers` と `ad` はリクエストごとに 0.5 クレジットです。

## TikTok 広告ライブラリ

### リクエスト

```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": "tiktok_ad_library", "advertiserName": "NIKE Retail B.V.", "country": "DE", "sortBy": "published_asc", "limit": 14 } }'
```

task を送信したら、`GET /v1/async/task/{id}` をポーリングするか、webhook で受け取ります。参照: [非同期 task](https://docs.querying.ai/ja/concepts/async-tasks.md)。広告 300 件の検索は約 1 分で完了します。

### 競合の広告を分析する

3 つのリクエストで競合分析がそろいます。

1. 競合の名前の先頭部分で `advertisers` を送り、ライブラリが把握している正確な名前と ID を受け取ります。
2. その名前を `advertiserName` に入れて `search` を送り、広告主の広告を一覧します。`sortBy` は公開日、最終表示日、インプレッションの順に並べ、`activeStatus` は掲載中または終了した広告だけを残し、`summary` は形式ごとの広告数と週ごとに開始した広告数を数えます。
3. 広告の `libraryId` で `ad` を送り、ランディングページ、費用の支払者、ターゲティング、オーディエンスの規模、国、年齢、性別ごとのインプレッションを受け取ります。

広告を文面で探すには、`advertiserName` の代わりに `query` を使います。テキスト、ハッシュタグ、広告主名を検索します。

### パラメーター

* `action`: `search`(デフォルト)、`advertisers`、`ad`。
* `country`: すべてのアクションで必須です。`AT`, `BE`, `BG`, `BR`, `CH`, `CY`, `CZ`, `DE`, `DK`, `EE`, `ES`, `FI`, `FR`, `GB`, `GR`, `HR`, `HU`, `IE`, `IS`, `IT`, `LI`, `LT`, `LU`, `LV`, `MT`, `NL`, `NO`, `PL`, `PT`, `RO`, `SE`, `SI`, `SK`, `TR` のいずれか。`ALL` や、`US`、`KR`、`JP` のようにリスト外の国は、ライブラリがこれらの地域のみを対象とするため `400 VALIDATION_ERROR` で拒否されます。
* `query`: キーワード。`search` ではテキスト、ハッシュタグ、広告主を関連度順に探し、ライブラリが数える広告は最大 5,000 件です。`advertisers` では広告主名の先頭部分で、必須です。`search` には `query` または `advertiserName` のどちらかが必要で、両方は送りません。
* `advertiserName`: 広告主の正確な名前(例: `NIKE Retail B.V.`)。ライブラリがその広告主のすべての広告を数えます。
* `libraryId`: 広告の数字の ID(例: `1879578148398450`)。`ad` では必須です。
* `activeStatus`: `all`(デフォルト)、`active`、`inactive`。
* `mediaType`: `all`(デフォルト)、`video`、`image`。
* `startDate`、`endDate`: `YYYY-MM-DD`。2 つの日付の間に表示された広告を残します。デフォルトは直近 365 日です。
* `sortBy`: `published_desc`(デフォルト)、`published_asc`、`last_shown_desc`、`last_shown_asc`、`impressions_desc`、`impressions_asc`。`advertiserName` の検索に適用され、`query` の検索は常に関連度順です。
* `limit`: 広告 1〜300 件。デフォルトは 30 です。
* `cursor`: 前のレスポンスの `nextCursor`。その後の広告を続けて受け取ります。

`search` は `libraryId` を除く上のすべてのフィールドを読み取ります。`advertisers` は `query` と `country`、`ad` は `libraryId` と `country` を読み取ります。ライブラリが検索できない値や、アクションが読み取らないフィールドは `400 VALIDATION_ERROR` で拒否され、`details` がそのフィールドを示します。

### 広告をさらに取得する

読み取る広告がさらにある場合、レスポンスに `nextCursor` が付きます。同じ検索にこの値を `cursor` として送ると、次の広告を再び `limit` 件まで受け取れます。ライブラリにこれ以上広告がなければ `nextCursor` は `null` です。カーソルは、それを返した検索でのみ使えます。`query`、`advertiserName`、`country`、`activeStatus`、`mediaType`、日付範囲や `sortBy` が異なる場合は `400 VALIDATION_ERROR` で拒否され、`limit` は変更できます。ライブラリが関連度順に並べる `query` の検索では、2 つのページの境界にある広告が数件、重複したり抜けたりすることがあります。重複は `libraryId` で見分けます。

### 広告主を探す

`action` `advertisers` は、名前が `query` で始まる広告主を最大 20 件返します。正確な名前を `advertiserName` として送ると、その広告主の広告を検索できます。

```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": "tiktok_ad_library", "action": "advertisers", "query": "nike", "country": "DE" } }'
```

```json theme={"theme":"css-variables"}
{
  "platform": "tiktok_ad_library",
  "action": "advertisers",
  "country": "DE",
  "query": "nike",
  "returnedCount": 5,
  "advertisers": [
    {
      "advertiserId": "7587573238117498896",
      "advertiserName": "NIKE COM SRL",
      "country": null,
      "verified": null,
      "adCount": null
    }
  ]
}
```

広告主ごとに `advertiserId` と `advertiserName` があります。ライブラリの候補はそれ以上の情報を示さないため、`country`、`adCount`、`verified` は `null` です。広告主の検索は 0.5 クレジットです。

### 検索レスポンスの例

```json theme={"theme":"css-variables"}
{
  "platform": "tiktok_ad_library",
  "action": "search",
  "country": "DE",
  "advertiserName": "NIKE Retail B.V.",
  "activeStatus": "all",
  "mediaType": "all",
  "sortBy": "published_asc",
  "totalCount": 20862,
  "returnedCount": 14,
  "hasMore": true,
  "nextCursor": "eyJ2IjoxLCJoIjoiRDBZOVVUcnFNamhOQkhXVyIsImMiOiJleUpzWVhOMFgzTnZjblFpT2xzeE56WXdOakF5TVRnM01EQXdYU3dpYm1WNGRGOWpkWEp6YjNJaU9qRXlmUT09IiwicyI6MiwicCI6MTR9",
  "libraryUrl": "https://library.tiktok.com/ads?region=DE&start_time=1763856000000&end_time=1795391999000&adv_name=NIKE%20Retail%20B.V.&adv_biz_ids=&query_type=2&sort_type=create_time%2Casc&ad_type=0&ad_status=0",
  "ads": [
    {
      "position": 1,
      "libraryId": "1845598948737025",
      "libraryUrl": "https://library.tiktok.com/ads/detail/",
      "advertiserId": null,
      "advertiserName": "NIKE Retail B.V.",
      "isActive": null,
      "startDate": "2025-10-22",
      "endDate": "2025-12-21",
      "activeDays": 61,
      "platforms": ["TIKTOK"],
      "format": "VIDEO",
      "title": "Built to Move Different.",
      "body": null,
      "ctaText": null,
      "ctaType": null,
      "linkUrl": null,
      "landingDomain": null,
      "utm": null,
      "payer": null,
      "impressions": { "min": 400000, "max": 500000 },
      "estimatedAudience": "400K-500K",
      "targeting": null,
      "reachedCountries": null,
      "images": [
        "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/oUghNK4doIQWDyBoVB8FvvvEQmDDPMAupgfSf8~tplv-tiktokx-origin.jpeg"
      ],
      "videos": [
        {
          "previewUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/oUghNK4doIQWDyBoVB8FvvvEQmDDPMAupgfSf8~tplv-tiktokx-origin.jpeg",
          "url": "https://library.tiktok.com/api/v1/cdn/1795365691/video/aHR0cHM6Ly92NTgudGlrdG9rY2RuLmNvbS92aWRlby90b3MvYWxpc2cvdG9zLWFsaXNnLXZlLTAwNTFjMDAxLXNnL29rbWhwZ2c4ZkFReU52UHJnRE5vOGZCNFZFQlFGRHZ1UEtHSWlvLw==/3cddf31b-4bd3-44fc-b813-42e1897d9536"
        }
      ],
      "category": null,
      "objective": null
    }
  ],
  "summary": {
    "ads": 14,
    "activeAds": 0,
    "advertisers": [
      { "advertiserName": "NIKE Retail B.V.", "ads": 14 }
    ],
    "formats": { "IMAGE": 2, "VIDEO": 12 },
    "platforms": { "TIKTOK": 14 },
    "ctaTypes": {},
    "landingDomains": [],
    "utmCampaigns": [],
    "launchesByWeek": [
      { "week": "2025-W42", "ads": 4 }
    ],
    "longestRunning": [
      {
        "libraryId": "1845598948737025",
        "advertiserName": "NIKE Retail B.V.",
        "isActive": null,
        "activeDays": 61,
        "title": "Built to Move Different."
      }
    ],
    "oldestStartDate": "2025-10-16",
    "newestStartDate": "2025-11-11",
    "medianActiveDays": 61
  }
}
```

* レスポンスは `platform`、`action`、`country`、`query` または `advertiserName`、`activeStatus`、`mediaType`、`sortBy` をそのまま返します。`totalCount` はライブラリが数えた条件に合う広告数で、`query` の検索では 5,000 で止まります。`returnedCount` は `ads` の広告数、`hasMore` はライブラリにさらに広告があれば `true` で `nextCursor` で続きを取得し、`libraryUrl` は同じ検索を広告ライブラリで開きます。
* 広告ごとに `position`、`libraryId`、`libraryUrl`、`advertiserName`、`title`、`format`(`VIDEO`、`IMAGE`、`TEXT`)、`images`、`videos`(`url`、`previewUrl`)、`startDate`、`endDate`、`activeDays`、`impressions`(`min`、`max`)、`estimatedAudience`(`400K-500K` のようにライブラリが示す範囲)、`platforms`(`TIKTOK`)があります。
* `startDate` と `endDate` は、ライブラリがその広告を最初と最後に表示した日です(UTC の日付)。`activeDays` は `startDate` から `endDate` までの日数で、両方の日を数えます。ライブラリは広告費を示しません。
* `isActive` は、`activeStatus` が `active` または `inactive` のとき `true` または `false` で、`all` のときは `null` です。
* `advertiserId`、`payer`、`linkUrl`、`landingDomain`、`utm`、`targeting` は検索では `null` です。`ad` が埋めます。
* `summary` はこのレスポンスの広告を数えます。`ads`、`activeAds`、`advertisers`(広告が最も多い 10 件)、`formats`、`platforms`、`oldestStartDate`、`newestStartDate`、`medianActiveDays` で、`launchesByWeek`(ISO 週ごとに開始した広告数)と `longestRunning`(`activeDays` が最大の広告 5 件)も持ちます。検索にはランディングページがないため、`landingDomains` と `utmCampaigns` はありません。
* 画像と動画の URL は署名されており、読み取りから約 5〜6 時間後に失効します。必要なファイルは保存してください。
* 条件に合う広告がない検索は、空の `ads` と広告 `0` 件の `summary` で完了します。

### ライブラリが保管する範囲

ライブラリは 34 地域で配信された広告を表示し、約 13 か月保管します。広告ごとに最初と最後に表示された日とインプレッションの範囲を示します。広告費は公開しません。

### 広告 1 件を開く

`action` `ad` は、送った `libraryId` と `country` の広告を開きます。

```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": "tiktok_ad_library", "action": "ad", "libraryId": "1879578148398450", "country": "DE" } }'
```

```json theme={"theme":"css-variables"}
{
  "platform": "tiktok_ad_library",
  "action": "ad",
  "country": "DE",
  "libraryId": "1879578148398450",
  "ad": {
    "position": 1,
    "libraryId": "1879578148398450",
    "libraryUrl": "https://library.tiktok.com/ads/detail/",
    "advertiserId": "6876453864464188162",
    "advertiserName": "NIKE Retail B.V.",
    "isActive": null,
    "startDate": "2026-10-20",
    "endDate": "2026-11-08",
    "activeDays": 20,
    "platforms": ["TIKTOK"],
    "format": "VIDEO",
    "title": "Neue Winterausrüstung in Nike Factory Stores.",
    "body": null,
    "ctaText": "Learn more",
    "ctaType": null,
    "linkUrl": "https://www.nike.com/de/retail",
    "landingDomain": "nike.com",
    "utm": null,
    "payer": "INITIATIVE MEDIA B.V.",
    "impressions": { "min": 300000, "max": 400000 },
    "estimatedAudience": "300K-400K",
    "targeting": {
      "byCountry": [
        { "country": "DE", "ages": ["18-24"], "genders": ["FEMALE"] }
      ],
      "cities": [],
      "creatorInteractions": null,
      "customAudience": "No",
      "deviceModels": [],
      "excludesAudience": "No",
      "highSpendingPower": "No",
      "interests": null,
      "languages": [],
      "operatingSystems": ["ALL"],
      "provinces": ["Berlin"],
      "targetAudienceSize": "15.5M-18.9M",
      "videoInteractions": null
    },
    "reachedCountries": ["DE"],
    "images": [
      "https://p16-common-sign.tiktokcdn.com/ad-site-i18n-sg/20261013c7c72a61615657cc4f6482cd~tplv-tiktokx-origin.jpeg"
    ],
    "videos": [
      {
        "previewUrl": "https://p16-common-sign.tiktokcdn.com/ad-site-i18n-sg/20261013c7c72a61615657cc4f6482cd~tplv-tiktokx-origin.jpeg",
        "url": "https://library.tiktok.com/api/v1/cdn/1795365698/video/aHR0cHM6Ly92NTgudGlrdG9rY2RuLmNvbS92aWRlby90b3MvYWxpc2cvdG9zLWFsaXNnLXZlLTUxYzc5OS1zZy9vc21jZFFBbjhBZ1BlRWVWQU1iVmRVQ2tzUUQ0WEdrUlVMRVJoZi8=/9aa37923-f585-4393-b635-1409c7ce6656"
      }
    ],
    "category": "Apparel & Accessories",
    "objective": "Traffic"
  },
  "advertiser": {
    "advertiserId": "6876453864464188162",
    "advertiserName": "NIKE Retail B.V.",
    "payer": "INITIATIVE MEDIA B.V.",
    "account": {
      "verified": true,
      "accountType": "VERIFIED_BA",
      "avatarUrl": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/e0b0ac7b6ad6447a8e923fd1eb162f2c~tplv-tiktokx-cropcenter:168:168.jpeg",
      "displayName": "Nike",
      "followers": "9.4M",
      "profileUrl": "https://www.tiktok.com/share/user/208464585232822272",
      "username": "nike"
    },
    "registryCountry": "Netherlands"
  },
  "transparency": {
    "byCountry": [
      {
        "country": "DE",
        "impressions": "357K",
        "breakdowns": [
          { "impressions": "44K", "age": "18-24", "gender": "MALE" }
        ]
      }
    ],
    "totalImpressions": "300K-400K"
  }
}
```

* `ad` は検索広告のフィールドに加えて、`linkUrl`、`landingDomain`、`payer`(広告の費用を支払った主体)、`category`、`objective`、`ctaText`、`advertiserId`、`reachedCountries`、`targeting` を持ちます。
* `targeting` は `byCountry`(国ごとの `ages` と `genders`)、`provinces`、`cities`、`languages`、`interests`、`targetAudienceSize`(`15.5M-18.9M` のようにライブラリが示す範囲)、`customAudience`、`excludesAudience`、`highSpendingPower`、`operatingSystems`、`deviceModels`、`videoInteractions`、`creatorInteractions` を持ちます。ライブラリがその広告について公開しない部分は `null` または空です。
* `advertiser` は `advertiserId`、`advertiserName`、`payer`、`registryCountry`、広告の背後にある TikTok の `account`(`username`、`displayName`、`verified`、`followers`、`accountType`、`profileUrl`、`avatarUrl`)を持ちます。
* `transparency` は `totalImpressions` と `byCountry` を持ちます。国ごとの `impressions` と、`age` と `gender` ごとの `breakdowns` です。
* ライブラリに広告がない `libraryId` は `PAGE_UNAVAILABLE` で失敗します。

## TikTok Creative Center

Creative Center は国別のトップ広告、つまり TikTok が直近 7 日、30 日、180 日で選んだ広告を一覧します。順位付けされたサンプルであり、広告主の全広告ではありません。広告主名は空であることが多く、日付、広告費、インプレッションは示しません。広告ごとにクリック率、いいね、コスト水準、業種、目的を示します。市場でどのフック、形式、商品が効いているかを探すときに使います。

### リクエスト

```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": "tiktok_creative_center", "country": "US", "limit": 25 } }'
```

### パラメーター

* `action`: `search`(デフォルト)または `ad`。Creative Center には広告主の検索がないため、`advertisers` は `400 VALIDATION_ERROR` で拒否されます。
* `country`: `search` では必須です。`AE`, `AR`, `AU`, `BR`, `CA`, `CO`, `DE`, `ES`, `FR`, `GB`, `ID`, `IT`, `JP`, `KR`, `MX`, `MY`, `NL`, `PH`, `PK`, `RO`, `SA`, `SE`, `SG`, `TH`, `TR`, `US`, `VN`, `ZA` のいずれか。`ALL` は拒否されます。
* `query`: キーワード。
* `period`: `7`、`30`(デフォルト)、`180` 日。
* `industry`: 業種 ID(例: `21103000000`(Hardware & Electrical))。広告の `industry.id` が示す値です。
* `objective`: `traffic`, `app_installs`, `conversions`, `video_views`, `reach`, `lead_generation`, `product_sales`, `app_promotion`。
* `adLanguage`: 言語コード: `en`, `es`, `ar`, `vi`, `th`, `de`, `id`, `pt`, `fr`, `ms`, `nl`, `ja`, `it`, `ro`, `zh-Hant`, `ko`。
* `adFormat`: `spark`(クリエイターの投稿をブーストする広告)または `non_spark`。
* `sortBy`: `for_you`(デフォルト)、`impression`、`ctr`、`play_2s_rate`、`play_6s_rate`、`cvr`、`like`。
* `limit`: 広告 1〜200 件。デフォルトは 30 です。
* `cursor`: 前のレスポンスの `nextCursor`。
* `libraryId`: トップ広告の数字の ID。`ad` では必須です。

`search` は `libraryId` を除く上のすべてのフィールドを読み取り、`ad` は `libraryId` だけを読み取ります。Creative Center は、1 つの国、期間、フィルターの組み合わせに対して広告を最大 400〜500 件ほど一覧します(`totalCount`)。

### 検索レスポンスの例

```json theme={"theme":"css-variables"}
{
  "platform": "tiktok_creative_center",
  "action": "search",
  "country": "US",
  "period": 30,
  "sortBy": "for_you",
  "totalCount": 183,
  "returnedCount": 25,
  "hasMore": true,
  "nextCursor": "eyJ2IjoxLCJoIjoiUzJCUk5GZ2V4bkNsM1NXcyIsImciOjIsInMiOjYsInAiOjI1fQ",
  "libraryUrl": "https://ads.tiktok.com/business/creativecenter/inspiration/topads/pc/en",
  "ads": [
    {
      "position": 1,
      "libraryId": "7705106910069080084",
      "libraryUrl": null,
      "advertiserId": null,
      "advertiserName": null,
      "isActive": null,
      "startDate": null,
      "endDate": null,
      "activeDays": null,
      "platforms": ["TIKTOK"],
      "format": "VIDEO",
      "width": 720,
      "height": 1280,
      "title": "No-BS Tool Video 103: Northern Tool + Equipment Wide Truck Toolbox",
      "body": null,
      "ctaText": null,
      "ctaType": null,
      "linkUrl": null,
      "landingDomain": null,
      "utm": null,
      "payer": null,
      "impressions": null,
      "targeting": null,
      "reachedCountries": null,
      "images": [
        "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-51c799-sg/oAQ4uJuVEAkCTi0B2YczHAViMtauDHIKBpPBA~tplv-noop.image"
      ],
      "videos": [
        {
          "previewUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-51c799-sg/oAQ4uJuVEAkCTi0B2YczHAViMtauDHIKBpPBA~tplv-noop.image",
          "url": "https://v16m-default.tiktokcdn.com/dd86ec10034c2f4740daf53e9bd6c280/6b036fbb/video/tos/alisg/tos-alisg-ve-0051c001-sg/oAMlOqB0IiATEFAdXQioXCBIAywNfmmu18gjwb/"
        }
      ],
      "aiSummary": null,
      "comments": null,
      "costLevel": 0,
      "ctrPercent": 0.66,
      "durationSeconds": 19.834,
      "industry": { "id": "21103000000", "name": "Hardware & Electrical" },
      "keywords": null,
      "likes": 787,
      "objectives": ["video_views"],
      "shares": null,
      "source": null,
      "videoUrls": {
        "1080p": "https://v16m-default.tiktokcdn.com/dd86ec10034c2f4740daf53e9bd6c280/6b036fbb/video/tos/alisg/tos-alisg-ve-0051c001-sg/oAMlOqB0IiATEFAdXQioXCBIAywNfmmu18gjwb/",
        "360p": "https://v16m-default.tiktokcdn.com/b36269b95476575962b9c114fc501dc3/6b036fbb/video/tos/alisg/tos-alisg-ve-0051c001-sg/o0NvZBpNAk4I2gfqugQFEnK7QB5fuCkcAgDEDZ/",
        "480p": "https://v16m-default.tiktokcdn.com/59590e737aed92b6a688cb20125bb307/6b036fbb/video/tos/alisg/tos-alisg-ve-0051c001-sg/ogfcNqEZ7n5EDE34BAIB2knfpNgg7FQDgKQBug/",
        "540p": "https://v16m-default.tiktokcdn.com/16951456d88cf46000321fb9be66eaa0/6b036fbb/video/tos/alisg/tos-alisg-ve-51c799-sg/oUfDB7pQBIAg2F65KQEncfgougEkZBDvqQNNpF/",
        "720p": "https://v16m-default.tiktokcdn.com/7be67d46e9a7a041e395d2bfabd195f2/6b036fbb/video/tos/alisg/tos-alisg-ve-51c799-sg/osfGceBcVAqbGTPRAaIIATCgED3LgJryVtPzNf/"
      },
      "voiceOver": null
    }
  ],
  "summary": {
    "ads": 25,
    "activeAds": 0,
    "advertisers": [
      { "advertiserName": "Marco Seven", "ads": 1 }
    ],
    "formats": { "VIDEO": 25 },
    "platforms": { "TIKTOK": 25 },
    "ctaTypes": {},
    "landingDomains": [],
    "utmCampaigns": [],
    "launchesByWeek": [],
    "longestRunning": [],
    "oldestStartDate": null,
    "newestStartDate": null,
    "medianActiveDays": null
  }
}
```

* レスポンスは `platform`、`action`、`country`、`period`、`sortBy`、および受け取ったフィルターをそのまま返します。`totalCount` はその組み合わせのトップ広告の数です。
* 広告ごとに `position`、`libraryId`、`title`、`advertiserName`(`null` のことが多い)、`format`、`ctrPercent`(クリック率、パーセント)、`costLevel`、`likes`、`industry`(`id`、`name`)、`objectives`、`durationSeconds`、`width`、`height`、`voiceOver`、`images`、`videos`、`videoUrls`(`360p`、`1080p` のように解像度別の動画ファイル)があります。
* Creative Center は `startDate`、`endDate`、`impressions`、`libraryUrl` を示さないため、これらは `null` で、`summary` は形式、広告主、プラットフォームだけを数えます。
* 動画と画像の URL は署名されており、読み取りから約 5〜6 時間後に失効します。

### 広告 1 件を開く

`action` `ad` は `libraryId` でトップ広告を開き、`linkUrl`、`landingDomain`、`reachedCountries`、`comments`、`shares`、`source`(広告が作られた場所。例: `TikTok Ads Manager`)を加えます。

```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": "tiktok_creative_center", "action": "ad", "libraryId": "7699613362636095496" } }'
```

```json theme={"theme":"css-variables"}
{
  "platform": "tiktok_creative_center",
  "action": "ad",
  "libraryId": "7699613362636095496",
  "ad": {
    "position": 1,
    "libraryId": "7699613362636095496",
    "libraryUrl": null,
    "advertiserId": null,
    "advertiserName": "Bob Mills Furniture",
    "isActive": null,
    "startDate": null,
    "endDate": null,
    "activeDays": null,
    "platforms": ["TIKTOK"],
    "format": "VIDEO",
    "width": 720,
    "height": 1280,
    "title": "Better Sleep Starts with the Right Mattress",
    "body": null,
    "ctaText": null,
    "ctaType": null,
    "linkUrl": "https://www.bobmillsfurniture.com/sleep-experts",
    "landingDomain": "bobmillsfurniture.com",
    "utm": null,
    "payer": null,
    "impressions": null,
    "targeting": null,
    "reachedCountries": ["US"],
    "images": [
      "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o47taaAAR0LVnI7BhqzPAuKziAYczLByGJi4E~tplv-noop.image"
    ],
    "videos": [
      {
        "previewUrl": "https://p16-common-sign.tiktokcdn.com/tos-alisg-p-0051c001-sg/o47taaAAR0LVnI7BhqzPAuKziAYczLByGJi4E~tplv-noop.image",
        "url": "https://v16m-default.tiktokcdn.com/474b4bf87f62a54743f28d85725bcaf2/6b036fca/video/tos/alisg/tos-alisg-ve-0051c001-sg/oE9AQRij1FVAIezCN8Q3CWtGbD2MUAsgqg8e3f/"
      }
    ],
    "aiSummary": null,
    "comments": 0,
    "costLevel": 1,
    "ctrPercent": 0.2,
    "durationSeconds": 30.55,
    "industry": { "id": "23123000000", "name": "Sports & Fitness" },
    "keywords": null,
    "likes": 28,
    "objectives": ["traffic"],
    "shares": 0,
    "source": "TikTok Ads Manager",
    "videoUrls": {
      "1080p": "https://v16m-default.tiktokcdn.com/474b4bf87f62a54743f28d85725bcaf2/6b036fca/video/tos/alisg/tos-alisg-ve-0051c001-sg/oE9AQRij1FVAIezCN8Q3CWtGbD2MUAsgqg8e3f/",
      "360p": "https://v16m-default.tiktokcdn.com/93487026a84b0472c46d3ff9471ee8f7/6b036fca/video/tos/alisg/tos-alisg-ve-0051c001-sg/oo1kCLCbgGVGt1GsCACGAAzbQefjqmDIfyIXQg/",
      "480p": "https://v16m-default.tiktokcdn.com/49d6ee93d4fc380675d41954037c55d1/6b036fca/video/tos/alisg/tos-alisg-ve-51c799-sg/okfRtfZroqDRIgEzhatFVDwDBABy2ENaWhQAQB/",
      "540p": "https://v16m-default.tiktokcdn.com/ce0699fb34b5ba3ccaa5251fba131ce2/6b036fca/video/tos/alisg/tos-alisg-ve-0051c001-sg/oUCWfxEEIBgqR32fDhFQapDtyZWaEDAVDBoNQh/",
      "720p": "https://v16m-default.tiktokcdn.com/d27a8eba19586eacc4784887cdd649e3/6b036fca/video/tos/alisg/tos-alisg-ve-0051c001-sg/o0fNIDWVyhREjDDafOB4EzahgQFZBqAo2tDQhE/"
    },
    "voiceOver": false
  }
}
```

Creative Center に広告がない `libraryId` は `PAGE_UNAVAILABLE` で失敗します。

## 料金

検索は開始時に、`limit` が要求した広告 30 件ごとに 0.5 クレジットを保留し、返した広告 30 件ごとに 0.5 クレジットを課金します(最低 0.5 クレジット)。デフォルトの検索(広告 30 件)は 0.5 クレジットで、広告ライブラリでの `limit` 300 の検索は 5 クレジットを保留します。`advertisers` と `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.