Dados Históricos da B3 com Python, pandas e API

O endpoint /api/v2/stocks/historical retorna séries OHLCV de ações, units, ETFs, BDRs, FIIs e índices negociados na B3. Você pode pedir uma janela pronta ou informar as datas inicial e final.

curl "https://brapi.dev/api/v2/stocks/historical?symbols=PETR4&range=1y&interval=1d&sortOrder=asc"

Cada ponto pode conter abertura, máxima, mínima, fechamento, volume e fechamento ajustado. A resposta fica pronta para um DataFrame sem baixar e interpretar o arquivo COTAHIST.

Baixar o histórico com Python

Instale as duas dependências usadas no exemplo:

pip install requests pandas

Depois faça a consulta e transforme a série em DataFrame:

import os
import requests
import pandas as pd

url = "https://brapi.dev/api/v2/stocks/historical"
token = os.getenv("BRAPI_TOKEN")
headers = {"Authorization": f"Bearer {token}"} if token else {}

response = requests.get(
    url,
    params={
        "symbols": "PETR4",
        "range": "1y",
        "interval": "1d",
        "sortOrder": "asc",
    },
    headers=headers,
    timeout=30,
)
response.raise_for_status()

payload = response.json()
result = payload["results"][0]
prices = result["data"]["historicalDataPrice"]

df = pd.DataFrame(prices)
df["date"] = pd.to_datetime(df["date"], unit="s", utc=True)
df = df.set_index("date").sort_index()

print(df[["open", "high", "low", "close", "adjustedClose", "volume"]].tail())

O campo de data pode ser timestamp Unix ou texto ISO, conforme o contrato documentado para o ativo. Se o pd.to_datetime receber texto, remova unit="s".

Escolher período e intervalo

Há duas formas de definir a janela.

Com range, você pede períodos como 1mo, 6mo, 1y, 5y, ytd ou max:

/api/v2/stocks/historical?symbols=VALE3&range=5y&interval=1d

Com datas, você controla as duas pontas:

/api/v2/stocks/historical?symbols=VALE3&startDate=2024-01-01&endDate=2024-12-31&interval=1d

Intervalos aceitos incluem minutos, horas, dias, semanas e meses. A quantidade de histórico e a granularidade disponível dependem da fonte e do plano.

Para análises diárias, prefira interval=1d. Dados intradiários ocupam mais memória, aumentam o número de pontos e nem sempre são necessários.

Consultar vários tickers

Separe até 20 símbolos por vírgula:

curl "https://brapi.dev/api/v2/stocks/historical?symbols=PETR4,VALE3,ITUB4&range=1y&interval=1d"

Para juntar as séries sem perder o ticker:

frames = []

for item in payload["results"]:
    frame = pd.DataFrame(item["data"]["historicalDataPrice"])
    frame["symbol"] = item["symbol"]
    frames.append(frame)

history = pd.concat(frames, ignore_index=True)

Esse formato longo funciona bem em bancos analíticos, gráficos e comparações entre ativos.

Fechamento normal e fechamento ajustado

close é o preço de fechamento observado naquele pregão. adjustedClose procura manter a série comparável após eventos como proventos e desdobramentos.

Use close para reproduzir o preço negociado naquela data. Use adjustedClose em cálculos de retorno quando o objetivo exigir uma série ajustada, depois de conferir a cobertura do ativo.

Não some dividendos a uma série ajustada sem entender o ajuste. Isso pode contar o mesmo evento duas vezes. O tema é detalhado em preço ajustado de ações na B3.

Exportar para CSV

df.to_csv(
    "PETR4-historico.csv",
    columns=["open", "high", "low", "close", "adjustedClose", "volume"],
    encoding="utf-8",
)

Ao importar o CSV em outro sistema, preserve o fuso horário e a ordem da série. O parâmetro sortOrder=asc evita inverter o tempo por acidente.

Evitar erros silenciosos

Trate pelo menos estes casos:

• resposta HTTP diferente de 200;
• ticker sem histórico para a janela solicitada;
• campos nulos em pregões sem informação completa;
• ticker antigo resolvido para um código novo;
• limites de intervalo e período do plano.

A resposta inclui requestedSymbol, symbol e changed quando a brapi resolve um código antigo. Salve o símbolo canônico junto com a série.

Para descobrir os ativos antes da consulta, veja como listar todas as ações da B3 por API.