Unite Research

Unite Research — Developer portal

API pública para consultar os 19 gráficos do Benchmark Criativo Black Friday Brasil 2026, com dados, períodos, comparações e fonte. A API fornece as mesmas 248 linhas agregadas publicadas nas tabelas do estudo. O acesso é gratuito, somente leitura e não exige cadastro nem chave.

Quickstart


curl --fail --show-error 'https://research.unitebr.com/api/v1/charts?query=CPM&limit=5'

curl --fail --show-error 'https://research.unitebr.com/api/v1/charts/ch-bfday?limit=20'

curl --fail --show-error 'https://research.unitebr.com/api/v1/citation?chart_id=ch-bfday'

Base URL and authentication

Base URL: https://research.unitebr.com/api/v1. No authentication required: os endpoints são públicos e não usam API keys, OAuth ou cookies. O acesso à plataforma comercial da Unite é separado e não é oferecido por esta API. CORS permite consultas de outros sites; não há operação de escrita ou acesso a contas de anúncios.

API reference

GET /api/v1/charts lista gráficos. Parâmetros opcionais: query (até 160 caracteres), offset (inteiro a partir de 0) e limit (1 a 50, padrão 10). A busca ignora maiúsculas e acentos e consulta título, comparação, período e nomes das colunas. A resposta inclui total, offset, next_offset e items.

GET /api/v1/charts/{chart_id} retorna os dados de um gráfico. Use um chart_id obtido na listagem. Parâmetros opcionais: offset e limit (padrão 20). chart.columns identifica a ordem das células de cada linha em items. chart.comparison e chart.period_and_population preservam a base de comparação e o período. citation inclui fonte, URL canônica e metodologia.

GET /api/v1/citation retorna orientações de citação, datas, metodologia e permissão de reprodução. O parâmetro opcional chart_id acrescenta o contexto específico do gráfico. GET /api/v1/health informa disponibilidade da API, versão da base e contagem de gráficos e linhas; não é uma promessa de SLA.

Paginação e formato dos valores

Prefira cursor: envie o next_cursor da resposta anterior no parâmetro cursor e repita até ele ser null. O cursor mantém a mesma consulta e revisão da base; um cursor inválido ou antigo recebe 400 e deve ser substituído por uma nova consulta inicial. Para compatibilidade, offset e next_offset continuam disponíveis, mas não combine offset com cursor. Offset acima do total retorna items vazio. As séries diárias têm mais de 20 linhas e exigem paginação com o limite padrão.

Os valores são strings como no estudo: vírgula decimal, sinal de menos, % para percentuais, × para razões e valores textuais como igual. Preserve os cabeçalhos: variação percentual contra outubro não é um nível absoluto de CPM, e porcentagem não deve ser convertida automaticamente em pontos percentuais. Cada gráfico informa seu período e população. Tendências observadas não são testes controlados nem garantias de resultado.

JavaScript example


const url = 'https://research.unitebr.com/api/v1/charts/ch-bfday?limit=20';

const response = await fetch(url);

if (!response.ok) throw new Error(await response.text());

const data = await response.json();

console.log(data.chart.columns, data.items, data.next_offset);

Python example


import json

from urllib.request import urlopen



url = 'https://research.unitebr.com/api/v1/citation?chart_id=ch-bfday'

with urlopen(url, timeout=20) as response:

    data = json.load(response)

print(data['citation']['canonical_url'])

Errors, caching and limits

400 indica parâmetro inválido, repetido ou desconhecido; 404 indica gráfico ou endpoint inexistente; 405 indica método não suportado. Erros usam application/problem+json, com type, title, status, detail e instance. Use as orientações de detail para corrigir a consulta. Somente GET, HEAD e OPTIONS são aceitos.

As respostas possuem ETag e suportam If-None-Match com 304 para conteúdo inalterado. O cache compartilhado é de até uma hora. O firewall limita /api/* e /mcp a 300 requisições por IP em uma janela fixa de 60 segundos por região. As respostas permitidas anunciam RateLimit-Limit: 300 e RateLimit-Policy: 300;w=60; esses cabeçalhos informam a política, não um saldo individual. Ao exceder o limite, o firewall responde 429 em texto simples. Se não houver Retry-After, aguarde pelo menos 60 segundos. Não há garantia de disponibilidade publicada. Reutilize respostas e use tentativas limitadas com espera progressiva para falhas transitórias; respeite Retry-After se a plataforma responder 429. Não repita erros 400/404 sem corrigir a consulta.

WebMCP and agent discovery

A página do estudo registra list_charts, get_chart_data e get_citation em navegadores com WebMCP disponível. O token de origin trial do Chrome permite a habilitação em versões compatíveis até 29/03/2027, sujeita aos limites do experimento. A API HTTP funciona independentemente do navegador.

Version and changes

API 1.0.0, publicada em 15/10/2026. A versão da base é a data de atualização editorial do estudo e aparece nas respostas de listagem e saúde. Alterações de conteúdo mantêm as mesmas rotas e contratos; mudanças incompatíveis exigirão uma nova versão documentada. Os arquivos de dados são regenerados a partir das tabelas HTML em cada build e testados contra elas.

MCP server

Endpoint público: https://research.unitebr.com/mcp. Transporte Streamable HTTP; sem chave, login ou pagamento. O servidor usa o SDK oficial e oferece list_charts, get_chart_data e get_citation, com schemas de entrada, conteúdo estruturado e indicações de leitura/idempotência. Os protocolos 2026-07-28, 2025-11-25 e 2025-06-18 são suportados. O transporte negocia os detalhes do protocolo; para clientes de 2025, cada requisição é stateless e não há sessão persistente.


{

  "mcpServers": {

    "unite-research": {

      "type": "http",

      "url": "https://research.unitebr.com/mcp"

    }

  }

}

Esse é um exemplo de configuração para clientes que usam o formato mcpServers; o formato de instalação depende do cliente. Manifesto do servidor. As ferramentas usam a mesma base e validação da API REST.

API versioning and idempotency

A versão do contrato está no caminho /api/v1 e no cabeçalho API-Version: 1.0.0. As rotas antigas /api/charts, /api/charts/{chart_id}, /api/citation e /api/health continuam como aliases de v1. Mudanças incompatíveis serão publicadas em nova versão; não há uma data de desativação anunciada para v1.

GET, HEAD e OPTIONS são operações de leitura idempotentes: repeti-las não cria registros, cobranças, formulários ou jobs. Idempotency-Key não é necessário e não é um recurso de escrita deste serviço. Use o mesmo GET para uma nova tentativa transitória e If-None-Match para revalidar um resultado. As ferramentas MCP também são marcadas como somente leitura e idempotentes.

Consulte a política de versões, depreciação e migração. Uma futura descontinuação será anunciada com antecedência mínima de 90 dias. Não há data de encerramento de v1.

MCP Apps: consulta interativa

O servidor MCP 1.1.0 oferece a visualização Unite Research Explorer em ui://unite-research/explorer.html. Em clientes compatíveis com MCP Apps, list_charts e get_chart_data abrem uma interface para buscar temas, selecionar gráficos e consultar tabelas com período, população, fonte e limites de interpretação. Os clientes sem suporte visual continuam recebendo os mesmos dados estruturados.

A interface recebe resultados e chama ferramentas pelo canal do cliente MCP; não faz requisições externas, não usa cookies e não envia dados pessoais. O manifesto CSP do recurso não permite origens externas. Especificação MCP Apps.

SDKs oficiais e CLI

Os clientes oficiais JavaScript/TypeScript e Python oferecem busca, consulta de gráficos, citação, saúde e iteradores que percorrem todas as páginas por cursor. Os valores publicados são preservados como strings. Não exigem chave, não fazem escritas e não repetem requisições automaticamente. Erros HTTP incluem status e detalhes do problema; timeout padrão de 20 segundos.

A CLI unite-research oferece os comandos charts, chart, citation e health, com saída JSON para automação. Instale uma das variantes da CLI por ambiente para evitar conflito entre os executáveis JavaScript e Python.

Instalação sem registro npm/PyPI: use os arquivos da release oficial 1.0.0.


npm install https://github.com/ZupTech/unite-research-sdk/releases/download/v1.0.0/unite-research-sdk-1.0.0.tgz

npx unite-research charts --query CPM



pip install https://github.com/ZupTech/unite-research-sdk/releases/download/v1.0.0/unite_research_sdk-1.0.0-py3-none-any.whl

python -m unite_research chart ch-bfday --limit 50