Video Central

Visão geral

A API Live Linear Program Dataset fornece dados de visualização programados para seus canais lineares e FAST ao vivo 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 changelog com sinais is_deleted para correções de cronograma. Dois feeds estão disponíveis: Channels (linear_program_event_log) e FAST (fast_linear_program_event_log).

Esses dados permitem que você:

Acompanhe a audiência em nível de programa (horas visualizadas, sessões) em todas as estações, territórios, dispositivos e horários.
Analise o desempenho por estação, programa, série e tipo de conteúdo.
Siga as correções do cronograma com precisão sem linhas obsoletas em seus dados.
Integre a visualização linear ao vivo com seus sistemas internos e fontes de dados.

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

Características principais

Característica	Detalhes
Detalhe do grão do programa	Uma linha por sessão de visualização, programa e agenda. Inclui título, estação, série, janela de exibição e tempo de exibição.
Sinal de remoção	Os agendamentos substituídos ou retirados são reenviados com is_deleted = 1, sinalizando que não são mais válidos.
Chave única estável	Cada linha carrega session_program_schedule_id. Use-o para desduplicar e MESCLAR.
Ingestão simplificada	Modelo de registro de alterações. Programar chamadas recorrentes e, em seguida, MESCLAR. Invertido em is_deleted = 0. Exclusão definitiva ou temporária 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	Description
Linha de programação do programa da sessão	Uma sessão de visualização de um programa em um horário agendado. Identificado por session_program_schedule_id.
Modelo de registro de alterações	Os dados são um changelog. 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 desduplique nesse campo.
sinal is_deletado	is_deleted = 0 significa que a agenda está ativa. is_deleted = 1 indica que a programação não está mais ativa ou válida.
Aplicando o sinal	is_deleted = 0: insira ou atualize a linha. is_deleted = 1: faça com que ele pare de aparecer em seus dados atuais. Solte a linha ou mantenha-a marcada e filtre-a.

Começando

Como integrar
a API Live Linear Program Dataset faz parte do Analytics API Suite. Ao se integrar ao Analytics API Suite, você receberá acesso a todas as APIs disponíveis dentro desse pacote, incluindo a API Live Linear Program Dataset (se solicitada durante a integração). Para obter instruções detalhadas de integração, visite a página de integração da API Analytics.

Pré-requisitos
Você precisa do seguinte antes de fazer solicitações de API:

Um login com o perfil de segurança da Amazon (LWA). Envie seu ID de cliente para seu CAM para ser adicionado à 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

Todos os pedidos 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 não autorizada.

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

Parâmetro	Padrão	Description
limitar	10	Number de documentos retornados por página. Máximo de 1.000.
desvio	0	Number de documentos a serem ignorados antes do primeiro resultado. Siga a próxima URL em vez de computá-la você mesmo.

Todos os comentários paginados incluem os seguintes campos:

Campo	Description
total	Contagem total de documentos em todas as páginas.
próximo	URL para a próxima página. Nulo se for a última página.

Recuperando arquivos do conjunto de dados

Endpoint
Use esse comando curl para recuperar uma lista de links de arquivos de conjuntos de dados para download:

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

Parâmetros

Parâmetro	Description
ACADIA_ID	O ID da sua conta Slate. Encontre-o em /v2/accounts.
GRUPO_RELATÓRIO	O segmento da linha de negócios. Use canais para o feed de canais ou rápidos para o feed FAST. Descubra o seu com GET /v2/accounts/ {ACADIA_ID}.
IDENTIFICADOR_ID	O valor do id retornado pelo endpoint dos identificadores. Para canais, é um hash opaco. Use o campo id conforme fornecido. Para FAST, é o código do seu fornecedor, retornado sem hash.
ID DO RELATÓRIO	Qual relatório retirar. Use linear_program_event_log para canais ou fast_linear_program_event_log para FAST.
Data e hora de início	Defina para a última vez que você puxou. Formato: aaaa-mm-ddthh:mm:ssz (UTC).
Data e hora de término	Defina para a hora atual. Formato: aaaa-mm-ddthh:mm:ssz (UTC).
limitar	Mínimo de 1, máximo de 1.000 links por página.

Relatórios disponíveis
Dois relatórios estão disponíveis. Extraia cada um separadamente colocando o ID do relatório no segmento de caminho dos conjuntos de dados/ {REPORT_ID}:

Relatório	ID do relatório	Conteúdos
Canais	registro de eventos do programa linear	SVOD/assinatura linear (3P_SUBS e FREE/PRIME, quando aplicável).
RÁPIDO	registro de eventos do programa linear rápido	Televisão com suporte para anúncios gratuitos/Canais lineares com suporte para anúncios (AVOD)

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

Endpoints Discovery

Use esses endpoints para encontrar seu ID de conta, grupos de relatórios, identificadores e conjuntos de dados disponíveis:

Ponto final	Devoluções
OBTENHA /v2/accounts	Lista de contas do Slate que você pode acessar.
OBTENHA /v2/accounts/ {ACADIA_ID}	Linhas de negócios disponíveis (por exemplo, canais, rápidas).
GET /v2/accounts/ {ACADIA_ID} /channels	Identificadores de relatório disponíveis para você. Cada entrada tem um ID e um nome amigável.
GET /v2/accounts/ {ACADIA_ID} /channels/ {IDENTIFIER_ID} /conjuntos de dados	Conjuntos de dados disponíveis para esse identificador.

Colunas de dados

As colunas a seguir estão presentes no feed linear_program_event_log (Channels). O feed fast_linear_program_event_log (FAST) tem o mesmo formato, com vendor_code adicionado e colunas de assinatura fornecidas como NULL.

Coluna	Type	Anulável	Description
ID de agendamento do programa de sessão	FIO	Não	Chave primária. ID exclusivo (codifica sessão, programa e janela de exibição). Desduplique e MESCLE nesse campo. Alterações quando o programa ou o horário de exibição mudam devido aos metadados atualizados do EPG.
ID da sessão	FIO	Não	Identificador exclusivo de sessão de visualização anônimo.
é_excluído	INT	Não	Sinal de status. 0 = o cronograma está ativo. 1 = o cronograma não está mais ativo (substituído ou retirado). Exclua is_deleted = 1 linha dos seus dados atuais.
horário_da_última atualização utc	TIMESTAMP	Não	Registre a hora da versão. Sempre use para desduplicar. Mantenha a linha com o valor mais recente para um determinado ID.
create_time_utc	TIMESTAMP	Não	Quando a linha foi criada pela primeira vez.
ID do programa	FIO	Não	Identificador do programa, por exemplo, ID do TMS.
pv_title_id	FIO	sim	Identificador de título global (GTI) do Prime Video para o programa. O mesmo que pv_title_id no feed TVOD.
título_programa	FIO	sim	Título do programa.
nome_da_estação	FIO	sim	Nome do canal ou da estação.
tipo_conteúdo	FIO	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 transmissão do programa (UTC).
segmento_inicial_utc	TIMESTAMP	Não	Visualizando o início da sessão (UTC).
segmento_final utc	TIMESTAMP	Não	Visualizando o final da sessão (UTC).
segundos_visualizados	LONGO	Não	Segundos visualizados nesta sessão.
SKU do fornecedor	FIO	sim	SKU do conteúdo (por exemplo, identificadores Gracenote).
etiqueta_canal_parente	FIO	sim	Identificador do canal principal com hash.
ácido	FIO	sim	ID do canal (efetivo).
id_benefício	FIO	sim	Identificador de direito/benefício.
id_da_oferta de assinatura	FIO	sim	Identificador da oferta de assinatura.
ID do evento de assinatura	FIO	sim	Identificador do evento de assinatura.
fuso horário da oferta de assinatura	FIO	sim	Fuso horário da oferta de assinatura.
ID do mercado	INT	Não	Identificador do Marketplace.
marketplace_desc	FIO	sim	Descrição do mercado.
território	FIO	sim	Código de território ou país (EUA, GB, DE, AU e outros).
classe_dispositivo	FIO	sim	Categoria do dispositivo.
sub_classe do dispositivo	FIO	sim	Subcategoria de dispositivo.
tipo_de_conexão	FIO	sim	Tipo de conexão (wifi, com fio e outros).
método_reprodução	FIO	sim	Como a sessão foi consumida: online (streaming) ou offline (download). O Live Linear está efetivamente sempre online.
geo_dma	FIO	sim	DMA geográfico.
tipo_de_fluxo	FIO	Não	Sempre LINEAR_TV.

Nota do feed FAST: O feed fast_linear_program_event_log tem o mesmo formato. 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 fornecidas como NULL.

O entendimento é_excluído

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

Value	Significado	Como aplicá-lo
0	Programar está ativo (a versão atual).	Insira-a ou substitua a linha existente dessa chave.
1	Programar não está mais ativo (substituído ou retirado).	Faça com que ele pare de aparecer em seus dados atuais. Solte a linha ou mantenha-a marcada e filtre-a.

Quando é que is_deleted = 1 ocorre?

Programar correção. O programa ou o horário de exibição foram corrigidos. O antigo session_program_schedule_id chega como is_deleted = 1. Um novo ID chega como is_deleted = 0. Aplique o antigo como não mais ativo e insira o novo.
A aeração foi removida. A exibição foi totalmente retirada. Seu ID chega como is_deleted = 1.

Notas importantes

Um determinado session_program_schedule_id nunca é 0 e 1 no mesmo lote. Uma aeração corrigida se torna uma chave diferente.
As linhas que nunca atenderam aos critérios de elegibilidade do feed não são entregues. Não espere um is_deleted = 1 para uma linha que você nunca recebeu.

Desduplicação

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

Mantenha a versão mais recente de cada ID. Para cada ID, mantenha somente a linha com o último último update_time_utc mais recente e descarte os mais antigos. Esse valor só avança, então o mais recente sempre vence.

MESCLE as linhas desduplicadas em sua tabela. Use o padrão MERGE abaixo. Atue em is_deleted toda vez que você carrega dados.

Use um MERGE, não um inserto em massa. Se você carregar cada arquivo como novas linhas, as linhas is_deleted = 1 ficarão na tabela como dados ativos em vez de serem aplicadas. Sempre aja de acordo com a bandeira.

Alternativa de exclusão reversível. Substitua a ramificação DELETE por UPDATE SET is_deleted = 1 e, em seguida, filtre WHERE is_deleted = 0 em suas consultas. Ambos os métodos fornecem 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	1 a 4 vezes por dia para se manter atualizado.
Estratégia incremental	Defina startDateTime como a última data recuperada e endDateTime como a hora atual. Baixe e processe todos os arquivos retornados e, em seguida, MESCLE.
Consumidores diários/semanais	Se você buscar diariamente ou semanalmente, processe todos os arquivos do período. Isso garante que você não perca atualizações ou exclusões.

Observação: cada lote mistura linhas ativas (is_deleted = 0) e linhas não mais ativas (is_deleted = 1). Eles não são entregues em arquivos separados. A coluna is_deleted os diferencia.

Exemplo de uso da API

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

Etapa 0: Liste suas contas
Ligue para GET /v2/accounts para listar as contas do Slate que você pode acessar.

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

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

Etapa 2a: Os identificadores de canais
chamam GET /v2/accounts/12345678/channels? offset=0&limit=100 para listar seus identificadores de canais.

Etapa 2b: Os identificadores FAST
chamam GET /v2/accounts/12345678/fast? offset=0&limit=100 para listar seus identificadores FAST.

Etapa 2c: Conjuntos de dados disponíveis para um Identifier
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 dos arquivos do conjunto de dados para seu identificador de canais. A resposta retorna uma lista de URLs de download para arquivos CSV compactados com gzip.

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

Exemplos de consultas

Essas consultas pressupõem que você já tenha mesclado seus dados. Se você mantiver as linhas is_deleted em uma tabela bruta, adicione WHERE is_deleted = 0 a cada consulta.

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

Os X principais programas por horas visualizadas

Resumo da visualização diária

Horas visualizadas por Território

Pipeline ETL

Use esse padrão de quatro etapas para criar seu pipeline de ETL para o Conjunto de Dados do Programa Linear ao Vivo.

Extração inicial de dados. Extraia todos os arquivos do seu canal dentro do intervalo de tempo desejado usando o endpoint da API. Baixe todos os arquivos retornados. Cada um contém linhas em CSV compactado com gzip.
Desduplicar. Quando existirem vários registros para o mesmo session_program_schedule_id nos arquivos que você extraiu, mantenha somente a linha com o último last_update_time_utc. Consulte a seção Desduplicação para ver o padrão SQL completo.
Inscreva-se no destino. MESCLE os registros desduplicados em sua tabela de destino digitada em session_program_schedule_i d. Upsert em is_deleted = 0. Em is_deleted = 1, faça com que o ID pare de aparecer em seus dados atuais. Exclua-a de forma definitiva ou mantenha a linha marcada e filtre-a.
Processamento incremental. Para cargas contínuas, defina como a última vez que você puxou e endDateTime como a hora atual. Processe todos os arquivos retornados e MERGULHE-OS em seu destino.

Dicas rápidas

Lembre-se dessas dicas ao integrar a API ao seu pipeline.

session_program_schedule_id é sua chave exclusiva. Sempre desduplique usando last_update_time_utc.
Use um MERGE, não um inserto em massa. Aja com base nos sinais is_deleted sempre que carregar dados.
Extraia de 1 a 4 vezes por dia para obter os dados mais recentes.
Defina seu startDateTime como o último carimbo de data/hora de extração bem-sucedido para cargas incrementais.
Use os endpoints de descoberta para encontrar sua conta, identificadores e conjuntos de dados disponíveis.
Obtenha os canais e os feeds FAST se sua parceria abranger ambos.
Adicionar WHERE is_deleted = 0 a todas as consultas se você usar a abordagem de exclusão temporária.
A retenção máxima de dados é de 2 anos. Planeje suas atrações históricas de acordo.

Você sabia?

O acesso programático aos dados de visualização em nível de programa permite criar relatórios personalizados, alimentar seus sistemas de agendamento e combinar dados lineares com outros dados comerciais. Os parceiros que integram essa API em seus fluxos de trabalho tomam decisões mais rápidas e informadas sobre programação e aquisição de conteúdo.

Para análise visual e insights rápidos, visite o painel de programação linear no Slate Analytics.

API de conjunto de dados do Programa Linear ao Vivo