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

# Google Ads 투명성 센터 API

> 경쟁사 광고를 Google Ads 투명성 센터에서 JSON으로 분석합니다. 광고주가 Search, YouTube, 디스플레이, Play, 지도, 쇼핑에 게재하는 광고를 광고별 게재 기간과 함께 나열하고, 광고 하나를 열어 문구, 동영상, 국가별 노출 수를 받습니다.

Google Ads 투명성 센터를 비동기 task API로 읽어 경쟁사가 어떤 Google 광고를 내는지 JSON으로 받습니다. ADS는 자기 엔진입니다. `taskType` `ADS`에 `platform` `google_ads_transparency`를 보내고, `action`으로 읽을 대상을 고릅니다. 라이브러리는 모든 국가의 Google 검색, YouTube, 디스플레이, Google Play, 지도, 쇼핑 광고를 다룹니다. 광고 라이브러리 중에서 고르려면 [광고 라이브러리 비교](https://docs.querying.ai/ko/engines/ad-libraries.md)를 참고하십시오.

* `search`(기본값)는 `advertiserId`의 광고주 광고, `advertiserIds`로 여러 경쟁사의 광고, 또는 `domain`으로 웹사이트에 연결되는 광고를 내는 모든 광고주의 광고를 나열합니다. 광고마다 형식, 처음과 마지막으로 노출된 날, 게재 일수가 있고, 응답 끝에는 받은 광고를 요약한 `summary`가 붙습니다.
* `advertisers`는 이름으로 광고주의 `advertiserId`를 찾습니다.
* `ad`는 광고 하나를 엽니다. 광고의 문구, 동영상, 랜딩 페이지와 함께, 라이브러리가 공개하는 경우 국가별 노출 수와 Google 지면별 노출 수를 돌려줍니다.

검색은 받은 **광고 30개마다 0.5크레딧**입니다. `advertisers`와 `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": "google_ads_transparency", "domain": "nike.com", "country": "KR", "limit": 5 } }'
```

task를 제출한 뒤 `GET /v1/async/task/{id}`를 폴링하거나 웹훅으로 받습니다. 참고: [비동기 task](https://docs.querying.ai/ko/concepts/async-tasks.md).

## 경쟁사 광고 분석

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

1. 경쟁사 이름으로 `advertisers`를 보내 `advertiserId`와, 라이브러리가 그 이름에 제안하는 웹사이트를 받습니다.
2. 그 `advertiserId` 또는 경쟁사의 `domain`으로 `search`를 보내 광고를 나열합니다. `activeDays`는 오래 게재한 광고를 보여 주고, `mediaType`과 `publisherPlatforms`는 소재와 지면별로 광고를 나누며, `summary`는 형식별 광고 수와 주별로 시작한 광고 수를 셉니다.
3. 광고의 `libraryId`와 `advertiserId`로 `ad`를 보내 문구, 동영상, 도달한 국가를 받고, EU에 노출된 광고는 국가별, 지면별 노출 수도 받습니다.
4. `advertiserIds`로 `search`를 보내 최대 10개 경쟁사를 한 번에 비교합니다.

## 입력

* `action`: `search`(기본값), `advertisers`, `ad`.
* `query`: 광고주 이름, 1-100자. `advertisers`에 필수이고, `search`와 `ad`는 거절합니다.
* `advertiserId`: 광고주 ID(예: `AR16396071307843731457`). `search`에는 `advertiserId`, `advertiserIds`, `domain` 중 하나가 필요하고, `ad`에는 `advertiserId`가 필수입니다.
* `advertiserIds`: 광고주 ID 1-10개. 배열이나 쉼표로 구분한 텍스트로 보냅니다. 한 요청에는 `advertiserIds`나 `advertiserId` 중 하나를 보냅니다.
* `domain`: `nike.com` 같은 도메인만. `search`는 어느 광고주가 내든 그 도메인으로 연결되는 광고를 나열합니다. `domain`과 광고주 ID는 함께 쓸 수 없습니다.
* `libraryId`: 광고의 소재 ID(예: `CR07264436911983296513`). `ad`에 필수입니다.
* `country`: 광고가 게재된 국가의 2글자 코드, 또는 모든 국가를 뜻하는 `ALL`(기본값). 한 번에 한 국가만 받습니다. `search`가 읽습니다.
* `publisherPlatforms`: 광고가 게재된 곳: `search`, `youtube`, `maps`, `shopping`, `play`. 한 번에 한 값만 받습니다.
* `mediaType`: `all`(기본값), `text`, `image`, `video`.
* `startDate`, `endDate`: `YYYY-MM-DD`. 함께 보냅니다. 두 날짜 사이에 한 번 이상 노출된 광고를 남깁니다.
* `limit`: `search`는 광고 1-500개(기본값 30), `advertisers`는 광고주 1-50곳(기본값 30).
* `cursor`: 이전 응답의 `nextCursor`. 그 뒤의 광고를 받습니다.

`search`는 `advertiserId`, `advertiserIds`, `domain`, `country`, `publisherPlatforms`, `mediaType`, `startDate`, `endDate`, `limit`, `cursor`를 읽습니다. `advertisers`는 `query`와 `limit`, `ad`는 `advertiserId`와 `libraryId`를 읽습니다. `pageId`, `activeStatus`, `sortBy`처럼 라이브러리가 검색할 수 없는 필드나 액션이 읽지 않는 필드는 `400 VALIDATION_ERROR`로 거절하고, `details`가 그 필드를 알려 줍니다.

## 경쟁사 비교

`advertiserIds`는 한 요청으로 최대 10개 광고주의 광고를 나열합니다. 응답의 `summary`가 광고주별 광고 수를 세므로, 요청 하나로 광고를 가장 많이 내는 광고주를 확인합니다.

```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": "google_ads_transparency", "advertiserIds": ["AR16396071307843731457", "<competitor advertiserId>"], "country": "KR", "mediaType": "video" } }'
```

## 광고 더 받기

라이브러리의 한 페이지는 광고 최대 100개를 담으므로 `limit`이 100을 넘으면 한 요청에서 여러 페이지를 읽습니다. 받을 광고가 더 있으면 응답에 `nextCursor`가 붙습니다. 같은 검색에 이 값을 `cursor`로 보내면 다음 광고를 다시 `limit`만큼 받습니다. 라이브러리에 광고가 더 없으면 `nextCursor`는 `null`입니다.

커서는 그 커서를 돌려준 검색에서만 씁니다. `advertiserId`, `advertiserIds`, `domain`, `country`, `publisherPlatforms`, `mediaType`이나 날짜 범위가 다르면 `400 VALIDATION_ERROR`로 거절하고, `limit`은 바꿔도 됩니다.

## 광고주 찾기

`action` `advertisers`는 광고 라이브러리 검색창이 제안하는 것처럼 이름이 `query`와 맞는 광고주를 돌려줍니다. 고른 광고주의 `advertiserId`를 보내 그 광고주의 광고를 검색합니다.

```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": "google_ads_transparency", "action": "advertisers", "query": "올리브영" } }'
```

```json theme={"theme":"css-variables"}
{
  "platform": "google_ads_transparency",
  "action": "advertisers",
  "query": "올리브영",
  "returnedCount": 10,
  "libraryUrl": "https://adstransparency.google.com/?region=anywhere",
  "advertisers": [
    {
      "libraryUrl": "https://adstransparency.google.com/advertiser/AR16396071307843731457?region=anywhere",
      "advertiserId": "AR16396071307843731457",
      "advertiserName": "CJ올리브영",
      "country": "KR",
      "verified": false,
      "adCount": null,
      "adCountRange": { "min": 800, "max": 900 }
    }
  ],
  "domains": []
}
```

광고주마다 `advertiserId`, `advertiserName`, `country`(광고주가 등록된 국가), `verified`, `adCountRange`(라이브러리가 밝히는 광고주의 광고 수 범위, `min`과 `max`), 투명성 센터에서 그 광고주를 여는 `libraryUrl`이 있습니다. 라이브러리는 범위를 주므로 `adCount`는 `null`입니다. `domains`는 라이브러리가 그 이름으로 제안하는 웹사이트이며, `search`가 `domain`으로 받습니다. 그 이름의 광고주가 없으면 빈 `advertisers`로 완료됩니다. 광고주 검색은 `query`와 `limit`만 받고 0.5크레딧입니다.

## 검색 응답 예시

```json theme={"theme":"css-variables"}
{
  "platform": "google_ads_transparency",
  "action": "search",
  "country": "KR",
  "domain": "nike.com",
  "totalCount": null,
  "totalCountRange": { "min": 1000, "max": 2000 },
  "returnedCount": 5,
  "hasMore": true,
  "nextCursor": "eyJ2IjoxLCJoIjoiZnl5NGtZLXJ2MjBLQkVlcCIsImMiOiJDZ29BUDd6bWZJN0cwNlFURWhDUFRtUGphSW8rNThJRCtROEFBQUFBR2duOCtHUHIrSExRTEM4PSIsInAiOjV9",
  "libraryUrl": "https://adstransparency.google.com/?region=KR&domain=nike.com",
  "ads": [
    {
      "position": 1,
      "libraryId": "CR09172534072340119553",
      "libraryUrl": "https://adstransparency.google.com/advertiser/AR01437837420136497153/creative/CR09172534072340119553?region=anywhere",
      "advertiserId": "AR01437837420136497153",
      "advertiserName": "株式会社ナイキジャパン",
      "isActive": true,
      "startDate": "2025-01-08",
      "endDate": "2026-11-22",
      "activeDays": 684,
      "platforms": null,
      "format": "TEXT",
      "width": 348,
      "height": 517,
      "title": null,
      "body": null,
      "ctaText": null,
      "ctaType": null,
      "linkUrl": null,
      "landingDomain": "nike.com",
      "utm": null,
      "payer": null,
      "impressions": null,
      "targeting": null,
      "reachedCountries": null,
      "images": ["https://tpc.googlesyndication.com/archive/simgad/11407271379265753184"],
      "videos": []
    }
  ],
  "summary": {
    "ads": 5,
    "activeAds": 5,
    "advertisers": [
      { "advertiserId": "AR01437837420136497153", "advertiserName": "株式会社ナイキジャパン", "ads": 3 }
    ],
    "formats": { "TEXT": 5 },
    "platforms": {},
    "ctaTypes": {},
    "landingDomains": [
      { "domain": "nike.com", "ads": 5 }
    ],
    "utmCampaigns": [],
    "launchesByWeek": [
      { "week": "2022-W32", "ads": 1 }
    ],
    "longestRunning": [
      {
        "libraryId": "CR16869261615919267841",
        "advertiserName": "NIKE GLOBAL TRADING B.V. SINGAPORE BRANCH",
        "isActive": true,
        "activeDays": 1563,
        "title": null
      }
    ],
    "oldestStartDate": "2022-08-13",
    "newestStartDate": "2025-01-08",
    "medianActiveDays": 714
  }
}
```

* 응답은 `platform`, `action`, `country`, `advertiserId`, `advertiserIds` 또는 `domain`과 받은 필터를 그대로 돌려줍니다.
* `totalCountRange`는 라이브러리가 추정한 조건에 맞는 광고 수이며 `min`과 `max`로 나옵니다. `totalCount`는 `null`입니다. `returnedCount`는 `ads`의 광고 수, `hasMore`는 라이브러리에 광고가 더 있으면 `true`이며 `nextCursor`로 이어 받고, `libraryUrl`은 같은 검색을 투명성 센터에서 엽니다.
* 광고마다 `position`, `libraryId`, `libraryUrl`, `advertiserId`, `advertiserName`, `format`(`TEXT`, `IMAGE`, `VIDEO`), `width`, `height`, `images`, `videos`, `startDate`, `endDate`, `activeDays`, `isActive`, `landingDomain`이 있습니다.
* `startDate`와 `endDate`는 라이브러리가 그 광고를 처음과 마지막으로 보여 준 날입니다(UTC 날짜). `activeDays`는 `startDate`부터 `endDate`까지의 일수이고 두 날짜를 모두 셉니다. 라이브러리가 `startDate`를 주지 않으면 `null`입니다. 라이브러리는 광고가 마지막으로 노출된 시점만 공개하고 게재 여부는 알려 주지 않으므로, `isActive`는 오늘이나 어제 마지막으로 노출된 광고에서 `true`입니다.
* `landingDomain`은 광고 랜딩 페이지의 호스트이고, 소문자에 `www.`를 뺀 값입니다. 라이브러리가 주지 않으면 `null`입니다.
* 많은 텍스트 광고는 이미지로 옵니다. `images`는 라이브러리가 그린 광고의 링크를 담고, 문구는 `ad`에 있습니다. `title`, `body`, `ctaText`, `linkUrl`은 검색에서는 `null`이고, 광고 미리보기에 있으면 `ad`가 채웁니다. `impressions`는 EU에 노출된 광고에 대해 `ad`가 채웁니다. `platforms`, `targeting`, `payer`, `utm`은 `null`입니다.
* `summary`는 이 응답의 광고를 셉니다. `ads`, `activeAds`, `advertisers`(광고가 가장 많은 10곳: `advertiserId`, `advertiserName`, `ads`), `formats`, `landingDomains`(광고가 가장 많은 10개), `oldestStartDate`, `newestStartDate`, `medianActiveDays`입니다. `launchesByWeek`(ISO 주별로 시작한 광고 수, 오래된 주부터)와 `longestRunning`(`activeDays`가 가장 큰 광고 5개)도 담습니다. `limit` 500 검색은 광고 500개를 요약하고, `cursor`로 읽은 각 페이지는 그 페이지의 광고를 요약해 담습니다.
* 광고의 이미지 링크(`tpc.googlesyndication.com`)는 서명되지 않아 계속 열립니다. `ad`의 미리보기 링크는 서명되어 있어 만료될 수 있습니다.
* 조건에 맞는 광고가 없는 검색은 빈 `ads`와 광고 `0`개의 `summary`로 완료됩니다.

## 라이브러리가 보관하는 범위

* 라이브러리는 모든 국가의 광고를 보여 줍니다. 광고는 마지막으로 노출된 날부터 약 12개월간 남습니다.
* EU에 노출된 광고에는 노출 수가 있습니다. 광고 전체, 국가별(처음과 마지막 노출 날짜 포함), Google 지면별 범위입니다. 그 밖의 지역에 노출된 광고에는 광고가 도달한 국가와 마지막 노출 날짜가 있습니다. 이런 광고는 `ad`가 첫 노출 날짜(와 `activeDays`)를 광고주의 광고 목록에서 읽으며, `search`가 돌려주는 값과 같습니다. 광고가 도달한 국가의 목록 앞 800개 안에 없을 때만 `startDate`와 `activeDays`가 `null`이고, `debug.dates`는 `detail`, `search`, `not-found` 중 하나입니다.

경쟁사의 광고 이력을 남기려면 그 광고를 매일처럼 주기적으로 검색해 저장하십시오.

## 광고 하나 열기

`action` `ad`는 보낸 `libraryId`와 `advertiserId`의 광고를 엽니다. 두 값은 검색 결과에서 얻습니다. 광고, 광고주, 라이브러리가 그 광고에 공개하는 투명성 정보를 돌려줍니다.

```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": "google_ads_transparency", "action": "ad", "advertiserId": "AR18378488041124659201", "libraryId": "CR16529691107676651521" } }'
```

```json theme={"theme":"css-variables"}
{
  "platform": "google_ads_transparency",
  "action": "ad",
  "ad": {
    "libraryId": "CR16529691107676651521",
    "libraryUrl": "https://adstransparency.google.com/advertiser/AR18378488041124659201/creative/CR16529691107676651521?region=anywhere",
    "advertiserId": "AR18378488041124659201",
    "advertiserName": "Nike Retail BV",
    "isActive": true,
    "startDate": "2025-11-18",
    "endDate": "2026-11-22",
    "activeDays": 370,
    "platforms": null,
    "format": "TEXT",
    "title": "Nike Black Friday Days trwają - Rabat do 40% na wybrane modele",
    "body": "Dni Nike Black Friday Days wystartowały. Zniżki do 40% na wybrane produkty. Do 1 grudnia.",
    "ctaText": null,
    "ctaType": null,
    "linkUrl": null,
    "landingDomain": "nike.com",
    "utm": null,
    "payer": null,
    "impressions": { "min": 9000, "max": 10000 },
    "targeting": null,
    "reachedCountries": ["DE", "PL"],
    "images": [],
    "videos": [],
    "displayUrl": "www.nike.com/kobiety/fleece",
    "previewKind": "text",
    "previewText": ["nike.com", "www.nike.com/kobiety/fleece"],
    "previewUrl": "https://displayads-formats.googleusercontent.com/ads/preview/content.js"
  },
  "advertiser": {
    "libraryUrl": "https://adstransparency.google.com/advertiser/AR18378488041124659201?region=anywhere",
    "advertiserId": "AR18378488041124659201",
    "advertiserName": "Nike Retail BV"
  },
  "transparency": {
    "startDate": "2025-11-18",
    "endDate": "2026-11-22",
    "impressions": { "min": 9000, "max": 10000 },
    "surfaces": [
      {
        "impressions": { "min": 9000, "max": 10000 },
        "surfaceId": 3,
        "platform": "SEARCH"
      },
      {
        "impressions": { "min": 0, "max": 1000 },
        "surfaceId": 2,
        "platform": "MAPS"
      }
    ],
    "countries": [
      {
        "country": "DE",
        "startDate": "2025-11-24",
        "endDate": "2026-11-22",
        "impressions": { "min": 0, "max": 1000 },
        "surfaces": [
          {
            "impressions": { "min": 0, "max": 1000 },
            "surfaceId": 3,
            "platform": "SEARCH"
          }
        ]
      },
      {
        "country": "PL",
        "startDate": "2025-11-18",
        "endDate": "2026-11-22",
        "impressions": { "min": 9000, "max": 10000 },
        "surfaces": [
          {
            "impressions": { "min": 0, "max": 1000 },
            "surfaceId": 2,
            "platform": "MAPS"
          },
          {
            "impressions": { "min": 9000, "max": 10000 },
            "surfaceId": 3,
            "platform": "SEARCH"
          }
        ]
      }
    ]
  },
  "variants": [
    {
      "width": null,
      "height": null,
      "imageUrl": null,
      "previewUrl": "https://displayads-formats.googleusercontent.com/ads/preview/content.js"
    },
    {
      "width": null,
      "height": null,
      "imageUrl": null,
      "previewUrl": "https://displayads-formats.googleusercontent.com/ads/preview/content.js"
    }
  ]
}
```

* `ad`는 검색 광고의 필드에 광고 미리보기의 문구를 더해 갖습니다. `title`, `body`, `ctaText`, `displayUrl`, `linkUrl`, `longTitle`, `channelName`, `address`, `merchant`는 광고에 있는 것만 들어가고, `videos`(`url`, `previewUrl`)도 있습니다. `previewKind`는 광고 종류입니다. `text`(검색), `local`(지도, `address` 포함), `display`(디스플레이와 YouTube), `shopping`(`merchant` 포함). `previewText`는 미리보기의 문구를 나열하고, `previewUrl`은 미리보기를 엽니다.
* `reachedCountries`는 광고가 노출된 국가를 ISO 코드로 나열합니다.
* `impressions`(`min`, `max`)는 라이브러리가 EU에 노출된 광고에 공개하는 노출 수 범위입니다. EU 밖에서는 `null`입니다.
* `advertiser`는 `advertiserId`, `advertiserName`, `libraryUrl`을 갖습니다.
* `transparency`는 광고의 `startDate`, `endDate`, `impressions`, `surfaces`(Google 지면별 `surfaceId`와 노출 수 범위이며, `platform`은 알려진 지면 `SEARCH`와 `MAPS`에만 지면 이름을 담습니다), 그리고 각자의 `startDate`, `endDate`, `impressions`, `surfaces`를 가진 `countries`를 담습니다. EU 밖에서 노출된 광고의 `transparency`는 국가와 마지막 노출 날짜를 나열하고, 라이브러리가 EU에만 주는 날짜와 노출 수는 거기서 `null`입니다(광고 자체의 `startDate`는 광고 목록에서 읽습니다).
* `variants`는 라이브러리가 보관하는 광고의 렌더링을 나열합니다. `width`, `height`, `imageUrl`, `previewUrl`입니다.
* 라이브러리가 타기팅을 공개하지 않으므로 `platforms`와 `targeting`은 `null`입니다.
* 라이브러리에 광고가 없는 `libraryId`는 `PAGE_UNAVAILABLE`로 실패합니다.

## 가격

검색은 시작할 때 `limit`이 요청한 광고 30개마다 0.5크레딧을 보류하고, 받은 광고 30개마다 0.5크레딧을 과금하며 최소 0.5크레딧입니다. 기본 검색(광고 30개)은 0.5크레딧이고, `limit` 500 검색은 8.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.