API do Conjunto de dados de programas lineares ao vivo

Access session-level, program-grain viewership data for your Prime Video linear channels.

~13 min de leitura outubro 2, 2026

Este guia aborda tudo o que você precisa para acessar e usar a API do Conjunto de dados de programas lineares ao vivo

O que você vai aprender

  • O que a API fornece e quais feeds estão disponíveis.
  • Como fazer a autenticação e recuperar os arquivos do conjunto de dados.
  • O modelo de dados completo e as definições das colunas.
  • Como funcionam o registro de alterações e o sinal is_deleted.
  • Padrões de deduplicação e de MERGE que você pode copiar para o seu pipeline.
  • Cadência de ingestão recomendada.
  • Exemplos de consultas SQL para análises comuns.

Visão geral

A API do Conjunto de dados de programas lineares ao vivo fornece dados de audiência no nível do programa para os seus canais lineares ao vivo e FAST do Prime Video. Cada registro representa uma sessão de visualização de um programa agendado em um canal.

Os dados são entregues como um registro de alterações, com sinais is_deleted para as correções de programação. Há dois feeds disponíveis: Canais (linear_program_event_log) e FAST (fast_linear_program_event_log).

Com esses dados, você pode:

  • Acompanhar a audiência no nível do programa (horas visualizadas, sessões) por estação, território, dispositivo e período.
  • Analisar o desempenho por estação, programa, série e tipo de conteúdo.
  • Acompanhar com precisão as correções de programação, sem linhas desatualizadas nos seus dados.
  • Integrar a audiência linear ao vivo aos seus sistemas internos e fontes de dados.

Para análises baseadas em painéis, consulte: Programação linear no Slate Analytics

Principais recursos

Recurso

Detalhes

Detalhamento no nível do programa

Uma linha por sessão de visualização, programa e programação. Inclui título, estação, série, janela de exibição e tempo assistido.

Sinal de remoção

As programações substituídas ou retiradas são reenviadas com is_deleted = 1, sinalizando que não são mais válidas.

Chave única estável

Toda linha traz session_program_schedule_id. Use-a para fazer a deduplicação e o MERGE.

Ingestão simplificada

Modelo de registro de alterações. Agende chamadas recorrentes e, depois, faça o MERGE. Faça o upsert em is_deleted = 0. Exclua definitivamente ou de forma reversível em is_deleted = 1.

Consistência

Formatação padronizada em todos os territórios em uma única fonte. Não são necessárias tabelas dimensionais por território.

Conceitos-chave

Conceito

Descrição

Linha de sessão-programa-programação

Uma sessão de visualização de um programa em um horário da programação. Identificada por session_program_schedule_id.

Modelo de registro de alterações

Os dados são um registro de alterações. Se os atributos de uma linha mudarem, uma nova versão será publicada com o mesmo session_program_schedule_id e um last_update_time_utc mais recente.

Chave primária

session_program_schedule_id é o identificador exclusivo. Sempre faça a deduplicação por esse campo.

Sinal is_deleted

is_deleted = 0 significa que a programação está ativa. is_deleted = 1 indica que a programação não está mais ativa ou válida.

Como aplicar o sinal

is_deleted = 0: insira ou atualize a linha. is_deleted = 1: faça com que ela deixe de aparecer nos seus dados atuais. Exclua a linha ou mantenha-a sinalizada e filtre-a.

Primeiros passos

Como fazer a integração
A API do Conjunto de dados de programas lineares ao vivo faz parte do Pacote de APIs de análise. Ao fazer a integração ao Pacote de APIs de análise, você recebe acesso a todas as APIs disponíveis nesse pacote, inclusive à API do Conjunto de dados de programas lineares ao vivo (se solicitada durante a integração). Para obter instruções detalhadas de integração, acesse a página de integração da API de análise.

Pré-requisitos
Antes de fazer solicitações de API, você precisa do seguinte:

  • Um perfil de segurança do Login com a Amazon (LWA). Envie a sua ID do cliente ao seu CAM para que ela seja adicionada à página de administração interna do PV.
  • Um código de autorização para solicitar um token.
  • Um token para todas as solicitações de API.

URI base: https://videocentral.amazon.com/apis/v2

Todas as solicitações devem incluir um token de autenticação LWA válido no cabeçalho de autorização. Se o token estiver ausente ou expirado, a API retornará uma exceção de não autorizado.

Paginação
Todas as respostas são paginadas. Use estes parâmetros para navegar pelas páginas:

Parâmetro

Padrão

Descrição

limit

10

Número de documentos retornados por página. Máximo de 1.000.

offset

0

Número de documentos a ignorar antes do primeiro resultado. Use a URL do campo next em vez de calcular esse valor.

Todas as respostas paginadas incluem estes campos:

Campo

Descrição

total

Contagem total de documentos em todas as páginas.

next

URL para a próxima página. Null se esta for a última página.

Recuperação de arquivos do conjunto de dados

Endpoint
Use este comando curl para recuperar uma lista de links de arquivos do conjunto de dados que podem ser baixados:


Observação: Este endpoint retorna links para arquivos CSV compactados com gzip que podem ser baixados, e não as linhas diretamente.

Parâmetros

Parâmetro

Descrição

ACADIA_ID

A ID da sua conta Slate. Encontre-a em /v2/accounts.

REPORT_GROUP

O segmento da linha de negócios. Use channels para o feed de Canais ou fast para o feed FAST. Descubra o seu com GET /v2/accounts/{ACADIA_ID}.

IDENTIFIER_ID

O valor de id retornado pelo endpoint de identificadores. Em Canais, é um hash opaco. Use o campo id como fornecido. No FAST, é o seu código do fornecedor, retornado sem hash.

REPORT_ID

O relatório a extrair. Use linear_program_event_log para Canais ou fast_linear_program_event_log para o FAST.

startDateTime

Defina como o horário da última extração. Formato: YYYY-MM-DDThh:mm:ssZ (UTC).

endDateTime

Defina como o horário atual. Formato: YYYY-MM-DDThh:mm:ssZ (UTC).

limit

Mínimo de 1 e máximo de 1.000 links por página.

Relatórios disponíveis
Há dois relatórios disponíveis. Extraia cada um separadamente, inserindo a ID do relatório no segmento de caminho datasets/{REPORT_ID}:

Relatório

ID do relatório

Conteúdo

Canais

linear_program_event_log

Linear por SVOD/assinatura (3P_SUBS e FREE/PRIME, quando aplicável).

FAST

fast_linear_program_event_log

Canais lineares de televisão gratuita com anúncios (FAST) / com anúncios (AVOD)

Observação: A retenção máxima de dados é de dois anos. Solicitações com mais de dois anos não retornarão resultados.

Endpoints de descoberta

Use estes endpoints para encontrar a ID da sua conta, os grupos de relatórios, os identificadores e os conjuntos de dados disponíveis:

Endpoint

Retorno

GET /v2/accounts

Lista de contas do Slate a que você tem acesso.

GET /v2/accounts/{ACADIA_ID}

Linhas de negócios disponíveis (por exemplo, channels, fast).

GET /v2/accounts/{ACADIA_ID}/channels

Identificadores de relatório disponíveis para você. Cada entrada tem uma id e um nome amigável.

GET /v2/accounts/{ACADIA_ID}/channels/{IDENTIFIER_ID}/datasets

Conjuntos de dados disponíveis para esse identificador.

Colunas de dados

As colunas a seguir estão presentes no feed linear_program_event_log (Canais). O feed fast_linear_program_event_log (FAST) tem a mesma estrutura, com vendor_code acrescentado e as colunas de assinatura entregues como NULL.

Coluna

Tipo

Anulável

Descrição

session_program_schedule_id

STRING

Não

Chave primária. ID exclusiva (codifica a sessão, o programa e a janela de exibição). Faça a deduplicação e o MERGE por este campo. Muda quando o programa ou o horário de exibição mudam devido a metadados de EPG atualizados.

session_id

STRING

Não

Identificador exclusivo e anonimizado da sessão de visualização.

is_deleted

INT

Não

Sinal de status. 0 = a programação está ativa. 1 = a programação não está mais ativa (substituída ou retirada). Exclua dos seus dados atuais as linhas com is_deleted = 1.

last_update_time_utc

TIMESTAMP

Não

Horário da versão do registro. Use sempre para fazer a deduplicação. Mantenha a linha com o valor mais recente para cada ID.

create_time_utc

TIMESTAMP

Não

Quando a linha foi criada.

program_id

STRING

Não

Identificador do programa, por exemplo, a ID do TMS.

pv_title_id

STRING

Sim

Identificador global de título (GTI) do Prime Video para o programa. O mesmo que pv_title_id no feed de TVOD.

program_title

STRING

Sim

Título do programa.

station_name

STRING

Sim

Nome do canal ou da estação.

content_type

STRING

Não

live_broadcast ou scheduled_tv.

airing_start_utc

TIMESTAMP

Não

Início da exibição do programa (UTC).

airing_end_utc

TIMESTAMP

Não

Fim da exibição do programa (UTC).

start_segment_utc

TIMESTAMP

Não

Início da sessão de visualização (UTC).

end_segment_utc

TIMESTAMP

Não

Fim da sessão de visualização (UTC).

seconds_viewed

LONG

Não

Segundos visualizados nesta sessão.

vendor_sku

STRING

Sim

SKU do conteúdo (por exemplo, identificadores da Gracenote).

parent_channel_label

STRING

Sim

Identificador do canal principal, com hash.

cid

STRING

Sim

ID do canal (efetiva).

benefit_id

STRING

Sim

Identificador de direito/benefício.

subscription_offer_id

STRING

Sim

Identificador da oferta de assinatura.

subscription_event_id

STRING

Sim

Identificador do evento de assinatura.

subscription_offer_time_zone

STRING

Sim

Fuso horário da oferta de assinatura.

marketplace_id

INT

Não

Identificador do marketplace.

marketplace_desc

STRING

Sim

Descrição do marketplace.

territory

STRING

Sim

Código do território ou do país (US, GB, DE, AU e outros).

device_class

STRING

Sim

Categoria do dispositivo.

device_sub_class

STRING

Sim

Subcategoria do dispositivo.

connection_type

STRING

Sim

Tipo de conexão (wifi, com fio e outros).

playback_method

STRING

Sim

Como a sessão foi consumida: online (streaming) ou offline (download). O linear ao vivo é, na prática, sempre on-line.

geo_dma

STRING

Sim

DMA geográfica.

stream_type

STRING

Não

Sempre LINEAR_TV.

Observação sobre o feed FAST: O feed fast_linear_program_event_log tem a mesma estrutura. A coluna vendor_code (código do parceiro) está presente. As colunas de assinatura (subscription_offer_id, subscription_event_id, subscription_offer_time_zone) são entregues como NULL.

Como funciona o is_deleted

Toda linha traz is_deleted. É um sinal sobre o status da programação. Há dois valores:

Valor

Significado

Como aplicar

0

A programação está ativa (a versão atual).

Insira-a ou substitua a linha existente dessa chave.

1

A programação não está mais ativa (substituída ou retirada).

Faça com que ela deixe de aparecer nos seus dados atuais. Exclua a linha ou mantenha-a sinalizada e filtre-a.

Quando ocorre is_deleted = 1?

  • Correção de programação. O programa ou o horário de exibição foi corrigido. O session_program_schedule_id antigo chega com is_deleted = 1. Uma nova ID chega com is_deleted = 0. Trate a antiga como não mais ativa e insira a nova.
  • Exibição removida. A exibição foi totalmente retirada. A ID dela chega com is_deleted = 1.

Observações importantes

  • Um mesmo session_program_schedule_id nunca vem com 0 e com 1 no mesmo lote. Uma exibição corrigida passa a ter uma chave diferente.
  • As linhas que nunca atenderam aos critérios de qualificação do feed não são entregues. Não espere um is_deleted = 1 para uma linha que você nunca recebeu.

Deduplicação

Você pode receber o mesmo session_program_schedule_id mais de uma vez. São versões atualizadas da mesma linha. Faça a deduplicação em três etapas:

  1. Mantenha a versão mais recente de cada ID. Para cada ID, mantenha somente a linha com o last_update_time_utc mais recente e exclua as mais antigas. Esse valor só avança, portanto o mais recente sempre prevalece.


  1. Faça o MERGE das linhas deduplicadas na sua tabela. Use o padrão de MERGE abaixo. Trate o is_deleted sempre que carregar dados.

Use um MERGE, não uma inserção em massa. Se você carregar cada arquivo como novas linhas, as linhas com is_deleted = 1 ficarão na sua tabela como dados ativos, em vez de serem aplicadas. Sempre trate o sinalizador.

  1. Alternativa de exclusão reversível. Substitua a ramificação DELETE por UPDATE SET is_deleted = 1 e, depois, filtre com WHERE is_deleted = 0 nas suas consultas. Os dois métodos dão o mesmo resultado.

Cadência de ingestão recomendada

Novos conjuntos de dados são publicados de forma incremental ao longo do dia.

Recomendação

Detalhes

Cadência recomendada

De uma a quatro vezes por dia, para manter os dados atualizados.

Estratégia incremental

Defina startDateTime como o último carimbo de data/hora recuperado e endDateTime como o horário atual. Faça download e processe todos os arquivos retornados e, depois, faça o MERGE.

Consumidores diários/semanais

Se você faz a busca diária ou semanal, processe todos os arquivos do período. Assim, você não perde atualizações nem exclusões.

Observação: Cada lote mistura linhas ativas (is_deleted = 0) e linhas que não estão mais ativas (is_deleted = 1). Elas não são entregues em arquivos separados. A coluna is_deleted as diferencia.

Exemplo de uso da API

Siga estas etapas para descobrir a sua conta, identificar o seu grupo de relatórios e os identificadores e recuperar os arquivos do conjunto de dados.

Etapa 0: Liste as suas contas
Chame GET /v2/accounts para listar as contas do Slate a que você tem acesso.

Etapa 1: Linhas de negócios da conta
Chame GET /v2/accounts/12345678 para ver as linhas de negócios disponíveis.

O campo id é o segmento de caminho {REPORT_GROUP} a ser usado nas chamadas seguintes.

Etapa 2a: Identificadores de Canais
Chame GET /v2/accounts/12345678/channels?offset=0&limit=100 para listar os seus identificadores de Canais.

Etapa 2b: Identificadores do FAST
Chame GET /v2/accounts/12345678/fast?offset=0&limit=100 para listar os seus identificadores do FAST.

Etapa 2c: Conjuntos de dados disponíveis para um identificador
Chame GET /v2/accounts/12345678/fast/ABC123/datasets para listar os conjuntos de dados disponíveis.

Etapa 3a: Arquivos do conjunto de dados de Canais
Chame o endpoint de arquivos do conjunto de dados para o seu identificador de Canais. A resposta retorna uma lista de URLs de download de arquivos CSV compactados com gzip.

Etapa 3b: Arquivos do conjunto de dados do FAST
Chame o endpoint de arquivos do conjunto de dados para o seu identificador do FAST.

Exemplos de consultas

Estas consultas pressupõem que você já fez o MERGE dos seus dados. Se você mantém as linhas com is_deleted em uma tabela bruta, acrescente WHERE is_deleted = 0 a cada consulta.

Horas visualizadas por estação em um período

Os X principais programas por horas visualizadas

Resumo diário de visualização

Horas visualizadas por território

Pipeline de ETL

Use este padrão de quatro etapas para criar o seu pipeline de ETL para o Conjunto de dados de programas lineares ao vivo.

  1. Extração inicial de dados. Extraia todos os arquivos do seu canal no intervalo de tempo desejado usando o endpoint da API. Faça download de todos os arquivos retornados. Cada um contém linhas em CSV compactado com gzip.
  2. Deduplicação. Quando existirem vários registros para o mesmo session_program_schedule_id nos arquivos extraídos, mantenha somente a linha com o last_update_time_utc mais recente. Consulte a seção Deduplicação para ver o padrão de SQL completo.
  3. Aplicação no destino. Faça o MERGE dos registros deduplicados na sua tabela de destino, com a chave session_program_schedule_id. Faça o upsert em is_deleted = 0. Em is_deleted = 1, faça com que a ID deixe de aparecer nos seus dados atuais. Exclua-a definitivamente ou mantenha a linha sinalizada e filtre-a.
  4. Processamento incremental. Para carregamentos contínuos, defina como o horário da última extração e endDateTime como o horário atual. Processe todos os arquivos retornados e faça o MERGE no seu destino.


Dicas rápidas

Tenha estas dicas em mente ao integrar a API ao seu pipeline.

  1. session_program_schedule_id é a sua chave exclusiva. Sempre faça a deduplicação usando last_update_time_utc.
  2. Use um MERGE, não uma inserção em massa. Trate os sinais is_deleted sempre que carregar dados.
  3. Extraia de uma a quatro vezes por dia para ter os dados mais recentes.
  4. Nos carregamentos incrementais, defina o startDateTime como o carimbo de data/hora da última extração bem-sucedida.
  5. Use os endpoints de descoberta para encontrar a sua conta, os identificadores e os conjuntos de dados disponíveis.
  6. Extraia os feeds de Canais e FAST se a sua parceria abranger os dois.
  7. Acrescente WHERE is_deleted = 0 a todas as consultas se você usar a exclusão reversível.
  8. A retenção máxima de dados é de dois anos. Planeje as suas extrações históricas de acordo.

Você sabia?

Com o acesso programático aos dados de audiência no nível do programa, você pode criar relatórios personalizados, alimentar os seus sistemas de programação e combinar os dados lineares com os seus outros dados de negócios. Os parceiros que integram esta API aos seus fluxos de trabalho tomam decisões mais rápidas e mais bem informadas sobre programação e aquisição de conteúdo.

Para análises visuais e insights rápidos, acesse o Painel de Programação linear no Slate Analytics.

Perguntas frequentes

Perguntas frequentes sobre a API do Conjunto de Dados do Programa Linear ao Vivo

Ainda precisa de ajuda?

Contate-nos

Neste guia



Erro interno do servidor! Tente novamente
Sua sessão expirou

Faça login para continuar

Faça seu login
edit