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 |
|
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:
curl -X GET \
-H "Authorization: Bearer Atza|auth_token" \
"https://videocentral.amazon.com/apis/v2/accounts/{ACADIA_ID}/{REPORT_GROUP}/{IDENTIFIER_ID}/datasets/{REPORT_ID}\
?startDateTime=YYYY-MM-DDThh:mm:ssZ\
&endDateTime=YYYY-MM-DDThh:mm:ssZ\
&offset=0&limit=1000"
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:
- 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.
SELECT *
FROM (
SELECT *,
ROW_NUMBER() OVER (
PARTITION BY session_program_schedule_id
ORDER BY last_update_time_utc DESC
) AS rn
FROM your_staging_table
) t
WHERE rn = 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.
MERGE INTO your_table AS target USING dedup_staging AS source ON target.session_program_schedule_id = source.session_program_schedule_id WHEN MATCHED AND source.is_deleted = 1 AND source.last_update_time_utc > target.last_update_time_utc THEN DELETE WHEN MATCHED AND source.is_deleted = 0 AND source.last_update_time_utc > target.last_update_time_utc THEN UPDATE SET program_title = source.program_title, seconds_viewed = source.seconds_viewed, airing_start_utc = source.airing_start_utc, airing_end_utc = source.airing_end_utc, last_update_time_utc = source.last_update_time_utc -- ... all other columns WHEN NOT MATCHED AND source.is_deleted = 0 THEN INSERT (session_program_schedule_id, session_id, program_id, ..., last_update_time_utc) VALUES (source.session_program_schedule_id, source.session_id, source.program_id, ..., source.last_update_time_utc);
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. |
- 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.{
"total": 1,
"next": null,
"data": [
{ "id": "12345678", "name": "MGM" }
]
}
Etapa 1: Linhas de negócios da conta
Chame GET /v2/accounts/12345678 para ver as linhas de negócios disponíveis.{
"total": 2,
"next": null,
"data": [
{ "id": "channels", "name": "Channels" },
{ "id": "fast", "name": "FAST" }
]
}
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.{
"total": 2,
"next": null,
"data": [
{ "id": "3f6c1b9d-8a2d-4e7f-9c31-0d5b7b2e6f14", "name": "MGM+" },
{ "id": "a91d4c21-57e0-4b8a-b6f3-2e9c0e1f8b77", "name": "MGM+ Espanol" }
]
}
Etapa 2b: Identificadores do FAST
Chame GET /v2/accounts/12345678/fast?offset=0&limit=100 para listar os seus identificadores do FAST.{
"total": 1,
"next": null,
"data": [
{ "id": "ABC123", "name": "MGM 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.{
"total": 1,
"next": null,
"data": [
{ "id": "fast_linear_program_event_log", "name": "FAST Linear Program Event Log" }
]
}
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.GET /v2/accounts/12345678/channels/3f6c1b9d-8a2d-4e7f-9c31-0d5b7b2e6f14
/datasets/linear_program_event_log
?startDateTime=2026-09-14T00:00:00Z&endDateTime=2026-09-15T00:00:00Z&offset=0&limit=1000
{
"total": 3,
"next": null,
"data": [
{ "downloadUrl": "https://pvreporting-datasets-prod.s3.amazonaws.com/linear_program_event_log/
3f6c1b9d.../2026/09/14/06/...linear_2f0c...e91a.csv.gz?X-Amz-Algorithm=..." },
{ "downloadUrl": "https://pvreporting-datasets-prod.s3.amazonaws.com/linear_program_event_log/
3f6c1b9d.../2026/09/14/14/...linear_7b41...03cd.csv.gz?..." },
{ "downloadUrl": "https://pvreporting-datasets-prod.s3.amazonaws.com/linear_program_event_log/
3f6c1b9d.../2026/09/14/22/...linear_c8d9...5e60.csv.gz?..." }
]
}
Etapa 3b: Arquivos do conjunto de dados do FAST
Chame o endpoint de arquivos do conjunto de dados para o seu identificador do FAST.GET /v2/accounts/12345678/fast/ABC123/datasets/fast_linear_program_event_log
?startDateTime=2026-09-14T00:00:00Z&endDateTime=2026-09-15T00:00:00Z&offset=0&limit=1000
{
"total": 1,
"next": null,
"data": [
{ "downloadUrl": "https://pvreporting-datasets-prod.s3.amazonaws.com/fast_linear_program_event_log/
ABC123/2026/09/14/15/...fast_linear_c258fb25...758add.csv.gz?X-Amz-Algorithm=..." }
]
}
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íodoSELECT station_name,
COUNT(*) AS sessions,
SUM(seconds_viewed) / 3600.0 AS hours_viewed
FROM your_table
WHERE start_segment_utc BETWEEN '[START_DATE]' AND '[END_DATE]'
GROUP BY station_name
ORDER BY hours_viewed DESC;
Os X principais programas por horas visualizadasSELECT program_title, station_name,
SUM(seconds_viewed) / 3600.0 AS hours_viewed
FROM your_table
WHERE start_segment_utc BETWEEN '[START_DATE]' AND '[END_DATE]'
GROUP BY program_title, station_name
ORDER BY hours_viewed DESC
LIMIT [X];
Resumo diário de visualizaçãoSELECT DATE(start_segment_utc) AS view_date,
COUNT(*) AS sessions,
SUM(seconds_viewed) / 3600.0 AS hours_viewed
FROM your_table
WHERE start_segment_utc BETWEEN '[START_DATE]' AND '[END_DATE]'
GROUP BY DATE(start_segment_utc)
ORDER BY view_date DESC;
Horas visualizadas por territórioSELECT territory,
SUM(seconds_viewed) / 3600.0 AS hours_viewed
FROM your_table
WHERE start_segment_utc BETWEEN '[START_DATE]' AND '[END_DATE]'
GROUP BY territory
ORDER BY hours_viewed DESC;
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.
- 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.
- 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.
- 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.
- 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.
startDateTime = {last_successful_pull_timestamp}
endDateTime = {current_utc_timestamp}
Dicas rápidas
Tenha estas dicas em mente ao integrar a API ao seu pipeline.
- session_program_schedule_id é a sua chave exclusiva. Sempre faça a deduplicação usando last_update_time_utc.
- Use um MERGE, não uma inserção em massa. Trate os sinais is_deleted sempre que carregar dados.
- Extraia de uma a quatro vezes por dia para ter os dados mais recentes.
- Nos carregamentos incrementais, defina o startDateTime como o carimbo de data/hora da última extração bem-sucedida.
- Use os endpoints de descoberta para encontrar a sua conta, os identificadores e os conjuntos de dados disponíveis.
- Extraia os feeds de Canais e FAST se a sua parceria abranger os dois.
- Acrescente WHERE is_deleted = 0 a todas as consultas se você usar a exclusão reversível.
- 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. |