taskType ADS에 platform google_ads_transparency를 보내고, action으로 읽을 대상을 고릅니다. 라이브러리는 모든 국가의 Google 검색, YouTube, 디스플레이, Google Play, 지도, 쇼핑 광고를 다룹니다. 광고 라이브러리 중에서 고르려면 광고 라이브러리 비교를 참고하십시오.
search(기본값)는advertiserId의 광고주 광고,advertiserIds로 여러 경쟁사의 광고, 또는domain으로 웹사이트에 연결되는 광고를 내는 모든 광고주의 광고를 나열합니다. 광고마다 형식, 처음과 마지막으로 노출된 날, 게재 일수가 있고, 응답 끝에는 받은 광고를 요약한summary가 붙습니다.advertisers는 이름으로 광고주의advertiserId를 찾습니다.ad는 광고 하나를 엽니다. 광고의 문구, 동영상, 랜딩 페이지와 함께, 라이브러리가 공개하는 경우 국가별 노출 수와 Google 지면별 노출 수를 돌려줍니다.
advertisers와 ad는 요청당 0.5크레딧입니다.
요청
GET /v1/async/task/{id}를 폴링하거나 웹훅으로 받습니다. 참고: 비동기 task.
경쟁사 광고 분석
요청 네 개로 경쟁사 분석을 마칩니다.- 경쟁사 이름으로
advertisers를 보내advertiserId와, 라이브러리가 그 이름에 제안하는 웹사이트를 받습니다. - 그
advertiserId또는 경쟁사의domain으로search를 보내 광고를 나열합니다.activeDays는 오래 게재한 광고를 보여 주고,mediaType과publisherPlatforms는 소재와 지면별로 광고를 나누며,summary는 형식별 광고 수와 주별로 시작한 광고 수를 셉니다. - 광고의
libraryId와advertiserId로ad를 보내 문구, 동영상, 도달한 국가를 받고, EU에 노출된 광고는 국가별, 지면별 노출 수도 받습니다. 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개)도 담습니다.limit500 검색은 광고 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크레딧입니다. 완료된 요청만 과금합니다.