taskType ADS에 두 플랫폼 중 하나를 보내고, action으로 읽을 대상을 고릅니다. 광고 라이브러리 중에서 고르려면 광고 라이브러리 비교를 참고하십시오.
tiktok_ad_library는 TikTok 광고 라이브러리(Commercial Content Library)를 읽습니다. EU와 EEA 국가, 영국, 스위스, 튀르키예, 브라질의 34개 지역에서 노출된 광고를 나열합니다. 광고마다 처음과 마지막으로 노출된 날과 노출 수 범위가 있고,ad는 랜딩 페이지, 광고비를 낸 주체, 타기팅, 국가, 연령, 성별 노출 수를 더합니다. 경쟁사의 모든 광고를 볼 때 씁니다.tiktok_creative_center는 TikTok Creative Center의 상위 광고를 읽습니다. 미국, 한국, 일본을 포함한 28개 국가에서 최근 7일, 30일, 180일 동안 성과가 가장 좋았던 광고를 클릭률, 좋아요, 업종과 함께 나열합니다. 시장에서 어떤 소재가 통하는지 볼 때 씁니다.
advertisers와 ad는 요청당 0.5크레딧입니다.
TikTok 광고 라이브러리
요청
GET /v1/async/task/{id}를 폴링하거나 웹훅으로 받습니다. 참고: 비동기 task. 광고 300개 검색은 1분 안팎에 끝납니다.
경쟁사 광고 분석
요청 세 개로 경쟁사 분석을 마칩니다.- 경쟁사 이름의 앞부분으로
advertisers를 보내 라이브러리가 아는 정확한 이름과 ID를 받습니다. - 그 이름을
advertiserName에 넣어search를 보내 광고주의 광고를 나열합니다.sortBy는 게시일, 마지막 노출일, 노출 수 순으로 정렬하고,activeStatus는 게재 중이거나 중단된 광고만 남기며,summary는 형식별 광고 수와 주별로 시작한 광고 수를 셉니다. - 광고의
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으로 보내 그 광고주의 광고를 검색합니다.
advertiserId와 advertiserName이 있습니다. 라이브러리의 제안은 그 이상을 주지 않으므로 country, adCount, verified는 null입니다. 광고주 검색은 0.5크레딧입니다.
검색 응답 예시
- 응답은
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의 광고를 엽니다.
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와 광고 뒤의 TikTokaccount(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일 동안 고른 광고를 나열합니다. 순위를 매긴 표본이며 광고주의 전체 광고가 아닙니다. 광고주 이름은 비어 있는 경우가 많고, 날짜, 광고비, 노출 수는 주지 않습니다. 광고마다 클릭률, 좋아요, 비용 수준, 업종, 목표를 줍니다. 시장에서 어떤 훅, 형식, 상품이 통하는지 찾을 때 씁니다.요청
입력
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).
검색 응답 예시
- 응답은
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)를 더합니다.
libraryId는 PAGE_UNAVAILABLE로 실패합니다.
가격
검색은 시작할 때limit이 요청한 광고 30개마다 0.5크레딧을 보류하고, 받은 광고 30개마다 0.5크레딧을 과금하며 최소 0.5크레딧입니다. 기본 검색(광고 30개)은 0.5크레딧이고, 광고 라이브러리에서 limit 300 검색은 5크레딧을 보류합니다. advertisers와 ad는 요청당 0.5크레딧입니다. 완료된 요청만 과금합니다.