Saltar al contenido principal
Lee las fuentes de anuncios de TikTok como JSON a través de la API asíncrona de tareas. ADS es un motor propio: envía taskType ADS con una de dos plataformas, y action elige qué leer. Para elegir entre las bibliotecas de anuncios, consulta Bibliotecas de anuncios comparadas.
  • tiktok_ad_library lee la Biblioteca de anuncios de TikTok (la Commercial Content Library). Lista los anuncios mostrados en 34 regiones: los países de la UE y del EEE, el Reino Unido, Suiza, Türkiye y Brasil. Cada anuncio incluye su primer y su último día de emisión y un rango de impresiones, y ad añade la página de destino, quién pagó, la segmentación y las impresiones por país, edad y género. Úsala para ver todos los anuncios de un competidor.
  • tiktok_creative_center lee los anuncios destacados del TikTok Creative Center. Lista los anuncios que mejor rindieron en un país durante los últimos 7, 30 o 180 días, con su tasa de clics, sus «me gusta» y su sector, para 28 países, entre ellos EE. UU., Corea y Japón. Úsalo para ver qué creativos funcionan en un mercado.
Una búsqueda cuesta 0.5 créditos por cada 30 anuncios que devuelve en ambas plataformas. advertisers y ad cuestan 0.5 créditos cada uno.

Biblioteca de anuncios de TikTok

Solicitud

Envía la tarea y consulta GET /v1/async/task/{id} o recibe su webhook. Consulta Tareas asíncronas. Una búsqueda de 300 anuncios tarda aproximadamente un minuto.

Analiza los anuncios de un competidor

Tres solicitudes cubren un análisis de la competencia:
  1. advertisers con el inicio del nombre del competidor devuelve los nombres exactos y los IDs que conoce la biblioteca.
  2. search con ese nombre en advertiserName lista los anuncios del anunciante. sortBy los ordena por fecha de publicación, fecha de la última emisión o impresiones, activeStatus conserva los anuncios en emisión o los detenidos, y summary cuenta los formatos y los anuncios que empezaron cada semana.
  3. ad con el libraryId de un anuncio devuelve la página de destino, quién pagó, la segmentación, el tamaño del público y las impresiones por país, edad y género.
Para encontrar anuncios por lo que dicen, usa query en lugar de advertiserName: busca en el texto, los hashtags y los nombres de los anunciantes.

Parámetros

  • action: search (por defecto), advertisers o ad.
  • country: Obligatorio en todas las acciones. Uno 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 y TR. ALL y los países fuera de la lista, como US, KR y JP, se rechazan con 400 VALIDATION_ERROR, porque la biblioteca cubre solo estas regiones.
  • query: Una palabra clave. En search coincide con el texto, los hashtags y los anunciantes por orden de relevancia, y la biblioteca cuenta como máximo 5,000 anuncios. En advertisers es el inicio del nombre de un anunciante y es obligatorio. search necesita query o advertiserName, y no ambos.
  • advertiserName: El nombre exacto de un anunciante, como NIKE Retail B.V.. La biblioteca cuenta todos sus anuncios.
  • libraryId: El ID numérico de un anuncio, como 1879578148398450. ad lo requiere.
  • activeStatus: all (por defecto), active o inactive.
  • mediaType: all (por defecto), video o image.
  • startDate, endDate: YYYY-MM-DD. Conserva los anuncios mostrados entre los dos días. Por defecto son los últimos 365 días.
  • sortBy: published_desc (por defecto), published_asc, last_shown_desc, last_shown_asc, impressions_desc o impressions_asc. Se aplica a una búsqueda por advertiserName, y una búsqueda por query siempre va por orden de relevancia.
  • limit: De 1 a 300 anuncios. Por defecto 30.
  • cursor: El nextCursor de una respuesta anterior, para leer los anuncios siguientes.
search lee todos los campos anteriores excepto libraryId. advertisers lee query y country, y ad lee libraryId y country. Un valor que la biblioteca no puede buscar o un campo que la acción no lee se rechaza con 400 VALIDATION_ERROR, y details indica el campo.

Leer más anuncios

Una respuesta con más anuncios por leer incluye nextCursor. Envíalo como cursor con la misma búsqueda para recibir los anuncios siguientes, de nuevo hasta limit. nextCursor es null cuando la biblioteca no tiene más. Un cursor solo funciona con la búsqueda que lo devolvió: un query, advertiserName, country, activeStatus, mediaType, rango de fechas o sortBy distinto se rechaza con 400 VALIDATION_ERROR, mientras que limit puede cambiar. En una búsqueda por query, que la biblioteca ordena por relevancia, unos pocos anuncios en el límite entre dos páginas pueden repetirse o perderse; libraryId permite distinguir los repetidos.

Encontrar un anunciante

action advertisers devuelve hasta 20 anunciantes cuyos nombres empiezan por query. Envía el nombre exacto como advertiserName para buscar los anuncios de ese anunciante.
Cada anunciante tiene advertiserId y advertiserName. country, adCount y verified son null, porque las sugerencias de la biblioteca no dan más. Una búsqueda de anunciantes cuesta 0.5 créditos.

Respuesta de búsqueda

  • La respuesta devuelve platform, action, country, query o advertiserName, activeStatus, mediaType y sortBy. totalCount es el recuento de la biblioteca de los anuncios coincidentes, que se detiene en 5,000 en una búsqueda por query. returnedCount cuenta los anuncios de ads, hasMore es true cuando la biblioteca tiene más, que nextCursor lee, y libraryUrl abre la misma búsqueda en la Biblioteca de anuncios.
  • Cada anuncio tiene position, libraryId, libraryUrl, advertiserName, title, format (VIDEO, IMAGE o TEXT), images, videos (url, previewUrl), startDate, endDate, activeDays, impressions (min, max), estimatedAudience (el rango de la biblioteca, como 400K-500K) y platforms (TIKTOK).
  • startDate y endDate son el primer y el último día en que la biblioteca muestra el anuncio (días en UTC). activeDays cuenta los días desde startDate hasta endDate, contando ambos. La biblioteca no da el gasto.
  • isActive es true o false cuando activeStatus es active o inactive, y null cuando es all.
  • advertiserId, payer, linkUrl, landingDomain, utm y targeting son null en una búsqueda. ad los rellena.
  • summary cuenta los anuncios de esta respuesta: ads, activeAds, advertisers (los 10 con más anuncios), formats, platforms, oldestStartDate, newestStartDate y medianActiveDays, con launchesByWeek (los anuncios que empezaron en cada semana ISO) y longestRunning (los 5 anuncios con más activeDays). No incluye landingDomains ni utmCampaigns, porque una búsqueda no incluye páginas de destino.
  • Las URL de imágenes y vídeos están firmadas y caducan unas 5 a 6 horas después de la lectura. Guarda los archivos que necesites.
  • Una búsqueda sin anuncios coincidentes se completa con ads vacío y un summary de 0 anuncios.

Qué conserva la biblioteca

La biblioteca muestra los anuncios emitidos en sus 34 regiones y los conserva unos 13 meses. Da el primer y el último día de emisión y un rango de impresiones de cada anuncio. No publica el gasto.

Abrir un anuncio

action ad abre el anuncio con el libraryId y el country que envíes.
  • ad tiene los campos de un anuncio de búsqueda, más linkUrl, landingDomain, payer (quién pagó el anuncio), category, objective, ctaText, advertiserId, reachedCountries y targeting.
  • targeting incluye byCountry (los ages y genders de cada país), provinces, cities, languages, interests, targetAudienceSize (el rango de la biblioteca, como 15.5M-18.9M), customAudience, excludesAudience, highSpendingPower, operatingSystems, deviceModels, videoInteractions y creatorInteractions. Una parte que la biblioteca no publica para el anuncio es null o está vacía.
  • advertiser tiene advertiserId, advertiserName, payer, registryCountry y la account de TikTok detrás de los anuncios (username, displayName, verified, followers, accountType, profileUrl, avatarUrl).
  • transparency incluye totalImpressions y byCountry: las impressions de cada país y sus breakdowns por age y gender.
  • Un libraryId para el que la biblioteca no tiene ningún anuncio falla con PAGE_UNAVAILABLE.

TikTok Creative Center

El Creative Center lista los anuncios con mejor rendimiento de un país, los que TikTok selecciona para los últimos 7, 30 o 180 días. Es una muestra ordenada, no el conjunto completo de anuncios de un anunciante: el nombre del anunciante suele estar vacío, y la biblioteca no da fechas, gasto ni impresiones. Da la tasa de clics, los «me gusta», el nivel de coste, el sector y los objetivos de cada anuncio. Úsalo para encontrar qué ganchos, formatos y productos funcionan en un mercado.

Solicitud

Parámetros

  • action: search (por defecto) o ad. advertisers se rechaza con 400 VALIDATION_ERROR, porque el Creative Center no tiene búsqueda de anunciantes.
  • country: Obligatorio en search. Uno 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 y ZA. ALL se rechaza.
  • query: Una palabra clave.
  • period: 7, 30 (por defecto) o 180 días.
  • industry: Un ID de sector, como 21103000000 (Hardware & Electrical), tal como lo indica el industry.id de un anuncio.
  • objective: traffic, app_installs, conversions, video_views, reach, lead_generation, product_sales o app_promotion.
  • adLanguage: Un código de idioma: en, es, ar, vi, th, de, id, pt, fr, ms, nl, ja, it, ro, zh-Hant o ko.
  • adFormat: spark (anuncios que impulsan una publicación de un creador) o non_spark.
  • sortBy: for_you (por defecto), impression, ctr, play_2s_rate, play_6s_rate, cvr o like.
  • limit: De 1 a 200 anuncios. Por defecto 30.
  • cursor: El nextCursor de una respuesta anterior.
  • libraryId: El ID numérico de un anuncio destacado. ad lo requiere.
search lee todos los campos anteriores excepto libraryId, y ad lee solo libraryId. El Creative Center lista como máximo unos 400 a 500 anuncios para un país, un periodo y un conjunto de filtros (totalCount).

Respuesta de búsqueda

  • La respuesta devuelve platform, action, country, period, sortBy y los filtros recibidos. totalCount es el número de anuncios destacados de esa combinación.
  • Cada anuncio tiene position, libraryId, title, advertiserName (a menudo null), format, ctrPercent (la tasa de clics en porcentaje), costLevel, likes, industry (id, name), objectives, durationSeconds, width, height, voiceOver, images, videos y videoUrls (el archivo de vídeo por resolución, como 360p y 1080p).
  • El Creative Center no da startDate, endDate, impressions ni libraryUrl, así que son null, y summary cuenta solo los formatos, los anunciantes y las plataformas.
  • Las URL de vídeo e imagen están firmadas y caducan unas 5 a 6 horas después de la lectura.

Abrir un anuncio

action ad abre un anuncio destacado por libraryId y añade linkUrl, landingDomain, reachedCountries, comments, shares y source (dónde se creó el anuncio, como TikTok Ads Manager).
Un libraryId para el que el Creative Center no tiene ningún anuncio falla con PAGE_UNAVAILABLE.

Precio

Una búsqueda reserva 0.5 créditos por cada 30 anuncios que pide su limit, y cobra 0.5 créditos por cada 30 anuncios que devuelve, con un mínimo de 0.5 créditos. La búsqueda predeterminada de 30 anuncios cuesta 0.5 créditos, y una búsqueda con limit 300 en la Biblioteca de anuncios reserva 5 créditos. advertisers y ad cuestan 0.5 créditos cada uno. Solo se cobran las solicitudes completadas.

Relacionado