Documentação da API v1: Endpoints de Dados

Esta documentação detalha o uso de dois endpoints principais para a extração de dados de performance: /data-ch para dados consolidados e /advanced/qualitative-data para dados detalhados e qualitativos.

Autenticação

Todas as requisições para a API devem incluir sua chave de acesso no cabeçalho (header) para autenticação.

  • Header: X-API-KEY
  • Valor: SUA_CHAVE_DE_API_AQUI

1. Endpoint: /data-ch (Dados Consolidados)

Este endpoint retorna dados de performance agregados por hora. É ideal para a construção de dashboards e relatórios gerenciais.

  • Método: GET
  • URL: https://apibrz.adsanalytics.com.br/api/v1/data-ch

Parâmetros de Query

Parâmetro Obrigatório Descrição Exemplo
from_date Sim Data de início do período da consulta, no formato YYYY-MM-DD. 2024-10-01
to_date Sim Data de fim do período da consulta, no formato YYYY-MM-DD. 2024-10-07
placement_ids Não Filtra por um ou mais IDs de placements, separados por vírgula. 401,402

Exemplo de Requisição (cURL)

curl -X GET 'https://apibrz.adsanalytics.com.br/api/v1/data-ch?from_date=2024-10-01&to_date=2024-10-07' \
  -H 'X-API-KEY: SUA_CHAVE_DE_API_AQUI'

Exemplo de Resposta (JSON)

A resposta será um array de objetos JSON, com as colunas de métricas de vídeo já renomeadas para um formato legível.

[
  {
    "date": "2024-10-28",
    "hour": "14:00:00",
    "advertiser_id": 101,
    "publisher": "Portal de Notícias Nacional",
    "placement_name": "[CPV][Home][1920x1080]",
    "placement_size": "1920x1080",
    "impressions": 5200,
    "clicks": 25,
    "ctr": 0.48,
    "conversions": 3,
    "viewable_impression": 4150,
    "VIDEO START": 1500,
    "VIDEO 25%": 1250,
    "VIDEO 50%": 1000,
    "VIDEO 75%": 800,
    "VIDEO 100%": 750
  }
]

2. Endpoint: /advanced/qualitative-data (Dados Qualitativos)

Este endpoint fornece dados brutos e detalhados, enriquecidos com informações de categoria e risco da URL. Devido ao alto volume de dados, este endpoint é paginado.

  • Método: GET
  • URL: https://apibrz.adsanalytics.com.br/api/v1/advanced/qualitative-data

Parâmetros de Query

Parâmetro Obrigatório Descrição Exemplo
from_date Sim Data de início do período da consulta, no formato YYYY-MM-DD. 2024-10-01
to_date Sim Data de fim do período da consulta, no formato YYYY-MM-DD. 2024-10-07
page_size Não Número de registros por página (chunk). Padrão: 1000, Máximo: 50000. 15000
page Não Número da página a consultar. Padrão: 1. 1

Paginação (Coleta de Dados em Chunks)

Para obter o conjunto de dados completo, você deve fazer requisições em um loop, incrementando o parâmetro page até que o número de registros retornados seja menor que o page_size.

Lógica de Coleta:
  1. Defina o page_size (tamanho do chunk). Ex: 15000.
  2. Inicie a primeira requisição com page=1.
  3. Receba a resposta e processe os registros.
  4. Verifique a quantidade de registros recebidos.
  5. Se a quantidade for igual ao page_size`, há mais dados. Incremente page (para page=2) e faça a próxima requisição.
  6. Se a quantidade for menor que o page_size`, esta é a última página. Encerre o loop.

Exemplo de Requisição (cURL) - Primeira Página

curl -X GET 'https://apibrz.adsanalytics.com.br/api/v1/advanced/qualitative-data?from_date=2024-10-01&to_date=2024-10-07&page=1&page_size=15000' \
  -H 'X-API-KEY: SUA_CHAVE_DE_API_AQUI'

Exemplo de Resposta (JSON)

A resposta será um array de objetos JSON com nomes de colunas padronizados e IDs internos removidos.

[
  {
    "date": "2024-10-28",
    "campaign": "Campanha de Fim de Ano - Varejo",
    "publisher": "Portal de Notícias Nacional",
    "banner_name": "[Banner Principal][CPV][Home][1920x1080]",
    "placement_name": "[CPV][ROS][1920x1080]",
    "url": "noticias.exemplo.com.br/economia",
    "impressions": 15230,
    "clicks": 45,
    "category": "noticias_e_midia",
    "risk": "low",
    "country": "Brazil",
    "country_code": "BR",
    "region": "São Paulo",
    "city": "São Paulo",
    "os": "Android",
    "browser": "Chrome Mobile"
  }
]