Documentacao BacenData

Acesse dados do Banco Central do Brasil em 1 linha de Python. Wrapper com paginacao automatica, cache inteligente e API REST pronta para producao.

Por que BacenData? Desde marco/2025, a API SGS do BACEN limita consultas a 10 anos. O BacenData resolve isso com paginacao automatica e transparente — consulte 30, 40, 50 anos de dados sem se preocupar.

Instalacao

Wrapper Python (biblioteca)

Terminal

pip install bacendata

API REST (servidor local)

Terminal

pip install "bacendata[api]"
uvicorn bacendata.api.app:create_app --factory --reload --port 8000

Acesse http://localhost:8000/docs para a documentacao interativa Swagger.

Quickstart

Python

from bacendata import sgs

# Buscar Selic por nome do catalogo
selic = sgs.get("selic", start="2024-01-01")

# Buscar IPCA por codigo SGS
ipca = sgs.get(433, last=12)

# Buscar multiplas series de uma vez
df = sgs.get({"Selic": 11, "IPCA": 433, "Dolar": 1}, start="2020-01-01")

# Retorno: pandas DataFrame pronto para analise
print(selic)
#              valor
# data
# 2024-01-02   11.65
# 2024-01-03   11.65
# ...

Dica O retorno e sempre um pandas.DataFrame com indice data e coluna valor. Facil de exportar para CSV, Excel ou plotar graficos.

Consultar serie unica

Use sgs.get() com codigo numerico ou nome do catalogo:

Python

from bacendata import sgs

# Por codigo SGS
selic = sgs.get(11, start="2024-01-01")

# Por nome do catalogo
selic = sgs.get("selic", start="2024-01-01")

# Com data de inicio e fim
selic = sgs.get(11, start="2024-01-01", end="2024-06-30")

# Ultimos N valores
ipca = sgs.get(433, last=12)

# Paginacao automatica para periodos > 10 anos
historico = sgs.get(11, start="2000-01-01", end="2024-12-31")

Parametro	Tipo	Descricao
`codigo`	`int` ou `str`	Codigo SGS ou nome do catalogo (ex: `11` ou `"selic"`)
`start`	`str`	Data inicial: `"2024-01-01"` ou `"01/01/2024"`
`end`	`str`	Data final (padrao: hoje)
`last`	`int`	Ultimos N valores (ignora start/end)

Multiplas series

Passe um dict para buscar varias series de uma vez. Cada chave vira o nome da coluna no DataFrame:

Python

from bacendata import sgs

df = sgs.get(
    {"Selic": 11, "IPCA": 433, "Dolar": 1},
    start="2020-01-01"
)

print(df.columns)
# Index(['Selic', 'IPCA', 'Dolar'], dtype='object')

# Exportar para Excel
df.to_excel("indicadores_2020.xlsx")

# Plotar comparativo
df.plot(subplots=True, figsize=(12, 8), title="Indicadores 2020-2024")

Catalogo de series

O BacenData inclui 14 series pre-configuradas que podem ser acessadas por nome ou alias:

Codigo	Nome	Aliases	Periodicidade
11	Selic diaria	`selic`, `selic_diaria`	Diaria
433	IPCA	`ipca`, `inflacao`	Mensal
1	Dolar (compra)	`dolar`, `usd`, `ptax`, `cambio`	Diaria
21619	Euro (compra) PTAX	`euro`, `eur`	Diaria
4390	Selic anualizada	`selic_anual`, `selic_anualizada`	Mensal
12	Selic acumulada no mes	`selic_mensal`, `selic_acumulada`	Mensal
4189	Juros PF	`juros_pf`, `taxa_pf`	Mensal
25434	Juros Credito Livre	`juros_credito`, `credito_livre`	Mensal
7326	Reservas Internacionais	`reservas`	Diaria
20542	Saldo Credito Livre	`saldo_credito`, `carteira_credito`	Mensal
21112	Inadimplencia PF	`inadimplencia_pf`, `default_pf`	Mensal
21082	Inadimplencia PJ	`inadimplencia_pj`, `default_pj`	Mensal
27574	Expectativa IPCA 12m	`focus_ipca`, `expectativa_ipca`	Semanal
27575	Expectativa Selic	`focus_selic`, `expectativa_selic`	Semanal

Qualquer codigo SGS funciona O catalogo e um atalho. Voce pode usar qualquer codigo SGS valido: sgs.get(4389, last=10) busca o CDI, por exemplo.

Python

# Listar todas as series do catalogo
from bacendata.wrapper.catalogo import listar

for serie in listar():
    print(f"{serie.codigo:>6} | {serie.nome} ({serie.periodicidade})")

Cache local

Ative o cache para evitar chamadas repetidas a API do BACEN. O cache usa SQLite com TTL por periodicidade:

Periodicidade	TTL
Diaria	1 hora
Semanal	6 horas
Mensal	24 horas

Python

from bacendata import sgs

sgs.cache.ativar()  # Salva em ~/.bacendata/cache.db

selic = sgs.get(11, start="2020-01-01")  # Busca na API
selic = sgs.get(11, start="2020-01-01")  # Le do cache (instantaneo)

# Caminho customizado
sgs.cache.ativar("/tmp/meu_cache.db")

# Limpar cache
sgs.cache.limpar()

# Desativar
sgs.cache.desativar()

Interface async

Para uso em FastAPI ou outros frameworks async, use sgs.aget():

Python

import asyncio
from bacendata import sgs

async def main():
    # Mesma interface, mas await
    df = await sgs.aget(11, start="2024-01-01")
    meta = await sgs.ametadata(433)
    print(df)

asyncio.run(main())

Metadados

Python

info = sgs.metadata(433)
print(info)
# {'codigo': 433, 'nome': 'IPCA - Variacao mensal',
#  'periodicidade': 'Mensal', 'unidade': '% a.m.', ...}

Tratamento de erros

Python

from bacendata.wrapper.exceptions import (
    SerieNaoEncontrada,
    BacenAPIError,
    BacenTimeoutError,
    ParametrosInvalidos,
)

try:
    df = sgs.get(99999, start="2024-01-01")
except SerieNaoEncontrada:
    print("Serie nao existe")
except BacenTimeoutError:
    print("API do BACEN nao respondeu")
except BacenAPIError as e:
    print(f"Erro {e.status_code}: {e.mensagem}")

API REST — Visao geral

A BacenData API e uma interface REST que roda sobre o wrapper Python. Base URL de producao:

URL

https://bacendata-production.up.railway.app

Documentacao interativa: /docs (Swagger) | /redoc

Autenticacao

Envie sua API key via header X-API-Key:

cURL

# Sem autenticacao (plano free: 100 req/dia)
curl "https://bacendata-production.up.railway.app/api/v1/series/selic?last=5"

# Com API key (plano pro: 10.000 req/dia)
curl -H "X-API-Key: sua-chave-pro" \
     "https://bacendata-production.up.railway.app/api/v1/series/selic?last=5"

Endpoints

GET /api/v1/series/{codigo}

Busca dados de uma serie temporal.

cURL

# Por codigo
curl "https://bacendata-production.up.railway.app/api/v1/series/11?start=2024-01-01&end=2024-06-30"

# Por nome
curl "https://bacendata-production.up.railway.app/api/v1/series/selic?start=2024-01-01"

# Ultimos N valores
curl "https://bacendata-production.up.railway.app/api/v1/series/433?last=12"

POST /api/v1/series/bulk

Busca ate 20 series em uma unica requisicao.

cURL

curl -X POST "https://bacendata-production.up.railway.app/api/v1/series/bulk" \
  -H "Content-Type: application/json" \
  -d '{
    "series": [
      {"codigo": 11, "nome": "Selic"},
      {"codigo": 433, "nome": "IPCA"},
      {"codigo": "dolar", "nome": "USD/BRL"}
    ],
    "start": "2024-01-01"
  }'

GET /api/v1/catalogo

Lista todas as 14 series do catalogo com aliases.

GET /api/v1/catalogo/search?q={termo}

Busca series por nome, descricao ou alias.

GET /api/v1/series/{codigo}/metadata

Retorna metadados de uma serie (nome, periodicidade, fonte, unidade).

Rate limiting

Plano	Limite	Preco
Free (sem API key)	100 req/dia	R$ 0
Pro (com API key)	10.000 req/dia	R$ 79/mes
Enterprise	Ilimitado	R$ 399/mes

Headers de rate limit retornados em cada resposta:

X-RateLimit-Limit — limite total por dia
X-RateLimit-Remaining — requisicoes restantes
Retry-After — segundos ate resetar (quando excedido)

Caso de uso: Economistas

Acompanhe inflacao, juros e expectativas do mercado:

Python

from bacendata import sgs

# IPCA dos ultimos 24 meses
ipca = sgs.get("ipca", last=24)

# Expectativas Focus: IPCA e Selic
focus = sgs.get({
    "IPCA esperado": 27574,
    "Selic esperada": 27575,
}, last=52)

# Selic historica desde 2003
selic = sgs.get("selic_anual", start="2003-01-01")
selic["valor"].plot(title="Meta Selic 2003-2024", figsize=(12,5))

Caso de uso: Fintechs

Integre cotacoes de cambio e juros na sua aplicacao:

Python

import httpx

API = "https://bacendata-production.up.railway.app/api/v1"
KEY = "sua-chave-pro"

# Dolar e Euro atuais
resp = httpx.post(
    f"{API}/series/bulk",
    headers={"X-API-Key": KEY},
    json={
        "series": [
            {"codigo": "dolar", "nome": "USD"},
            {"codigo": "euro", "nome": "EUR"},
        ],
        "last": 1,
    }
)

for s in resp.json()["series"]:
    print(f"{s['nome']}: R$ {s['dados'][0]['valor']:.4f}")

Caso de uso: Analistas de credito

Monitore inadimplencia e juros do mercado de credito:

Python

from bacendata import sgs

credito = sgs.get({
    "Inadimplencia PF": 21112,
    "Inadimplencia PJ": 21082,
    "Juros PF": 4189,
    "Saldo Credito": 20542,
}, start="2019-01-01")

credito.plot(subplots=True, figsize=(14,10), title="Painel de Credito")

Caso de uso: Pesquisadores

Baixe series historicas longas com paginacao automatica:

Python

from bacendata import sgs

# Selic desde 1986 (quase 40 anos — paginacao automatica)
selic = sgs.get(11, start="1986-06-01")
print(f"Total: {len(selic)} registros")

# IPCA desde 1980
ipca = sgs.get(433, start="1980-01-01")

# Exportar tudo para Excel
selic.to_excel("selic_historico.xlsx")
ipca.to_excel("ipca_historico.xlsx")