Video Central

Aperçu

L’API Live Linear Program Dataset fournit des données d’audience détaillées pour vos chaînes Prime Video Live Linear et FAST. Chaque enregistrement représente une session de visionnage d’un programme programmé sur une chaîne.

Les données sont fournies sous forme de journal des modifications avec des signaux is_deleted pour les corrections de planification. Deux flux sont disponibles : Channels (linear_program_event_log) et FAST (fast_linear_program_event_log).

Ces données vous permettent de :

Suivez le nombre de spectateurs au niveau des programmes (heures visionnées, sessions) par station, par territoire, par appareil et par heure.
Analysez les performances par station, programme, série et type de contenu.
Suivez les corrections du calendrier avec précision, sans aucune ligne périmée dans vos données.
Intégrez le visionnage linéaire en direct à vos systèmes internes et à vos sources de données.

Pour une analyse basée sur un tableau de bord, voir : Programmation linéaire sur Slate Analytics

Caractéristiques principales

Fonctionnalité	Détails
Détails du grain du programme	Une ligne par session de visionnage, programme et calendrier. Comprend le titre, la station, la série, la fenêtre de diffusion et l’heure de visionnage.
Signal de retrait	Les programmes remplacés ou retirés sont renvoyés avec is_deleted = 1, ce qui indique qu’ils ne sont plus valides.
Clé unique stable	Chaque ligne porte le nom de session_program_schedule_id. Utilisez-le pour dédupliquer et FUSIONNER.
Ingestion simplifiée	Modèle de journal des modifications. Planifier des appels récurrents, puis FUSIONNER. Upsert sur is_deleted = 0. Suppression définitive ou logicielle sur is_deleted = 1.
Cohérence	Formatage standardisé sur tous les territoires dans une source unique. Aucun tableau dimensionnel par territoire n’est nécessaire.

Concepts clés

Concept	Description
Ligne du programme des sessions et du calendrier	Une session de visionnage d’un programme dans un créneau programmé. Identifié par session_program_schedule_id.
Modèle de journal des modifications	Les données sont un journal des modifications. Si les attributs d’une ligne changent, une nouvelle version est publiée avec le même session_program_schedule_id et un last_update_time_utc plus récent.
Clé primaire	session_program_schedule_id est l’identifiant unique. Dédupliquez toujours dans ce champ.
signal is_supprimé	is_deleted = 0 signifie que le planning est actif. is_deleted = 1 indique que le planning n’est plus actif ou n’est plus valide.
Appliquer le signal	is_deleted = 0 : insérez ou mettez à jour la ligne. is_deleted = 1 : faites en sorte qu’il n’apparaisse plus dans vos données actuelles. Supprimez la ligne ou gardez-la marquée et filtrez-la.

Commencer

Comment intégrer
L’API Live Linear Program Dataset fait partie de la suite d’API Analytics. Lorsque vous intégrez la suite d’API Analytics, vous aurez accès à toutes les API disponibles dans cette suite, y compris l’API Live Linear Program Dataset (si demandé lors de l’intégration). Pour obtenir des instructions d’intégration détaillées, consultez la page d’intégration de l’API Analytics.

Conditions préalables
Vous devez disposer des éléments suivants avant de faire des demandes d’API :

Un profil de sécurité de connexion avec Amazon (LWA). Envoyez votre ID client à votre CAM pour qu’il soit ajouté à la page d’administration interne de PV.
Code d’autorisation pour demander un jeton.
Un jeton pour toutes les demandes d’API.

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

Tous/Toutes les demandes doivent inclure un jeton d’authentification LWA valide dans l’en-tête d’autorisation. Si le jeton est manquant ou a expiré, l’API renvoie une exception non autorisée.

Pagination
Toutes les réponses sont paginées. Utilisez les paramètres suivants pour naviguer dans les pages :

Paramètre	Par défaut	Description
limite	10	Number de documents renvoyés par page. 1 000 au maximum.
décalage	0	Nombre de documents à ignorer avant le premier résultat. Suivez l’URL suivante au lieu de la calculer vous-même.

Tous/Toutes les réponses paginées incluent les champs suivants :

Champ	Description
total	Nombre total de documents sur toutes les pages.
suivant	URL de la page suivante. Null s’il s’agit de la dernière page.

Récupération de fichiers d’ensembles de données

Endpoint
Utilisez cette commande curl pour récupérer une liste de liens vers des fichiers de jeux de données téléchargeables :

Remarque : Ce point de terminaison renvoie des liens vers des fichiers CSV compressés au format gzip téléchargeables, et non directement vers les lignes.

Paramètres

Paramètre	Description
ACADIA_ID	L’identifiant de votre compte Slate. Trouvez-le sur /v2/accounts.
GROUPE_DE RAPPORTS	Le segment du secteur d’activité. Utilisez des canaux pour le flux Channels ou fast pour le flux FAST. Découvrez le vôtre avec GET /v2/accounts/ {ACADIA_ID}.
IDENTIFIANT_ID	La valeur d’identifiant renvoyée par le point de terminaison des identifiants. Pour les canaux, il s’agit d’un hachage opaque. Utilisez le champ id tel qu’il est indiqué. Pour FAST, il s’agit de votre code fournisseur, renvoyé sans hachage.
IDENTIFIANT_RAPPORT	Quel rapport extraire. Utilisez linear_program_event_log pour Channels ou fast_linear_program_event_log pour FAST.
Date/heure de début	Réglez sur la dernière fois que vous avez tiré. Format : YYYY-MM-DDTHH:MM:SSZ (UTC).
Date/heure de fin	Réglé à l’heure actuelle. Format : YYYY-MM-DDTHH:MM:SSZ (UTC).
limite	Minimum 1, maximum 1 000 liens par page.

Rapports disponibles
Deux rapports sont disponibles. Extrayez chacun séparément en insérant son ID de rapport dans le segment de chemin datasets/ {REPORT_ID} :

Rapport	ID du rapport	Contenus
Canaux	journal des événements du programme linéaire	SVOD/abonnement linéaire (3P_SUBS et FREE/PRIME le cas échéant).
RAPIDE	journal des événements du programme fast_linear_log	Télévision financée par la publicité gratuite/chaînes linéaires financées par la publicité (AVOD)

Remarque : La durée maximale de conservation des données est de 2 ans. Les demandes datant de plus de 2 ans ne donneront aucun résultat.

Points de terminaison de découverte

Utilisez ces points de terminaison pour trouver votre identifiant de compte, les groupes de rapports, les identifiants et les ensembles de données disponibles :

Point final	Retours
GET /v2/comptes	Liste des comptes Slate auxquels vous pouvez accéder.
OBTENEZ /v2/accounts/ {ACADIA_ID}	Secteurs d’activité disponibles (par exemple, canaux, fast).
GET /v2/accounts/ {ACADIA_ID} /channels	Identifiants de rapport mis à votre disposition. Chaque entrée possède un identifiant et un nom convivial.
GET /v2/accounts/ {ACADIA_ID} /channels/ {IDENTIFIER_ID} /ensembles de données	Ensembles de données disponibles pour cet identifiant.

Colonnes de données

Les colonnes suivantes sont présentes dans le flux linear_program_event_log (Channels). Le flux fast_linear_program_event_log (FAST) a la même forme, avec l’ajout de vendor_code et les colonnes d’abonnement livrées sous la forme NULL.

Colonne	Type	Nullable	Description
ID du planificateur_du programme de session	CHAÎNE	Non	Clé primaire. ID unique (code la session, le programme et la fenêtre de diffusion). Dédupliquez et fusionnez sur ce champ. Modifie lorsque le programme ou l’heure de diffusion changent en raison de la mise à jour des métadonnées EPG.
identifiant_session	CHAÎNE	Non	Identifiant de session de visionnage unique anonymisé.
est supprimé	INT	Non	Signal de statut. 0 = le programme est actif. 1 = le calendrier n’est plus actif (remplacé ou retiré). Excluez is_deleted = 1 ligne de vos données actuelles.
heure_dernière_mise à jour_utc	HORODATAGE	Non	Enregistrez l’heure de la version. Utilisez toujours pour dédupliquer. Conservez la ligne contenant la valeur la plus récente pour un ID donné.
créer_heure_utc	HORODATAGE	Non	Quand la ligne a été créée pour la première fois.
identifiant_programme	CHAÎNE	Non	Identifiant du programme, par exemple TMS ID.
pv_title_id	CHAÎNE	Oui	Prime Video Global Title Identifier (GTI) pour le programme. Identique à pv_title_id dans le flux TVOD.
titre_programme	CHAÎNE	Oui	Titre du programme.
nom_station	CHAÎNE	Oui	Nom de la chaîne ou de la station.
type_contenu	CHAÎNE	Non	live_broadcast ou scheduled_tv.
airing_start_utc	HORODATAGE	Non	Début de diffusion du programme (UTC).
airing_end_utc	HORODATAGE	Non	Fin de diffusion du programme (UTC).
start_segment_utc	HORODATAGE	Non	Début de session de visualisation (UTC).
end_segment_utc	HORODATAGE	Non	Fin de session de visionnage (UTC).
secondes vues	LONGUE	Non	Secondes visionnées au cours de cette session.
vendor_sku	CHAÎNE	Oui	SKU du contenu (par exemple, les identifiants Gracenote).
parent_channel_label	CHAÎNE	Oui	Identifiant de canal parent haché.
cid	CHAÎNE	Oui	ID de chaîne (effectif).
identifiant d’avantage	CHAÎNE	Oui	Identifiant des droits ou des avantages.
identifiant de l’offre_d’abonnement	CHAÎNE	Oui	Identifiant de l’offre d’abonnement.
identifiant_événement_abonnement	CHAÎNE	Oui	Identifiant de l’événement d’abonnement.
fuseau horaire de l’offre_d’abonnement	CHAÎNE	Oui	Fuseau horaire de l’offre d’abonnement.
identifiant du marché	INT	Non	Identifiant du marché.
marketplace_desc	CHAÎNE	Oui	Description de la place de marché.
territoire	CHAÎNE	Oui	Territoire ou code de pays (US, GB, DE, AU, etc.)
classe_appareil	CHAÎNE	Oui	Catégorie d’appareil.
sous-classe_appareil	CHAÎNE	Oui	Sous-catégorie d’appareils.
type_de connexion	CHAÎNE	Oui	Type de connexion (wifi, filaire et autres).
méthode de lecture	CHAÎNE	Oui	Mode de consommation de la session : en ligne (streaming) ou hors ligne (téléchargement). Live Linear est effectivement toujours en ligne.
geo_dma	CHAÎNE	Oui	DMA géographique.
type_flux	CHAÎNE	Non	Toujours LINEAR_TV.

Remarque relative au flux FAST : Le flux fast_linear_program_event_log a la même forme. La colonne vendor_code (code partenaire) est présente. Les colonnes d’abonnement (subscription_offer_id, subscription_event_id, subscription_offer_time_zone) sont fournies sous la forme NULL.

Comprendre is_deleted

Chaque ligne porte le nom is_deleted. Il s’agit d’un signal concernant l’état du calendrier. Il existe deux valeurs :

Value	Signification	Comment l’appliquer
0	Planifier est actif (version actuelle).	Insérez-la ou remplacez la ligne existante pour cette clé.
1	Planifier n’est plus actif (remplacé ou retiré).	Faites en sorte qu’il n’apparaisse plus dans vos données actuelles. Supprimez la ligne ou gardez-la marquée et filtrez-la.

Quand se produit is_deleted = 1 ?

Planifier la correction. Le programme ou l’heure de diffusion ont été corrigés. L’ancien session_program_schedule_id arrive sous la forme is_deleted = 1. Un nouvel ID arrive sous la forme is_deleted = 0. Appliquez l’ancien comme n’étant plus actif et insérez le nouveau.
Aération supprimée. La diffusion a été complètement interrompue. Son ID arrive sous la forme is_deleted = 1.

Remarques importantes

Un session_program_schedule_id donné ne vaut jamais à la fois 0 et 1 dans le même lot. Une aération corrigée devient une clé différente.
Les lignes qui ne répondent jamais aux critères d’éligibilité du fil ne sont pas livrées. Ne vous attendez pas à un is_deleted = 1 pour une ligne que vous n’avez jamais reçue.

Déduplication

Vous pouvez recevoir le même session_program_schedule_id plusieurs fois. Il s’agit de versions mises à jour de la même ligne. Gérez la déduplication en trois étapes :

Conservez la dernière version de chaque identifiant. Pour chaque ID, ne conservez que la ligne contenant le dernier last_update_time_utc et supprimez les plus anciennes. Cette valeur ne fait qu’avancer, donc la dernière l’emporte toujours.

FUSIONNEZ les lignes dédupliquées dans votre tableau. Utilisez le modèle MERGE ci-dessous. Agissez sur is_deleted chaque fois que vous chargez des données.

Utilisez un MERGE, pas un insert groupé. Si vous chargez chaque fichier sous forme de nouvelles lignes, les lignes is_deleted = 1 figurent dans votre table en tant que données actives au lieu d’être appliquées. Agissez toujours en fonction du drapeau.

Alternative à suppression douce. Remplacez la branche DELETE par UPDATE SET is_deleted = 1, puis filtrez WHERE is_deleted = 0 dans vos requêtes. Les deux méthodes donnent le même résultat.

Cadence d’ingestion recommandée

Les nouveaux ensembles de données sont publiés progressivement tout au long de la journée.

Recommandation	Détails
Cadence recommandée	1 à 4 fois par jour pour rester au courant.
Stratégie progressive	Définissez StartDateTime sur le dernier horodatage récupéré et EndDateTime sur l’heure actuelle. Téléchargez et traitez tous les fichiers renvoyés, puis MERGEZ.
Consommateurs quotidiens ou hebdomadaires	Si vous effectuez des extractions tous les jours ou toutes les semaines, traitez tous les fichiers de la période. Cela vous garantit de ne pas manquer de mises à jour ou de suppressions.

Remarque : Chaque lot mélange des lignes actives (is_deleted = 0) et des lignes qui ne sont plus actives (is_deleted = 1). Ils ne sont pas fournis dans des fichiers séparés. La colonne is_deleted les distingue.

Exemple d’utilisation de l’API

Suivez ces étapes pour découvrir votre compte, identifier votre groupe de rapports et vos identifiants, et récupérer des fichiers de jeux de données.

Étape 0 : Répertoriez vos comptes
Appelez GET/v2/accounts pour répertorier les comptes Slate auxquels vous pouvez accéder.

Étape 1 : Secteurs d’activité associés au compte
Appelez GET/v2/accounts/1234567 8 pour connaître les secteurs d’activité disponibles.

Le champ id est le segment de chemin {REPORT_GROUP} à utiliser lors des appels suivants.

Étape 2a : Identifiants des canaux
Appelez GET/v2/accounts/12345678/channels ? offset=0&limit=100 pour répertorier les identifiants de vos chaînes.

Étape 2b : Identifiants FAST
Appelez GET/v2/accounts/12345678/fast ? offset=0&limit=100 pour répertorier vos identifiants FAST.

Étape 2c : Ensembles de données disponibles pour un identifiant
Appelez GET /v2/Accounts/12345678/Fast/ABC123/Datasets pour répertorier les ensembles de données disponibles.

Étape 3a : Fichiers du jeu de données des canaux
Appelez le point de terminaison des fichiers du jeu de données pour obtenir votre identifiant de canaux. La réponse renvoie une liste d’URL de téléchargement pour les fichiers CSV compressés au format gzip.

Étape 3b : Fichiers du jeu de données FAST
Appelez le point de terminaison des fichiers du jeu de données pour obtenir votre identifiant FAST.

Exemples de requêtes

Ces requêtes supposent que vous avez déjà fusionné vos données. Si vous conservez les lignes is_deleted dans une table brute, ajoutez WHERE is_deleted = 0 à chaque requête.

Heures consultées par station au cours d’une période

Les X meilleurs programmes par heures de visionnage

Résumé des visites quotidiennes

Heures consultées par Territoire

Pipeline ETL

Utilisez ce modèle en quatre étapes pour créer votre pipeline ETL pour le jeu de données du Programme linéaire en direct.

Extraction initiale des données. Extrayez tous les fichiers de votre chaîne dans la plage de temps souhaitée à l’aide du point de terminaison de l’API. Téléchargez tous les fichiers renvoyés. Chacune contient des lignes au format CSV compressé au format gzip.
Dédupliquer. Lorsque plusieurs enregistrements existent pour le même session_program_schedule_id dans les fichiers que vous avez extraits, ne conservez que la ligne contenant le dernier last_update_time_utc. Consultez la section Déduplication pour le modèle SQL complet.
Postulez à Destination. FUSIONNEZ les enregistrements dédupliqués dans votre table de destination saisie sur session_program_schedule_i d. Upsert sur is_deleted = 0. Sur is_deleted = 1, faites en sorte que l’ID cesse d’apparaître dans vos données actuelles. Supprimez-le définitivement ou maintenez la ligne marquée et filtrez-la.
Traitement incrémentiel. Pour les chargements en cours, réglez sur la dernière fois que vous avez extrait et EndDateTime sur l’heure actuelle. Traitez tous les fichiers renvoyés et FUSIONNEZ-LES dans votre destination.

Conseils rapides

Gardez ces conseils à l’esprit lorsque vous intégrez l’API dans votre pipeline.

session_program_schedule_id est votre clé unique. Dédupliquez toujours en utilisant last_update_time_utc.
Utilisez un MERGE, pas un insert groupé. Agissez sur les signaux is_deleted chaque fois que vous chargez des données.
Effectuez des recherches 1 à 4 fois par jour pour obtenir les données les plus récentes.
Définissez votre StartDateTime sur le dernier horodatage d’extraction réussi pour les chargements incrémentiels.
Utilisez les points de terminaison de découverte pour trouver votre compte, vos identifiants et les ensembles de données disponibles.
Utilisez à la fois les chaînes et les flux FAST si votre partenariat couvre les deux.
Ajouter WHERE is_deleted = 0 à toutes les requêtes si vous utilisez l’approche soft-delete.
La durée maximale de conservation des données est de 2 ans. Planifiez vos extractions historiques en conséquence.

Le saviez-vous ?

L’accès programmatique aux données d’audience au niveau du programme vous permet de créer des rapports personnalisés, d’alimenter vos systèmes de planification et de combiner des données linéaires avec vos autres données commerciales. Les partenaires qui intègrent cette API dans leurs flux de travail prennent des décisions plus rapides et plus éclairées en matière de programmation et d’acquisition de contenu.

Pour une analyse visuelle et des informations rapides, consultez le tableau de bord de programmation linéaire sur Slate Analytics.

API d’ensemble de données du Programme linéaire en direct