API do BRradar

Começar

Endereço base: https://brradar.com.br/v1. As respostas são JSON em UTF-8, com datas no formato AAAA-MM-DD e números como números JSON (ponto decimal) ou null. O identificador de cada série (o slug) é o mesmo do endereço da página dela, como /indicador/ipca, e a lista completa sai de /v1/series.

# catálogo (filtros: theme, q)
curl "https://brradar.com.br/v1/series?theme=inflacao"

# uma série: metadados, último valor e fonte efetiva
curl "https://brradar.com.br/v1/series/ipca"

# observações, com período e transformação (acumulado em 12 meses)
curl "https://brradar.com.br/v1/series/ipca/observations?from=2020-01-01&transform=acc12"

# até 4 séries lado a lado
curl "https://brradar.com.br/v1/compare?s=ipca-12m,selic-meta&from=2020-01-01"

Todas as rotas, parâmetros e campos estão na referência abaixo, gerada do contrato OpenAPI em /v1/openapi.json.

Limites e chave gratuita

• Sem chave: até 60 pedidos por minuto por endereço IP (60 de uma vez, depois 1 por segundo).
• Com uma chave gratuita: até 600 pedidos por minuto por chave, enviada no cabeçalho X-API-Key.
• Só contam os pedidos que chegam ao servidor do BRradar: a Cloudflare responde a maior parte dos GET com a cópia que guarda, e esses não gastam o limite. Essa cópia sai sem conferir a chave.
• Acima do limite, a resposta é 429 com o cabeçalho Retry-After: espere esses segundos antes de repetir.

A chave sai na hora, sem cadastro: o BRradar não pede nem guarda nada sobre você, só um resumo (hash) da chave, que por isso aparece uma única vez. Perdeu? Gere outra. São até 3 chaves por endereço de uma vez, depois uma a cada 20 minutos.

Para revogar uma chave, mande o prefixo dela (os 12 primeiros caracteres) pelos contatos do projeto. Precisa de mais que 600 por minuto? Conte para que é, pelo mesmo caminho.

Cache e atualização

Os dados são coletados das fontes oficiais todo dia de madrugada e mudam no máximo uma vez por dia. As leituras saem com Cache-Control: public, s-maxage=3600, stale-while-revalidate=86400, stale-if-error=86400: a Cloudflare renova a cópia dela a cada hora, mas pode seguir entregando a anterior por até mais um dia enquanto renova ou enquanto o servidor do BRradar está fora do ar. A cópia de /v1/status dura um minuto (e mais um enquanto renova); a de uma visualização, /v1/views/{code}, um dia.

As leituras (GET e HEAD) que dão certo ou que recusam o pedido trazem um ETag, menos a 401 e a 429: repita o pedido com If-None-Match e, se nada mudou, a resposta é 304 sem corpo. Os erros 5xx e os POST saem com no-store e sem ETag. Guardar o que você baixou e perguntar de novo uma vez por hora já basta para acompanhar qualquer série.

Exportações CSV e XLSX

Cada série sai em planilha com o mesmo período e transformação dos parâmetros: /v1/series/{slug}/export.csv e /export.xlsx. O CSV vem por padrão em locale=pt-BR (ponto e vírgula e vírgula decimal, como o Excel em português espera); locale=en troca para vírgula e ponto. As linhas iniciais com # trazem a fonte, a unidade, a transformação, o endereço da consulta, a hora em que o arquivo foi gerado e a licença.

curl -o ipca.csv "https://brradar.com.br/v1/series/ipca/export.csv?from=2020-01-01"

# uma coluna de data e uma por série
curl -o comparacao.xlsx "https://brradar.com.br/v1/compare/export.xlsx?s=ipca-12m,selic-meta"

# todos os estados numa data
curl -o desemprego-uf.csv "https://brradar.com.br/v1/series/desemprego/regions/export.csv"

Erros

Todo erro tem o mesmo corpo, {"error": "<código>", "detail": "<texto>"}: o error é estável e serve para o seu código decidir; o detail é um texto em português para pessoas e pode mudar.

Licenças dos dados

Os dados pertencem aos seus publicadores, e cada série traz publisher, publisher_url e license em /v1/series/{slug}. As fontes federais brasileiras usam licenças abertas (Licença Aberta de Dados / CC BY); o Banco Mundial, CC BY 4.0; o Tesouro Nacional e o SCR.data do Banco Central, a ODbL, que pede a mesma licença em qualquer base derivada; o PNUD, CC BY 3.0 IGO. Os detalhes de cada uma estão em Sobre.

Ao republicar, cite a fonte oficial e o BRradar. Os números não são recomendação de investimento: confira sempre a publicação oficial.