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:
- 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.
- 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). - 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.
- 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.
- 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. 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: Beareren 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}-stagingno 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_timedeavailability_intervalsen 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.