Integra las recomendaciones con la API de REST

La API de REST de descubrimiento de videos de Google TV permite que los socios envíen candidatos de recomendaciones no personalizadas a dispositivos Google TV y Android TV desde sus servidores de backend. El envío de candidatos desde su backend mantiene actualizados el catálogo y las recomendaciones de programación en vivo de un socio en estos dispositivos sin que los usuarios tengan que abrir la app del socio.

Los socios envían candidatos a los feeds de recomendaciones. Google crea cada feed para el socio y configura los países o las regiones, y los idiomas de los dispositivos de TV en los que se muestra el feed. Un feed puede contener películas, programas de TV y programas de TV en vivo.

Si quieres publicar recomendaciones personalizadas desde el dispositivo del usuario, consulta Cómo integrar recomendaciones integrado en el dispositivo con el SDK de Engage.

Requisitos previos

Antes de realizar la integración con la API de REST, asegúrate de tener lo siguiente:

  • Un proyecto de Google Cloud desde el que se realizarán las solicitudes a la API
  • Una cuenta de Google Workspace asociada a tu organización
  • Tu ID de socio y los IDs del feed de recomendaciones, que proporciona tu representante de socios de Google TV durante la integración. Consulta Feeds de recomendaciones para saber cómo se usan estos IDs.

Obtener acceso

El acceso a la API de REST de Google TV Video Discovery está restringido a los socios de contenido multimedia de Google TV registrados. Cada emisor se autentica con una cuenta de servicio de Google Cloud que se asigna en el servidor a exactamente un ID de socio.

Para solicitar y configurar el acceso a la API, sigue estos pasos:

  1. Crea una cuenta de Google Workspace. Sigue las instrucciones de la página de asistencia de Google Workspace para configurar una cuenta para tu organización.
  2. Busca tu ID de cliente de Google Workspace. Sigue los pasos que se indican en Encuentra tu ID de cliente para obtenerlo (por ejemplo, C0123abcd).
  3. Crea un proyecto y una cuenta de servicio de Google Cloud. En la consola de Google Cloud, en tu organización de Google Workspace, crea un proyecto de Google Cloud y una cuenta de servicio para tu servidor de backend.
  4. Solicita la incorporación de socios. Proporciona tu ID de cliente de Google Workspace, el ID del proyecto de Google Cloud y la dirección de correo electrónico de la cuenta de servicio (o el ID numérico único) a tu representante de socios de Google TV, junto con los países o regiones y los idiomas de los dispositivos de TV a los que deseas enviar candidatos. Tu representante de socio de Google TV te notificará después de asignar tu organización, proyecto y cuenta de servicio de Google Workspace a tu ID de socio, y te proporcionará los IDs de feed de recomendaciones creados para tu socio.
  5. Habilita la API y genera credenciales. Después de que tu representante confirme que se otorgó el acceso, habilita la API de Google TV Video Discovery (tvvideodiscovery.googleapis.com) en tu proyecto de Google Cloud y genera credenciales de OAuth 2.0 para tu cuenta de servicio.
  6. Autentica tus solicitudes. Solicita tokens de acceso de OAuth 2.0 con el siguiente permiso de OAuth y pasa el token en el encabezado HTTP Authorization: Bearer en cada llamada:

    https://www.googleapis.com/auth/tvvideodiscovery
    

Límites de frecuencia

Las solicitudes a replaceCandidates están sujetas a los siguientes límites de frecuencia por proyecto y límites de carga útil por solicitud:

Límite Valor
Solicitudes por minuto por proyecto de Google Cloud 5
Solicitudes por día por proyecto de Google Cloud 100
RecommendationCandidate elementos por solicitud De 1 a 25

Las solicitudes a un feed de etapa de pruebas se descuentan de la misma cuota que las solicitudes al feed de producción correspondiente.

Feeds de recomendaciones

La API organiza los candidatos de recomendación en feeds de recomendaciones. Un feed se identifica con un nombre de recurso que tiene el siguiente formato:

partners/{partner}/recommendationsFeeds/{recommendationsFeed}

Socios

{partner} es el ID de socio que Google te asigna durante la integración. La cuenta de servicio con la que te autenticas se asigna exactamente a un ID de socio. Las solicitudes que nombran a cualquier otro socio fallan con 403 PERMISSION_DENIED.

IDs de feeds

{recommendationsFeed} es un ID de feed que Google crea para ti durante la incorporación. No puedes crear feeds con la API.

Cada feed se orienta a un público que Google configura cuando crea el feed:

  • Países o regiones: Son las ubicaciones donde se muestran los candidatos del feed.
  • Idiomas del dispositivo de TV: Son los idiomas que los usuarios segmentados configuraron en su dispositivo de TV. Este no es el idioma del texto que envías. Para proporcionar texto en más de un idioma, consulta LocalizedString.

Google decide dónde aparecen los candidatos de un feed en los dispositivos Google TV y Android TV. Envías candidatos a cada feed de la misma manera.

Feeds de etapa de pruebas

Cada feed tiene un feed de etapa de pruebas coincidente llamado {recommendationsFeed}-staging. Un feed de etapa de pruebas solo se publica en las cuentas de prueba de una lista de entidades permitidas. Úsala para validar tu integración antes de enviar candidatos al feed de producción.

Los feeds de etapa de pruebas usan el mismo extremo, las mismas credenciales, la misma validación de solicitudes y la misma cuota que los feeds de producción. Solo difiere el público.

Reemplazo

El feed es la unidad de reemplazo. Cada llamada a replaceCandidates reemplaza todos los candidatos almacenados anteriormente para ese feed y deja intactos todos los demás feeds.

Reemplaza los candidatos de recomendación

Usa el método partners.recommendationsFeeds.replaceCandidates para enviar la lista completa de candidatos de recomendación para un feed.

Solicitud HTTP

POST https://tvvideodiscovery.googleapis.com/v1/{name=partners/*/recommendationsFeeds/*}:replaceCandidates

La ruta de URL contiene el nombre del recurso del feed cuyos candidatos se reemplazan. El cuerpo de la solicitud contiene todos los campos que no forman parte de la ruta de URL.

Parámetros de ruta

Parámetro Descripción
name Obligatorio. Es el nombre del recurso del feed, con el formato partners/{partner}/recommendationsFeeds/{recommendationsFeed}. {partner} debe ser el ID de socio al que se asigna tu cuenta de servicio. {recommendationsFeed} debe ser un ID del feed que Google creó para ese socio o ese ID del feed con el sufijo -staging.

ReplaceCandidatesRequest

El cuerpo de la solicitud JSON tiene la siguiente estructura:

Campo Tipo Obligatorio Descripción
recommendation_candidates array of RecommendationCandidate Sí Es una lista de 1 a 25 elementos RecommendationCandidate. Estos candidatos reemplazan a los candidatos actuales del feed.

Esquemas candidatos

Cada elemento de recommendation_candidates es un objeto RecommendationCandidate que contiene una carga útil de tipo candidato, motivos de recomendación opcionales y períodos de disponibilidad de visualización opcionales.

RecommendationCandidate

Un objeto RecommendationCandidate contiene exactamente un campo de carga útil de tipo de contenido multimedia, motivos de recomendación opcionales y, también, intervalos de disponibilidad opcionales.

Campo de unión candidate_type

candidate_type es obligatorio: configura exactamente uno de los siguientes campos. Los campos son mutuamente excluyentes, y se rechaza un candidato que no establece ninguno o más de uno. No hay ninguna clave candidate_type en el JSON; establece el campo elegido directamente en el objeto RecommendationCandidate.

Campo Tipo Descripción
movie_candidate MovieCandidate Una película on demand (consulta MovieCandidate)
tv_show_candidate TvShowCandidate Un programa de TV a nivel del programa (consulta TvShowCandidate)
live_tv_program_candidate LiveTvProgramCandidate Es una transmisión de TV en vivo programada o un evento transmitido (consulta LiveTvProgramCandidate).

Contexto y disponibilidad

Ambos campos son opcionales:

Campo Tipo Obligatorio Descripción
recommendation_contexts array of RecommendationContext No Por qué se recomienda el candidato y durante cuánto tiempo se aplica cada motivo (consulta RecommendationContext).
availability_intervals array of Interval No Son los períodos durante los que se puede mostrar el candidato (consulta Interval). Cada período comienza en su start_time (inclusive) y termina en su end_time (exclusivo). Si no se establece, el candidato será apto durante el tiempo que esté almacenado. Nunca se muestra un candidato cuyas ventanas están todas en el pasado.

MovieCandidate

El objeto MovieCandidate representa una película on demand:

Campo Tipo Obligatorio Descripción
title LocalizedString Sí Es el título de la película (consulta LocalizedString). Cada valor tiene entre 1 y 100 puntos de código Unicode y se muestra tal como se envía.
description LocalizedString Sí Es una descripción breve de la película (consulta LocalizedString). Cada valor tiene entre 1 y 400 puntos de código Unicode.
localized_media_images array of LocalizedMediaImage Sí Imágenes de material gráfico de 16:9, una entrada por idioma (consulta LocalizedMediaImage). Debe contener al menos una imagen. Proporciona el archivo de origen más grande disponible; se recomienda que sea de 1920 x 1080 píxeles.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri Sí Vínculos directos por plataforma y por idioma (consulta LocalizedProviderPlaybackUri). Al menos una entrada debe incluir PLATFORM_ANDROID_TV.
release_date Date Sí Es la fecha de lanzamiento de la película (consulta Date).
external_entity_ids array of ExternalEntityId No Identificadores de catálogo externos para la coincidencia de entidades (consulta ExternalEntityId). Como máximo, una entrada por tipo de identificador.
duration string (Duration) No La duración de la película (consulta Duration). Por ejemplo, "7200s" para 2 horas.
content_ratings array of ContentRating No Clasificaciones del contenido oficiales (consulta ContentRating)

TvShowCandidate

El objeto TvShowCandidate representa un programa de TV a nivel del programa. Los dispositivos Google TV y Android TV muestran una tarjeta para el programa. Usa el vínculo directo para decidir si la reproducción comienza en la página del programa o en un episodio específico.

Campo Tipo Obligatorio Descripción
title LocalizedString Sí Es el título del programa de TV (consulta LocalizedString). Cada valor tiene entre 1 y 100 puntos de código Unicode y se muestra tal como se envía.
description LocalizedString Sí Es una descripción breve del programa de TV (consulta LocalizedString). Cada valor tiene entre 1 y 400 puntos de código Unicode.
localized_media_images array of LocalizedMediaImage Sí Imágenes de material gráfico de 16:9, una entrada por idioma (consulta LocalizedMediaImage). Debe contener al menos una imagen. Proporciona el archivo de origen más grande disponible; se recomienda que sea de 1920 x 1080 píxeles.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri Sí Vínculos directos por plataforma y por idioma (consulta LocalizedProviderPlaybackUri). Al menos una entrada debe incluir PLATFORM_ANDROID_TV. El uri puede apuntar a la página del programa o a un episodio.
first_episode_air_date Date Sí Fecha de emisión del primer episodio (consulta Date).
external_entity_ids array of ExternalEntityId No Identificadores de catálogo externos para la coincidencia de entidades (consulta ExternalEntityId). Como máximo, una entrada por tipo de identificador.
season_count integer (int32) No Es la cantidad de temporadas disponibles en tu servicio.
content_ratings array of ContentRating No Clasificaciones del contenido oficiales (consulta ContentRating)

LiveTvProgramCandidate

El objeto LiveTvProgramCandidate representa una transmisión de TV en vivo o un evento transmitido programados. La ventana de transmisión forma parte del candidato y es independiente de los availability_intervals del candidato superior, que controlan cuándo se puede mostrar la tarjeta.

Campo Tipo Obligatorio Descripción
title LocalizedString Sí Es el título del programa de TV en vivo (consulta LocalizedString). Cada valor tiene entre 1 y 100 puntos de código Unicode y se muestra tal como se envía.
description LocalizedString Sí Es una descripción breve del programa de TV en vivo (consulta LocalizedString). Cada valor tiene entre 1 y 400 puntos de código Unicode.
localized_media_images array of LocalizedMediaImage Sí Imágenes de material gráfico de 16:9, una entrada por idioma (consulta LocalizedMediaImage). Debe contener al menos una imagen. Proporciona el archivo de origen más grande disponible; se recomienda que sea de 1920 x 1080 píxeles.
localized_provider_playback_uris array of LocalizedProviderPlaybackUri Sí Vínculos directos por plataforma y por idioma (consulta LocalizedProviderPlaybackUri). Al menos una entrada debe incluir PLATFORM_ANDROID_TV.
broadcast_interval Interval Sí Inicio y finalización de la transmisión del programa (consulta Interval). Se requieren start_time y end_time.
external_entity_ids array of ExternalEntityId No Identificadores de catálogo externos para la coincidencia de entidades (consulta ExternalEntityId). Como máximo, una entrada por tipo de identificador.
content_ratings array of ContentRating No Clasificaciones del contenido oficiales (consulta ContentRating)

Esquemas compatibles

Las cargas útiles candidatas hacen referencia a los siguientes objetos compartidos para el texto localizado, los vínculos directos, el material gráfico, los identificadores externos, los motivos de la recomendación, los intervalos de visualización, las clasificaciones de contenido y los tipos de fecha y hora conocidos.

LocalizedString

El objeto LocalizedString contiene el mismo texto en uno o más idiomas. Cada valor se etiqueta con su idioma para que los dispositivos Google TV y Android TV puedan mostrar el texto que coincida con el idioma del dispositivo de TV del usuario:

Campo Tipo Obligatorio Descripción
values array of LocalizedText Sí Es el texto en cada idioma que proporcionas (consulta LocalizedText). Debe contener al menos un valor.

LocalizedText

El objeto LocalizedText es texto en un solo idioma:

Campo Tipo Obligatorio Descripción
text string Sí Es el texto en el idioma que se indica en language_code.
language_code string Sí Es el código de idioma BCP-47 de text, como "en-US" o "sr-Latn".

LocalizedMediaImage

El objeto LocalizedMediaImage vincula una imagen con el idioma de cualquier texto que aparezca en ella:

Campo Tipo Obligatorio Descripción
language_code string Sí Es el código de idioma BCP-47 del texto de la imagen, como "en-US" o "sr-Latn".
image MediaImage Sí Una imagen de 16:9 (consulta MediaImage). Proporciona la fuente más grande disponible; se recomienda 1920 x 1080 píxeles.

LocalizedProviderPlaybackUri

El objeto LocalizedProviderPlaybackUri vincula un vínculo directo con el idioma del contenido que abre y la app que lo abre:

Campo Tipo Obligatorio Descripción
playback_uri PlaybackUri Sí El vínculo directo y las plataformas a las que se aplica (consulta PlaybackUri)
language_code string Sí Es el código de idioma BCP-47 del contenido que abre el vínculo directo, como "en-US" o "sr-Latn".
package_name string Sí Es el nombre del paquete de aplicación para Android que se usa para abrir el vínculo directo (por ejemplo, "com.example.tvapp").

PlaybackUri

El objeto PlaybackUri define un vínculo directo y sus plataformas de destino:

Campo Tipo Obligatorio Descripción
uri string Sí Es el URI del vínculo directo que inicia la reproducción del candidato en tu app.
platforms array of string (enum) Sí Son las plataformas a las que se aplica este vínculo directo. Valores permitidos: PLATFORM_UNSPECIFIED, PLATFORM_ANDROID_TV, PLATFORM_ANDROID, PLATFORM_IOS. Incluye PLATFORM_ANDROID_TV para dispositivos Google TV y Android TV.

MediaImage

El objeto MediaImage especifica una URL de imagen, sus dimensiones en píxeles y el texto de accesibilidad:

Campo Tipo Obligatorio Descripción
url string Sí Es la URL HTTPS de acceso público de la imagen.
width integer Sí Es el ancho máximo de la imagen sin modificar, en píxeles.
height integer Sí Es la altura máxima de la imagen sin modificar en píxeles.
accessibility_text string Sí Texto de accesibilidad (alternativo) que describe la imagen.

ExternalEntityId

El objeto ExternalEntityId asigna un candidato a un identificador en un catálogo externo. Establece exactamente uno de los siguientes campos por entrada y, como máximo, incluye una entrada por tipo de identificador en la lista external_entity_ids de un candidato:

Campo Tipo Obligatorio Descripción
tms_root_id string Uno de ID raíz de TMS de Gracenote. Identifica un título: una película, un programa o un episodio.
tms_id string Uno de Es el ID de la variante de TMS de Gracenote. Identifica una edición o una ficha de transmisión.
data_feed_element_id string Uno de Es el ID de la entidad de tu feed de datos de Acciones multimedia. Este valor no está relacionado con el segmento {recommendationsFeed} del nombre del recurso.

RecommendationContext

El objeto RecommendationContext explica por qué se recomienda un candidato y durante cuánto tiempo se aplica esa explicación:

Campo Tipo Obligatorio Descripción
recommendation_reason RecommendationReason No Por qué se recomienda el candidato (consulta RecommendationReason).
validity_interval Interval No Es el período durante el cual se aplica este contexto (consulta Interval). Por ejemplo, un candidato es nuevo solo durante una cantidad limitada de días. Si no se establece, el contexto se aplica mientras se almacene el candidato.

RecommendationReason

El objeto RecommendationReason contiene un motivo. Establece exactamente uno de los siguientes campos:

Campo Tipo Obligatorio Descripción
top_on_partner object Uno de El candidato es un elemento que ocupa una posición alta en tu servicio. Contiene un solo campo de número entero positivo rank (por ejemplo, {"rank": 1} para "Top 1 on Partner").
popular_on_partner object Uno de El candidato es popular en tu servicio. Pasa un objeto vacío ({}).
new_on_partner object Uno de El candidato es nuevo en tu servicio. Pasa un objeto vacío ({}).
generic object Uno de Un motivo personalizado Contiene un solo campo LocalizedString generic_reason (consulta LocalizedString). Cada valor tiene entre 1 y 100 puntos de código Unicode.

ContentRating

El objeto ContentRating representa una clasificación de contenido oficial asignada por una agencia de clasificación:

Campo Tipo Obligatorio Descripción
rating_system string Sí Es la agencia o el sistema de clasificación, por ejemplo, "MPAA", "BBFC" o "CBFC".
rating_value string Sí Es la clasificación según lo define rating_system, por ejemplo, "PG-13" o "U/A 13+".

Timestamp

Un Timestamp se codifica en JSON como una cadena RFC 3339 en UTC con un sufijo Z, por ejemplo, "2026-10-01T18:00:00Z". Se permiten fracciones de segundos, por ejemplo, "2026-10-01T18:00:00.500Z".

Duration

Un Duration se codifica en JSON como una cadena que contiene la cantidad de segundos seguida del sufijo s, por ejemplo, "7200s" para 2 horas. Se permiten segundos fraccionarios, por ejemplo, "5400.5s".

Date

Un Date es una fecha de calendario sin zona horaria. Se codifica en JSON como un objeto con los siguientes campos:

Campo Tipo Obligatorio Descripción
year integer Sí Año de la fecha, por ejemplo, 2025.
month integer No Mes del año, de 1 a 12. Establécelo en 0 o, si no se conoce el mes, omítelo.
day integer No Es el día del mes, de 1 a 31, y es válido para el año y el mes indicados. Establécelo en 0 o, si no se conoce el día, omítelo. Se requiere month.

Por ejemplo, {"year": 2025, "month": 1, "day": 17} representa el 17 de enero de 2025, {"year": 2025, "month": 1} representa enero de 2025 con un día desconocido y {"year": 2025} representa una fecha en 2025 con un mes y un día desconocidos.

Interval

Un Interval es un período semiabierto que comienza en start_time (inclusive) y finaliza en end_time (exclusivo). Un tiempo T está dentro del intervalo cuando start_time <= T y T < end_time.

Campo Tipo Obligatorio Descripción
start_time string (Timestamp) Sí Es el inicio inclusivo de la ventana (consulta Timestamp), por ejemplo, "2026-10-01T18:00:00Z".
end_time string (Timestamp) Sí Es el final exclusivo de la ventana (consulta Timestamp), por ejemplo, "2026-10-01T21:00:00Z". Debe ser posterior al start_time.

Ejemplo de solicitud

En el siguiente ejemplo, se reemplazan los candidatos del feed in-en-cricket del socio example-partner por tres candidatos (una película, un programa de TV y un programa de TV en vivo). La película tiene texto en dos idiomas:

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"
          }
        ]
      }
    ]
  }'

Comportamiento de respuesta y reemplazo

En esta sección, se describe la respuesta HTTP que devuelve replaceCandidates y cómo cada llamada actualiza los candidatos almacenados.

ReplaceCandidatesResponse

Si la solicitud se realiza correctamente, la API devuelve el código HTTP 200 OK con un cuerpo ReplaceCandidatesResponse:

Campo Tipo Descripción
replaced_candidates_count integer (int32) Es la cantidad de candidatos reemplazados.

Para la solicitud de ejemplo anterior, la respuesta es la siguiente:

{
  "replaced_candidates_count": 3
}

Comportamiento de reemplazo

Comprender cómo replaceCandidates actualiza los candidatos almacenados es esencial para diseñar tu integración:

  • Reemplazo completo por feed. Cada llamada reemplaza por completo la lista de candidatos almacenada anteriormente para el feed que se indica en la ruta de URL. Envía siempre el conjunto completo de candidatos activos para ese feed.
  • Los demás feeds no cambian. Los feeds a los que no envías candidatos permanecen sin cambios hasta que lo haces. Por ejemplo, reemplazar los candidatos de un feed no modifica los candidatos almacenados para ningún otro feed, y reemplazar los candidatos de {recommendationsFeed}-staging no modifica {recommendationsFeed}.
  • Una llamada por feed. Para actualizar varios feeds, realiza una llamada por feed. Las llamadas son independientes: si una falla, los otros feeds conservan sus candidatos nuevos y solo vuelves a intentar la llamada que falló.
  • Vuelve a enviar los feeds de actividad activos al menos cada 30 días. Incluso si tu catálogo para un feed no cambió, vuelve a enviar cada feed activo al menos una vez cada 30 días (o en un programa diario o semanal regular con fluctuación aleatoria) para que tus candidatos permanezcan activos y no venzan. Establecer un end_time de availability_intervals en un futuro lejano no reemplaza el reenvío periódico.
  • Ejecución atómica. La API aplica la solicitud de forma atómica. Si algún candidato no supera la validación, la API rechaza toda la solicitud y el feed conserva sus candidatos anteriores.