메인 콘텐츠로 건너뛰기
Google Ads 투명성 센터를 비동기 task API로 읽어 경쟁사가 어떤 Google 광고를 내는지 JSON으로 받습니다. ADS는 자기 엔진입니다. taskType ADS에 platform google_ads_transparency를 보내고, action으로 읽을 대상을 고릅니다. 라이브러리는 모든 국가의 Google 검색, YouTube, 디스플레이, Google Play, 지도, 쇼핑 광고를 다룹니다. 광고 라이브러리 중에서 고르려면 광고 라이브러리 비교를 참고하십시오.
  • search(기본값)는 advertiserId의 광고주 광고, advertiserIds로 여러 경쟁사의 광고, 또는 domain으로 웹사이트에 연결되는 광고를 내는 모든 광고주의 광고를 나열합니다. 광고마다 형식, 처음과 마지막으로 노출된 날, 게재 일수가 있고, 응답 끝에는 받은 광고를 요약한 summary가 붙습니다.
  • advertisers는 이름으로 광고주의 advertiserId를 찾습니다.
  • ad는 광고 하나를 엽니다. 광고의 문구, 동영상, 랜딩 페이지와 함께, 라이브러리가 공개하는 경우 국가별 노출 수와 Google 지면별 노출 수를 돌려줍니다.
검색은 받은 광고 30개마다 0.5크레딧입니다. advertisers와 ad는 요청당 0.5크레딧입니다.

요청

task를 제출한 뒤 GET /v1/async/task/{id}를 폴링하거나 웹훅으로 받습니다. 참고: 비동기 task.

경쟁사 광고 분석

요청 네 개로 경쟁사 분석을 마칩니다.
  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가 광고주별 광고 수를 세므로, 요청 하나로 광고를 가장 많이 내는 광고주를 확인합니다.

광고 더 받기

라이브러리의 한 페이지는 광고 최대 100개를 담으므로 limit이 100을 넘으면 한 요청에서 여러 페이지를 읽습니다. 받을 광고가 더 있으면 응답에 nextCursor가 붙습니다. 같은 검색에 이 값을 cursor로 보내면 다음 광고를 다시 limit만큼 받습니다. 라이브러리에 광고가 더 없으면 nextCursor는 null입니다. 커서는 그 커서를 돌려준 검색에서만 씁니다. advertiserId, advertiserIds, domain, country, publisherPlatforms, mediaType이나 날짜 범위가 다르면 400 VALIDATION_ERROR로 거절하고, limit은 바꿔도 됩니다.

광고주 찾기

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

검색 응답 예시

  • 응답은 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의 광고를 엽니다. 두 값은 검색 결과에서 얻습니다. 광고, 광고주, 라이브러리가 그 광고에 공개하는 투명성 정보를 돌려줍니다.
  • 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크레딧입니다. 완료된 요청만 과금합니다.

관련 문서