> ## 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`에 두 플랫폼 중 하나를 보내고, `action`으로 읽을 대상을 고릅니다. 광고 라이브러리 중에서 고르려면 [광고 라이브러리 비교](https://docs.querying.ai/ko/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}`를 폴링하거나 웹훅으로 받습니다. 참고: [비동기 task](https://docs.querying.ai/ko/concepts/async-tasks.md). 광고 300개 검색은 1분 안팎에 끝납니다.

### 경쟁사 광고 분석

요청 세 개로 경쟁사 분석을 마칩니다.

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`. 두 날짜 사이에 노출된 광고를 남깁니다. 기본값은 최근 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` 검색에서는 두 페이지 경계의 광고 몇 개가 반복되거나 빠질 수 있습니다. 반복은 `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개월간 보관합니다. 광고마다 처음과 마지막으로 노출된 날과 노출 수 범위를 줍니다. 광고비는 공개하지 않습니다.

### 광고 하나 열기

`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는 국가, 기간, 필터 조합 하나에 광고를 최대 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시간 뒤 만료됩니다.

### 광고 하나 열기

`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/ko/engines/ad-libraries.md)
* [Meta 광고 라이브러리](https://docs.querying.ai/ko/engines/meta-ad-library.md)
* [엔진 목록](https://docs.querying.ai/ko/engines/overview.md)
* [크레딧과 한도](https://docs.querying.ai/ko/concepts/credits-and-limits.md)


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