API de conjuntos de datos de programas lineales en directo

Access session-level, program-grain viewership data for your Prime Video linear channels.

~14 min de lectura octubre 2, 2026

Esta guía abarca todo lo que necesitas para acceder a la API de conjuntos de datos de programas lineales en directo y usarla

Lo que aprenderás

  • Qué ofrece la API y qué fuentes están disponibles.
  • Cómo autenticarte y recuperar los archivos de conjuntos de datos.
  • El modelo de datos completo y las definiciones de columnas.
  • Cómo funcionan el registro de cambios y la señal is_deleted.
  • Patrones de eliminación de duplicados y MERGE que puedes copiar en tu canalización.
  • Cadencia de ingesta recomendada.
  • Ejemplos de consultas SQL para análisis comunes.

Descripción general

La API de conjuntos de datos de programas lineales en directo proporciona datos de audiencia a nivel de programa para tus canales lineales en directo y FAST de Prime Video. Cada registro representa una sesión de visualización de un programa programado en un canal.

Los datos se entregan como un registro de cambios con señales is_deleted para las correcciones de programación. Existen dos fuentes disponibles: Channels (linear_program_event_log) y FAST (fast_linear_program_event_log).

Estos datos te permiten:

  • Realizar un seguimiento de la audiencia a nivel de programa (horas vistas, sesiones) en todas las estaciones, territorios, dispositivos y horas.
  • Analizar el desempeño por estación, programa, serie y tipo de contenido.
  • Seguir las correcciones del programa con precisión sin filas obsoletas en tus datos.
  • Integrar la audiencia de televisión lineal en directo con tus sistemas internos y fuentes de datos.

Para el análisis basado en el panel de control, consulta: Programación lineal en Slate Analytics

Funciones principales

Función

Detalles

Detalle a nivel de programa

Una fila por sesión de visualización, programa y programación. Incluye título, estación, serie, ventana de emisión y tiempo de visualización.

Señal de eliminación

Las programaciones reemplazadas o retiradas se reenvían con is_deleted = 1, lo que indica que ya no son válidas.

Clave única estable

Cada fila contiene session_program_schedule_id. Se usa para eliminar duplicados y ejecutar una MERGE.

Ingesta simplificada

Modelo de registro de cambios. Programa llamadas recurrentes y luego ejecuta una MERGE. Actualiza o inserta con is_deleted = 0. Elimina de forma física o lógica con is_deleted = 1.

Coherencia

Formato estandarizado en todos los territorios en una sola fuente. No se necesitan tablas dimensionales por territorio.

Conceptos clave

Concepto

Descripción

Fila de sesión, programa y programación

Una sesión de visualización de un programa en una franja programada. Identificado por session_program_schedule_id.

Modelo de registro de cambios

Los datos son un registro de cambios. Si los atributos de una fila cambian, se publica una versión nueva con el mismo session_program_schedule_id y un last_update_time_utc más reciente.

Clave principal

session_program_schedule_id es el identificador único. Siempre elimina los duplicados en este campo.

is_deleted signal

is_deleted = 0 significa que la programación está activa. is_deleted = 1 indica que la programación ya no está activa ni es válida.

Aplicación de la señal

is_deleted = 0: inserta o actualiza la fila. is_deleted = 1: haz que deje de aparecer en tus datos actuales. Elimina la fila o mantenla marcada y fíltrala.

Primeros pasos

Cómo incorporarse
La API de conjuntos de datos de programas lineales en directo forma parte de la suite de API de Analytics. Cuando te incorpores a la suite de API de Analytics, obtendrás acceso a todas las API disponibles de esa suite, incluida la API de conjuntos de datos de programas lineales en directo (si lo solicitas durante la incorporación). Para obtener instrucciones detalladas sobre la incorporación, visita la página de Incorporación a la API de Analytics.

Requisitos previos
Necesitas lo siguiente antes de hacer solicitudes a la API:

  • Un perfil de seguridad de inicio de sesión con Amazon (LWA). Enviar tu identificador de cliente a tu CAM para que te agregue a la página de administración interna de PV.
  • Un código de autorización para solicitar un token.
  • Un token para todas las solicitudes a la API.

URI base: https://videocentral.amazon.com/apis/v2

Todas las solicitudes deben incluir un token de autenticación de LWA válido en el encabezado de la autorización. Si falta el token o está vencido, la API devuelve una excepción de no autorizado.

Paginación
Todas las respuestas están paginadas. Utiliza estos parámetros para navegar por las páginas:

Parámetro

Predeterminado

Descripción

limit

10

Número de documentos devueltos por página. Máximo 1000.

offset

0

Número de documentos que se deben omitir antes del primer resultado. Usa la siguiente URL en lugar de calcularla tú mismo.

Todas las respuestas paginadas incluyen los siguientes campos:

Campo

Descripción

total

Recuento total de documentos en todas las páginas.

next

La dirección URL de la siguiente página. Es nulo si es la última página.

Recuperación de archivos de conjuntos de datos

Punto de conexión
Usa este comando curl para recuperar una lista de enlaces descargables a archivos de conjuntos de datos:


Nota: Este punto de conexión devuelve enlaces a archivos CSV comprimidos en gzip descargables, no las filas directamente.

Parámetros

Parámetro

Descripción

ACADIA_ID

El identificador de tu cuenta de Slate. Encuéntralo en /v2/accounts.

REPORT_GROUP

El segmento de línea de negocio. Usa channels para la fuente de Channels o FAST para la fuente de FAST Descubre el tuyo con GET /v2/accounts/{ACADIA_ID}

IDENTIFIER_ID

El valor de id que devuelve el punto de conexión de los identificadores. Para Channels, es un hash opaco. Usa el campo id tal como se proporciona En el caso de FAST, es tu código de proveedor, devuelto sin hash.

REPORT_ID

Qué informe extraer. Usa linear_program_event_log para Channels o fast_linear_program_event_log para FAST.

startDateTime

Configurado según la última vez que hiciste la extracción. Formato: YYYY-MM-DDThh:mm:ssZ (UTC).

endDateTime

Ajusta a la hora actual. Formato: YYYY-MM-DDThh:mm:ssZ (UTC).

limit

Mínimo 1, máximo 1000 enlaces por página.

Informes disponibles
Hay dos informes disponibles. Extrae cada uno por separado colocando su identificador de informe en el segmento de ruta datasets/{REPORT_ID}:

Informe

ID del informe

Contenidos

Canales

linear_program_event_log

SVOD/subscription linear (3P_SUBS, y FREE/PRIME cuando corresponda).

FAST

fast_linear_program_event_log

Televisión gratuita con anuncios/canales lineales con anuncios (AVOD)

Nota: Nuestra retención máxima de datos es de 2 años. Las solicitudes de más de 2 años no arrojarán resultados.

Puntos de conexión de sugerencias

Usa estos puntos de conexión para encontrar el identificador de tu cuenta, los grupos de informes, los identificadores y los conjuntos de datos disponibles:

Punto de conexión

Devoluciones

GET /v2/accounts

Lista de cuentas de Slate a las que puedes acceder.

GET /v2/accounts/{ACADIA_ID}

Líneas de negocio disponibles (por ejemplo, Channels, FAST).

GET /v2/accounts/{ACADIA_ID}/channels

Identificadores de informes disponibles para ti. Cada entrada tiene un identificador y un nombre descriptivo.

GET /v2/accounts/{ACADIA_ID}/channels/{IDENTIFIER_ID}/datasets

Conjuntos de datos disponibles para ese identificador.

Columnas de datos

Las siguientes columnas están presentes en la fuente linear_program_event_log (Channels). La fuente fast_linear_program_event_log (FAST) tiene la misma estructura, con vendor_code agregado y las columnas de suscripción entregadas como NULL.

Columna

Tipo

Se puede anular

Descripción

session_program_schedule_id

STRING

No

Clave principal. Identificador único (codifica sesión, programa y ventana de emisión). Elimina duplicados y ejecuta MERGE en este campo. Cambia cuando el programa o la hora de emisión cambian por metadatos actualizados de la EPG.

session_id

STRING

No

Identificador de sesión de visualización único anonimizado.

is_deleted

INT

No

Señal de estado. 0 = la programación está activa. 1 = la programación ya no está activa (reemplazada o retirada). Excluye las filas con is_deleted = 1 de tus datos actuales.

last_update_time_utc

TIMESTAMP

No

Tiempo de versión récord. Utilízalo siempre para eliminar duplicados. Conserva la fila con el valor más reciente para un identificador determinado.

create_time_utc

TIMESTAMP

No

Cuando se creó la fila por primera vez.

program_id

STRING

No

Identificador del programa, p. ej., ID de TMS.

pv_title_id

STRING

Sí

Identificador global de título (GTI) de Prime Video para el programa. Igual que pv_title_id en la fuente de TVOD.

program_title

STRING

Sí

Título del programa.

station_name

STRING

Sí

Nombre del canal o la estación

content_type

STRING

No

live_broadcast or scheduled_tv.

airing_start_utc

TIMESTAMP

No

Inicio de emisión del programa (UTC).

airing_end_utc

TIMESTAMP

No

Fin de la emisión del programa (UTC).

start_segment_utc

TIMESTAMP

No

Inicio de la sesión de visualización (UTC).

end_segment_utc

TIMESTAMP

No

Fin de la sesión de visualización (UTC).

seconds_viewed

LONG

No

Segundos vistos en esta sesión.

vendor_sku

STRING

Sí

SKU de contenido (por ejemplo, identificadores de Gracenote).

parent_channel_label

STRING

Sí

Identificador de canal parent con hash.

cid

STRING

Sí

ID del canal (vigente).

benefit_id

STRING

Sí

Identificador de derecho o beneficio.

subscription_offer_id

STRING

Sí

Identificador de oferta de suscripción.

subscription_event_id

STRING

Sí

Identificador de evento de suscripción.

subscription_offer_time_zone

STRING

Sí

Zona horaria de la oferta de suscripción.

marketplace_id

INT

No

Identificador del sitio web.

marketplace_desc

STRING

Sí

Descripción del sitio web.

territory

STRING

Sí

Código de territorio o país (US, GB, DE, AU y otros).

device_class

STRING

Sí

Categoría de dispositivo.

device_sub_class

STRING

Sí

Subcategoría de dispositivo.

connection_type

STRING

Sí

Tipo de conexión (wifi, cableada y otras).

playback_method

STRING

Sí

Cómo se consumió la sesión: en línea (streaming) o sin conexión (descarga). La programación lineal en directo es en la práctica siempre en línea.

geo_dma

STRING

Sí

DMA geográfico.

stream_type

STRING

No

Siempre LINEAR_TV.

Nota sobre la fuente de FAST: La fuente fast_linear_program_event_log tiene la misma estructura. La columna vendor_code (código de socio) está presente. Las columnas de suscripción (subscription_offer_id, subscription_event_id, subscription_offer_time_zone) se entregan como NULL.

Cómo interpretar is_deleted

Todas las filas contienen is_deleted. Es una señal sobre el estado de la programación. Existen dos valores:

Valor

Significado

Cómo aplicarlo

0

La programación está activa (la versión actual).

Insértalo o sobrescribe la fila existente para esta clave.

1

La programación ya no está activa (reemplazada o retirada).

Haz que deje de aparecer en tus datos actuales. Elimina la fila o mantenla marcada y fíltrala.

¿Cuándo ocurre is_deleted = 1?

  • Corrección de programación. El programa o la hora de emisión se corrigieron. El antiguo session_program_schedule_id llega como is_deleted = 1. Un identificador nuevo llega como is_deleted = 0. Aplica el antiguo como ya no activo e inserta el nuevo.
  • Emisión eliminada. La emisión se suspendió por completo. Su identificador llega como is_deleted = 1.

Notas importantes

  • Un session_program_schedule_id determinado nunca es 0 y 1 a la vez en el mismo lote. Una emisión corregida se convierte en una clave distinta.
  • Las filas que nunca cumplieron los criterios de aptitud de la fuente no se entregan. No esperes un is_deleted = 1 para una fila que nunca recibiste.

Eliminación de duplicados

Es posible que recibas el mismo session_program_schedule_id más de una vez. Se trata de versiones actualizadas de la misma fila. Gestiona la eliminación de duplicados en tres pasos:

  1. Conserva la versión más reciente de cada identificador. Para cada identificador, conserva solo la fila con el last_update_time_utc más reciente y descarta las anteriores. Este valor solo avanza, así que la más reciente siempre gana.


  1. Ejecuta una MERGE con las filas sin duplicados en tu tabla. Usa el patrón de MERGE que aparece a continuación. Actúa según is_deleted cada vez que cargues datos.

Usa una MERGE, no una inserción masiva. Si cargas todos los archivos como filas nuevas, las filas con is_deleted = 1 se quedan en tu tabla como datos activos en lugar de aplicarse. Actúa siempre según la marca.

  1. Alternativa de eliminación lógica. Sustituye la rama DELETE por UPDATE SET is_deleted = 1 y luego filtra con WHERE is_deleted = 0 en tus consultas. Ambos métodos dan el mismo resultado.

Cadencia de ingesta recomendada

Los nuevos conjuntos de datos se publican de forma incremental a lo largo del día.

Recomendación

Detalles

Cadencia recomendada

De 1 a 4 veces al día para mantenerte actualizado.

Estrategia incremental

Configura startDateTime en la última marca de hora recuperada y endDateTime en la hora actual. Descarga y procesa todos los archivos devueltos, y luego ejecuta una MERGE.

Consumidores diarios o semanales

Si extraes datos a diario o semanalmente, procesa todos los archivos del periodo. Esto garantiza que no pierdas actualizaciones ni eliminaciones.

Nota: Cada lote mezcla filas activas (is_deleted = 0) y filas que ya no están activas (is_deleted = 1). No se entregan en archivos separados. La columna is_deleted las diferencia.

Ejemplo de uso de la API

Sigue estos pasos para descubrir tu cuenta, identificar tu grupo de informes y tus identificadores, y recuperar los archivos de conjuntos de datos.

Paso 0: Enumera tus cuentas
Llama a GET /v2/accounts para enumerar las cuentas de Slate a las que puedes acceder.

Paso 1: Líneas de negocio de la cuenta
Llama a GET /v2/accounts/12345678 para ver las líneas de negocio disponibles.

El campo id es el segmento de ruta {REPORT_GROUP} que debes usar en las llamadas posteriores.

Paso 2a: Identificadores de canales
Llama a GET /v2/accounts/12345678/channels?offset=0&limit=100 para enumerar tus identificadores de Channels.

Paso 2b: Identificadores de FAST
Llama a GET /v2/accounts/12345678/fast?offset=0&limit=100 para enumerar tus identificadores de FAST.

Paso 2c: Conjuntos de datos disponibles para un identificador
Llama a GET /v2/accounts/12345678/fast/ABC123/datasets para enumerar los conjuntos de datos disponibles.

Paso 3a: Archivos del conjunto de datos de Channels
Llama al punto de conexión de archivos del conjunto de datos para tu identificador de Channels. La respuesta devuelve una lista de URL de descarga de archivos CSV comprimidos en gzip.

Paso 3b: Archivos del conjunto de datos de FAST
Llama al punto de conexión de archivos del conjunto de datos para tu identificador de FAST.

Ejemplos de consultas

Estas consultas suponen que ya ejecutaste una MERGE con tus datos. Si conservas las filas con is_deleted en una tabla sin procesar, agrega WHERE is_deleted = 0 a cada consulta.

Horas vistas por estación en un período

Los X programas principales por horas vistas

Resumen de visualización diaria

Horas vistas por territorio

Canalización de ETL

Usa este patrón de cuatro pasos para crear tu canalización de ETL del conjunto de datos de programas lineales en directo.

  1. Extracción inicial de datos. Extrae todos los archivos de tu canal dentro del intervalo de tiempo deseado mediante el punto de conexión de la API. Descarga todos los archivos que se devolvieron. Cada uno contiene filas en CSV comprimido en gzip.
  2. Eliminación de duplicados. Cuando existan varios registros para el mismo session_program_schedule_id en los archivos que extrajiste, conserva solo la fila con el last_update_time_utc más reciente. Consulta la sección Eliminación de duplicados para ver el patrón SQL completo.
  3. Aplicación al destino. Ejecuta una MERGE con los registros sin duplicados en tu tabla de destino usando session_program_schedule_id como clave. Actualiza o inserta con is_deleted = 0. Con is_deleted = 1, haz que el identificador deje de aparecer en tus datos actuales. Elimínala de forma física o mantén la fila marcada y fíltrala.
  4. Procesamiento incremental. Para cargas continuas, establece startDateTime en la última vez que extrajiste datos y endDateTime en la hora actual. Procesa todos los archivos devueltos y ejecuta una MERGE en tu destino.


Consejos rápidos

Ten en cuenta estos consejos cuando integres la API en tu canalización.

  1. session_program_schedule_id es tu clave única. Elimina siempre los duplicados con last_update_time_utc.
  2. Usa una MERGE, no una inserción masiva. Actúa según las señales is_deleted cada vez que cargues datos.
  3. Extrae datos de 1 a 4 veces al día para obtener los datos más recientes.
  4. Establece tu startDateTime en la marca de tiempo de la última extracción correcta para las cargas incrementales.
  5. Usa los puntos de conexión de descubrimiento para encontrar tu cuenta, tus identificadores y los conjuntos de datos disponibles.
  6. Extrae las fuentes de Channels y FAST si tu asociación abarca ambas.
  7. Agrega WHERE is_deleted = 0 a todas las consultas si usas el enfoque de eliminación lógica.
  8. Nuestra retención máxima de datos es de 2 años. Planifica tus extracciones históricas según corresponda.

¿Sabías que...?

El acceso programático a los datos de audiencia a nivel de programa te permite crear informes personalizados, alimentar tus sistemas de programación y combinar datos lineales con tus otros datos de negocio. Los socios que integran esta API en sus flujos de trabajo toman decisiones más rápidas e informadas sobre programación y adquisición de contenido.

Para obtener información rápida y un análisis visual, visita el panel de control de programación lineal en Slate Analytics.

Preguntas frecuentes

Preguntas frecuentes sobre la API de conjuntos de datos de programas lineales en vivo

¿Aún necesitas ayuda?

Contáctanos

En esta guía



Error interno del servidor. Inténtelo nuevamente.
La sesión ha caducado.

Inicie sesión para continuar.

Iniciar sesión
edit