API de dados econômicos: Banco Central, IBGE e Tesouro em Python

Banco Central, IBGE e Tesouro Nacional publicam suas estatísticas por interfaces abertas, gratuitas e sem cadastro. Não é preciso pedir chave, assinar contrato nem baixar planilhas à mão: uma requisição HTTP devolve JSON (ou um arquivo oficial) que o Python lê com a biblioteca padrão. O IPCA de setembro de 2026, por exemplo, que subiu 0,82%, sai da API do Sistema Gerenciador de Séries Temporais (SGS) do Banco Central com seis linhas de código.

Este guia junta num só lugar as APIs oficiais que importam para quem trabalha com dados macroeconômicos do Brasil: o SGS e o Olinda (Focus e PTAX) do Banco Central, a API SIDRA e a API de Agregados do IBGE e os arquivos do Tesouro Nacional (Resultado do Tesouro Nacional e Tesouro Direto). Para cada fonte há um exemplo com HTTP direto (só urllib e json, sem dependências) e outro com os fetchers de código aberto da Quantilica. Todos os trechos foram executados em 20 de outubro de 2026, e as saídas mostradas são as dessa data.

Quais APIs oficiais de dados econômicos existem no Brasil

São seis portas de entrada, com formatos e limites diferentes. A tabela resume o que cada uma entrega e as restrições que conferimos na prática.

Os limites do SGS e do SIDRA não vêm de documentação antiga: são as mensagens de erro que as próprias APIs devolvem quando recebem um pedido grande demais, reproduzidas mais abaixo.

API do Banco Central (SGS) em Python com HTTP direto

Cada série do SGS tem um código numérico: 433 é o IPCA mensal, 432 a meta Selic, 1 o dólar PTAX de venda, 4380 o PIB mensal em valores correntes. O endereço segue um padrão fixo: bcdata.sgs.{código}/dados, com ?formato=json no fim. O sufixo /ultimos/N traz só as N observações mais recentes.

import json
import urllib.request

url = "https://api.bcb.gov.br/dados/serie/bcdata.sgs.433/dados/ultimos/3?formato=json"
with urllib.request.urlopen(url, timeout=30) as resp:
    dados = json.load(resp)

for obs in dados:
    print(obs["data"], obs["valor"])

Saída em 20/10/2026:

01/07/2026 0.07
01/08/2026 -0.32
01/09/2026 0.82

Três detalhes evitam bugs silenciosos:

• Datas vêm como texto dd/mm/aaaa. Séries mensais usam o dia 1 como marcador do mês; converta com datetime.strptime(obs["data"], "%d/%m/%Y").
• Valores vêm como texto com ponto decimal ("0.82"), nunca com vírgula. Use Decimal quando precisar de exatidão, ou float para análise.
• /ultimos/N aceita no máximo 20 observações. Com /ultimos/21, a API responde HTTP 400 com a mensagem "A quantidade máxima de valores deve ser 20".

O limite de 10 anos nas séries diárias

Para séries mensais, /dados?formato=json sem parâmetros devolve o histórico inteiro (o IPCA tem 561 meses, desde janeiro de 1980). Séries diárias funcionam de outro jeito. Sem dataInicial, a API responde HTTP 406 com a mensagem "O sistema aceita uma janela de consulta de, no máximo, 10 anos em séries de periodicidade diária". A solução é paginar por janelas de datas:

import datetime as dt
import json
import urllib.request

BASE = "https://api.bcb.gov.br/dados/serie/bcdata.sgs.{codigo}/dados"


def sgs_diaria(codigo, inicio, fim):
    """Baixa uma série diária do SGS em janelas de até 10 anos."""
    pontos = []
    janela_ini = inicio
    while janela_ini <= fim:
        janela_fim = min(dt.date(janela_ini.year + 9, 12, 31), fim)
        url = (
            BASE.format(codigo=codigo)
            + f"?formato=json&dataInicial={janela_ini:%d/%m/%Y}"
            + f"&dataFinal={janela_fim:%d/%m/%Y}"
        )
        with urllib.request.urlopen(url, timeout=60) as resp:
            pontos.extend(json.load(resp))
        janela_ini = janela_fim + dt.timedelta(days=1)
    return pontos


ptax = sgs_diaria(1, dt.date(2010, 1, 1), dt.date(2026, 10, 19))
print(len(ptax), "cotações")
print(ptax[0])
print(ptax[-1])

4218 cotações
{'data': '04/01/2010', 'valor': '1.7240'}
{'data': '19/10/2026', 'valor': '5.0564'}

A série 1 é o dólar PTAX de venda. Para a leitura econômica das séries de câmbio, veja o guia Dólar e euro no Brasil: a série histórica.

API do Banco Central com o fetcher Quantilica (bcb-sgs-fetcher)

Escrever o laço de janelas, o tratamento de erros e a conversão de tipos para cada projeto cansa. O bcb-sgs-fetcher, pacote de código aberto da Quantilica, faz isso e devolve objetos tipados. A instalação passa pela CLI quantilica, que instala cada fonte de dados sob demanda no mesmo ambiente Python (use um ambiente virtual):

pip install quantilica-cli
quantilica install bcb-sgs
quantilica install sidra
quantilica install rtn
quantilica install td

Com o pacote instalado, o cliente SgsDataClient funciona como gerenciador de contexto e reaproveita a conexão HTTP entre chamadas:

from bcb_sgs_fetcher import SgsDataClient

with SgsDataClient() as client:
    ipca = client.fetch_series_data(series_id=433)  # histórico completo
    ptax = client.fetch_series_data(series_id=1, period="latest")  # últimas 20

print(len(ipca), ipca[0])
print(ipca[-1])
print(ptax[-1].date, ptax[-1].value)

561 SeriesPoint(series_id=433, date=datetime.date(1980, 1, 1), value=Decimal('6.62'), date_end=None)
SeriesPoint(series_id=433, date=datetime.date(2026, 9, 1), value=Decimal('0.82'), date_end=None)
2026-10-20 5.0140

Cada observação é um SeriesPoint com date já convertida para datetime.date e value em Decimal. Para o histórico completo de uma série diária, passe frequency_acronym="D": o cliente busca as 20 observações mais recentes e recua ano a ano até o início da série, sem bater no limite de 10 anos. O parâmetro min_interval do construtor impõe um intervalo mínimo entre requisições, útil em coletas longas.

Se você prefere a linha de comando, o mesmo download grava JSON e um manifesto de proveniência em disco:

quantilica bcb-sgs series sync 433 --period latest -o ./dados/bcb

O arquivo sai como series_433@<data-hora>.json, acompanhado de um .manifest.json com a URL de origem, o horário da coleta e o hash do conteúdo. Para escolher séries, o guia Índices de inflação no SGS lista os códigos de IPCA, INPC e IGP-M, e o guia de Selic e CDI traz os de juros.

Focus e PTAX: como consultar a API Olinda do Banco Central

O Olinda é a plataforma de serviços OData do Banco Central. Ali ficam as expectativas do Boletim Focus e a PTAX por boletim (abertura, intermediários e fechamento), entre outros conjuntos. A consulta usa parâmetros OData como $filter, $orderby, $top e $select. O erro mais comum é montar a URL à mão e esquecer de codificar espaços, aspas simples e o cifrão. Deixe urllib.parse.urlencode cuidar disso, com quote_via=urllib.parse.quote para que os espaços virem %20:

import json
import urllib.parse
import urllib.request

base = "https://olinda.bcb.gov.br/olinda/servico/Expectativas/versao/v1/odata/"
recurso = "ExpectativasMercadoInflacao12Meses"
params = {
    "$filter": "Indicador eq 'IPCA' and Suavizada eq 'S' and baseCalculo eq 0",
    "$orderby": "Data desc",
    "$top": "1",
    "$format": "json",
    "$select": "Indicador,Data,Mediana,numeroRespondentes",
}
url = base + recurso + "?" + urllib.parse.urlencode(params, quote_via=urllib.parse.quote)
with urllib.request.urlopen(url, timeout=30) as resp:
    print(json.load(resp)["value"])

[{'Indicador': 'IPCA', 'Data': '2026-10-16', 'Mediana': 4.5146, 'numeroRespondentes': 125}]

A mediana das projeções para o IPCA dos 12 meses seguintes estava em 4,51% na pesquisa de 16 de outubro de 2026, com 125 instituições respondentes. A PTAX segue a mesma lógica. A diferença é que alguns recursos recebem parâmetros de função, e as datas vão no formato americano MM-DD-AAAA entre aspas simples:

import json
import urllib.parse
import urllib.request

base = "https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/odata/"
recurso = "CotacaoDolarPeriodo(dataInicial=@dataInicial,dataFinalCotacao=@dataFinalCotacao)"
params = {
    "@dataInicial": "'10-13-2026'",  # formato MM-DD-AAAA, entre aspas simples
    "@dataFinalCotacao": "'10-19-2026'",
    "$format": "json",
    "$select": "cotacaoCompra,cotacaoVenda,dataHoraCotacao",
}
url = base + recurso + "?" + urllib.parse.urlencode(params, quote_via=urllib.parse.quote)
with urllib.request.urlopen(url, timeout=30) as resp:
    for linha in json.load(resp)["value"]:
        print(linha["dataHoraCotacao"], linha["cotacaoCompra"], linha["cotacaoVenda"])

2026-10-13 13:04:26.866133 5.009 5.0096
2026-10-14 13:05:17.833426 5.0435 5.0441
2026-10-15 13:05:33.305854 5.0515 5.0521
2026-10-16 13:04:14.548156 5.082 5.0826
2026-10-19 13:05:47.20983 5.0558 5.0564

A PTAX de venda de 19/10/2026 (R$ 5,0564) é idêntica à da série 1 do SGS, o que serve de checagem cruzada entre as duas APIs. Como o Banco Central chega a esse número, com a conta refeita a partir dos boletins da PTAX via API Olinda, está no guia sobre a PTAX. Para descobrir os recursos e campos de cada serviço, abra a página "aplicação" do serviço no Olinda; ela lista os recursos e gera URLs de exemplo.

API do IBGE em Python: SIDRA e Agregados

O IBGE oferece duas APIs sobre o mesmo acervo de tabelas.

• API SIDRA (apisidra.ibge.gov.br/values): devolve uma lista "achatada", em que cada linha é um valor. A primeira linha descreve as colunas.
• API de Agregados v3 (servicodados.ibge.gov.br/api/v3/agregados): devolve JSON aninhado por variável, classificação e localidade, e expõe os metadados (períodos disponíveis, níveis territoriais, unidades).

Na API SIDRA, a consulta é um caminho de pares parâmetro/valor: t é a tabela, n1…n6 o nível territorial (Brasil, região, UF, município…), v a variável, p o período e c as classificações. O exemplo usa a tabela 4709 do Censo 2022:

import json
import urllib.request

# Tabela 4709 (Censo 2022) | n1 = Brasil | v/93 = população residente | p = período
url = "https://apisidra.ibge.gov.br/values/t/4709/n1/all/v/93/p/all"
with urllib.request.urlopen(url, timeout=60) as resp:
    linhas = json.load(resp)

cabecalho, dados = linhas[0], linhas[1:]  # a 1ª linha descreve as colunas
for linha in dados:
    print(linha["D1N"], linha["D2N"], linha["D3N"], linha["V"], linha["MN"])

Brasil População residente 2022 203080756 Pessoas

O mesmo dado pela API de Agregados, agora por unidade da federação (N3):

import json
import urllib.request

# Mesmo dado pela API de Agregados v3: população residente por UF (N3)
url = (
    "https://servicodados.ibge.gov.br/api/v3/agregados/4709"
    "/periodos/2022/variaveis/93?localidades=N3[all]"
)
with urllib.request.urlopen(url, timeout=60) as resp:
    resultado = json.load(resp)

series = resultado[0]["resultados"][0]["series"]
print(resultado[0]["variavel"], "-", len(series), "UFs")
for s in series[:3]:
    print(s["localidade"]["nome"], s["serie"]["2022"])

População residente - 27 UFs
Rondônia 1581196
Acre 830018
Amazonas 3941613

O limite de 50.000 valores da API SIDRA

O número de valores de uma consulta é o produto das quantidades escolhidas em cada dimensão: localidades × variáveis × períodos × categorias. Pedir a população estimada (tabela 6579) dos 5.570 municípios em todos os anos disponíveis dá 122.562 valores, e a API recusa com HTTP 400 e a mensagem "Quantidade de valores solicitados: 122562 excedeu o limite: 50000". Para tabelas grandes, divida a consulta por período ou por grupo de localidades.

O fetcher sidra-fetcher

O SidraClient lê os metadados da tabela, planeja as requisições por nível territorial e junta o resultado numa lista:

from sidra_fetcher.fetcher import SidraClient

with SidraClient() as client:
    linhas = client.get_dados_agregado(
        4709, niveis_territoriais=["N3"], variaveis=["93"]
    )

cabecalho, dados = linhas[0], linhas[1:]
print(len(dados), "UFs")
for linha in dados[:3]:
    print(linha["D1N"], linha["V"])

27 UFs
Rondônia 1581196
Acre 830018
Amazonas 3941613

Use o cliente sempre dentro do bloco with: fora dele, cada requisição abre uma conexão nova, com novo handshake TLS. Para tabelas grandes, iter_dados_agregado devolve os blocos um a um, sem acumular tudo na memória. Pela linha de comando, o download vai para NDJSON com manifesto:

quantilica sidra info 4709
quantilica sidra sync 4709 --niveis N6 --variaveis 93 -o ./dados/sidra

O segundo comando grava dados_N6.ndjson com as 5.570 linhas municipais, mais a linha de cabeçalho. A opção --dry-run mostra o plano de requisições sem baixar nada. A mesma tabela pode ser explorada sem código na página de extração da tabela 4709.

Existe API do Tesouro Nacional? RTN e Tesouro Direto

O Tesouro não tem um endpoint JSON equivalente ao SGS para as estatísticas fiscais. O Resultado do Tesouro Nacional (RTN) sai todo mês numa planilha "Série Histórica", com uma aba por tabela, e os dados do Tesouro Direto saem como arquivos CSV no Tesouro Transparente. O trabalho, portanto, é baixar o arquivo oficial e transformá-lo em tabela longa. O rtn-fetcher faz as duas coisas:

import tempfile
from pathlib import Path

from rtn_fetcher import read_sheet
from rtn_fetcher.fetcher import download_latest_file

pasta = Path(tempfile.mkdtemp(prefix="rtn-"))
arquivo = download_latest_file(pasta)  # planilha "Série Histórica" do RTN
dados, contas = read_sheet(arquivo, "1.1")  # Tabela 1.1, valores em R$ correntes

# Conta 5 = resultado primário do Governo Central (acima da linha)
primario_2026 = [
    linha for linha in dados.iter_rows() if linha[2] == "5" and linha[0] == 2026
]
total = sum(linha[3] for linha in primario_2026)
ultimo_mes = primario_2026[-1][1]
print(arquivo.name)
print(f"Jan-{ultimo_mes:02d}/2026: R$ {total / 1e9:.1f} bilhões")

[email protected]
Jan-08/2026: R$ -94.9 bilhões

O Governo Central acumulou déficit primário de R$ 94,9 bilhões de janeiro a agosto de 2026. read_sheet devolve duas tabelas: dados, no formato longo (year, month, account, value, com a primeira linha de cabeçalho), e contas, com o código, o nome e a hierarquia de cada linha da planilha. O nome do arquivo carrega o carimbo Last-Modified do servidor do Tesouro, então cada nova divulgação gera um arquivo novo, sem sobrescrever o anterior. A mesma conta pode ser consultada no navegador na página do resultado primário do Governo Central.

Pela CLI, quantilica rtn list mostra o catálogo de publicações do RTN (são milhares de arquivos desde a década de 1990, entre PDFs, anexos e planilhas) e quantilica rtn sync baixa as entradas selecionadas. Rode com --dry-run antes, para ver o que será baixado.

No Tesouro Direto, a fonte primária são os conjuntos de dados do Tesouro Transparente. O conjunto "Taxas dos Títulos Ofertados" traz taxas e preços de compra e venda de cada título, dia a dia. O tesouro-direto-fetcher resolve os endereços dos CSV pelo catálogo CKAN e baixa os arquivos:

quantilica td list
quantilica td sync prices -o ./dados/td

O grupo prices corresponde às taxas e preços; há também operations, investors, stock, buybacks e sales. Uma ressalva prática: o catálogo CKAN do Tesouro Transparente respondia HTTP 503 em 20 de outubro de 2026, quando este guia foi testado. Portais de dados abertos têm janelas de indisponibilidade, e o pipeline precisa tentar de novo mais tarde em vez de quebrar. As taxas já coletadas podem ser vistas na página de títulos do Tesouro Direto.

HTTP direto ou fetcher: qual escolher

Boas práticas para coletar dados econômicos por API

• Guarde o dado bruto antes de transformar. Salve a resposta original (JSON, NDJSON, xlsx) com data e hora no nome. Se a fonte revisar o número, você consegue reconstituir o que tinha e quando. É o que os manifestos dos fetchers registram.
• Respeite a fonte. Nenhuma dessas APIs cobra, mas todas são infraestrutura pública. Faça cache local, evite baixar o histórico inteiro a cada execução e espace as requisições em coletas longas.
• Trate revisões e datas de referência. O PIB e as séries do RTN passam por revisões; o SGS marca séries mensais no dia 1; o Focus é semanal e tem a data da pesquisa, não a da publicação.
• Valide com uma segunda fonte. A PTAX do SGS e a do Olinda devem coincidir. A população do Censo na API SIDRA e na de Agregados também. Divergência é sinal de filtro errado.
• Programe a falha. Use timeout em toda requisição, trate 400, 404, 406 e 503 explicitamente e registre a URL que falhou.

Alternativa: uma API única para BCB, IBGE e Tesouro

Quem prefere uma única interface para as quatro fontes pode usar a API v2 do Quantilica. Ela entrega séries do Banco Central, do RTN, do SIDRA e do Tesouro Direto por um identificador único, com metadados, observações em JSON ou CSV, consultas em lote, busca no catálogo e calendário de divulgações. A chave é gratuita, criada na área de credenciais da conta após o cadastro. O plano gratuito permite 30 requisições por minuto, 5.000 requisições por mês, 3 chaves ativas e lotes de até 10 séries por chamada. A documentação, os exemplos em Python, R e cURL e a referência interativa estão no Portal do Desenvolvedor.

Leia também:

• Corrigir valor pela inflação: IPCA, INPC e IGP-M com exemplos
• Resultado primário 2026: a meta do arcabouço será cumprida?
• Censo 2022 por município: população e domicílios no SIDRA
• DATASUS: SIM, SINASC, SIH, SIA ou SINAN? Qual base usar
• Como abrir arquivos .DBC do DATASUS e converter para CSV/Parquet

Perguntas Frequentes

A API do Banco Central é gratuita?

Sim. A API do SGS (api.bcb.gov.br) e os serviços do Olinda são públicos e gratuitos, e não exigem cadastro nem chave de acesso. Os limites são técnicos: até 20 observações em /ultimos/N e janela máxima de 10 anos por consulta em séries diárias.

Como baixar dados do IBGE (SIDRA) em Python?

Monte a URL da API SIDRA com tabela, nível territorial, variável e período (por exemplo, /values/t/4709/n1/all/v/93/p/all) e leia o JSON com urllib e json. Para tabelas grandes, o sidra-fetcher divide a consulta automaticamente.

Qual o limite de dados por consulta na API SGS?

Séries mensais, trimestrais e anuais vêm completas numa única chamada. Séries diárias exigem dataInicial e aceitam janelas de no máximo 10 anos; sem isso, a API responde HTTP 406. O sufixo /ultimos/N aceita N de no máximo 20.

Existe API do Tesouro Nacional?

Não há um endpoint JSON de séries fiscais como o do Banco Central. O RTN é publicado mensalmente numa planilha "Série Histórica" e o Tesouro Direto em arquivos CSV no Tesouro Transparente. Os fetchers rtn-fetcher e tesouro-direto-fetcher baixam esses arquivos oficiais e os transformam em tabelas.

Qual o limite da API SIDRA do IBGE?

Cada consulta pode pedir no máximo 50.000 valores, contados como o produto de localidades, variáveis, períodos e categorias. Acima disso, a API responde HTTP 400 e informa a quantidade solicitada.

Como obter as projeções do Boletim Focus por API?

Pelo serviço Expectativas do Olinda. O recurso ExpectativasMercadoInflacao12Meses traz a inflação esperada para os 12 meses seguintes, e ExpectativasMercadoAnuais traz as projeções por ano-calendário de IPCA, Selic, câmbio e PIB. Filtre com $filter e ordene por Data desc para pegar a pesquisa mais recente.

Preciso de requests ou httpx para usar essas APIs?

Não. Todos os exemplos com HTTP direto deste guia usam só urllib.request e json, que vêm com o Python. Bibliotecas como requests ou httpx deixam o código mais curto, mas não são necessárias.

Referências

1. BANCO CENTRAL DO BRASIL. Portal de Dados Abertos do Banco Central do Brasil. Brasília: BCB, 2026. Disponível em: https://dadosabertos.bcb.gov.br/. Acesso em: 20 out. 2026.
2. BANCO CENTRAL DO BRASIL. Sistema Gerenciador de Séries Temporais (SGS). Brasília: BCB, 2026. Disponível em: https://www3.bcb.gov.br/sgspub/consultarvalores/telaCvsSelecionarSeries.paint. Acesso em: 20 out. 2026.
3. BANCO CENTRAL DO BRASIL. Olinda: serviço PTAX (Dólar comercial). Brasília: BCB, 2026. Disponível em: https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/aplicacao. Acesso em: 20 out. 2026.
4. BANCO CENTRAL DO BRASIL. Olinda: serviço Expectativas de Mercado (Focus). Brasília: BCB, 2026. Disponível em: https://olinda.bcb.gov.br/olinda/servico/Expectativas/versao/v1/aplicacao. Acesso em: 20 out. 2026.
5. INSTITUTO BRASILEIRO DE GEOGRAFIA E ESTATÍSTICA. API de dados agregados (versão 3). Rio de Janeiro: IBGE, 2026. Disponível em: https://servicodados.ibge.gov.br/api/docs/agregados?versao=3. Acesso em: 20 out. 2026.
6. INSTITUTO BRASILEIRO DE GEOGRAFIA E ESTATÍSTICA. Tabela 4709: população residente (Censo Demográfico 2022). Rio de Janeiro: IBGE, 2023. Disponível em: https://sidra.ibge.gov.br/tabela/4709. Acesso em: 20 out. 2026.
7. SECRETARIA DO TESOURO NACIONAL. Resultado do Tesouro Nacional (RTN). Brasília: STN, 2026. Disponível em: https://www.gov.br/tesouronacional/pt-br/estatisticas-fiscais-e-planejamento/resultado-do-tesouro-nacional-rtn. Acesso em: 20 out. 2026.
8. SECRETARIA DO TESOURO NACIONAL. Tesouro Transparente. Brasília: STN, 2026. Disponível em: https://www.tesourotransparente.gov.br/. Acesso em: 20 out. 2026.
9. OASIS. OData: Open Data Protocol, documentação. 2026. Disponível em: https://www.odata.org/documentation/. Acesso em: 20 out. 2026.
10. QUANTILICA. quantilica-cli (pacote Python). 2026. Disponível em: https://pypi.org/project/quantilica-cli/. Acesso em: 20 out. 2026.