L'API REST Google TV Video Discovery permet aux partenaires d'envoyer des recommandations non personnalisées aux appareils Google TV et Android TV depuis leurs serveurs backend. L'envoi de candidats depuis leur backend permet de maintenir à jour le catalogue et les recommandations de programmation en direct d'un partenaire sur ces appareils, sans que les utilisateurs aient besoin d'ouvrir l'application du partenaire.
Les partenaires envoient des candidats aux flux de recommandations. Google crée chaque flux pour le partenaire et configure les pays ou régions ainsi que les langues des appareils TV pour lesquels le flux est diffusé. Un flux peut contenir des films, des séries TV et des programmes télévisés en direct.
Si vous souhaitez publier des recommandations personnalisées à partir de l'appareil de l'utilisateur, consultez Intégrer des recommandations sur l'appareil à l'aide du SDK Engage.
Prérequis
Avant d'intégrer l'API REST, assurez-vous de disposer des éléments suivants :
- Un projet Google Cloud à partir duquel effectuer des requêtes API.
- Un compte Google Workspace associé à votre organisation.
- Votre ID de partenaire et les ID de vos flux de recommandations, fournis par votre représentant Google TV lors de l'intégration. Pour savoir comment ces ID sont utilisés, consultez Flux de recommandations.
Souscrire
L'accès à l'API REST Google TV Video Discovery est réservé aux partenaires multimédias Google TV enregistrés. Chaque appelant est authentifié à l'aide d'un compte de service Google Cloud mappé sur le serveur à un seul ID de partenaire.
Pour demander et configurer l'accès à l'API, procédez comme suit :
- Créez un compte Google Workspace. Suivez les instructions de la page d'assistance Google Workspace pour configurer un compte pour votre organisation.
- Trouvez votre numéro client Google Workspace. Recherchez votre numéro client (par exemple,
C0123abcd) en suivant la procédure décrite dans Trouver votre numéro client. - Créez un projet et un compte de service Google Cloud. Dans la console Google Cloud, sous votre organisation Google Workspace, créez un projet Google Cloud et un compte de service pour votre serveur backend.
- Demandez l'intégration d'un partenaire. Fournissez votre ID client Google Workspace, votre ID de projet Google Cloud et l'adresse e-mail de votre compte de service (ou l'ID numérique unique) à votre représentant Google TV, ainsi que les pays ou régions et les langues des appareils TV auxquels vous souhaitez envoyer des candidats. Votre représentant Google TV vous informe une fois qu'il a mappé votre organisation, votre projet et votre compte de service Google Workspace à votre ID de partenaire. Il vous fournit également les ID de flux de recommandations créés pour votre partenaire.
- Activez l'API et générez des identifiants. Une fois que votre représentant a confirmé que l'accès est accordé, activez l'API Google TV Video Discovery (
tvvideodiscovery.googleapis.com) dans votre projet Google Cloud et générez des identifiants OAuth 2.0 pour votre compte de service. Authentifiez vos requêtes. Demandez des jetons d'accès OAuth 2.0 à l'aide du champ d'application OAuth suivant et transmettez le jeton dans l'en-tête HTTP
Authorization: Bearerà chaque appel :https://www.googleapis.com/auth/tvvideodiscovery
Limites de débit
Les requêtes adressées à replaceCandidates sont soumises aux limites de débit par projet et aux limites de charge utile par requête suivantes :
| Limite | Valeur |
|---|---|
| Requêtes par minute et par projet Google Cloud | 5 |
| Requêtes par jour et par projet Google Cloud | 100 |
RecommendationCandidate éléments par requête |
1 à 25 |
Les requêtes envoyées à un flux de préproduction sont comptabilisées dans le même quota que les requêtes envoyées au flux de production correspondant.
Flux de recommandations
L'API organise les candidats à la recommandation en flux de recommandations. Un flux est identifié par un nom de ressource au format suivant :
partners/{partner}/recommendationsFeeds/{recommendationsFeed}
Partenaires
{partner} est l'ID de partenaire que Google vous attribue lors de l'intégration. Le compte de service avec lequel vous vous authentifiez est mappé à un seul ID de partenaire.
Les requêtes qui nomment un autre partenaire échouent avec l'erreur 403 PERMISSION_DENIED.
ID de flux
{recommendationsFeed} est un ID de flux que Google crée pour vous lors de l'intégration. Vous ne pouvez pas créer de flux avec l'API.
Chaque flux cible une audience que Google configure lorsqu'il crée le flux :
- Pays ou régions : où les candidats du flux sont affichés.
- Langues de l'appareil TV : langues que les utilisateurs ciblés ont définies sur leur téléviseur. Il ne s'agit pas de la langue du texte que vous envoyez. Pour fournir du texte dans plusieurs langues, consultez
LocalizedString.
Google décide de l'emplacement des candidats d'un flux sur les appareils Google TV et Android TV. Vous envoyez des candidats à chaque flux de la même manière.
Flux de préproduction
Chaque flux possède un flux de préproduction correspondant nommé {recommendationsFeed}-staging. Un flux de préproduction n'est diffusé que sur les comptes de test d'une liste d'autorisation. Utilisez-le pour valider votre intégration avant d'envoyer des candidats au flux de production.
Les flux de préproduction utilisent le même point de terminaison, les mêmes identifiants, la même validation de requête et le même quota que les flux de production. Seule l'audience diffère.
Remplacement
Le flux est l'unité de remplacement. Chaque appel replaceCandidates remplace tous les candidats précédemment stockés pour ce flux et ne modifie aucun autre flux.
Remplacer les candidats à la recommandation
Utilisez la méthode partners.recommendationsFeeds.replaceCandidates pour envoyer la liste complète des candidats à la recommandation pour un flux.
Requête HTTP
POST https://tvvideodiscovery.googleapis.com/v1/{name=partners/*/recommendationsFeeds/*}:replaceCandidates
Le chemin d'accès de l'URL contient le nom de ressource du flux dont les candidats sont remplacés. Le corps de la requête contient tous les champs qui ne font pas partie du chemin d'URL.
Paramètres de chemin d'accès
| Paramètre | Description |
|---|---|
name |
Obligatoire. Nom de ressource du flux, au format partners/{partner}/recommendationsFeeds/{recommendationsFeed}. {partner} doit être l'ID de partenaire auquel votre compte de service est associé. {recommendationsFeed} doit être un ID de flux que Google a créé pour ce partenaire, ou cet ID de flux avec le suffixe -staging. |
ReplaceCandidatesRequest
Le corps de la requête JSON présente la structure suivante :
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
recommendation_candidates |
array of RecommendationCandidate |
Oui | Liste de 1 à 25 éléments RecommendationCandidate. Ces candidats remplacent les candidats actuels du flux. |
Schémas candidats
Chaque élément de recommendation_candidates est un objet RecommendationCandidate qui contient une charge utile de type candidat, des motifs de recommandation facultatifs et des créneaux de disponibilité d'affichage facultatifs.
RecommendationCandidate
Un objet RecommendationCandidate contient exactement un champ de charge utile de type média, des motifs de recommandation facultatifs et des intervalles de disponibilité facultatifs.
Champ d'union candidate_type
candidate_type est obligatoire : définissez exactement l'un des champs suivants. Les champs s'excluent mutuellement, et un candidat qui n'en définit aucun ou qui en définit plusieurs est rejeté. Il n'y a pas de clé candidate_type dans le fichier JSON. Définissez le champ choisi directement sur l'objet RecommendationCandidate.
| Champ | Type | Description |
|---|---|---|
movie_candidate |
MovieCandidate |
Un film à la demande (voir MovieCandidate). |
tv_show_candidate |
TvShowCandidate |
Une série TV au niveau de la série (voir TvShowCandidate). |
live_tv_program_candidate |
LiveTvProgramCandidate |
Diffusion télévisée en direct ou événement diffusé en streaming (voir LiveTvProgramCandidate). |
Contexte et disponibilité
Les deux champs sont facultatifs :
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
recommendation_contexts |
array of RecommendationContext |
Non | Pourquoi le candidat est recommandé et pendant combien de temps chaque motif s'applique (voir RecommendationContext). |
availability_intervals |
array of Interval |
Non | Périodes pendant lesquelles le candidat peut être affiché (voir Interval). Chaque période commence à son start_time (inclus) et se termine à son end_time (exclus). Si cette valeur n'est pas définie, le candidat est éligible tant qu'il est stocké. Un candidat dont les fenêtres sont toutes dans le passé n'est jamais affiché. |
MovieCandidate
L'objet MovieCandidate représente un film à la demande :
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
title |
LocalizedString |
Oui | Titre du film (voir LocalizedString). Chaque valeur est comprise entre 1 et 100 points de code Unicode et s'affiche telle qu'elle est envoyée. |
description |
LocalizedString |
Oui | Brève description du film (voir LocalizedString). Chaque valeur est comprise entre 1 et 400 points de code Unicode. |
localized_media_images |
array of LocalizedMediaImage |
Oui | Images d'illustration au format 16:9, une entrée par langue (voir LocalizedMediaImage). Doit contenir au moins une image. Fournissez la plus grande source disponible. Nous vous recommandons une résolution de 1 920 x 1 080 pixels. |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
Oui | Liens profonds par plate-forme et par langue (voir LocalizedProviderPlaybackUri). Au moins une entrée doit lister PLATFORM_ANDROID_TV. |
release_date |
Date |
Oui | Date de sortie du film (voir Date). |
external_entity_ids |
array of ExternalEntityId |
Non | Identifiants de catalogue externe pour la mise en correspondance des entités (voir ExternalEntityId). Au maximum une entrée par type d'identifiant. |
duration |
string (Duration) |
Non | Durée du film (voir Duration). Par exemple, "7200s" pour deux heures. |
content_ratings |
array of ContentRating |
Non | Classifications officielles du contenu (voir ContentRating) |
TvShowCandidate
L'objet TvShowCandidate représente un programme TV au niveau de l'émission. Les appareils Google TV et Android TV affichent une fiche pour la série. Utilisez le lien profond pour décider si la lecture commence sur la page de la série ou sur un épisode spécifique.
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
title |
LocalizedString |
Oui | Titre du programme TV (voir LocalizedString). Chaque valeur est comprise entre 1 et 100 points de code Unicode et s'affiche telle qu'elle a été envoyée. |
description |
LocalizedString |
Oui | Brève description du programme TV (voir LocalizedString). Chaque valeur est comprise entre 1 et 400 points de code Unicode. |
localized_media_images |
array of LocalizedMediaImage |
Oui | Images d'illustration au format 16:9, une entrée par langue (voir LocalizedMediaImage). Doit contenir au moins une image. Fournissez la plus grande source disponible. Nous vous recommandons une résolution de 1 920 x 1 080 pixels. |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
Oui | Liens profonds par plate-forme et par langue (voir LocalizedProviderPlaybackUri). Au moins une entrée doit lister PLATFORM_ANDROID_TV. Le uri peut pointer vers la page de l'émission ou vers un épisode. |
first_episode_air_date |
Date |
Oui | Date de diffusion du premier épisode (voir Date). |
external_entity_ids |
array of ExternalEntityId |
Non | Identifiants de catalogue externe pour la mise en correspondance des entités (voir ExternalEntityId). Au maximum une entrée par type d'identifiant. |
season_count |
integer (int32) |
Non | Nombre de saisons disponibles sur votre service. |
content_ratings |
array of ContentRating |
Non | Classifications officielles du contenu (voir ContentRating) |
LiveTvProgramCandidate
L'objet LiveTvProgramCandidate représente une diffusion télévisée en direct ou un événement diffusé en streaming. La fenêtre de diffusion fait partie du candidat et est distincte de l'élément availability_intervals du candidat parent, qui contrôle quand la fiche peut être affichée.
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
title |
LocalizedString |
Oui | Titre du programme de télévision en direct (voir LocalizedString). Chaque valeur est comprise entre 1 et 100 points de code Unicode et est affichée telle qu'elle est envoyée. |
description |
LocalizedString |
Oui | Brève description du programme de télévision en direct (voir LocalizedString). Chaque valeur est comprise entre 1 et 400 points de code Unicode. |
localized_media_images |
array of LocalizedMediaImage |
Oui | Images d'illustration au format 16:9, une entrée par langue (voir LocalizedMediaImage). Doit contenir au moins une image. Fournissez la plus grande source disponible. Nous vous recommandons une résolution de 1 920 x 1 080 pixels. |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
Oui | Liens profonds par plate-forme et par langue (voir LocalizedProviderPlaybackUri). Au moins une entrée doit lister PLATFORM_ANDROID_TV. |
broadcast_interval |
Interval |
Oui | Début et fin de la diffusion du programme (voir Interval). start_time et end_time sont tous deux obligatoires. |
external_entity_ids |
array of ExternalEntityId |
Non | Identifiants de catalogue externe pour la mise en correspondance des entités (voir ExternalEntityId). Au maximum une entrée par type d'identifiant. |
content_ratings |
array of ContentRating |
Non | Classifications officielles du contenu (voir ContentRating) |
Schémas compatibles
Les charges utiles candidates font référence aux objets partagés suivants pour le texte localisé, les liens profonds, les images, les identifiants externes, les motifs de recommandation, les intervalles d'affichage, les classifications de contenu et les types de date et d'heure connus.
LocalizedString
L'objet LocalizedString contient le même texte dans une ou plusieurs langues.
Chaque valeur est associée à une langue afin que les appareils Google TV et Android TV puissent afficher le texte correspondant à la langue de l'appareil de l'utilisateur :
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
values |
array of LocalizedText |
Oui | Texte dans chaque langue que vous fournissez (voir LocalizedText). Doit contenir au moins une valeur. |
LocalizedText
L'objet LocalizedText est un texte dans une seule langue :
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
text |
string |
Oui | Texte dans la langue indiquée par language_code. |
language_code |
string |
Oui | Code de langue BCP-47 de text, par exemple "en-US" ou "sr-Latn". |
LocalizedMediaImage
L'objet LocalizedMediaImage associe une image à la langue de tout texte qu'elle contient :
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
language_code |
string |
Oui | Code de langue BCP-47 du texte de l'image, tel que "en-US" ou "sr-Latn". |
image |
MediaImage |
Oui | Image au format 16:9 (voir MediaImage). Fournissez la plus grande source disponible. Nous vous recommandons une résolution de 1 920 x 1 080 pixels. |
LocalizedProviderPlaybackUri
L'objet LocalizedProviderPlaybackUri associe un lien profond à la langue du contenu qu'il ouvre et à l'application qui l'ouvre :
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
playback_uri |
PlaybackUri |
Oui | Le lien profond et les plates-formes auxquelles il s'applique (voir PlaybackUri). |
language_code |
string |
Oui | Code de langue BCP-47 du contenu ouvert par le lien profond, par exemple "en-US" ou "sr-Latn". |
package_name |
string |
Oui | Nom du package de l'application Android utilisé pour ouvrir le lien profond (par exemple, "com.example.tvapp"). |
PlaybackUri
L'objet PlaybackUri définit un lien profond et ses plates-formes cibles :
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
uri |
string |
Oui | URI de lien profond qui lance la lecture du candidat dans votre application. |
platforms |
array of string (enum) |
Oui | Plates-formes auxquelles ce lien profond s'applique. Valeurs autorisées : PLATFORM_UNSPECIFIED, PLATFORM_ANDROID_TV, PLATFORM_ANDROID, PLATFORM_IOS. Incluez PLATFORM_ANDROID_TV pour les appareils Google TV et Android TV. |
MediaImage
L'objet MediaImage spécifie l'URL d'une image, ses dimensions en pixels et un texte d'accessibilité :
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
url |
string |
Oui | URL HTTPS de l'image accessible publiquement. |
width |
integer |
Oui | Largeur maximale de l'image non modifiée, en pixels. |
height |
integer |
Oui | Hauteur de l'image non modifiée (maximale) en pixels. |
accessibility_text |
string |
Oui | Texte d'accessibilité (alternatif) décrivant l'image. |
ExternalEntityId
L'objet ExternalEntityId mappe un candidat à un identifiant dans un catalogue externe. Définissez exactement l'un des champs suivants par entrée et incluez au maximum une entrée par type d'identifiant dans la liste external_entity_ids d'un candidat :
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
tms_root_id |
string |
Une | ID racine Gracenote TMS. Identifie un titre : un film, une série ou un épisode. |
tms_id |
string |
Une | ID de variante Gracenote TMS. Identifie une édition ou une liste de diffusion. |
data_feed_element_id |
string |
Une | ID d'entité de votre flux de données Media Actions. Cette valeur n'est pas liée au segment {recommendationsFeed} du nom de la ressource. |
RecommendationContext
L'objet RecommendationContext explique pourquoi un candidat est recommandé et pendant combien de temps cette explication s'applique :
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
recommendation_reason |
RecommendationReason |
Non | Pourquoi le candidat est recommandé (voir RecommendationReason). |
validity_interval |
Interval |
Non | Période pendant laquelle ce contexte s'applique (voir Interval). Par exemple, un candidat n'est nouveau que pendant un nombre limité de jours. Si ce champ n'est pas défini, le contexte s'applique tant que le candidat est stocké. |
RecommendationReason
L'objet RecommendationReason contient une raison. Définissez exactement l'un des champs suivants :
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
top_on_partner |
object |
Une | Le candidat est un élément de premier plan dans votre service. Contient un seul champ d'entier positif rank (par exemple, {"rank": 1} pour "Top 1 sur le partenaire"). |
popular_on_partner |
object |
Une | Le candidat est populaire sur votre service. Transmettez un objet vide ({}). |
new_on_partner |
object |
Une | Le candidat est nouveau sur votre service. Transmettez un objet vide ({}). |
generic |
object |
Une | Un motif personnalisé. Contient un seul champ LocalizedString generic_reason (voir LocalizedString). Chaque valeur est comprise entre 1 et 100 points de code Unicode. |
ContentRating
L'objet ContentRating représente une classification de contenu officielle attribuée par un organisme de classification :
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
rating_system |
string |
Oui | Agence ou système de classification, par exemple "MPAA", "BBFC" ou "CBFC". |
rating_value |
string |
Oui | Classification telle que définie par rating_system, par exemple "PG-13" ou "U/A 13+". |
Timestamp
Un Timestamp est encodé en JSON sous la forme d'une chaîne RFC 3339 au format UTC avec un suffixe Z, par exemple "2026-10-01T18:00:00Z". Les fractions de seconde sont autorisées, par exemple "2026-10-01T18:00:00.500Z".
Duration
Un Duration est encodé en JSON sous la forme d'une chaîne contenant le nombre de secondes suivi du suffixe s, par exemple "7200s" pour deux heures. Les fractions de seconde sont autorisées, par exemple "5400.5s".
Date
Une Date est une date de calendrier sans fuseau horaire. Il est encodé en JSON en tant qu'objet avec les champs suivants :
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
year |
integer |
Oui | Année de la date, par exemple 2025. |
month |
integer |
Non | Mois de l'année, de 1 à 12. Définissez la valeur sur 0 ou omettez-la si le mois n'est pas connu. |
day |
integer |
Non | Jour du mois, de 1 à 31, et valide pour l'année et le mois donnés. Définissez la valeur sur 0 ou omettez-la si le jour n'est pas connu. Nécessite month. |
Par exemple, {"year": 2025, "month": 1, "day": 17} représente le 17 janvier 2025, {"year": 2025, "month": 1} représente janvier 2025 avec un jour inconnu et {"year": 2025} représente une date en 2025 avec un mois et un jour inconnus.
Interval
Un Interval est une période semi-ouverte qui commence à start_time (inclus) et se termine à end_time (exclus). Une heure T se trouve dans l'intervalle lorsque start_time <= T et T < end_time.
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
start_time |
string (Timestamp) |
Oui | Début inclusif de la fenêtre (voir Timestamp), par exemple "2026-10-01T18:00:00Z". |
end_time |
string (Timestamp) |
Oui | Fin exclusive de la fenêtre (voir Timestamp), par exemple "2026-10-01T21:00:00Z". Doit être postérieure au start_time. |
Exemple de requête
L'exemple suivant remplace les candidats du flux in-en-cricket du partenaire example-partner par trois candidats (un film, une émission télévisée et un programme télévisé en direct). Le film comporte du texte dans deux langues :
curl -X POST \
"https://tvvideodiscovery.googleapis.com/v1/partners/example-partner/recommendationsFeeds/in-en-cricket:replaceCandidates" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{
"recommendation_candidates": [
{
"movie_candidate": {
"title": {
"values": [
{
"text": "Example Action Movie",
"language_code": "en-US"
},
{
"text": "Película de acción de ejemplo",
"language_code": "es-419"
}
]
},
"description": {
"values": [
{
"text": "An example action movie synopsis.",
"language_code": "en-US"
},
{
"text": "Sinopsis de una película de acción de ejemplo.",
"language_code": "es-419"
}
]
},
"localized_media_images": [
{
"language_code": "en-US",
"image": {
"url": "https://www.example.com/images/movie-1001-16x9-en.jpg",
"width": 1920,
"height": 1080,
"accessibility_text": "Artwork for Example Action Movie"
}
},
{
"language_code": "es-419",
"image": {
"url": "https://www.example.com/images/movie-1001-16x9-es.jpg",
"width": 1920,
"height": 1080,
"accessibility_text": "Imagen de Película de acción de ejemplo"
}
}
],
"localized_provider_playback_uris": [
{
"playback_uri": {
"uri": "https://www.example.com/watch/movie-1001?lang=en",
"platforms": ["PLATFORM_ANDROID_TV", "PLATFORM_ANDROID"]
},
"language_code": "en-US",
"package_name": "com.example.tvapp"
},
{
"playback_uri": {
"uri": "https://www.example.com/watch/movie-1001?lang=es",
"platforms": ["PLATFORM_ANDROID_TV", "PLATFORM_ANDROID"]
},
"language_code": "es-419",
"package_name": "com.example.tvapp"
}
],
"release_date": {
"year": 2025,
"month": 11,
"day": 14
},
"external_entity_ids": [
{
"tms_root_id": "MV001234560000"
}
],
"duration": "7200s",
"content_ratings": [
{
"rating_system": "MPAA",
"rating_value": "PG-13"
}
]
},
"recommendation_contexts": [
{
"recommendation_reason": {
"top_on_partner": {
"rank": 1
}
}
}
],
"availability_intervals": [
{
"start_time": "2026-11-01T00:00:00Z",
"end_time": "2026-12-01T00:00:00Z"
}
]
},
{
"tv_show_candidate": {
"title": {
"values": [
{
"text": "Example Drama Series",
"language_code": "en-US"
}
]
},
"description": {
"values": [
{
"text": "An example drama series synopsis.",
"language_code": "en-US"
}
]
},
"localized_media_images": [
{
"language_code": "en-US",
"image": {
"url": "https://www.example.com/images/show-2002-16x9.jpg",
"width": 1920,
"height": 1080,
"accessibility_text": "Artwork for Example Drama Series"
}
}
],
"localized_provider_playback_uris": [
{
"playback_uri": {
"uri": "https://www.example.com/watch/show-2002",
"platforms": ["PLATFORM_ANDROID_TV"]
},
"language_code": "en-US",
"package_name": "com.example.tvapp"
}
],
"first_episode_air_date": {
"year": 2024,
"month": 3,
"day": 8
},
"external_entity_ids": [
{
"data_feed_element_id": "show-2002"
}
],
"season_count": 3,
"content_ratings": [
{
"rating_system": "TV_PG",
"rating_value": "TV-14"
}
]
},
"recommendation_contexts": [
{
"recommendation_reason": {
"new_on_partner": {}
},
"validity_interval": {
"start_time": "2026-11-01T00:00:00Z",
"end_time": "2026-11-15T00:00:00Z"
}
}
],
"availability_intervals": [
{
"start_time": "2026-11-01T00:00:00Z",
"end_time": "2026-12-01T00:00:00Z"
}
]
},
{
"live_tv_program_candidate": {
"title": {
"values": [
{
"text": "Championship Live Broadcast",
"language_code": "en-US"
}
]
},
"description": {
"values": [
{
"text": "Live coverage of the championship match.",
"language_code": "en-US"
}
]
},
"localized_media_images": [
{
"language_code": "en-US",
"image": {
"url": "https://www.example.com/images/live-prog-500-16x9.jpg",
"width": 1920,
"height": 1080,
"accessibility_text": "Artwork for Championship Live Broadcast"
}
}
],
"localized_provider_playback_uris": [
{
"playback_uri": {
"uri": "https://www.example.com/live/sports-1",
"platforms": ["PLATFORM_ANDROID_TV"]
},
"language_code": "en-US",
"package_name": "com.example.tvapp"
}
],
"broadcast_interval": {
"start_time": "2026-11-15T18:00:00Z",
"end_time": "2026-11-15T21:00:00Z"
},
"external_entity_ids": [
{
"tms_id": "EP012345670001"
}
],
"content_ratings": [
{
"rating_system": "TV_PG",
"rating_value": "TV-PG"
}
]
},
"recommendation_contexts": [
{
"recommendation_reason": {
"generic": {
"generic_reason": {
"values": [
{
"text": "Live this weekend",
"language_code": "en-US"
}
]
}
}
}
}
],
"availability_intervals": [
{
"start_time": "2026-11-14T18:00:00Z",
"end_time": "2026-11-15T21:00:00Z"
}
]
}
]
}'
Comportement de réponse et de remplacement
Cette section décrit la réponse HTTP renvoyée par replaceCandidates et la manière dont chaque appel met à jour vos candidats stockés.
ReplaceCandidatesResponse
Si la requête aboutit, l'API renvoie le code d'état HTTP 200 OK avec un corps ReplaceCandidatesResponse :
| Champ | Type | Description |
|---|---|---|
replaced_candidates_count |
integer (int32) |
Nombre de candidats remplacés. |
Pour l'exemple de requête précédent, la réponse est la suivante :
{
"replaced_candidates_count": 3
}
Comportement de remplacement
Il est essentiel de comprendre comment replaceCandidates met à jour les candidats stockés pour concevoir votre intégration :
- Remplacement complet par flux. Chaque appel remplace complètement la liste de candidats précédemment stockée pour le flux nommé dans le chemin d'URL. Envoyez toujours l'ensemble complet des candidats actifs pour ce flux.
- Les autres flux restent inchangés. Les flux auxquels vous n'envoyez pas de candidats restent inchangés jusqu'à ce que vous le fassiez. Par exemple, le remplacement des candidats d'un flux ne modifie pas les candidats stockés pour un autre flux, et le remplacement des candidats de
{recommendationsFeed}-stagingne modifie pas{recommendationsFeed}. - Un appel par flux. Pour mettre à jour plusieurs flux, effectuez un appel par flux. Les appels sont indépendants : si l'un d'eux échoue, les autres flux conservent leurs nouveaux candidats et vous ne relancez que l'appel ayant échoué.
- Renvoyez les flux actifs au moins tous les 30 jours. Même si votre catalogue pour un flux n'a pas changé, renvoyez chaque flux actif au moins une fois tous les 30 jours (ou selon un calendrier quotidien ou hebdomadaire régulier avec une gigue aléatoire) afin que vos candidats restent actifs et n'expirent pas. Définir un
end_timeavailability_intervalslointain ne remplace pas le renvoi périodique. - Exécution atomique. L'API applique la requête de manière atomique. Si un candidat échoue à la validation, l'API rejette l'intégralité de la requête et le flux conserve ses candidats précédents.