A API REST de descoberta de vídeos do Google TV permite que os parceiros enviem candidatos a recomendações não personalizadas para dispositivos Google TV e dispositivos Android TV usando os servidores de back-end deles. O envio de candidatos do back-end mantém as recomendações de catálogo e programação ao vivo de um parceiro atualizadas nesses dispositivos sem que os usuários precisem abrir o app do parceiro.
Os parceiros enviam candidatos para feeds de recomendações. O Google cria cada feed para o parceiro e configura os países ou regiões e os idiomas do dispositivo de TV em que o feed é exibido. Um feed pode conter filmes, programas de TV e programas de TV ao vivo.
Se você quiser publicar recomendações personalizadas do dispositivo do usuário, consulte Integrar recomendações no dispositivo usando o SDK Engage.
Pré-requisitos
Antes de fazer a integração com a API REST, verifique se você tem o seguinte:
- Um projeto na nuvem do Google Cloud para fazer solicitações de API.
- Uma conta do Google Workspace associada à sua organização.
- Seu ID de parceiro e os IDs do feed de recomendações, fornecidos pelo representante de parceiros do Google TV durante a integração. Consulte Feeds de recomendações para saber como esses IDs são usados.
Quero acessar
O acesso à API REST de descoberta de vídeos do Google TV é restrito a parceiros de mídia registrados do Google TV. Cada autor da chamada é autenticado usando uma conta de serviço do Google Cloud que é mapeada no servidor para exatamente um ID de parceiro.
Para solicitar e configurar o acesso à API, siga estas etapas:
- Crie uma conta do Google Workspace. Siga as instruções na página de suporte do Google Workspace para configurar uma conta para sua organização.
- Localize seu ID de cliente do Google Workspace. Encontre seu ID de cliente (por exemplo,
C0123abcd) seguindo as etapas em Encontrar seu ID de cliente. - Crie um projeto na nuvem e uma conta de serviço do Google Cloud. No console do Google Cloud, na organização do Google Workspace, crie um projeto do Google Cloud e uma conta de serviço para o servidor de back-end.
- Solicite a integração do parceiro. Informe seu ID de cliente do Google Workspace, ID do projeto do Google Cloud e endereço de e-mail da conta de serviço (ou ID numérico exclusivo) ao representante do parceiro do Google TV, junto com os países ou regiões e os idiomas do dispositivo de TV para os quais você quer enviar candidatos. O representante do parceiro do Google TV vai notificar você depois de mapear a organização, o projeto e a conta de serviço do Google Workspace para seu ID de parceiro e vai fornecer os IDs de feed de recomendações criados para seu parceiro.
- Ative a API e gere credenciais. Depois que o representante
confirmar que o acesso foi concedido, ative a API Google TV Video Discovery
(
tvvideodiscovery.googleapis.com) no seu projeto na nuvem do Google Cloud e gere credenciais do OAuth 2.0 para sua conta de serviço. Autentique suas solicitações. Solicite tokens de acesso do OAuth 2.0 usando o seguinte escopo do OAuth e transmita o token no cabeçalho HTTP
Authorization: Bearerem cada chamada:https://www.googleapis.com/auth/tvvideodiscovery
Limites de taxas
As solicitações para replaceCandidates estão sujeitas aos seguintes limites de taxa por projeto e limites de payload por solicitação:
| Limite | Valor |
|---|---|
| Solicitações por minuto por projeto do Google Cloud | 5 |
| Solicitações por dia por projeto do Google Cloud | 100 |
RecommendationCandidate itens por solicitação |
1 a 25 |
As solicitações para um feed de teste são contabilizadas na mesma cota que as solicitações para o feed de produção correspondente.
Feeds de recomendações
A API organiza os candidatos a recomendação em feeds de recomendações. Um feed é identificado por um nome de recurso com o seguinte formato:
partners/{partner}/recommendationsFeeds/{recommendationsFeed}
Parceiros
{partner} é o ID do parceiro que o Google atribui a você durante a integração. A conta de serviço usada para autenticação é mapeada para exatamente um ID de parceiro.
As solicitações que nomeiam qualquer outro parceiro falham com 403 PERMISSION_DENIED.
IDs de feed
{recommendationsFeed} é um ID de feed que o Google cria para você durante
a integração. Não é possível criar feeds com a API.
Cada feed segmenta um público-alvo que o Google configura ao criar o feed:
- Países ou regiões: onde os candidatos do feed são mostrados.
- Idiomas do dispositivo de TV: os idiomas que os usuários segmentados definiram no dispositivo de TV. Esse não é o idioma do texto que você envia. Para
fornecer texto em mais de um idioma, consulte
LocalizedString.
O Google decide onde os candidatos de um feed aparecem nos dispositivos Google TV e Android TV. Você envia candidatos para todos os feeds da mesma forma.
Feeds de preparo
Cada feed tem um feed de preparo correspondente chamado {recommendationsFeed}-staging. Um
feed de preparo é veiculado apenas para contas de teste em uma lista de permissões. Use-o para
validar sua integração antes de enviar candidatos ao feed de produção.
Os feeds de preparo usam o mesmo endpoint, as mesmas credenciais, a mesma validação de solicitação e a mesma cota dos feeds de produção. Apenas o público é diferente.
Substituição
O feed é a unidade de substituição. Cada chamada replaceCandidates substitui todos os candidatos armazenados anteriormente para esse feed e deixa todos os outros feeds intocados.
Substituir candidatos à recomendação
Use o método partners.recommendationsFeeds.replaceCandidates para enviar a
lista completa de candidatos à recomendação de um feed.
Solicitação HTTP
POST https://tvvideodiscovery.googleapis.com/v1/{name=partners/*/recommendationsFeeds/*}:replaceCandidates
O caminho do URL contém o nome do recurso do feed em que os candidatos são substituídos. O corpo da solicitação contém todos os campos que não fazem parte do caminho do URL.
Parâmetros de caminho
| Parâmetro | Descrição |
|---|---|
name |
Obrigatório. O nome do recurso do feed, no formato partners/{partner}/recommendationsFeeds/{recommendationsFeed}. {partner} precisa ser o ID do parceiro ao qual sua conta de serviço está mapeada. {recommendationsFeed} precisa ser um ID de feed que o Google criou para esse parceiro ou esse ID de feed com o sufixo -staging. |
ReplaceCandidatesRequest
O corpo da solicitação JSON tem a seguinte estrutura:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
recommendation_candidates |
array of RecommendationCandidate |
Sim | Uma lista de 1 a 25 itens RecommendationCandidate. Esses candidatos substituem os atuais do feed. |
Esquemas candidatos
Cada item em recommendation_candidates é um objeto RecommendationCandidate
que contém um payload do tipo candidato, motivos de recomendação opcionais e
períodos de disponibilidade de exibição opcionais.
RecommendationCandidate
Um objeto RecommendationCandidate contém exatamente um campo de payload de tipo de mídia,
motivos de recomendação opcionais e intervalos de disponibilidade opcionais.
Campo de união candidate_type
candidate_type é obrigatório: defina exatamente um dos campos a seguir. Os campos são mutuamente exclusivos, e um candidato que não define nenhum ou mais de um é rejeitado. Não há chave candidate_type no JSON. Defina o campo escolhido
diretamente no objeto RecommendationCandidate.
| Campo | Tipo | Descrição |
|---|---|---|
movie_candidate |
MovieCandidate |
Um filme on demand (consulte MovieCandidate). |
tv_show_candidate |
TvShowCandidate |
Uma série de TV no nível do programa (consulte TvShowCandidate). |
live_tv_program_candidate |
LiveTvProgramCandidate |
Uma transmissão de TV ao vivo programada ou um evento transmitido (consulte LiveTvProgramCandidate). |
Contexto e disponibilidade
Os dois campos são opcionais:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
recommendation_contexts |
array of RecommendationContext |
Não | Por que o candidato é recomendado e por quanto tempo cada motivo se aplica (consulte RecommendationContext). |
availability_intervals |
array of Interval |
Não | Janelas de tempo em que o candidato pode ser mostrado (consulte Interval). Cada janela começa em start_time (inclusive) e termina em end_time (exclusive). Se não for definido, o candidato vai se qualificar enquanto estiver armazenado. Um candidato com todas as janelas no passado nunca é mostrado. |
MovieCandidate
O objeto MovieCandidate representa um filme on demand:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
title |
LocalizedString |
Sim | Título do filme (consulte LocalizedString). Cada valor tem de 1 a 100 pontos de código Unicode e é mostrado como enviado. |
description |
LocalizedString |
Sim | Breve descrição do filme (consulte LocalizedString). Cada valor tem de 1 a 400 pontos de código Unicode. |
localized_media_images |
array of LocalizedMediaImage |
Sim | Imagens de arte em 16:9, uma entrada por idioma (consulte LocalizedMediaImage). É necessário incluir pelo menos uma imagem. Forneça a maior fonte disponível. Recomendamos 1920 x 1080 pixels. |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
Sim | Links diretos por plataforma e por idioma (consulte LocalizedProviderPlaybackUri). Pelo menos uma entrada precisa listar PLATFORM_ANDROID_TV. |
release_date |
Date |
Sim | Data de lançamento do filme (consulte Date). |
external_entity_ids |
array of ExternalEntityId |
Não | Identificadores de catálogo externo para correspondência de entidades (consulte ExternalEntityId). No máximo uma entrada por tipo de identificador. |
duration |
string (Duration) |
Não | A duração do filme (consulte Duration). Por exemplo, "7200s" para 2 horas. |
content_ratings |
array of ContentRating |
Não | Classificações oficiais de conteúdo (consulte ContentRating). |
TvShowCandidate
O objeto TvShowCandidate representa uma série de TV no nível da série. Os dispositivos Google TV
e Android TV mostram um card para o programa. Use o link direto para decidir
se a reprodução começa na página do programa ou em um episódio específico.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
title |
LocalizedString |
Sim | Título da série de TV (consulte LocalizedString). Cada valor tem de 1 a 100 pontos de código Unicode e é mostrado como enviado. |
description |
LocalizedString |
Sim | Breve descrição do programa de TV (consulte LocalizedString). Cada valor tem de 1 a 400 pontos de código Unicode. |
localized_media_images |
array of LocalizedMediaImage |
Sim | Imagens de arte em 16:9, uma entrada por idioma (consulte LocalizedMediaImage). É necessário incluir pelo menos uma imagem. Forneça a maior fonte disponível. Recomendamos 1920 x 1080 pixels. |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
Sim | Links diretos por plataforma e por idioma (consulte LocalizedProviderPlaybackUri). Pelo menos uma entrada precisa listar PLATFORM_ANDROID_TV. O uri pode apontar para a página do programa ou para um episódio. |
first_episode_air_date |
Date |
Sim | Data de estreia do primeiro episódio (consulte Date). |
external_entity_ids |
array of ExternalEntityId |
Não | Identificadores de catálogo externo para correspondência de entidades (consulte ExternalEntityId). No máximo uma entrada por tipo de identificador. |
season_count |
integer (int32) |
Não | Número de temporadas disponíveis no seu serviço. |
content_ratings |
array of ContentRating |
Não | Classificações oficiais de conteúdo (consulte ContentRating). |
LiveTvProgramCandidate
O objeto LiveTvProgramCandidate representa uma transmissão de TV ao vivo programada ou
um evento transmitido. A janela de transmissão faz parte do candidato e é separada do availability_intervals do candidato pai, que controla quando o card pode ser mostrado.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
title |
LocalizedString |
Sim | Título do programa de TV ao vivo (consulte LocalizedString). Cada valor tem de 1 a 100 pontos de código Unicode e é mostrado como enviado. |
description |
LocalizedString |
Sim | Breve descrição do programa de TV ao vivo (consulte LocalizedString). Cada valor tem de 1 a 400 pontos de código Unicode. |
localized_media_images |
array of LocalizedMediaImage |
Sim | Imagens de arte em 16:9, uma entrada por idioma (consulte LocalizedMediaImage). É necessário incluir pelo menos uma imagem. Forneça a maior fonte disponível. Recomendamos 1920 x 1080 pixels. |
localized_provider_playback_uris |
array of LocalizedProviderPlaybackUri |
Sim | Links diretos por plataforma e por idioma (consulte LocalizedProviderPlaybackUri). Pelo menos uma entrada precisa listar PLATFORM_ANDROID_TV. |
broadcast_interval |
Interval |
Sim | Início e fim da transmissão do programa (consulte Interval). start_time e end_time são obrigatórios. |
external_entity_ids |
array of ExternalEntityId |
Não | Identificadores de catálogo externo para correspondência de entidades (consulte ExternalEntityId). No máximo uma entrada por tipo de identificador. |
content_ratings |
array of ContentRating |
Não | Classificações oficiais de conteúdo (consulte ContentRating). |
Esquemas de suporte
Os payloads candidatos fazem referência aos seguintes objetos compartilhados para texto localizado, links diretos, arte, identificadores externos, motivos de recomendação, intervalos de exibição, classificações de conteúdo e tipos de data e hora conhecidos.
LocalizedString
O objeto LocalizedString carrega o mesmo texto em um ou mais idiomas.
Cada valor é marcado com o idioma para que os dispositivos Google TV e Android TV
possam mostrar o texto que corresponde ao idioma do dispositivo de TV do usuário:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
values |
array of LocalizedText |
Sim | O texto em cada idioma que você fornecer (consulte LocalizedText). Precisa conter pelo menos um valor. |
LocalizedText
O objeto LocalizedText é um texto em um único idioma:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
text |
string |
Sim | O texto no idioma fornecido por language_code. |
language_code |
string |
Sim | Código de idioma BCP-47 de text, como "en-US" ou "sr-Latn". |
LocalizedMediaImage
O objeto LocalizedMediaImage associa uma imagem ao idioma de qualquer texto
nela:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
language_code |
string |
Sim | Código de idioma BCP-47 do texto na imagem, como "en-US" ou "sr-Latn". |
image |
MediaImage |
Sim | Uma imagem de 16:9 (consulte MediaImage). Forneça a maior fonte disponível. Recomendamos 1920 x 1080 pixels. |
LocalizedProviderPlaybackUri
O objeto LocalizedProviderPlaybackUri associa um link direto ao idioma
do conteúdo que ele abre e ao app que o abre:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
playback_uri |
PlaybackUri |
Sim | O link direto e as plataformas em que ele se aplica (consulte PlaybackUri). |
language_code |
string |
Sim | Código de idioma BCP-47 do conteúdo que o link direto abre, como "en-US" ou "sr-Latn". |
package_name |
string |
Sim | Nome do pacote de aplicativo Android usado para abrir o link direto (por exemplo, "com.example.tvapp"). |
PlaybackUri
O objeto PlaybackUri define um link direto e as plataformas de destino:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
uri |
string |
Sim | URI do link direto que inicia a reprodução do candidato no seu app. |
platforms |
array of string (enum) |
Sim | Plataformas em que este link direto é válido. Valores permitidos: PLATFORM_UNSPECIFIED, PLATFORM_ANDROID_TV, PLATFORM_ANDROID, PLATFORM_IOS. Inclua PLATFORM_ANDROID_TV para dispositivos Google TV e Android TV. |
MediaImage
O objeto MediaImage especifica um URL de imagem, as dimensões em pixels e o texto de acessibilidade:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
url |
string |
Sim | URL HTTPS de acesso público da imagem. |
width |
integer |
Sim | Largura da imagem não modificada (máxima) em pixels. |
height |
integer |
Sim | Altura máxima da imagem não modificada em pixels. |
accessibility_text |
string |
Sim | Texto de acessibilidade (alternativo) que descreve a imagem. |
ExternalEntityId
O objeto ExternalEntityId mapeia um candidato para um identificador em um catálogo
externo. Defina exatamente um dos campos a seguir por entrada e inclua no máximo uma entrada por tipo de identificador na lista external_entity_ids de um candidato:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
tms_root_id |
string |
Uma | ID raiz do TMS da Gracenote. Identifica um título: um filme, um programa ou um episódio. |
tms_id |
string |
Uma | ID da variante do TMS da Gracenote. Identifica uma edição ou uma listagem de transmissão. |
data_feed_element_id |
string |
Uma | ID da entidade do seu feed de dados de ações de mídia. Esse valor não está relacionado ao segmento {recommendationsFeed} do nome do recurso. |
RecommendationContext
O objeto RecommendationContext explica por que um candidato é recomendado e
por quanto tempo essa explicação se aplica:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
recommendation_reason |
RecommendationReason |
Não | Por que o candidato é recomendado (consulte RecommendationReason). |
validity_interval |
Interval |
Não | Janela de tempo em que esse contexto se aplica (consulte Interval). Por exemplo, um candidato é novo apenas por um número limitado de dias. Se não for definido, o contexto será aplicado enquanto o candidato estiver armazenado. |
RecommendationReason
O objeto RecommendationReason carrega um motivo. Defina exatamente um dos
seguintes campos:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
top_on_partner |
object |
Uma | O candidato é um item de classificação superior no seu serviço. Contém um único campo de número inteiro positivo rank (por exemplo, {"rank": 1} para "Top 1 no parceiro"). |
popular_on_partner |
object |
Uma | O candidato é popular no seu serviço. Transmita um objeto vazio ({}). |
new_on_partner |
object |
Uma | O candidato é novo no seu serviço. Transmita um objeto vazio ({}). |
generic |
object |
Uma | Um motivo personalizado. Contém um único campo LocalizedString generic_reason (consulte LocalizedString). Cada valor tem de 1 a 100 pontos de código Unicode. |
ContentRating
O objeto ContentRating representa uma classificação de conteúdo oficial atribuída por uma
agência de classificação:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
rating_system |
string |
Sim | Agência ou sistema de classificação, por exemplo, "MPAA", "BBFC" ou "CBFC". |
rating_value |
string |
Sim | Classificação conforme definido por rating_system, por exemplo, "PG-13" ou "U/A 13+". |
Timestamp
Um Timestamp é codificado em JSON como uma string RFC 3339 em UTC com um sufixo Z, por exemplo, "2026-10-01T18:00:00Z". Frações de segundos são permitidas,
por exemplo, "2026-10-01T18:00:00.500Z".
Duration
Um Duration é codificado em JSON como uma string que contém o número de segundos
seguido pelo sufixo s, por exemplo, "7200s" para 2 horas. Segundos fracionários são permitidos, por exemplo, "5400.5s".
Date
Um Date é uma data de calendário sem fuso horário. Ele é codificado em JSON como um
objeto com os seguintes campos:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
year |
integer |
Sim | Ano da data, por exemplo, 2025. |
month |
integer |
Não | Mês do ano, de 1 a 12. Defina como 0 ou omita se o mês não for conhecido. |
day |
integer |
Não | Dia do mês, de 1 a 31, válido para o ano e o mês informados. Defina como 0 ou omita se o dia não for conhecido. Requer month. |
Por exemplo, {"year": 2025, "month": 1, "day": 17} representa 17 de janeiro de 2025, {"year": 2025, "month": 1} representa janeiro de 2025 com um dia desconhecido e {"year": 2025} representa uma data em 2025 com um mês e dia desconhecidos.
Interval
Um Interval é uma janela de tempo semiaberta que começa em start_time
(inclusive) e termina em end_time (exclusive). Um horário T está dentro do intervalo quando start_time <= T e T < end_time.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
start_time |
string (Timestamp) |
Sim | Início inclusivo da janela (consulte Timestamp), por exemplo, "2026-10-01T18:00:00Z". |
end_time |
string (Timestamp) |
Sim | Fim exclusivo da janela (consulte Timestamp), por exemplo, "2026-10-01T21:00:00Z". Precisa ser posterior a start_time. |
Exemplo de solicitação
O exemplo a seguir substitui os candidatos do feed in-en-cricket do
parceiro example-partner por três candidatos (um filme, um programa de TV e um programa de TV
ao vivo). O filme tem texto em dois 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"
}
]
}
]
}'
Comportamento de resposta e substituição
Nesta seção, descrevemos a resposta HTTP retornada por replaceCandidates e
como cada chamada atualiza os candidatos armazenados.
ReplaceCandidatesResponse
Se a solicitação for bem-sucedida, a API vai retornar HTTP 200 OK com um corpo ReplaceCandidatesResponse:
| Campo | Tipo | Descrição |
|---|---|---|
replaced_candidates_count |
integer (int32) |
Número de candidatos substituídos. |
Para o exemplo de solicitação anterior, a resposta é:
{
"replaced_candidates_count": 3
}
Comportamento de substituição
Entender como o replaceCandidates atualiza os candidatos armazenados é essencial
para projetar sua integração:
- Substituição completa por feed. Cada chamada substitui completamente a lista de candidatos armazenada anteriormente para o feed nomeado no caminho do URL. Sempre envie o conjunto completo de candidatos ativos para esse feed.
- Os outros feeds permanecem inalterados. Os feeds para os quais você não envia candidatos
permanecem inalterados até que você faça isso. Por exemplo, substituir os candidatos de um
feed não modifica os candidatos armazenados para nenhum outro feed, e substituir
os candidatos de
{recommendationsFeed}-stagingnão modifica{recommendationsFeed}. - Uma chamada por feed. Para atualizar vários feeds, faça uma chamada por feed. As chamadas são independentes: se uma falhar, os outros feeds vão manter os novos candidatos, e você vai tentar novamente apenas a chamada que falhou.
- Reenvie os feeds ativos pelo menos a cada 30 dias. Mesmo que o catálogo de um
feed não tenha mudado, reenvie cada feed ativo pelo menos uma vez a cada 30 dias
(ou em uma programação diária ou semanal regular com jitter aleatório) para que os
candidatos permaneçam ativos e não expirem. Definir um
end_timeavailability_intervalsmuito distante no futuro não substitui o reenvio periódico. - Execução atômica. A API aplica a solicitação de forma atômica. Se algum candidato não for validado, a API vai rejeitar toda a solicitação, e o feed vai manter os candidatos anteriores.