API Set di dati dei programmi lineari live

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

~15 min di lettura ottobre 2, 2026

Questa guida illustra tutto ciò che serve per accedere all’API Set di dati dei programmi lineari live e utilizzarla

Cosa imparerai

  • I dati forniti dall’API e i feed disponibili.
  • Le modalità di autenticazione e recupero dei file dei set di dati.
  • Il modello dati completo e le definizioni delle colonne.
  • Il funzionamento del changelog e dell’indicatore is_deleted.
  • I modelli di deduplicazione e MERGE che puoi integrare nella tua pipeline.
  • La frequenza di acquisizione consigliata.
  • Query SQL di esempio per le analisi più comuni.

Panoramica

L’API Set di dati dei programmi lineari live fornisce dati di visualizzazione a livello di programma per i canali live lineari e FAST di Prime Video. Ogni record rappresenta una sessione di visualizzazione di un singolo programma programmato su un determinato canale.

I dati vengono forniti sotto forma di changelog, con indicatori is_deleted per gestire le correzioni della programmazione. Sono disponibili due feed: canali (linear_program_event_log) e FAST (fast_linear_program_event_log).

Questi dati consentono di:

  • Monitorare le visualizzazioni a livello di programma (ore visualizzate, sessioni) tra stazioni, territori, dispositivi e intervalli temporali.
  • Analizzare le performance per stazione, programma, serie e tipo di contenuto.
  • Tenere traccia in modo accurato delle correzioni alla programmazione, senza righe obsolete nei dati.
  • Integrare le visualizzazioni live lineari con i tuoi sistemi interni e le tue fonti di dati.

Per l’analisi tramite dashboard, consulta: Programmazione lineare su Slate Analytics

Caratteristiche principali

Funzionalità

Dettagli

Dettaglio a livello di programma

Una riga per ogni sessione di visualizzazione, programma e programmazione. Include titolo, stazione, serie, intervallo di trasmissione e tempo di visualizzazione.

Indicatore di rimozione

Le programmazioni sostituite o ritirate vengono inviate nuovamente con is_deleted = 1, a indicare che non sono più valide.

Chiave univoca stabile

Ogni riga contiene session_program_schedule_id. Utilizzalo per deduplicare i dati ed eseguire operazioni MERGE.

Acquisizione semplificata

Modello basato su changelog. Pianifica chiamate ricorrenti, quindi esegui operazioni MERGE. Esegui l’operazione di inserimento o aggiornamento (upsert) quando is_deleted = 0. Elimina fisicamente o contrassegna come eliminata la riga (hard delete o soft delete) quando is_deleted = 1.

Coerenza

Formattazione standardizzata per tutti i territori in un’unica fonte. Non sono necessarie tabelle dimensionali separate per ciascun territorio.

Concetti chiave

Concetto

Descrizione

Riga sessione-programma-programmazione

Una sessione di visualizzazione di un programma in uno specifico intervallo di programmazione. È identificata da session_program_schedule_id.

Modello basato su changelog

I dati vengono forniti sotto forma di changelog. Se gli attributi di una riga cambiano, viene pubblicata una nuova versione con lo stesso session_program_schedule_id e un valore più recente di last_update_time_utc.

Chiave primaria

session_program_schedule_id è l’identificatore univoco. Esegui sempre la deduplicazione utilizzando questo campo.

is_deleted signal

is_deleted = 0 significa che la programmazione è attiva. is_deleted = 1 significa che la programmazione non è più attiva o valida.

Applicazione dell’indicatore

is_deleted = 0: inserisci la riga o aggiorna quella esistente. is_deleted = 1: fai in modo che la riga non compaia più nei dati correnti. Puoi eliminare la riga oppure mantenerla contrassegnata come eliminata ed escluderla tramite un filtro.

Guida introduttiva

Come effettuare l’onboarding
L’API Set di dati dei programmi lineari live fa parte della Analytics API Suite. Quando completi l’onboarding alla Analytics API Suite, ottieni l’accesso a tutte le API disponibili all’interno della suite, inclusa l’API Set di dati dei programmi lineari live, se richiesta durante la procedura di onboarding. Per istruzioni dettagliate sull’onboarding, consulta la pagina Analytics API Onboarding.

Prerequisiti
Prima di effettuare richieste API, devi disporre di quanto segue:

  • Un accesso con il profilo di sicurezza Amazon (LWA). Il tuo Client ID, da inviare al tuo CAM affinché venga aggiunto alla PV Internal Admin Page.
  • Un codice di autorizzazione per richiedere un token.
  • Un token da utilizzare per tutte le richieste API.

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

Tutte le richieste devono includere un token di autenticazione LWA valido nell’intestazione di autorizzazione. Se il token manca o è scaduto, l’API restituisce un’eccezione di accesso non autorizzato.

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

Parametro

Default

Descrizione

limit

10

Numero di documenti restituiti per pagina. Massimo 1.000.

offset

0

Numero di documenti da saltare prima del primo risultato. Segui l’URL successivo anziché calcolarlo autonomamente.

Tutte le risposte impaginate includono i seguenti campi:

Campo

Descrizione

total

Numero totale di documenti su tutte le pagine.

next

L’URL della pagina successiva. Null se questa è l’ultima pagina.

Recupero dei file del set di dati

Endpoint
Utilizza il seguente comando curl per recuperare un elenco di link ai file dei set di dati scaricabili:


Nota: Questo endpoint restituisce link a file CSV compressi in formato gzip da scaricare, non direttamente le righe dei dati.

Parametri

Parametro

Descrizione

ACADIA_ID

L’ID del tuo account Slate. Trovalo su /v2/accounts.

REPORT_GROUP

Segmento della linea di business. Usa channels per il feed Canali o fast per il feed FAST. Puoi individuare il tuo segmento tramite GET /v2/accounts/{ACADIA_ID}.

IDENTIFIER_ID

Utilizza il valore id restituito dagli identificatori dell’endpoint. Per i Canali è un hash opaco. Utilizza il campo id esattamente come restituito. Per FAST corrisponde al codice del fornitore (vendor code), restituito senza hashing.

REPORT_ID

Indica quale report recuperare. Usa linear_program_event_log per i Canali o fast_linear_program_event_log per FAST.

startDateTime

Impostato sull’ultima volta che hai estratto. Formato: AAAA-MM-GGThh:mm:ssZ (UTC).

endDateTime

Impostato sull’ora corrente. Formato: AAAA-MM-GGThh:mm:ssZ (UTC).

limit

Minimo 1, massimo 1.000 link per pagina.

Report disponibili
Sono disponibili due report. Recupera ciascun report separatamente, inserendo il relativo ID nel segmento del percorso datasets/{REPORT_ID}:

Report

ID del report

Contenuti

Canali

linear_program_event_log

Feed per la programmazione lineare SVOD/in abbonamento (3P_SUBS e FREE/PRIME, ove applicabile).

FAST

fast_linear_program_event_log

Feed per i canali televisivi lineari gratuiti supportati da pubblicità (FAST/AVOD)

Nota: Il periodo massimo di conservazione dei dati è di 2 anni. Le richieste relative a periodi antecedenti agli ultimi 2 anni non restituiscono risultati.

Endpoint di individuazione

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

Endpoint

Restituisce

GET /v2/accounts

Elenco degli account Slate a cui puoi accedere.

GET /v2/accounts/{ACADIA_ID}

Linee di business disponibili, ad esempio canali e fast.

GET /v2/accounts/{ACADIA_ID}/channels

Identificatori dei report disponibili per il tuo account. Ogni voce contiene un ID e un nome descrittivo.

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

Set di dati disponibili per quell’identificatore.

Colonne dei dati

Le seguenti colonne sono presenti nel feed linear_program_event_log (Canali). Il feed fast_linear_program_event_log (FAST) presenta la stessa struttura, con l’aggiunta di vendor_code; le colonne relative agli abbonamenti vengono valorizzate con NULL.

Colonna

Tipo

Nullable

Descrizione

session_program_schedule_id

STRING

No

Chiave primaria. ID univoco che codifica la sessione, il programma e l’intervallo di trasmissione. Esegui la deduplicazione e le operazioni MERGE utilizzando questo campo. Il valore cambia quando il programma o l’orario di trasmissione vengono modificati a seguito di aggiornamenti dei metadati EPG.

session_id

STRING

No

Identificatore univoco anonimizzato della sessione di visualizzazione.

is_deleted

INT

No

Indicatore di stato. 0 = programmazione attiva. 1 = programmazione non più attiva (sostituita o ritirata). Escludi le righe con is_deleted = 1 dai dati correnti.

last_update_time_utc

TIMESTAMP

No

Data e ora della versione del record. Usale sempre per la deduplicazione. Per ogni ID, conserva la riga con il valore più recente.

create_time_utc

TIMESTAMP

No

Data e ora della prima creazione della riga.

program_id

STRING

No

Identificatore del programma, ad esempio un ID TMS.

pv_title_id

STRING

Sì

Identificatore globale del titolo Prime Video (GTI) associato al programma. Corrisponde al campo pv_title_id presente nel feed TVOD.

program_title

STRING

Sì

Titolo del programma.

station_name

STRING

Sì

Nome del canale o della stazione.

content_type

STRING

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).

seconds_viewed

LONG

No

Secondi visualizzati in questa sessione.

vendor_sku

STRING

Sì

SKU del contenuto (ad esempio, identificatori Gracenote).

parent_channel_label

STRING

Sì

Identificatore del canale principale sottoposto ad hashing.

cid

STRING

Sì

ID del canale (effettivo).

benefit_id

STRING

Sì

Identificatore del diritto o beneficio.

subscription_offer_id

STRING

Sì

Identificatore dell’offerta di abbonamento.

subscription_event_id

STRING

Sì

Identificatore dell’evento di abbonamento.

subscription_offer_time_zone

STRING

Sì

Fuso orario dell’offerta di abbonamento.

marketplace_id

INT

No

Identificatore del marketplace.

marketplace_desc

STRING

Sì

Descrizione del marketplace.

territory

STRING

Sì

Codice del territorio o del Paese (US, GB, DE, AU e altri).

device_class

STRING

Sì

Categoria del dispositivo.

device_sub_class

STRING

Sì

Sottocategoria del dispositivo.

connection_type

STRING

Sì

Tipo di connessione (wifi, cablata e altre).

playback_method

STRING

Sì

Modalità di fruizione della sessione: online (streaming) o offline (download). La visione dei canali live lineari avviene, di fatto, sempre online.

geo_dma

STRING

Sì

Area geografica DMA.

stream_type

STRING

No

Sempre LINEAR_TV.

Nota sul feed FAST: Il feed fast_linear_program_event_log presenta la stessa struttura. È presente la colonna vendor_code (codice del partner). Le colonne relative agli abbonamenti (subscription_offer_id, subscription_event_id, subscription_offer_time_zone) vengono restituite con valore NULL.

Comprendere is_deleted

Ogni riga contiene il campo is_deleted. Si tratta di un indicatore dello stato della programmazione. Esistono due valori:

Valore

Significato

Come applicarlo

0

Programmazione attiva (versione corrente).

Inserisci la riga oppure sovrascrivi quella esistente per questa chiave.

1

Programmazione non più attiva (sostituita o ritirata).

Fai in modo che non compaia più nei dati correnti. Puoi eliminare la riga oppure mantenerla contrassegnata come eliminata ed escluderla tramite un filtro.

Quando si verifica is_deleted = 1?

  • Correzione della programmazione. Il programma o l’orario di trasmissione è stato corretto. Il vecchio session_program_schedule_id viene restituito con is_deleted = 1. Viene restituito un nuovo ID con is_deleted = 0. Contrassegna il vecchio ID come non più attivo e inserisci quello nuovo.
  • Rimozione di una trasmissione. La trasmissione è stata completamente ritirata. Il relativo ID viene restituito con is_deleted = 1.

Note importanti

  • Un determinato session_program_schedule_id non presenta mai contemporaneamente i valori 0 e 1 nello stesso batch. Una trasmissione corretta viene associata a una chiave diversa.
  • Le righe che non hanno mai soddisfatto i criteri di idoneità del feed non vengono fornite. Non aspettarti di ricevere is_deleted = 1 per una riga che non hai mai ricevuto.

Deduplicazione

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

  1. Conserva la versione più recente di ogni ID. Per ciascun ID, conserva soltanto la riga con il valore più recente di last_update_time_utc ed elimina quelle precedenti. Questo valore procede sempre in avanti, quindi prevale sempre la versione più recente.


  1. Esegui il MERGE delle righe deduplicate nella tabella. Utilizza il modello MERGE riportato di seguito. Gestisci is_deleted ogni volta che carichi i dati.

Utilizza MERGE, non un inserimento in blocco. Se carichi ogni file come un insieme di nuove righe, quelle con is_deleted = 1 rimarranno nella tabella come dati attivi, invece di essere gestite correttamente. Applica sempre l’indicatore di stato.

  1. Alternativa: eliminazione logica (soft delete). Sostituisci il ramo DELETE con UPDATE SET is_deleted = 1, quindi aggiungi WHERE is_deleted = 0 alle query. Entrambi i metodi producono lo stesso risultato.

Frequenza di acquisizione consigliata

I nuovi set di dati vengono pubblicati in modo incrementale durante la giornata.

Raccomandazione

Dettagli

Frequenza consigliata

Da 1 a 4 volte al giorno, per mantenere i dati aggiornati.

Strategia incrementale

Imposta startDateTime sull’ultimo timestamp recuperato ed endDateTime sull’ora corrente. Scarica ed elabora tutti i file restituiti, quindi esegui il MERGE.

Elaborazioni giornaliere o settimanali

Se recuperi i dati su base giornaliera o settimanale, elabora tutti i file relativi al periodo. In questo modo eviti di perdere aggiornamenti o eliminazioni.

Nota: ogni batch contiene sia righe attive (is_deleted = 0) sia righe non più attive (is_deleted = 1). Non vengono distribuite in file separati. È la colonna is_deleted a distinguerle.

Esempio di utilizzo dell’API

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

Passaggio 0: elenco degli account
Chiama GET /v2/accounts per elencare gli account Slate a cui puoi accedere.

Passaggio 1: linee di business dell’account
Chiama GET /v2/accounts/12345678 per visualizzare le linee di business disponibili.

Il campo id contiene il segmento del percorso {REPORT_GROUP} da utilizzare nelle chiamate successive.

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

Passaggio 2b: identificatori FAST
Chiama GET /v2/accounts/12345678/fast?offset=0&limit=100 per elencare gli identificatori FAST.

Passaggio 2c: set di dati disponibili per un identificatore
Chiama GET /v2/accounts/12345678/fast/ABC123/datasets per elencare i set di dati disponibili.

Passaggio 3a: file del set di dati dei canali
Chiama l’endpoint dei file del set di dati per il tuo identificatore Canali. La risposta restituisce un elenco di URL per scaricare file CSV compressi in formato gzip.

Passaggio 3b: file del set di dati FAST
Chiama l’endpoint dei file del set di dati per il tuo identificatore FAST.

Query di esempio

Queste query presuppongono che tu abbia già eseguito il MERGE dei dati. Se conservi le righe con is_deleted in una tabella grezza, aggiungi WHERE is_deleted = 0 a ogni query.

Ore di visualizzazione per stazione in un determinato periodo

I primi X programmi per ore di visualizzazione

Riepilogo giornaliero delle visualizzazioni

Ore di visualizzazione per territorio

Pipeline ETL

Segui questo schema in quattro passaggi per creare la pipeline ETL del Set di dati dei programmi lineari live.

  1. Estrazione iniziale dei dati. Estrai tutti i file relativi al tuo canale nell’intervallo di tempo desiderato, utilizzando l’endpoint API. Scarica tutti i file restituiti. Ogni file contiene righe in formato CSV compresso con gzip.
  2. Deduplicazione. Quando più record con lo stesso session_program_schedule_id sono presenti nei file recuperati, conserva soltanto la riga con il valore più recente di last_update_time_utc. Per il modello SQL completo, consulta la sezione dedicata alla deduplicazione.
  3. Applicazione alla tabella di destinazione. Esegui il MERGE dei record deduplicati nella tabella di destinazione, utilizzando session_program_schedule_id come chiave. Esegui l’operazione di inserimento o aggiornamento (upsert) quando is_deleted = 0. Quando is_deleted = 1, fai in modo che l’ID non compaia più nei dati correnti. Puoi eliminarlo fisicamente oppure mantenerlo contrassegnato come eliminato ed escluderlo tramite un filtro.
  4. Elaborazione incrementale. Per i caricamenti successivi, imposta startDateTime sull’ora dell’ultima estrazione e endDateTime sull’ora corrente. Elabora tutti i file restituiti ed esegui il MERGE nella tabella di destinazione.


Suggerimenti rapidi

Tieni presenti queste raccomandazioni quando integri l’API nella tua pipeline.

  1. session_program_schedule_id è la chiave univoca. Esegui sempre la deduplicazione utilizzando last_update_time_utc.
  2. Utilizza MERGE, non un inserimento in blocco. Gestisci gli indicatori is_deleted a ogni caricamento.
  3. Estrai i dati da 1 a 4 volte al giorno per mantenerli aggiornati.
  4. Per i caricamenti incrementali, imposta startDateTime sul timestamp dell’ultima estrazione completata correttamente.
  5. Utilizza gli endpoint di individuazione per trovare il tuo account, gli identificatori e i set di dati disponibili.
  6. Recupera sia il feed Canali sia il feed FAST, se la tua partnership comprende entrambi.
  7. Se utilizzi l’approccio soft delete, aggiungi WHERE is_deleted = 0 a tutte le query.
  8. Il periodo massimo di conservazione dei dati è di 2 anni. Pianifica di conseguenza i recuperi dei dati storici.

Lo sapevi?

L’accesso programmatico ai dati di visualizzazione a livello di programma consente di creare report personalizzati, alimentare i sistemi di pianificazione e combinare i dati dei canali lineari con altre informazioni aziendali. I partner che integrano questa API nei propri flussi di lavoro possono prendere decisioni più rapide e consapevoli in materia di programmazione e acquisizione dei contenuti.

Per analisi visive e approfondimenti immediati, visita la dashboard Programmazione lineare su Slate Analytics.

Domande frequenti

Domande frequenti sull’API Live Linear Program Dataset

Hai ancora bisogno di aiuto?

Contattaci

In questa guida



Errore interno del server. Riprova tra qualche istante.
La tua sessione è scaduta

Accedi per continuare

Accedi
edit