Saltar para o conteúdo principal
Leia as fontes de anúncios do TikTok como JSON pela API de tarefas assíncronas. ADS é um mecanismo próprio: envie taskType ADS com uma de duas plataformas, e action escolhe o que ler. Para escolher entre as bibliotecas de anúncios, veja Bibliotecas de anúncios comparadas.
  • tiktok_ad_library lê a Biblioteca de Anúncios do TikTok (a Commercial Content Library). Ela lista os anúncios exibidos em 34 regiões: os países da UE e do EEE, o Reino Unido, a Suíça, a Türkiye e o Brasil. Cada anúncio traz o primeiro e o último dia de exibição e uma faixa de impressões, e ad acrescenta a página de destino, quem pagou, a segmentação e as impressões por país, idade e gênero. Use-a para ver todos os anúncios de um concorrente.
  • tiktok_creative_center lê os principais anúncios do TikTok Creative Center. Ele lista os anúncios que tiveram o melhor desempenho em um país nos últimos 7, 30 ou 180 dias, com taxa de cliques, curtidas e setor, para 28 países, incluindo EUA, Coreia e Japão. Use-o para ver quais criativos funcionam em um mercado.
Uma busca custa 0.5 crédito a cada 30 anúncios que retorna nas duas plataformas. advertisers e ad custam 0.5 crédito cada.

Biblioteca de Anúncios do TikTok

Requisição

Envie a tarefa e depois consulte GET /v1/async/task/{id} ou receba o webhook. Veja Tarefas assíncronas. Uma busca de 300 anúncios leva cerca de um minuto.

Analise os anúncios de um concorrente

Três requisições cobrem uma análise de concorrentes:
  1. advertisers com o início do nome do concorrente retorna os nomes exatos e os IDs que a biblioteca conhece.
  2. search com esse nome em advertiserName lista os anúncios do anunciante. sortBy os ordena por data de publicação, data da última exibição ou impressões, activeStatus mantém os anúncios ativos ou os que pararam, e summary conta os formatos e os anúncios que começaram em cada semana.
  3. ad com o libraryId de um anúncio retorna a página de destino, quem pagou, a segmentação, o tamanho do público e as impressões por país, idade e gênero.
Para encontrar anúncios pelo que eles dizem, use query em vez de advertiserName: ele pesquisa o texto, as hashtags e os nomes dos anunciantes.

Parâmetros

  • action: search (padrão), advertisers ou ad.
  • country: Obrigatório em todas as ações. Um de 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 e TR. ALL e países fora da lista, como US, KR e JP, são recusados com 400 VALIDATION_ERROR, porque a biblioteca cobre apenas essas regiões.
  • query: Uma palavra-chave. Em search, corresponde ao texto, às hashtags e aos anunciantes por ordem de relevância, e a biblioteca conta no máximo 5,000 anúncios. Em advertisers, é o início do nome de um anunciante e é obrigatório. search precisa de query ou advertiserName, e não de ambos.
  • advertiserName: O nome exato de um anunciante, como NIKE Retail B.V.. A biblioteca conta todos os anúncios dele.
  • libraryId: O ID numérico de um anúncio, como 1879578148398450. ad o exige.
  • activeStatus: all (padrão), active ou inactive.
  • mediaType: all (padrão), video ou image.
  • startDate, endDate: YYYY-MM-DD. Mantém os anúncios exibidos entre os dois dias. O padrão são os últimos 365 dias.
  • sortBy: published_desc (padrão), published_asc, last_shown_desc, last_shown_asc, impressions_desc ou impressions_asc. Vale para uma busca por advertiserName, e uma busca por query segue sempre a ordem de relevância.
  • limit: De 1 a 300 anúncios. Padrão 30.
  • cursor: O nextCursor de uma resposta anterior, para ler os anúncios seguintes.
search lê todos os campos acima, exceto libraryId. advertisers lê query e country, e ad lê libraryId e country. Um valor que a biblioteca não consegue pesquisar ou um campo que a ação não lê é recusado com 400 VALIDATION_ERROR, e details indica o campo.

Ler mais anúncios

Uma resposta com mais anúncios para ler traz nextCursor. Envie-o como cursor com a mesma busca para receber os anúncios seguintes, de novo até limit. nextCursor é null quando a biblioteca não tem mais. Um cursor só funciona com a busca que o retornou: um query, advertiserName, country, activeStatus, mediaType, intervalo de datas ou sortBy diferente é recusado com 400 VALIDATION_ERROR, enquanto limit pode mudar. Em uma busca por query, que a biblioteca ordena por relevância, alguns anúncios no limite entre duas páginas podem se repetir ou ficar de fora; libraryId permite identificar as repetições.

Encontre um anunciante

action advertisers retorna até 20 anunciantes cujos nomes começam com query. Envie o nome exato como advertiserName para buscar os anúncios desse anunciante.
Cada anunciante tem advertiserId e advertiserName. country, adCount e verified são null, porque as sugestões da biblioteca não informam mais. Uma busca de anunciantes custa 0.5 crédito.

Resposta da busca

  • A resposta repete platform, action, country, query ou advertiserName, activeStatus, mediaType e sortBy. totalCount é a contagem da biblioteca dos anúncios correspondentes, que para em 5,000 em uma busca por query. returnedCount conta os anúncios em ads, hasMore é true quando a biblioteca tem mais, o que nextCursor lê, e libraryUrl abre a mesma busca na Biblioteca de Anúncios.
  • Cada anúncio tem position, libraryId, libraryUrl, advertiserName, title, format (VIDEO, IMAGE ou TEXT), images, videos (url, previewUrl), startDate, endDate, activeDays, impressions (min, max), estimatedAudience (a faixa da biblioteca, como 400K-500K) e platforms (TIKTOK).
  • startDate e endDate são o primeiro e o último dia em que a biblioteca mostra o anúncio (dias em UTC). activeDays conta os dias de startDate a endDate, ambos incluídos. A biblioteca não informa o gasto.
  • isActive é true ou false quando activeStatus é active ou inactive, e null quando é all.
  • advertiserId, payer, linkUrl, landingDomain, utm e targeting são null em uma busca. ad os preenche.
  • summary conta os anúncios desta resposta: ads, activeAds, advertisers (os 10 com mais anúncios), formats, platforms, oldestStartDate, newestStartDate e medianActiveDays, com launchesByWeek (os anúncios que começaram em cada semana ISO) e longestRunning (os 5 anúncios com mais activeDays). Não tem landingDomains nem utmCampaigns, porque uma busca não traz páginas de destino.
  • As URLs de imagens e vídeos são assinadas e expiram cerca de 5 a 6 horas após a leitura. Salve os arquivos de que precisar.
  • Uma busca sem anúncios correspondentes termina com ads vazio e um summary de 0 anúncios.

O que a biblioteca guarda

A biblioteca mostra os anúncios exibidos em suas 34 regiões e os guarda por cerca de 13 meses. Ela informa o primeiro e o último dia de exibição e uma faixa de impressões de cada anúncio. Não publica o gasto.

Abra um anúncio

action ad abre o anúncio com o libraryId e o country que você enviar.
  • ad tem os campos de um anúncio de busca, mais linkUrl, landingDomain, payer (quem pagou o anúncio), category, objective, ctaText, advertiserId, reachedCountries e targeting.
  • targeting traz byCountry (os ages e genders de cada país), provinces, cities, languages, interests, targetAudienceSize (a faixa da biblioteca, como 15.5M-18.9M), customAudience, excludesAudience, highSpendingPower, operatingSystems, deviceModels, videoInteractions e creatorInteractions. Uma parte que a biblioteca não publica para o anúncio é null ou vazia.
  • advertiser tem advertiserId, advertiserName, payer, registryCountry e a account do TikTok por trás dos anúncios (username, displayName, verified, followers, accountType, profileUrl, avatarUrl).
  • transparency traz totalImpressions e byCountry: as impressions de cada país e seus breakdowns por age e gender.
  • Um libraryId para o qual a biblioteca não tem anúncio falha com PAGE_UNAVAILABLE.

TikTok Creative Center

O Creative Center lista os anúncios de melhor desempenho de um país, os anúncios que o TikTok seleciona para os últimos 7, 30 ou 180 dias. É uma amostra ranqueada, e não o conjunto completo de anúncios de um anunciante: o nome do anunciante costuma estar vazio, e a biblioteca não informa datas, gasto nem impressões. Ela informa a taxa de cliques, as curtidas, o nível de custo, o setor e os objetivos de cada anúncio. Use-o para descobrir quais ganchos, formatos e produtos funcionam em um mercado.

Requisição

Parâmetros

  • action: search (padrão) ou ad. advertisers é recusado com 400 VALIDATION_ERROR, porque o Creative Center não tem busca de anunciantes.
  • country: Obrigatório em search. Um de 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 e ZA. ALL é recusado.
  • query: Uma palavra-chave.
  • period: 7, 30 (padrão) ou 180 dias.
  • industry: Um ID de setor, como 21103000000 (Hardware & Electrical), como o industry.id de um anúncio o nomeia.
  • objective: traffic, app_installs, conversions, video_views, reach, lead_generation, product_sales ou app_promotion.
  • adLanguage: Um código de idioma: en, es, ar, vi, th, de, id, pt, fr, ms, nl, ja, it, ro, zh-Hant ou ko.
  • adFormat: spark (anúncios que impulsionam a publicação de um criador) ou non_spark.
  • sortBy: for_you (padrão), impression, ctr, play_2s_rate, play_6s_rate, cvr ou like.
  • limit: De 1 a 200 anúncios. Padrão 30.
  • cursor: O nextCursor de uma resposta anterior.
  • libraryId: O ID numérico de um anúncio do ranking. ad o exige.
search lê todos os campos acima, exceto libraryId, e ad lê somente libraryId. O Creative Center lista no máximo cerca de 400 a 500 anúncios para um país, um período e um conjunto de filtros (totalCount).

Resposta da busca

  • A resposta repete platform, action, country, period, sortBy e os filtros recebidos. totalCount é o número de anúncios do ranking para essa combinação.
  • Cada anúncio tem position, libraryId, title, advertiserName (muitas vezes null), format, ctrPercent (a taxa de cliques em porcentagem), costLevel, likes, industry (id, name), objectives, durationSeconds, width, height, voiceOver, images, videos e videoUrls (o arquivo de vídeo por resolução, como 360p e 1080p).
  • O Creative Center não informa startDate, endDate, impressions nem libraryUrl, então esses campos são null, e summary conta apenas os formatos, os anunciantes e as plataformas.
  • As URLs de vídeo e imagem são assinadas e expiram cerca de 5 a 6 horas após a leitura.

Abra um anúncio

action ad abre um anúncio do ranking por libraryId e acrescenta linkUrl, landingDomain, reachedCountries, comments, shares e source (onde o anúncio foi criado, como TikTok Ads Manager).
Um libraryId para o qual o Creative Center não tem anúncio falha com PAGE_UNAVAILABLE.

Preço

Uma busca reserva 0.5 crédito a cada 30 anúncios que o limit dela pede, e cobra 0.5 crédito a cada 30 anúncios que retorna, no mínimo 0.5 crédito. A busca padrão de 30 anúncios custa 0.5 crédito, e uma busca com limit 300 na Biblioteca de Anúncios reserva 5 créditos. advertisers e ad custam 0.5 crédito cada. Apenas requisições concluídas são cobradas.

Relacionado