Saltar al contenido principal

Introducción

Las métricas de analítica ayudan a socios y anunciantes a comprender el rendimiento del contenido que promocionan en X. Esto incluye información como impresiones, clics, visualizaciones de vídeo e inversión publicitaria. Además, los socios y anunciantes pueden obtener métricas detalladas para varios segmentos de las audiencias a las que llegan. La Ads API admite dos formas de recuperar métricas detalladas de rendimiento de campaña: de manera sincrónica y asincrónica. Con las llamadas de analítica sincrónicas, las métricas solicitadas se devuelven en la respuesta. Con los endpoints de analítica asincrónicos, las métricas solicitadas están disponibles en un archivo de resultados descargable después de que la “tarea” (“job”) asociada haya terminado de procesarse. El endpoint sincrónico admite rangos de tiempo cortos y es ideal para optimizaciones de campaña en tiempo real. Los endpoints asincrónicos admiten rangos de tiempo mucho más largos y, por lo tanto, están pensados para obtener muchos más datos, ideales para generar informes o realizar cargas históricas de datos.

Detalles

Sincrónico vs. asincrónico

Las diferencias entre los endpoints de analítica sincrónicos y asincrónicos se resumen en la siguiente tabla. Esta información está destinada a ayudar a los desarrolladores a elegir qué conjunto de endpoints usar.
  • Esto se refiere al número máximo de trabajos que pueden estar en estado de procesamiento en un momento dado.
** Una vez que el trabajo haya terminado de procesarse correctamente, se devuelve una URL. Desde allí se puede descargar el archivo de resultados comprimido (gzip).Aparte de esto, los endpoints ofrecen la misma funcionalidad.

Casos de uso

Hay tres casos de uso principales de analíticas.
  1. Optimización en tiempo real: usar métricas de rendimiento para actualizar campañas activas
  2. Sincronización: sincronizaciones periódicas en segundo plano
  3. Incorporación de cuentas nuevas: completar datos históricos
El endpoint síncrono de analíticas se puede usar para la optimización en tiempo real y para actualizar campañas basándose en cambios en las métricas producidos en los últimos 5 a 15 minutos. Cualquiera de los endpoints se puede usar para la sincronización de analíticas. Ten en cuenta que el intervalo de tiempo deseado y si se requiere segmentación determinarán qué endpoint usar. La incorporación de cuentas nuevas solo se debe realizar usando los endpoints asíncronos de analíticas. (El endpoint síncrono de analíticas nunca se debe usar para recuperar grandes volúmenes de datos). Los endpoints asíncronos de analíticas pueden alimentar paneles y otros elementos de la interfaz de usuario si las métricas se sincronizan mediante un proceso en el backend. Tu implementación debe evitar invocar los endpoints asíncronos de analíticas para atender solicitudes de la interfaz de usuario.

Opciones de solicitud

Las solicitudes de analytics están asociadas a cuentas publicitarias y, por lo tanto, requieren el ID de la cuenta en la ruta del recurso. Las opciones de solicitud, que se indican a continuación, se especifican como parámetros de consulta. Se requieren los siguientes tipos de valores:
  • Entities: el tipo de entidad, así como hasta 20 id de entidad para las que quieres solicitar analytics
  • Intervalo de tiempo: las horas de inicio y fin, expresadas en ISO 8601
    • Nota: se deben expresar en horas completas
  • Grupos de métricas: uno o más conjuntos de métricas relacionadas (consulta Métricas y segmentación para ver una lista de métricas dentro de cada grupo de métricas)
  • Granularidad: especifica el nivel de agregación en el que se deben devolver las métricas
  • Placement: determina si las métricas se extraen para anuncios que se publicaron dentro o fuera de X
    • Nota: solo se puede especificar un único valor de placement por solicitud
Usa los parámetros de solicitud start_time y end_time para especificar un intervalo de tiempo. Estos valores deben alinearse con la granularidad especificada de la siguiente manera:
  1. TOTAL: especifica cualquier intervalo de tiempo (dentro de los límites del endpoint)
  2. DAY: tanto la hora de inicio como la hora de fin deben alinearse con la medianoche en la zona horaria de la cuenta
  3. HOUR: especifica cualquier intervalo de tiempo (dentro de los límites del endpoint)
La hora de fin es exclusiva. Por ejemplo, una solicitud con start_time=2019-01-01T00:00:00Z y end_time=2019-01-02T00:00:00Z devolverá métricas de analytics correspondientes a un solo día (no dos), ya que este intervalo de tiempo solo cubre un período de 24 horas. Segmentación Disponible solo a través de nuestros endpoints de analytics asíncronos, la segmentación permite a los socios y anunciantes obtener métricas desglosadas por valores de segmentación específicos. Para solicitar métricas segmentadas, usa el parámetro de solicitud segmentation_type. Para obtener más detalles sobre las opciones de segmentación, consulta Métricas y segmentación.

Preguntas frecuentes

¿Por qué las cifras de la Ads API no coinciden con lo que se muestra en la interfaz de X Ads?
  • Asegúrate de haber solicitado datos para todas las ubicaciones: ALL_ON_TWITTER y PUBLISHER_NETWORK, SPOTLIGHT y TREND.
  • Recuerda que las horas de finalización en la Ads API son exclusivas; en la interfaz de Ads son inclusivas.
¿Por qué cambian las cifras según el momento en que solicito los datos?
  • Tan pronto como las métricas de informes están disponibles, puedes recuperarlas. Están disponibles casi en tiempo real. Sin embargo, estos primeros resultados son estimaciones y, como resultado, es de esperar que cambien. Las métricas se finalizan después de 24 horas, con la excepción de los datos de gasto.
  • Las métricas de gasto generalmente se consideran finales dentro de los 3 días posteriores al evento. Sin embargo, procesamos datos de facturación hasta 14 días a partir de la fecha del evento (por ejemplo, para filtrado de spam).
¿Cómo puedo determinar qué IDs de entidades debo solicitar para un período de tiempo específico? ¿Por qué todos los valores en la respuesta de analytics son null?
  • Es probable que la campaña no se haya entregado durante el período de tiempo solicitado.
  • Usa el endpoint Active Entities para determinar para qué entidades y para qué período de tiempo debes recuperar analytics.
¿Por qué la API muestra valores null mientras que la interfaz muestra ceros?
  • La interfaz decide mostrar estos valores como ceros, pero los valores son equivalentes.
¿Cómo puedo solicitar métricas asociadas con una ubicación granular, como el timeline de X?
  • Admitimos los siguientes valores de ubicación en analytics: ALL_ON_TWITTER y PUBLISHER_NETWORK, SPOTLIGHT y TREND (es decir, la X Audience Platform)
¿Es posible recuperar métricas de entidades eliminadas o en pausa?
  • Sí. El estado de la entidad no afecta la disponibilidad de las métricas de analytics.
¿Por qué los valores segmentados no coinciden con los no segmentados?
  • No se espera que los datos segmentados se sumen al 100 % de los datos no segmentados, debido a cómo se obtiene esta información.
¿Es posible solicitar datos segmentados por múltiples dimensiones?
  • No admitimos la segmentación múltiple.

Mejores prácticas

Algunas de las mejores prácticas para recopilar datos de analytics de la Ads API.

Limitación de frecuencia y reintentos

  • En las solicitudes sujetas a limitación de frecuencia (aquellas que devuelven un código de estado HTTP 429), debes inspeccionar el encabezado x-rate-limit-reset y reintentar solo en o después del momento indicado.
  • En las solicitudes que resulten en un código de estado HTTP 503 Service Unavailable, debes inspeccionar el encabezado retry-after y reintentar solo después del momento indicado.
  • A las aplicaciones que no respeten los tiempos indicados para los reintentos se les podría revocar o restringir el acceso a la Ads API sin previo aviso.

Métricas de Analytics en pocas palabras

  • Todas las métricas de Analytics quedan bloqueadas y no se modificarán después de 24 horas, con la excepción de billed_charge_local_micro.
  • La métrica billed_charge_local_micro es una estimación durante un máximo de 3 días después de que se devuelven los datos.
  • Después de 24 horas, esta métrica puede disminuir debido a créditos por exceso de gasto (anuncios servidos después del end_time indicado) y por eventos facturables que se determinan como no válidos (junk). Esta métrica cambia mínimamente después de 24 horas.
  • Consulta Analytics para obtener más información.

Obtención de datos en tiempo real, no segmentados

  • Proporciona siempre tanto un start_time como un end_time.
  • No extraigas datos de ninguna entidad con más de 7 días de antigüedad.
  • Solicita datos (idealmente) con granularidad HOUR, ya que siempre puedes agregar y consolidar métricas para obtener granularidad DAY y TOTAL.
  • Solicita datos (idealmente) a nivel de line_items y promoted_tweets, ya que siempre puedes agregar y consolidar estas métricas para obtener totales en toda la jerarquía de entidades de publicidad (es decir, para los niveles de campaña, instrumento de financiación o cuenta).
  • Guarda y almacena los valores de las métricas de analítica en tu sistema (localmente).
  • No consultes de forma repetida datos con más de 30 días de antigüedad. Estos datos no cambiarán y deben almacenarse localmente.
  • Todos los datos no segmentados son en tiempo real y los datos deberían estar disponibles en cuestión de segundos después de que se produzca un evento.
  • Agrupa las métricas de conversión y las métricas que no son de conversión en solicitudes separadas.

Obtención de datos segmentados

  • Consulta las pautas indicadas arriba para “Fetching Real-time, Non-segmented Data”. A continuación se ofrece asesoramiento adicional.
  • Para la mayoría de los tipos de datos segmentados, es posible que los datos no estén completos durante un máximo de 1 hora en determinados momentos. Los datos segmentados por INTERESTS pueden retrasarse hasta 12 horas.
  • No se espera que los datos segmentados se agreguen al 100 % de los datos no segmentados, debido a la forma en que se obtiene esta información.

Obtención de datos históricos

  • Al realizar una carga histórica de datos (es decir, al agregar una nueva cuenta de anunciante), es posible que debas realizar varias solicitudes en intervalos más pequeños de start_time y end_time.
  • Limita tus consultas a ventanas de fechas de 30 días.
  • Limita la velocidad de estas solicitudes y distribúyelas en el tiempo para no agotar tus límites de tasa para estas consultas.

Ejemplo

Puedes encontrar un script de ejemplo que muestra algunas de estas mejores prácticas (fetch_stats) en nuestro repositorio de GitHub, ads-platform-tools.

Métricas por objetivo

Las métricas aplicables a una entidad dependen del objetivo de campaña. Usa esta guía para determinar qué grupos de métricas debes recuperar para cada tipo de objetivo, así como cómo calcular métricas derivadas adicionales.

ENGAGEMENTS

Grupos de métricas relevantes:ENGAGEMENT y BILLING. MEDIA también es aplicable si se utiliza contenido multimedia en los creativos.

WEBSITE_CLICKS y WEBSITE_CONVERSIONS

Grupos de métricas relevantes: ENGAGEMENT, BILLING y WEB_CONVERSION. MEDIA también es aplicable si se utiliza contenido multimedia en los creativos.

APP_INSTALLS y APP_ENGAGEMENTS

Grupos de métricas relevantes: ENGAGEMENT, BILLING, MOBILE_CONVERSION y LIFE_TIME_VALUE_MOBILE_CONVERSION. MEDIA y VIDEO también aplican si se utiliza una app card con medios o video en los creativos.

FOLLOWERS

Grupos de métricas relevantes: ENGAGEMENT y BILLING. MEDIA también es aplicable si se utiliza contenido multimedia en las creatividades.

LEAD_GENERATION

Grupos de métricas relevantes: ENGAGEMENT y BILLING. MEDIA también es aplicable si se utiliza contenido multimedia en los creativos.

VIDEO_VIEWS

Grupos de métricas relevantes: ENGAGEMENT, BILLING y VIDEO.

VIDEO_VIEWS_PREROLL

Grupos de métricas relevantes: ENGAGEMENT, BILLING y VIDEO.

Métricas y segmentación

Este documento es una descripción general de las métricas disponibles en nuestra Analytics para cada tipo de entidad, así como de las segmentaciones disponibles para cada grupo de métricas. *Algunas métricas de la familia de métricas ENGAGEMENT no están disponibles a nivel de ACCOUNT ni de FUNDING_INSTRUMENT. Consulta la sección ENGAGEMENT para más detalles.

Métricas disponibles por grupo de métricas

ENGAGEMENT

BILLING

VIDEO

Aviso sobre cambios en la definición de las métricas de video: La métrica video_total_views dentro del grupo de métricas VIDEO informará todas las visualizaciones en las que el video haya estado al menos un 50 % visible en pantalla durante 2 segundos, según el estándar MRC. Nuestra definición original de visualización de video (100 % del video visible en pantalla durante al menos 3 segundos) seguirá estando disponible como una nueva métrica video_3s100pct_views en el grupo de métricas VIDEO. Para seguir pujando y que el cobro se realice según la definición original de visualización, usa la nueva bid_unit VIEW_3S_100PCT.

MEDIA

WEB_CONVERSION

MOBILE_CONVERSION

Las estadísticas de conversiones en dispositivos móviles están disponibles solo para las cuentas de anunciantes habilitadas para MACT.

LIFE_TIME_VALUE_MOBILE_CONVERSION

Las estadísticas de conversiones móviles de valor de vida (lifetime) solo están disponibles para cuentas de anunciantes con MACT habilitado.

Segmentación

Los informes de segmentación permiten la obtención de métricas desglosadas según los valores de un tipo de segmentación determinado. La segmentación solo está disponible a través de consultas analíticas asíncronas debido a la complejidad adicional que implican. La segmentación no se admite para las entidades MEDIA_CREATIVE u ORGANIC_TWEET. Algunos tipos de segmentación requieren que se incluyan parámetros adicionales. Se documentan a continuación. Al segmentar por CITIES o POSTAL_CODES, la API solo devolverá ubicaciones objetivo. La segmentación por región y zona metropolitana devolverá tanto ubicaciones objetivo como no objetivo.

Métricas derivadas

Las métricas de campaña dependen de su objetivo de campaña. Usa esta guía para determinar cómo calcular las métricas derivadas que se utilizarán según los objetivos definidos. Cualquier metric sin llaves es una métrica que devuelven los endpoints de analytics de la Ads API. Cualquier nombre entre {llaves} indica una métrica derivada para esa categoría.

INTERACCIONES

WEBSITE_CLICKS

APP_INSTALLS y APP_ENGAGEMENTS

SEGUIDORES

GENERACIÓN_DE_LEADS

VIDEO_VIEWS

IMPRESIONES_CALIFICADAS

PERSONALIZADO

Para placement_type de PROMOTED_ACCOUNT, consulta el objetivo FOLLOWERS anterior. Para todos los demás emplazamientos con este objetivo, consulta ENGAGEMENTS para ver las métricas derivadas correspondientes.

Guías

Entidades activas

Introducción

El endpoint de Active Entities está diseñado para utilizarse junto con nuestros endpoints de analítica sincrónicos y asincrónicos, ya que proporciona información sobre qué campañas deben solicitar analíticas. Lo hace devolviendo detalles sobre las entidades de anuncios y cuándo cambiaron sus métricas. Usar este endpoint simplificará en gran medida tu código y la lógica para obtener analíticas. Esta guía incluye información y contexto sobre el endpoint y su fuente de datos. También proporciona directrices de uso y una serie de ejemplos de solicitudes que muestran cómo usar Active Entities junto con nuestros endpoints de analítica. La sección Summary ofrece una visión general del enfoque recomendado.

Datos

Cada vez que cambia una métrica de una entidad de anuncios, registramos información sobre ese cambio. Estos eventos de cambio se almacenan en intervalos horarios e incluyen detalles sobre la entidad, así como el momento al que se aplica el cambio. Esto último es necesario porque los eventos de cambio no siempre corresponden al momento en que se registraron. Los ajustes de facturación son una razón común para esto, pero también hay otras.

Endpoint

Request

Las solicitudes de Active Entities están asociadas a cuentas publicitarias y tienen tres parámetros de consulta obligatorios: entity, start_time y end_time. twurl -H ads-api.x.com "/11/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2019-03-05T00:00:00Z&end_time=2019-03-06T00:00:00Z" Se admiten los siguientes valores para entity: CAMPAIGN, FUNDING_INSTRUMENT, LINE_ITEM, MEDIA_CREATIVE, PROMOTED_ACCOUNT y PROMOTED_TWEET. Esto refleja los tipos de entidades que admiten nuestros endpoints de analítica. Los valores de start_time y end_time deben expresarse en formato ISO 8601 y especificar qué intervalos horarios se van a consultar. Estos deben expresarse en horas completas. Este endpoint también admite tres parámetros opcionales que se pueden usar para filtrar los resultados: funding_instrument_ids, campaign_ids y line_item_ids. Estos funcionan en todos los niveles de la jerarquía de anuncios y con cualquier tipo de entity especificado.

Respuesta

La respuesta de Active Entities correspondiente a la solicitud anterior se muestra a continuación.
La array data incluye un objeto por cada entidad que debe incluirse en una solicitud de analytics posterior. No debes solicitar analytics para id fuera de este conjunto. Cada objeto incluye cuatro campos: entity_id, activity_start_time, activity_end_time y placements. Los tiempos de inicio y fin de la actividad representan el intervalo de tiempo al que se aplican los eventos de cambio de la entidad asociada y, por lo tanto, determinan las fechas que deben especificarse en solicitudes de analytics posteriores. La array placements puede incluir los siguientes valores: ALL_ON_TWITTER, PUBLISHER_NETWORK, SPOTLIGHT y TREND. Indica qué ubicaciones deben solicitarse para el id de entidad dado.

Uso

El endpoint de Active Entities debe definir cómo se realizan las solicitudes de analíticas. Las siguientes pautas de uso están redactadas para admitir la sincronización de analíticas, lo que permite a los socios mantener sus almacenes de datos sincronizados con Twitter. En otras palabras, describen cómo realizar sincronizaciones periódicas en segundo plano. Hay dos decisiones que un desarrollador debe tomar.
  1. Con qué frecuencia solicitar información de entidades activas y, por lo tanto, con qué frecuencia obtener analíticas.
  2. Cómo usar las horas de inicio y fin de la actividad para determinar los valores de start_time y end_time de la solicitud de analíticas.
Estos puntos se analizan con mayor detalle en cada una de las dos subsecciones a continuación, después del resumen.

Resumen

Utiliza el endpoint de Active Entities de la siguiente manera para definir cómo se realizan las solicitudes de analítica. Sigue estos pasos después de decidir con qué frecuencia solicitar la información de entidades activas y, por lo tanto, con qué frecuencia obtener datos de analítica.
  1. Realiza la solicitud a Active Entities.
  2. Divide la respuesta por placement. Un grupo para ALL_ON_TWITTER, uno para PUBLISHER_NETWORK, uno para SPOTLIGHT y uno para TREND.
  3. Para cada grupo de placement, haz lo siguiente.
    1. Extrae los id de las entidades.
    2. Determina los valores de start_time y end_time de analítica.
      • Encuentra el valor mínimo de activity_start_time. Redondea este valor hacia abajo.
      • Encuentra el valor máximo de activity_end_time. Redondea este valor hacia arriba.
    3. Realiza las solicitudes de analítica.
      • Agrupa los id de las entidades en lotes de 20.
      • Utiliza los valores de start_time y end_time del paso 3b.
      • Especifica el valor de placement apropiado.
    4. Escribe en tu almacén de datos.
Consulta active_entities.py como ejemplo de uso del SDK de Python.

Frecuencia

La respuesta a la primera pregunta determina el intervalo de tiempo que debe usarse en las solicitudes de Active Entities. Por ejemplo, si se solicita información de entidades activas cada hora, el intervalo de tiempo debe ser de una hora. Si se solicita información de entidades activas una vez al día, el intervalo de tiempo debe ser de un día. En otras palabras, los intervalos de tiempo deben seleccionarse de forma que el start_time de la solicitud actual sea igual al end_time de la solicitud anterior.
Nota: Una ventana de tiempo solo debe solicitarse una vez. Solicitar una ventana de tiempo más de una vez generará solicitudes de analíticas innecesarias. (Excepción a continuación).
Para los socios que deseen solicitar analíticas varias veces por hora durante la hora actual, se aplica el mismo patrón: la frecuencia determina el intervalo de tiempo. La siguiente tabla muestra ejemplos de marcas de tiempo de inicio y fin de Active Entities para este escenario. Dada la forma en que se almacenan los eventos de cambio, las cuatro solicitudes de Active Entities anteriores consultan el mismo segmento horario, lo cual es necesario para este caso de uso. Sin embargo, después de la hora actual, ya no se debe consultar este segmento horario.

Tiempos de actividad

Recomendamos el siguiente enfoque para trabajar con las horas de inicio y fin de la actividad. En todos los objetos de la respuesta de Active Entities, busca el valor mínimo de activity_start_time y el valor máximo de activity_end_time. Modifica estos valores redondeando hacia abajo la hora mínima de inicio de la actividad y redondeando hacia arriba la hora máxima de fin de la actividad. En concreto, establece en cero los componentes de hora, minuto y segundo de ambos timestamps y suma un día a la hora de finalización, como se ilustra en la tabla siguiente. Estos son los tiempos de inicio y fin que se deben especificar en las solicitudes de analíticas posteriores. Nota: Es importante incluir los timestamps con las horas, minutos y segundos establecidos en cero. De lo contrario, si solo se pasa la fecha, asumiremos que estás solicitando analíticas que empiezan y terminan a medianoche en la zona horaria de la cuenta de anuncios, lo cual puede no ser lo deseable. Por ejemplo, si la hora mínima de inicio de actividad es 2019-02-28T01:30:07Z y se omite el timestamp para una cuenta de anuncios con un desplazamiento de -08:00:00, la solicitud de analíticas no incluirá los cambios que se produjeron entre las 01:30 y las 08:00. De forma alternativa, si prefieres solicitar analíticas solo para la ventana de tiempo de actividad devuelta sin ampliarla a días completos, puedes hacerlo. Con este enfoque, los tiempos de inicio y fin derivados serían 2019-03-04T20:00:00Z y 2019-03-05T15:00:00Z, respectivamente. (Ten en cuenta que rangos como estos no se aceptan si especificas granularidad DAY en la solicitud de analíticas.)

Ejemplo

Esta sección muestra cómo usar Active Entities junto con el endpoint de analytics síncrono. (Las respuestas se han modificado ligeramente para facilitar la lectura). En este ejemplo, el endpoint de Active Entities se invoca al comienzo de cada hora y cada solicitud analiza la hora anterior. La respuesta determina cómo se utiliza el endpoint de analytics síncrono. La primera solicitud de Active Entities se realiza a las 03:00:00. La respuesta indica que las métricas del line item dvcz7 cambiaron y que esos eventos de cambio se aplican a la ventana de tiempo entre las 02:02:55 y las 02:28:12.
Basándonos en estas horas de inicio y fin de la actividad y utilizando el enfoque descrito anteriormente, los valores de analytics start_time y end_time se establecen en 2019-02-11T00:00:00Z y 2019-02-12T00:00:00Z, respectivamente. Vemos que el tercer elemento de cada uno de los arreglos de métricas que se muestran a continuación es distinto de cero, tal como esperábamos según la información de entidades activas.
La siguiente solicitud de Active Entities se realiza a las 04:00:00 y solo abarca la hora anterior. Como se indicó antes, una ventana de tiempo debe solicitarse solo una vez. A partir de la respuesta, vemos que los eventos de cambio para este line item se aplican a tanto las 02:00:00 como las 03:00:00. En la solicitud de analíticas posterior, esperamos ver cambios para ambas horas.
Además de ver métricas mayores que cero para las 03:00:00, vemos que las impresiones, el gasto y las vistas de video MRC se han actualizado respecto a sus valores anteriores. Las impresiones, por ejemplo, ahora son 2.995 para la hora de las 02:00:00, frente a 2.792. Esto demuestra cómo los eventos de cambio que se registraron durante la hora de las 03:00:00 se aplican a la hora de las 02:00:00.
La solicitud de Active Entities a las 05:00:00, de nuevo considerando solo la hora anterior, muestra que los eventos de cambio se aplican únicamente a la hora de las 03:00:00. Los cambios en las métricas de analytics en la solicitud siguiente reflejan esto.
La respuesta de analytics muestra que solo han cambiado las métricas de las 03:00:00; los valores de las 02:00:00 son los mismos que en la solicitud de analytics anterior.
Finalmente, a las 06:00:00 vemos que no hay eventos de cambio adicionales. Nota: Sin embargo, esto no implica que las métricas de esta partida no puedan cambiar en el futuro.

Guía asíncrona

Referencia de la API

Analítica asíncrona

Introducción

Los endpoints de analítica asíncrona permiten a socios y anunciantes solicitar métricas enviando solicitudes de creación que el servidor procesa de forma asíncrona. (Nos referimos a estas como “jobs” de analítica asíncrona). Con este enfoque, la conexión del cliente no necesita permanecer abierta hasta que se haya completado la solicitud. Estos endpoints, al igual que su contraparte síncrona, permiten a socios y anunciantes solicitar estadísticas detalladas sobre el rendimiento de las campañas. Admiten solicitudes de datos para cuentas, instrumentos de financiación, campañas, line items, Tweets promocionados y creatividades de medios. La diferencia entre estos endpoints y el síncrono es que los endpoints de analítica asíncrona admiten rangos de fechas más amplios, de hasta 90 días, así como segmentación. Puedes encontrar más detalles sobre las diferencias entre ambos en nuestra página de Información general sobre Analytics. A diferencia de nuestros endpoints síncronos, la limitación de tasa se basa en el número de jobs concurrentes para una cuenta determinada. En otras palabras, se basa en el número de jobs que pueden estar en estado de procesamiento en un momento dado. Contabilizamos esto a nivel de cuenta publicitaria.

Uso

Obtener métricas de campaña mediante los endpoints de analytics asíncronos es un proceso de varios pasos. Implica crear un job, comprobar si el job ha terminado de procesarse y, por último, descargar los datos. El archivo de datos debe descomprimirse. Los cuatro pasos específicos se describen a continuación.
  1. Crea el job utilizando el endpoint POST stats/jobs/accounts/:account_id.
  2. Realiza solicitudes a intervalos regulares al endpoint GET stats/jobs/accounts/:account_id para determinar si el job ha terminado de procesarse.
  3. Una vez que el job haya terminado de procesarse, descarga el archivo de datos.
  4. Descomprime el archivo de datos.
El objeto de respuesta devuelto en el archivo de datos tiene el mismo esquema JSON que la respuesta del endpoint de analytics síncrono. Las métricas de campaña segmentadas solo están disponibles a través de los endpoints de analytics asíncronos. Las métricas de campaña se pueden desglosar por ubicación, género, intereses, palabras clave y más. Para ver la lista completa de opciones, consulta la página de Métricas y segmentación. Para solicitar métricas segmentadas, utiliza el parámetro de solicitud segmentation_type al crear el job.

Ejemplo

Esta sección muestra cómo usar los endpoints de analítica asíncrona. Comienza por crear un job mediante el endpoint POST stats/jobs/accounts/:account_id. El siguiente ejemplo solicita métricas de interacción (engagement), como impresiones, Me gusta, clics, etc., para un line item específico durante un periodo de una semana. (Ten en cuenta que el intervalo de tiempo solicitado llega hasta el 20 de marzo, pero no lo incluye, ya que la marca de tiempo está configurada a la medianoche).
Esta respuesta no devuelve las métricas del elemento de línea. Solo proporciona información sobre el job que acabas de crear. El id del job es necesario para comprobar su estado. Este se muestra en los atributos de la respuesta id e id_str. A continuación, debes comprobar si el job que has creado usando el id_str de la respuesta anterior ha terminado de procesarse, tal como se indica con "status": "SUCCESS" en la respuesta. Esto significa que los datos ya están listos para descargarse. El campo url contiene el enlace de descarga.
Aunque en el ejemplo anterior estamos pasando un único ID de trabajo, en la práctica deberás usar el parámetro job_ids para consultar el estado de varios trabajos simultáneamente, especificando hasta 200 IDs de trabajo. A continuación, descarga el archivo de datos usando el valor url indicado.
Por último, descomprime el archivo.
A continuación se muestra el contenido del archivo.

Alcance y frecuencia promedio

GET stats/accounts/:account_id/reach/campaigns

Obtén métricas de alcance y frecuencia media para las campañas especificadas.

URL del recurso

https://ads-api.x.com/stats/accounts/:account_id/reach/campaigns

Parámetros

Ejemplo de solicitud

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/reach/campaigns?campaign_ids=8fgzf&start_time=2017-05-19&end_time=2017-05-26

Respuesta de ejemplo

GET stats/accounts/:account_id/reach/funding_instruments

Obtén las métricas de alcance y frecuencia promedio para los instrumentos de financiación especificados.

URL del recurso

https://ads-api.x.com/stats/accounts/:account_id/reach/funding_instruments

Parámetros

Ejemplo de solicitud

Ejemplo de respuesta

Analítica sincrónica

GET stats/accounts/:account_id

Obtiene estadísticas síncronas para la cuenta actual. Se permite un intervalo de tiempo máximo de 7 días para (end_time - start_time).

URL del recurso

https://ads-api.x.com/12/stats/accounts/:account_id

Parámetros

Ejemplo de solicitud

Ejemplo de respuesta

Entidades activas

GET stats/accounts/:account_id/active_entities

Obtén detalles sobre las entidades cuyas métricas de analítica han cambiado en un período de tiempo determinado. Este endpoint debe usarse junto con nuestros endpoints de analítica. Los resultados de este endpoint indican para qué entidades de anuncios se deben solicitar métricas de analítica. Consulta nuestra Guía de entidades activas para ver las pautas de uso. Los eventos de cambio están disponibles en bloques horarios.
  • Los valores de start_time y end_time especifican qué bloques horarios se deben consultar.
  • El array data devuelto incluirá un objeto por cada entidad que deba incluirse en solicitudes de analítica posteriores.
  • IMPORTANTE: Las fechas que deben especificarse en las solicitudes de analítica posteriores deben determinarse en función de los valores activity_start_time y activity_end_time.
    • Estos valores representan los rangos de tiempo a los que se aplican los eventos de cambio almacenados. Esto se devuelve por entidad.
Nota: Se permite un rango máximo de tiempo (end_time - start_time) de 90 días.

URL del recurso

https://ads-api.x.com/12/stats/accounts/:account_id/active_entities

Parámetros

Ejemplo de solicitud

GET https://ads-api.x.com/12/stats/accounts/18ce54d4x5t/active_entities?entity=PROMOTED_TWEET&start_time=2019-02-28&end_time=2019-03-01

Respuesta de ejemplo