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_librarylee 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, yadañ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_centerlee 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.
advertisers y ad cuestan 0.5 créditos cada uno.
Biblioteca de anuncios de TikTok
Solicitud
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:advertiserscon el inicio del nombre del competidor devuelve los nombres exactos y los IDs que conoce la biblioteca.searchcon ese nombre enadvertiserNamelista los anuncios del anunciante.sortBylos ordena por fecha de publicación, fecha de la última emisión o impresiones,activeStatusconserva los anuncios en emisión o los detenidos, ysummarycuenta los formatos y los anuncios que empezaron cada semana.adcon ellibraryIdde 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.
query en lugar de advertiserName: busca en el texto, los hashtags y los nombres de los anunciantes.
Parámetros
action:search(por defecto),advertisersoad.country: Obligatorio en todas las acciones. Uno deAT,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,SKyTR.ALLy los países fuera de la lista, comoUS,KRyJP, se rechazan con400 VALIDATION_ERROR, porque la biblioteca cubre solo estas regiones.query: Una palabra clave. Ensearchcoincide con el texto, los hashtags y los anunciantes por orden de relevancia, y la biblioteca cuenta como máximo 5,000 anuncios. Enadvertiserses el inicio del nombre de un anunciante y es obligatorio.searchnecesitaqueryoadvertiserName, y no ambos.advertiserName: El nombre exacto de un anunciante, comoNIKE Retail B.V.. La biblioteca cuenta todos sus anuncios.libraryId: El ID numérico de un anuncio, como1879578148398450.adlo requiere.activeStatus:all(por defecto),activeoinactive.mediaType:all(por defecto),videooimage.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_descoimpressions_asc. Se aplica a una búsqueda poradvertiserName, y una búsqueda porquerysiempre va por orden de relevancia.limit: De 1 a 300 anuncios. Por defecto 30.cursor: ElnextCursorde 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 incluyenextCursor. 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.
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,queryoadvertiserName,activeStatus,mediaTypeysortBy.totalCountes el recuento de la biblioteca de los anuncios coincidentes, que se detiene en 5,000 en una búsqueda porquery.returnedCountcuenta los anuncios deads,hasMoreestruecuando la biblioteca tiene más, quenextCursorlee, ylibraryUrlabre la misma búsqueda en la Biblioteca de anuncios. - Cada anuncio tiene
position,libraryId,libraryUrl,advertiserName,title,format(VIDEO,IMAGEoTEXT),images,videos(url,previewUrl),startDate,endDate,activeDays,impressions(min,max),estimatedAudience(el rango de la biblioteca, como400K-500K) yplatforms(TIKTOK). startDateyendDateson el primer y el último día en que la biblioteca muestra el anuncio (días en UTC).activeDayscuenta los días desdestartDatehastaendDate, contando ambos. La biblioteca no da el gasto.isActiveestrueofalsecuandoactiveStatusesactiveoinactive, ynullcuando esall.advertiserId,payer,linkUrl,landingDomain,utmytargetingsonnullen una búsqueda.adlos rellena.summarycuenta los anuncios de esta respuesta:ads,activeAds,advertisers(los 10 con más anuncios),formats,platforms,oldestStartDate,newestStartDateymedianActiveDays, conlaunchesByWeek(los anuncios que empezaron en cada semana ISO) ylongestRunning(los 5 anuncios con másactiveDays). No incluyelandingDomainsniutmCampaigns, 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
adsvacío y unsummaryde0anuncios.
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.
adtiene los campos de un anuncio de búsqueda, máslinkUrl,landingDomain,payer(quién pagó el anuncio),category,objective,ctaText,advertiserId,reachedCountriesytargeting.targetingincluyebyCountry(losagesygendersde cada país),provinces,cities,languages,interests,targetAudienceSize(el rango de la biblioteca, como15.5M-18.9M),customAudience,excludesAudience,highSpendingPower,operatingSystems,deviceModels,videoInteractionsycreatorInteractions. Una parte que la biblioteca no publica para el anuncio esnullo está vacía.advertisertieneadvertiserId,advertiserName,payer,registryCountryy laaccountde TikTok detrás de los anuncios (username,displayName,verified,followers,accountType,profileUrl,avatarUrl).transparencyincluyetotalImpressionsybyCountry: lasimpressionsde cada país y susbreakdownsporageygender.- Un
libraryIdpara el que la biblioteca no tiene ningún anuncio falla conPAGE_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) oad.advertisersse rechaza con400 VALIDATION_ERROR, porque el Creative Center no tiene búsqueda de anunciantes.country: Obligatorio ensearch. Uno deAE,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,VNyZA.ALLse rechaza.query: Una palabra clave.period:7,30(por defecto) o180días.industry: Un ID de sector, como21103000000(Hardware & Electrical), tal como lo indica elindustry.idde un anuncio.objective:traffic,app_installs,conversions,video_views,reach,lead_generation,product_salesoapp_promotion.adLanguage: Un código de idioma:en,es,ar,vi,th,de,id,pt,fr,ms,nl,ja,it,ro,zh-Hantoko.adFormat:spark(anuncios que impulsan una publicación de un creador) onon_spark.sortBy:for_you(por defecto),impression,ctr,play_2s_rate,play_6s_rate,cvrolike.limit: De 1 a 200 anuncios. Por defecto 30.cursor: ElnextCursorde una respuesta anterior.libraryId: El ID numérico de un anuncio destacado.adlo 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,sortByy los filtros recibidos.totalCountes el número de anuncios destacados de esa combinación. - Cada anuncio tiene
position,libraryId,title,advertiserName(a menudonull),format,ctrPercent(la tasa de clics en porcentaje),costLevel,likes,industry(id,name),objectives,durationSeconds,width,height,voiceOver,images,videosyvideoUrls(el archivo de vídeo por resolución, como360py1080p). - El Creative Center no da
startDate,endDate,impressionsnilibraryUrl, así que sonnull, ysummarycuenta 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).
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 sulimit, 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.