메인 콘텐츠로 건너뛰기
TikTok의 광고 소스를 비동기 task API로 읽어 JSON으로 받습니다. ADS는 자기 엔진입니다. taskType ADS에 두 플랫폼 중 하나를 보내고, action으로 읽을 대상을 고릅니다. 광고 라이브러리 중에서 고르려면 광고 라이브러리 비교를 참고하십시오.
  • 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 광고 라이브러리

요청

task를 제출한 뒤 GET /v1/async/task/{id}를 폴링하거나 웹훅으로 받습니다. 참고: 비동기 task. 광고 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으로 보내 그 광고주의 광고를 검색합니다.
광고주마다 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와 광고 뒤의 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일 동안 고른 광고를 나열합니다. 순위를 매긴 표본이며 광고주의 전체 광고가 아닙니다. 광고주 이름은 비어 있는 경우가 많고, 날짜, 광고비, 노출 수는 주지 않습니다. 광고마다 클릭률, 좋아요, 비용 수준, 업종, 목표를 줍니다. 시장에서 어떤 훅, 형식, 상품이 통하는지 찾을 때 씁니다.

요청

입력

  • 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)를 더합니다.
Creative Center에 광고가 없는 libraryId는 PAGE_UNAVAILABLE로 실패합니다.

가격

검색은 시작할 때 limit이 요청한 광고 30개마다 0.5크레딧을 보류하고, 받은 광고 30개마다 0.5크레딧을 과금하며 최소 0.5크레딧입니다. 기본 검색(광고 30개)은 0.5크레딧이고, 광고 라이브러리에서 limit 300 검색은 5크레딧을 보류합니다. advertisers와 ad는 요청당 0.5크레딧입니다. 완료된 요청만 과금합니다.

관련 문서