Questa guida illustra tutto ciò che serve per accedere all’API Set di dati dei programmi lineari live e utilizzarla
Cosa imparerai |
|
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:
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: 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:
- 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.
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;
- Esegui il MERGE delle righe deduplicate nella tabella. Utilizza il modello MERGE riportato di seguito. Gestisci is_deleted ogni volta che carichi i dati.
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);
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. |
- 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.{
"total": 1,
"next": null,
"data": [
{ "id": "12345678", "name": "MGM" }
]
}
Passaggio 1: linee di business dell’account
Chiama GET /v2/accounts/12345678 per visualizzare le linee di business disponibili.{
"total": 2,
"next": null,
"data": [
{ "id": "channels", "name": "Channels" },
{ "id": "fast", "name": "FAST" }
]
}
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.{
"total": 2,
"next": null,
"data": [
{ "id": "3f6c1b9d-8a2d-4e7f-9c31-0d5b7b2e6f14", "name": "MGM+" },
{ "id": "a91d4c21-57e0-4b8a-b6f3-2e9c0e1f8b77", "name": "MGM+ Espanol" }
]
}
Passaggio 2b: identificatori FAST
Chiama GET /v2/accounts/12345678/fast?offset=0&limit=100 per elencare gli identificatori FAST.{
"total": 1,
"next": null,
"data": [
{ "id": "ABC123", "name": "MGM 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.{
"total": 1,
"next": null,
"data": [
{ "id": "fast_linear_program_event_log", "name": "FAST Linear Program Event Log" }
]
}
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.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?..." }
]
}
Passaggio 3b: file del set di dati FAST
Chiama l’endpoint dei file del set di dati per il tuo identificatore 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=..." }
]
}
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 periodoSELECT 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;
I primi X programmi per ore di visualizzazioneSELECT 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];
Riepilogo giornaliero delle visualizzazioniSELECT 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;
Ore di visualizzazione per 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;
Pipeline ETL
Segui questo schema in quattro passaggi per creare la pipeline ETL del Set di dati dei programmi lineari live.
- 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.
- 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.
- 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.
- 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.
startDateTime = {last_successful_pull_timestamp}
endDateTime = {current_utc_timestamp}
Suggerimenti rapidi
Tieni presenti queste raccomandazioni quando integri l’API nella tua pipeline.
- session_program_schedule_id è la chiave univoca. Esegui sempre la deduplicazione utilizzando last_update_time_utc.
- Utilizza MERGE, non un inserimento in blocco. Gestisci gli indicatori is_deleted a ogni caricamento.
- Estrai i dati da 1 a 4 volte al giorno per mantenerli aggiornati.
- Per i caricamenti incrementali, imposta startDateTime sul timestamp dell’ultima estrazione completata correttamente.
- Utilizza gli endpoint di individuazione per trovare il tuo account, gli identificatori e i set di dati disponibili.
- Recupera sia il feed Canali sia il feed FAST, se la tua partnership comprende entrambi.
- Se utilizzi l’approccio soft delete, aggiungi WHERE is_deleted = 0 a tutte le query.
- 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. |