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 |
|
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:
curl -X GET \
-H "Authorization: Bearer Atza|auth_token" \
"https://videocentral.amazon.com/apis/v2/accounts/{ACADIA_ID}/{REPORT_GROUP}/{IDENTIFIER_ID}/datasets/{REPORT_ID}\
?startDateTime=YYYY-MM-DDThh:mm:ssZ\
&endDateTime=YYYY-MM-DDThh:mm:ssZ\
&offset=0&limit=1000"
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:
- 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.
SELECT *
FROM (
SELECT *,
ROW_NUMBER() OVER (
PARTITION BY session_program_schedule_id
ORDER BY last_update_time_utc DESC
) AS rn
FROM your_staging_table
) t
WHERE rn = 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.
MERGE INTO your_table AS target USING dedup_staging AS source ON target.session_program_schedule_id = source.session_program_schedule_id WHEN MATCHED AND source.is_deleted = 1 AND source.last_update_time_utc > target.last_update_time_utc THEN DELETE WHEN MATCHED AND source.is_deleted = 0 AND source.last_update_time_utc > target.last_update_time_utc THEN UPDATE SET program_title = source.program_title, seconds_viewed = source.seconds_viewed, airing_start_utc = source.airing_start_utc, airing_end_utc = source.airing_end_utc, last_update_time_utc = source.last_update_time_utc -- ... all other columns WHEN NOT MATCHED AND source.is_deleted = 0 THEN INSERT (session_program_schedule_id, session_id, program_id, ..., last_update_time_utc) VALUES (source.session_program_schedule_id, source.session_id, source.program_id, ..., source.last_update_time_utc);
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. |
- 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.{
"total": 1,
"next": null,
"data": [
{ "id": "12345678", "name": "MGM" }
]
}
Paso 1: Líneas de negocio de la cuenta
Llama a GET /v2/accounts/12345678 para ver las líneas de negocio disponibles.{
"total": 2,
"next": null,
"data": [
{ "id": "channels", "name": "Channels" },
{ "id": "fast", "name": "FAST" }
]
}
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.{
"total": 2,
"next": null,
"data": [
{ "id": "3f6c1b9d-8a2d-4e7f-9c31-0d5b7b2e6f14", "name": "MGM+" },
{ "id": "a91d4c21-57e0-4b8a-b6f3-2e9c0e1f8b77", "name": "MGM+ Espanol" }
]
}
Paso 2b: Identificadores de FAST
Llama a GET /v2/accounts/12345678/fast?offset=0&limit=100 para enumerar tus identificadores de FAST.{
"total": 1,
"next": null,
"data": [
{ "id": "ABC123", "name": "MGM 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.{
"total": 1,
"next": null,
"data": [
{ "id": "fast_linear_program_event_log", "name": "FAST Linear Program Event Log" }
]
}
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.GET /v2/accounts/12345678/channels/3f6c1b9d-8a2d-4e7f-9c31-0d5b7b2e6f14
/datasets/linear_program_event_log
?startDateTime=2026-09-14T00:00:00Z&endDateTime=2026-09-15T00:00:00Z&offset=0&limit=1000
{
"total": 3,
"next": null,
"data": [
{ "downloadUrl": "https://pvreporting-datasets-prod.s3.amazonaws.com/linear_program_event_log/
3f6c1b9d.../2026/09/14/06/...linear_2f0c...e91a.csv.gz?X-Amz-Algorithm=..." },
{ "downloadUrl": "https://pvreporting-datasets-prod.s3.amazonaws.com/linear_program_event_log/
3f6c1b9d.../2026/09/14/14/...linear_7b41...03cd.csv.gz?..." },
{ "downloadUrl": "https://pvreporting-datasets-prod.s3.amazonaws.com/linear_program_event_log/
3f6c1b9d.../2026/09/14/22/...linear_c8d9...5e60.csv.gz?..." }
]
}
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.GET /v2/accounts/12345678/fast/ABC123/datasets/fast_linear_program_event_log
?startDateTime=2026-09-14T00:00:00Z&endDateTime=2026-09-15T00:00:00Z&offset=0&limit=1000
{
"total": 1,
"next": null,
"data": [
{ "downloadUrl": "https://pvreporting-datasets-prod.s3.amazonaws.com/fast_linear_program_event_log/
ABC123/2026/09/14/15/...fast_linear_c258fb25...758add.csv.gz?X-Amz-Algorithm=..." }
]
}
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íodoSELECT station_name,
COUNT(*) AS sessions,
SUM(seconds_viewed) / 3600.0 AS hours_viewed
FROM your_table
WHERE start_segment_utc BETWEEN '[START_DATE]' AND '[END_DATE]'
GROUP BY station_name
ORDER BY hours_viewed DESC;
Los X programas principales por horas vistasSELECT program_title, station_name,
SUM(seconds_viewed) / 3600.0 AS hours_viewed
FROM your_table
WHERE start_segment_utc BETWEEN '[START_DATE]' AND '[END_DATE]'
GROUP BY program_title, station_name
ORDER BY hours_viewed DESC
LIMIT [X];
Resumen de visualización diariaSELECT DATE(start_segment_utc) AS view_date,
COUNT(*) AS sessions,
SUM(seconds_viewed) / 3600.0 AS hours_viewed
FROM your_table
WHERE start_segment_utc BETWEEN '[START_DATE]' AND '[END_DATE]'
GROUP BY DATE(start_segment_utc)
ORDER BY view_date DESC;
Horas vistas por territorioSELECT territory,
SUM(seconds_viewed) / 3600.0 AS hours_viewed
FROM your_table
WHERE start_segment_utc BETWEEN '[START_DATE]' AND '[END_DATE]'
GROUP BY territory
ORDER BY hours_viewed DESC;
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.
- 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.
- 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.
- 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.
- 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.
startDateTime = {last_successful_pull_timestamp}
endDateTime = {current_utc_timestamp}
Consejos rápidos
Ten en cuenta estos consejos cuando integres la API en tu canalización.
- session_program_schedule_id es tu clave única. Elimina siempre los duplicados con last_update_time_utc.
- Usa una MERGE, no una inserción masiva. Actúa según las señales is_deleted cada vez que cargues datos.
- Extrae datos de 1 a 4 veces al día para obtener los datos más recientes.
- Establece tu startDateTime en la marca de tiempo de la última extracción correcta para las cargas incrementales.
- Usa los puntos de conexión de descubrimiento para encontrar tu cuenta, tus identificadores y los conjuntos de datos disponibles.
- Extrae las fuentes de Channels y FAST si tu asociación abarca ambas.
- Agrega WHERE is_deleted = 0 a todas las consultas si usas el enfoque de eliminación lógica.
- 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. |