Video Central

Panoramica

L’API Live Linear Program Dataset fornisce dati di visualizzazione granulari del programma per i tuoi canali Prime Video live lineari e FAST. Ogni record rappresenta una sessione di visualizzazione di un programma programmato su un canale.

I dati vengono forniti come log delle modifiche con segnali is_deleted per le correzioni pianificate. Sono disponibili due feed: Channels (linear_program_event_log) e FAST (fast_linear_program_event_log).

Questi dati consentono di:

Tieni traccia delle visualizzazioni a livello di programma (ore di visualizzazione, sessioni) tra stazioni, territori, dispositivi e orari.
Analizza le prestazioni per stazione, programma, serie e tipo di contenuto.
Segui le correzioni pianificate in modo accurato senza righe obsolete nei dati.
Integra la visualizzazione lineare in tempo reale con i sistemi interni e le fonti di dati.

Per un’analisi basata su dashboard, consulta: Programmazione lineare su Slate Analytics

Caratteristiche principali

Caratteristica	Dettagli
Dettagli sulla grana del programma	Una riga per sessione di visualizzazione, programma e pianificazione. Include titolo, stazione, serie, finestra di messa in onda e tempo di visualizzazione.
Segnale di rimozione	Le pianificazioni sostituite o ritirate vengono inviate nuovamente con is_deleted = 1, segnalando che non sono più valide.
Chiave univoca stabile	Ogni riga riporta session_program_schedule_id. Usalo per deduplicare e UNIRE.
Inserimento semplificato	Modello Changelog. Pianifica le chiamate ricorrenti, quindi UNISCI. Sospeso su is_deleted = 0. Eliminazione definitiva o temporanea su is_deleted = 1.
Coerenza	Formattazione standardizzata in tutti i territori in un’unica fonte. Non sono necessarie tabelle dimensionali per territorio.

Concetti chiave

Concetto	Description
Riga Session-Program-Schedule	Una sessione di visualizzazione di un programma in uno slot programmato. Identificato da session_program_schedule_id.
Modello Changelog	I dati sono un log delle modifiche. Se gli attributi di una riga cambiano, viene pubblicata una nuova versione con lo stesso session_program_schedule_id e una versione più recente di last_update_time_utc.
Chiave primaria	session_program_schedule_id è l’identificatore univoco. Esegui sempre la deduplicazione su questo campo.
segnale is_deleted	is_deleted = 0 significa che la pianificazione è attiva. is_deleted = 1 segnala che la pianificazione non è più attiva o valida.
L’applicazione del segnale	is_deleted = 0: inserisce o aggiorna la riga. is_deleted = 1: fai in modo che non appaia più nei tuoi dati correnti. Rilascia la riga o tienila contrassegnata e filtrala.

Guida introduttiva

Come effettuare l’onboard
L’API Live Linear Program Dataset fa parte della Analytics API Suite. Quando effettui l’accesso alla Analytics API Suite, riceverai l’accesso a tutte le API disponibili all’interno di quella suite, inclusa l’API Live Linear Program Dataset (se richiesta durante l’onboarding). Per istruzioni dettagliate sull’onboarding, visita la pagina di onboarding dell’API Analytics.

Prerequisiti
È necessario quanto segue prima di effettuare richieste API:

Un login con Amazon (LWA) Security Profile. Invia il tuo ID cliente al tuo CAM per aggiungerlo alla pagina di amministrazione interna di PV.
Un codice di autorizzazione per richiedere un token.
Un token per tutte le richieste API.

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

Tutti le richieste devono includere un token di autenticazione LWA valido nell’intestazione di autorizzazione. Se il token è mancante o è scaduto, l’API restituisce un’eccezione non autorizzata.

Impaginazione Tutte le
risposte sono suddivise in pagine. Usa questi parametri per navigare tra le pagine:

Parametro	Predefinito	Description
limite	10	Numero di documenti restituiti per pagina. Massimo 1.000.
compensare	0	Numero di documenti da saltare prima del primo risultato. Segui l’URL successivo invece di calcolarlo tu stesso.

Tutti le risposte suddivise in pagine includono i seguenti campi:

Campo	Description
totale	Numero totale di documenti su tutte le pagine.
prossimo	URL alla pagina successiva. Null se questa è l’ultima pagina.

Recupero di file di set di dati

Endpoint
Usa questo comando curl per recuperare un elenco di collegamenti ai file di set di dati scaricabili:

Nota: questo endpoint restituisce collegamenti a file CSV compressi con gzip scaricabili, non direttamente le righe.

Parametri

Parametro	Description
ACADIA_ID	L’ID del tuo account Slate. Trovalo su /v2/accounts.
REPORT_GROUP	Il segmento della linea di business. Usa i canali per il feed Channels o fast per il feed FAST. Scopri la tua con GET /v2/accounts/ {ACADIA_ID}.
IDENTIFICATORE_ID	Il valore id restituito dall’endpoint degli identificatori. Per i canali, è un hash opaco. Usa il campo id come indicato. Per FAST, è il codice del fornitore, restituito senza hash.
REPORT_ID	Quale rapporto estrarre. Usa linear_program_event_log per Channels o fast_linear_program_event_log per FAST.
StartDateTime	Imposta l’ultima volta che hai tirato. Formato: aaaa-mm-ggthh:mm:ssz (UTC).
Data e ora di fine	Imposta l’ora corrente. Formato: aaaa-mm-ggthh:mm:ssz (UTC).
limite	Minimo 1, massimo 1.000 link per pagina.

Report disponibili Sono disponibili
due report. Estrai ciascuno separatamente inserendo il relativo ID del report nel segmento di percorso datasets/ {REPORT_ID}:

Rapporto	ID del rapporto	Contenuti
Canali	log degli eventi del programma lineare	SVOD/subscription linear (3P_SUBS e FREE/PRIME ove applicabile).
VELOCE	registro degli eventi del programma veloce lineare	Televisione supportata da Free-AD /Canali lineari supportati da AD (AVOD)

Nota: la conservazione massima dei dati è di 2 anni. Le richieste più vecchie di 2 anni non restituiranno risultati.

Endpoint Discovery

Usa questi endpoint per trovare l’ID del tuo account, i gruppi di report, gli identificatori e i set di dati disponibili:

Endpoint	Restituisce
OTTIENI /v2/accounts	Elenco degli account Slate a cui puoi accedere.
OTTIENI /v2/accounts/ {ACADIA_ID}	Linee di business disponibili (ad esempio, canali, fast).
SCARICA /v2/accounts/ {ACADIA_ID} /channels	Segnala gli identificatori a tua disposizione. Ogni voce ha un id e un nome descrittivo.
OTTIENI /v2/accounts/ {ACADIA_ID} /channels/ {IDENTIFIER_ID} /datasets	Set di dati disponibili per quell’identificatore.

Colonne di dati

Le seguenti colonne sono presenti nel feed linear_program_event_log (Channels). Il feed fast_linear_program_event_log (FAST) ha la stessa forma, con vendor_code aggiunto e le colonne di sottoscrizione fornite come NULL.

Colonna	Type	Annullabile	Description
session_program_schedule_id	CORDA	No	Chiave primaria. ID univoco (codifica sessione, programma e finestra di messa in onda). Deduplica e UNISCI in questo campo. Cambia quando il programma o l’orario di trasmissione cambiano a causa dell’aggiornamento dei metadati EPG.
id_sessione	CORDA	No	Identificatore di sessione di visualizzazione univoco anonimizzato.
è_eliminato	INT	No	Segnale di stato. 0 = la pianificazione è attiva. 1 = la pianificazione non è più attiva (sostituita o ritirata). Escludi is_deleted = 1 righe dai dati correnti.
last_update_time_utc	TIMESTAMP	No	Registra l’ora della versione. Usalo sempre per la deduplicazione. Mantieni la riga con il valore più recente per un determinato ID.
create_time_utc	TIMESTAMP	No	Quando la riga è stata creata per la prima volta.
program_id	CORDA	No	Identificatore del Programma, ad esempio ID TMS.
pv_title_id	CORDA	sì	Prime Video Global Title Identifier (GTI) per il programma. Uguale a pv_title_id nel feed TVOD.
program_title	CORDA	sì	Titolo del Programma.
nome_stazione	CORDA	sì	Nome del Canale o della stazione.
tipo_contenuto	CORDA	No	live_broadcast o scheduled_tv.
airing_start_utc	TIMESTAMP	No	Inizio della messa in onda del programma (UTC).
airing_end_utc	TIMESTAMP	No	Fine della messa in onda del programma (UTC).
start_segment_utc	TIMESTAMP	No	Visualizzazione dell’inizio della sessione (UTC).
end_segment_utc	TIMESTAMP	No	Visualizzazione della fine della sessione (UTC).
secondi_visualizzati	LUNGO	No	Secondi visualizzati in questa sessione.
vendor_sku	CORDA	sì	SKU del contenuto (ad esempio, identificatori Gracenote).
parent_channel_label	CORDA	sì	Identificatore del canale principale con hash.
cid	CORDA	sì	ID del canale (effettivo).
benefit_id	CORDA	sì	Identificatore del titolo/beneficio.
id_offer_sottoscrizione	CORDA	sì	Identificatore dell’offerta di abbonamento.
subscription_event_id	CORDA	sì	Identificatore dell’evento di sottoscrizione.
subscription_offer_time_zone	CORDA	sì	Fuso orario dell’offerta di abbonamento.
marketplace_id	INT	No	Identificatore del marketplace.
marketplace_desc	CORDA	sì	Descrizione del marketplace.
territorio	CORDA	sì	Territorio o prefisso del paese (US, GB, DE, AU e altri).
classe del dispositivo	CORDA	sì	Categoria di dispositivo.
device_sub_class	CORDA	sì	Sottocategoria di dispositivi.
tipo_connessione	CORDA	sì	Tipo di connessione (wifi, cablata e altro).
metodo_riproduzione	CORDA	sì	Come è stata consumata la sessione: online (streaming) o offline (download). Live linear è effettivamente sempre online.
geo_dma	CORDA	sì	DMA geografico.
tipo_flusso	CORDA	No	Sempre LINEAR_TV.

Nota sul feed FAST: il feed fast_linear_program_event_log ha la stessa forma. È presente la colonna vendor_code (codice partner). Le colonne di sottoscrizione (subscription_offer_id, subscription_event_id, subscription_offer_time_zone) vengono fornite come NULL.

Comprendere is_deleted

Ogni riga riporta is_deleted. È un segnale sullo stato della pianificazione. Esistono due valori:

Value	Significato	Come applicarlo
0	Pianifica è attiva (la versione attuale).	Inseriscila o sovrascrivi la riga esistente per questa chiave.
1	Pianifica non è più attiva (sostituita o ritirata).	Fai in modo che non appaia più nei tuoi dati correnti. Rilascia la riga o tienila contrassegnata e filtrala.

Quando si verifica is_deleted = 1?

Pianifica la correzione. Il programma o il tempo di messa in onda sono stati corretti. Il vecchio session_program_schedule_id arriva come is_deleted = 1. Un nuovo ID arriva come is_deleted = 0. Applica il vecchio come non più attivo e inserisci il nuovo.
Aerazione rimossa. La messa in onda è stata completamente sospesa. Il suo ID arriva come is_deleted = 1.

Note importanti

Un determinato session_program_schedule_id non è mai sia 0 che 1 nello stesso batch. Una messa in onda corretta diventa una chiave diversa.
Le righe che non hanno mai soddisfatto i criteri di idoneità del feed non vengono consegnate. Non aspettarti un valore is_deleted = 1 per una riga che non hai mai ricevuto.

Deduplicazione

Potresti ricevere lo stesso session_program_schedule_id più di una volta. Si tratta di versioni aggiornate della stessa riga. Gestisci la deduplicazione in tre passaggi:

Conserva la versione più recente di ogni ID. Per ogni ID, mantieni solo la riga con i last_update_time_utc più recenti ed elimina quelli più vecchi. Questo valore si sposta solo in avanti, quindi vince sempre l’ultimo.

UNISCI le righe deduplicate nella tua tabella. Usa il modello MERGE riportato di seguito. Agisci su is_deleted ogni volta che carichi dati.

Utilizzate un MERGE, non un inserto di massa. Se carichi ogni file come nuove righe, le righe is_deleted = 1 rimangono nella tabella come dati attivi anziché essere applicate. Agisci sempre sulla bandiera.

Alternativa alla cancellazione graduale. Sostituisci il ramo DELETE con UPDATE SET is_deleted = 1, quindi filtra WHERE is_deleted = 0 nelle tue query. Entrambi i metodi danno lo stesso risultato.

Cadenza di ingestione consigliata

I nuovi set di dati vengono pubblicati in modo incrementale nel corso della giornata.

raccomandazione	Dettagli
Cadenza consigliata	Da 1 a 4 volte al giorno per rimanere aggiornati.
Strategia incrementale	Imposta startDateTime sull’ultimo timestamp recuperato e endDateTime sull’ora corrente. Scarica ed elabora tutti i file restituiti, quindi UNISCI.
Consumatori giornalieri/settimanali	Se esegui il recupero giornalmente o settimanalmente, elabora tutti i file relativi al periodo. In questo modo non perderai aggiornamenti o eliminazioni.

Nota: ogni batch mescola righe attive (is_deleted = 0) e righe non più attive (is_deleted = 1). Non vengono consegnate in file separati. La colonna is_deleted li distingue.

Esempio di utilizzo dell’API

Segui questi passaggi per scoprire il tuo account, identificare il gruppo di report e gli identificatori e recuperare i file del set di dati.

Passaggio 0: Elenca i tuoi account
Chiama GET /v2/accounts per elencare gli account Slate a cui puoi accedere.

Fase 1: Linee di business per l’account
Chiama GET /v2/accounts/1234567 8 per vedere le linee di business disponibili.

Il campo id è il segmento di percorso {REPORT_GROUP} da utilizzare nelle chiamate successive.

Fase 2a: Gli identificatori dei canali chiamano GET
/v2/accounts/12345678/channels? offset=0&limit=100 per elencare gli identificatori dei canali.

Fase 2b: Gli identificatori FAST
chiamano GET /v2/accounts/12345678/fast? offset=0&limit=100 per elencare i tuoi identificatori FAST.

Fase 2c: Set di dati disponibili per un Identifier
Call GET /v2/accounts/12345678/fast/abc123/datasets per elencare i set di dati disponibili.

Fase 3a: File del set di dati dei canali
Richiama l’endpoint dei file del set di dati per l’identificatore dei canali. La risposta restituisce un elenco di URL di download per file CSV compressi con gzip.

Fase 3b: File del set di dati FAST
Richiama l’endpoint dei file del set di dati per il tuo identificatore FAST.

Domande di esempio

Queste interrogazioni presuppongono che tu abbia già unito i tuoi dati. Se conservi le righe is_deleted in una tabella non elaborata, aggiungi WHERE is_deleted = 0 a ciascuna query.

Ore visualizzate dalla stazione in un periodo

I 10 migliori programmi per ore di visualizzazione

Riepilogo delle visualizzazioni giornaliere

Ore visualizzate per Territorio

Pipeline ETL

Usa questo modello in quattro fasi per creare la tua pipeline ETL per il set di dati del Programma Live Linear.

Estrazione iniziale dei dati. Recupera tutti i file del tuo canale entro l’intervallo di tempo desiderato utilizzando l’endpoint API. Scarica tutti i file restituiti. Ciascuno contiene righe in formato CSV compresso con gzip.
Deduplica. Se esistono più record per lo stesso session_program_schedule_id tra i file che hai estratto, mantieni solo la riga con l’ultimo last_update_time_utc. Vedi la sezione Deduplicazione per il pattern SQL completo.
Applica alla destinazione. UNISCI i record deduplicati nella tabella di destinazione digitata su session_program_schedule_i d. Cancella su is_deleted = 0. Su is_deleted = 1, fai in modo che l’ID smetta di apparire nei tuoi dati correnti. Eliminalo definitivamente oppure mantieni la riga contrassegnata e filtrala.
Elaborazione incrementale. Per i carichi continui, imposta l’ultima volta che hai effettuato l’estrazione e EndDateTime sull’ora corrente. Elabora tutti i file restituiti e UNISCILI nella tua destinazione.

Suggerimenti rapidi

Tieni a mente questi suggerimenti quando integri l’API nella tua pipeline.

session_program_schedule_id è la tua chiave unica. Effettua sempre la deduplicazione utilizzando last_update_time_utc.
Usa un MERGE, non un inserto collettivo. Agisci sui segnali is_deleted ogni volta che carichi dati.
Esegui da 1 a 4 volte al giorno per avere dati sempre aggiornati.
Imposta startDateTime sull’ultimo timestamp di pull riuscito per i carichi incrementali.
Usa gli endpoint di rilevamento per trovare il tuo account, gli identificatori e i set di dati disponibili.
Utilizza entrambi i canali e i feed FAST se la tua partnership copre entrambi.
Aggiungi WHERE is_deleted = 0 a tutte le query se utilizzi l’approccio soft-delete.
La conservazione massima dei dati è di 2 anni. Pianifica di conseguenza i tuoi tiri storici.

Lo sapevate?

L’accesso programmatico ai dati di visualizzazione a livello di programma consente di creare report personalizzati, alimentare i sistemi di pianificazione e combinare dati lineari con altri dati aziendali. I partner che integrano questa API nei loro flussi di lavoro prendono decisioni più rapide e informate sulla programmazione e l’acquisizione di contenuti.

Per analisi visive e approfondimenti rapidi, visita la dashboard di programmazione lineare su Slate Analytics.

API Live Linear Program Dataset