Intégrer des recommandations à l'aide de l'API REST

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 :

  1. Créez un compte Google Workspace. Suivez les instructions de la page d'assistance Google Workspace pour configurer un compte pour votre organisation.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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}-staging ne 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_time availability_intervals lointain 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.