Video Central

Descripción general

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

Los datos se envían como un registro de cambios con las señales is_delete para corregir la programación. Hay dos canales disponibles: Channels (linear_program_event_log) y FAST (fast_linear_program_event_log).

Estos datos le permiten:

Realice un seguimiento de la audiencia a nivel de programa (horas vistas, sesiones) en todas las estaciones, territorios, dispositivos y horas.
Analice el rendimiento por estación, programa, serie y tipo de contenido.
Siga las correcciones de programación con precisión sin filas obsoletas en sus datos.
Integre la audiencia lineal en directo con sus sistemas internos y fuentes de datos.

Para obtener un análisis basado en un panel de control, consulte: Programación lineal en Slate Analytics

Características principales

Característica	Detalles
Detalles del grano del programa	Una fila por sesión de visualización, programa y horario. Incluye el título, la estación, la serie, la ventana de emisión y el tiempo de reproducción.
Señal de eliminación	Los horarios sustituidos o retirados se reenvían con is_deleted = 1, lo que indica que ya no son válidos.
Clave única estable	Cada fila contiene el session_program_schedule_id. Se usa para deduplicar y FUSIONAR.
Ingestión simplificada	Modelo de registro de cambios. Programar llamadas recurrentes y, a continuación, FUSIONAR. Upsert en is_deleted = 0. Eliminación automática o temporal en is_deleted = 1.
Consistencia	Formato estandarizado en todos los territorios en una sola fuente. No se necesitan tablas dimensionales por territorio.

Conceptos clave

Concepto	Description
Fila de programación del programa de la sesión	Sesión de visualización de un programa en un espacio programado. Se identifica mediante 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 nueva versión 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. Deduplique siempre en este campo.
es la señal eliminada	is_deleted = 0 significa que la programación está activa. is_delete = 1 indica que la programación ya no está activa o es válida.
Aplicando la señal	is_delete = 0: inserta o actualiza la fila. is_deleted = 1: haz que deje de aparecer en tus datos actuales. Elimine la fila o manténgala marcada y fíltrela.

Cómo empezar

Cómo incorporar
La API de conjuntos de datos del Programa Lineal en vivo forma parte del conjunto de API de Analytics. Cuando se incorpore a la suite de API de Analytics, recibirá acceso a todas las API disponibles dentro de esa suite, incluida la API de conjuntos de datos del Programa Lineal en vivo (si se solicita durante la incorporación). Para obtener instrucciones de incorporación detalladas, visite la página de incorporación de la API de Analytics.

Requisitos previos
Antes de realizar solicitudes a la API, es necesario tener en cuenta lo siguiente:

Un perfil de seguridad de inicio de sesión con Amazon (LWA). Envíe su ID de cliente a su CAM para añadirlo 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 de API.

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

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

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

Parámetro	Predeterminado	Description
limitar	10	Number of documents returned per page. Máximo 1000.
compensar	0	Number of documents to skip before the first result. Siga la siguiente URL en lugar de calcularla usted mismo.

Todos los campos de respuesta paginados incluyen los siguientes campos:

Campo	Description
total	Recuento total de documentos en todas las páginas.
próximo	URL a la página siguiente. Es nulo si es la última página.

Recuperación de archivos de conjuntos de datos

Endpoint
Utilice este comando curl para recuperar una lista de enlaces a archivos de conjuntos de datos descargables:

Nota: Este punto final devuelve enlaces a archivos CSV descargables comprimidos con gzip, no directamente a las filas.

Parámetros

Parámetro	Description
ACADIA_ID	Tu ID de cuenta de Slate. Encuéntrelo en /v2/accounts.
REPORT_GROUP	El segmento de líneas de negocio. Utilice los canales para la transmisión de los canales o los rápidos para la transmisión RÁPIDA. Descubre el tuyo con GET /v2/accounts/ {ACADIA_ID}.
IDENTIFIER_ID	El valor de identificación devuelto por el punto final de los identificadores. En el caso de los canales, es un hash opaco. Usa el campo de identificación tal y como se indica. En el caso de FAST, es el código de su proveedor, que se devuelve sin cifrar.
REPORT_ID	Qué informe obtener. Utilice linear_program_event_log para los canales o fast_linear_program_event_log para FAST.
Fecha y hora de inicio	Establézcalo como la última vez que tiraste. Formato: aaaa-mm-ddthh:mm:SSZ (UTC).
Fecha y hora de finalización	Establézcalo en la hora actual. Formato: aaaa-mm-ddthh:mm:SSZ (UTC).
limitar	Mínimo 1, máximo 1000 enlaces por página.

Informes disponibles Hay
dos informes disponibles. Para obtener cada uno de ellos por separado, coloque su ID de informe en el segmento de ruta de los conjuntos de datos/ {REPORT_ID}:

Informe	ID del informe	Contenido
Canales	linear_program_event_log	SVOD/suscripción lineal (3P_SUBS y FREE/PRIME cuando proceda).
RÁPIDO	fast_linear_program_event_log	Televisión gratuita compatible con publicidad o canales lineales con publicidad (AVOD)

Nota: La 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 finales de detección

Utilice estos puntos de enlace para encontrar el ID de su cuenta, los grupos de informes, los identificadores y los conjuntos de datos disponibles:

Punto final	Devoluciones
GET /v2/accounts	Lista de cuentas de Slate a las que puedes acceder.
OBTENGA /v2/accounts/ {ACADIA_ID}	Líneas de negocio disponibles (por ejemplo, canales, rápidas).
OBTÉN /v2/accounts/ {ACADIA_ID} /channels	Identificadores de informes disponibles para ti. Cada entrada tiene un identificador y un nombre descriptivo.
OBTENGA /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 el feed linear_program_event_log (Channels). El feed fast_linear_program_event_log (FAST) tiene la misma forma: se ha añadido vendor_code y las columnas de suscripción se muestran como NULL.

Columna	Type	Aceptable a valores nulos	Description
session_program_schedule_id	CADENA	No	Clave principal. ID único (codifica la sesión, el programa y la ventana de emisión). Deduplique y FUSIONE en este campo. Cambia cuando el programa o la hora de emisión cambian debido a la actualización de los metadatos de EPG.
session_id	CADENA	No	Identificador de sesión de visualización único y anónimo.
está_eliminado	INT	No	Señal de estado. 0 = la programación está activa. 1 = la programación ya no está activa (sustituida o retirada). Excluye is_deleted = 1 fila de tus datos actuales.
last_update_time_utc	MARCA DE TIEMPO	No	Registre la hora de la versión. Úselo siempre para deduplicar. Mantenga la fila con el valor más reciente de un ID determinado.
create_time_utc	MARCA DE TIEMPO	No	Cuando se creó la fila por primera vez.
program_id	CADENA	No	Identificador del programa, por ejemplo, ID de TMS.
pv_title_id	CADENA	Sí	Prime Video Global Title Identifier (GTI) para el programa. Igual que pv_title_id en el canal de TVOD.
program_title	CADENA	Sí	Título del programa.
nombre_estación	CADENA	Sí	Nombre del canal o de la emisora.
tipo_contenido	CADENA	No	live_broadcast o scheduled_tv.
airing_start_utc	MARCA DE TIEMPO	No	Inicio de emisión del programa (UTC).
airing_end_utc	MARCA DE TIEMPO	No	Fin de emisión del programa (UTC).
start_segment_utc	MARCA DE TIEMPO	No	Visualización del inicio de la sesión (UTC).
end_segment_utc	MARCA DE TIEMPO	No	Finalización de la sesión de visualización (UTC).
segundos_vistos	LARGO	No	Segundos vistos en esta sesión.
vendor_sku	CADENA	Sí	SKU del contenido (por ejemplo, identificadores de Gracenote).
etiqueta del canal principal	CADENA	Sí	Identificador de canal principal codificado.
ácido	CADENA	Sí	ID de Canal (efectivo).
benefit_id	CADENA	Sí	Identificador de derechos/prestaciones.
suscription_offer_id	CADENA	Sí	Identificador de oferta de suscripción.
subscription_event_id	CADENA	Sí	Identificador de eventos de suscripción.
subscription_offer_time_zone	CADENA	Sí	Zona horaria de la oferta de suscripción.
marketplace_id	INT	No	Identificador de Marketplace.
marketplace_desc	CADENA	Sí	Descripción del mercado.
territorio	CADENA	Sí	Código de territorio o país (EE. UU., GB, DE, AU y otros).
clase_dispositivo	CADENA	Sí	Categoría de dispositivo.
device_sub_class	CADENA	Sí	Subcategoría de dispositivos.
tipo_de_conexión	CADENA	Sí	Tipo de conexión (wifi, cableado y otros).
método_reproducción	CADENA	Sí	Cómo se consumió la sesión: en línea (streaming) o sin conexión (descarga). En efecto, Live Linear siempre está en línea.
geo_dma	CADENA	Sí	DMA geográfico.
tipo_de_flujo	CADENA	No	Siempre LINEAR_TV.

Nota sobre el feed FAST: El feed fast_linear_program_event_log tiene la misma forma. 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 muestran como NULL.

Entendiendo is_delete

Cada fila lleva is_delete. Es una señal sobre el estado de la programación. Hay dos valores:

Value	Significado	¿Cómo aplicarlo
0	Programar está activo (la versión actual).	Insértelo o sobrescriba la fila existente para esta clave.
1.	Programar ya no está activo (se reemplaza o se retira).	Haz que deje de aparecer en tus datos actuales. Elimine la fila o manténgala marcada y fíltrela.

¿Cuándo aparece is_delete = 1?

Programar corrección. Se corrigió el programa o la hora de emisión. El antiguo session_program_schedule_id llega como is_deleted = 1. Llega un nuevo ID como is_deleted = 0. Aplica el antiguo cuando ya no esté activo e inserta el nuevo.
Se ha eliminado la ventilación. La emisión se retiró por completo. Su ID llega como is_deleted = 1.

Notas importantes

Un session_program_schedule_id dado nunca es 0 y 1 en el mismo lote. Una emisión corregida se convierte en una clave diferente.
Las filas que nunca cumplieron con los criterios de aptitud del feed no se entregan. No esperes que aparezca is_deleted = 1 para una fila que nunca recibiste.

Deduplicación

Es posible que reciba el mismo session_program_schedule_id más de una vez. Son versiones actualizadas de la misma fila. Gestione la deduplicación en tres pasos:

Conserve la última versión de cada ID. Para cada ID, mantén solo la fila con el último last_update_time_utc y elimina los más antiguos. Este valor solo se mueve hacia delante, por lo que siempre gana el último.

COMBINA las filas desduplicadas en tu tabla. Usa el patrón MERGE que aparece a continuación. Actúe según is_deleted cada vez que cargue datos.

Utilice un MERGE, no un inserto masivo. Si carga todos los archivos como filas nuevas, las filas is_deleted = 1 se ubicarán en la tabla como datos activos en lugar de aplicarse. Actúa siempre según la bandera.

Alternativa de borrado suave. Sustituya la rama DELETE por UPDATE SET is_deleted = 1 y, a continuación, filtre WHERE is_deleted = 0 en las consultas. Ambos métodos dan el mismo resultado.

Cadencia de ingestión 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 mantenerse al día.
Estrategia incremental	Establezca StartDateTime en la última marca de tiempo recuperada y EndDateTime en la hora actual. Descargue y procese todos los archivos devueltos y, a continuación, COMBINE.
Consumidores diarios/semanales	Si los busca a diario o semanalmente, procese todos los archivos del período. Esto garantiza que no se pierda las actualizaciones ni las eliminaciones.

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

Ejemplo de uso de API

Siga estos pasos para descubrir su cuenta, identificar el grupo de informes y los identificadores y recuperar los archivos del conjunto de datos.

Paso 0: Enumere sus cuentas
Llame a GET /v2/accounts para ver las cuentas de Slate a las que puede acceder.

Paso 1: Líneas comerciales para la cuenta
Llame a GET /v2/accounts/1234567 8 para ver las líneas comerciales disponibles.

El campo id es el segmento de ruta {REPORT_GROUP} que se utilizará en llamadas posteriores.

Paso 2a: Los identificadores de canales
llaman a GET /v2/accounts/12345678/channels? offset=0&limit=100 para ver una lista de tus identificadores de canales.

Paso 2b: ¿Los identificadores FAST
llaman a GET /v2/accounts/12345678/fast? offset=0&limit=100 para ver una lista de tus identificadores FAST.

Paso 2c: Datasets Available for an Identifier
Llame a GET /v2/accounts/12345678/fast/ABC123/Datasets para ver una lista de los conjuntos de datos disponibles.

Paso 3a: Archivos de conjuntos de datos de canales
Llame al punto final de los archivos de conjunto de datos para su identificador de canales. La respuesta devuelve una lista de direcciones URL de descarga de archivos CSV comprimidos con gzip.

Paso 3b: Archivos de conjuntos de datos FAST
Llame al punto final de los archivos de conjunto de datos para su identificador FAST.

Consultas de muestra

Estas consultas asumen que ya ha fusionado sus datos. Si mantiene las filas is_deleted en una tabla sin procesar, añada WHERE is_deleted = 0 a cada consulta.

Horas vistas por estación durante un período

Los 10 mejores programas por horas vistas

Resumen de visualización diaria

Horas consultadas por Territorio

Tubería ETL

Utilice este patrón de cuatro pasos para crear su canalización de ETL para el conjunto de datos del Programa Lineal en Vivo.

Obtención inicial de datos. Extrae todos los archivos de tu canal en el intervalo de tiempo deseado mediante el punto final de la API. Descarga todos los archivos devueltos. Cada uno contiene filas en formato CSV comprimido con gzip.
Deduplicar. Si existen varios registros para el mismo session_program_schedule_id en los archivos que has extraído, conserva solo la fila con la última versión de last_update_time_utc. Consulte la sección de deduplicación para ver el patrón SQL completo.
Aplicar al destino. COMBINA los registros deduplicados en tu tabla de destino con la clave session_program_schedule_i d. Upsert on is_deleted = 0. En is_deleted = 1, haz que el ID deje de aparecer en tus datos actuales. Bórrelo de forma permanente o mantenga la fila marcada y fíltrela.
Procesamiento incremental. Para cargas continuas, establézcalo en la última vez que retiraste y EndDateTime en la hora actual. Procesa todos los archivos devueltos y COLÓCALOS en tu destino.

Consejos rápidos

Ten en cuenta estos consejos a la hora de integrar la API en tu canalización.

session_program_schedule_id es tu clave única. Deduplique siempre con last_update_time_utc.
Usa un comando MERGE, no un inserto masivo. Actúe según las señales de is_deleted cada vez que cargue datos.
Extraiga de 1 a 4 veces al día para obtener los datos más actualizados.
Para cargas incrementales, establece StartDateTime en la última marca de tiempo de extracción correcta.
Utilice los puntos finales de detección para encontrar su cuenta, sus identificadores y los conjuntos de datos disponibles.
Si tu asociación incluye ambos canales, utiliza canales y canales FAST.
Añadir WHERE is_deleted = 0 a todas las consultas si utiliza el enfoque de borrado suave.
La retención máxima de datos es de 2 años. Planifique sus tiradas históricas en consecuencia.

¿Lo sabías?

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

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

API de conjuntos de datos de programas lineales en vivo