Skip to content

instrucoes.md

Latest commit

 

History

History
271 lines (193 loc) · 10.2 KB

instrucoes.md

File metadata and controls

271 lines (193 loc) · 10.2 KB
Raw

BacenBR.jl — Instruções de Uso

Interface Julia para os serviços de dados abertos do Banco Central do Brasil (BCB): séries temporais (SGS), expectativas de mercado (Focus) e câmbio (PTAX/OLINDA).

Instalação / Ativação

Este pacote ainda não está registrado no General Registry. Para usar, ative o ambiente local:

import Pkg
Pkg.activate("caminho/para/pacote_julia")
using BacenBR

Ou, de dentro da pasta pacote_julia, abra o Julia e rode:

import Pkg; Pkg.activate("caminho/para/BacenBR.jl"); using BacenBR

sgs_series — Séries Temporais (SGS)

sgs_series(code; start_date=nothing, end_date=nothing, last=0, window_years=5)

Baixa uma ou mais séries temporais do BCB.

Formas de passar code

Forma Coluna resultante
433 "433"
"ipca" => 433 "ipca"
Dict("ipca" => 433) "ipca"
["ipca" => 433, "selic" => 432] "ipca", "selic"

Parâmetros opcionais

Parâmetro Tipo Descrição
start_date Date ou String Data inicial no formato "YYYY-MM-DD"
end_date Date ou String Data final no formato "YYYY-MM-DD"
last Int Últimos N registros. Ignora start_date/end_date/window_years.
window_years Int Tamanho máximo (em anos) de cada janela de consulta. Default: 5.

A API SGS rejeita consultas com dataFinal - dataInicial maior que 10 anos. Quando o intervalo pedido excede window_years, sgs_series fraciona a consulta em múltiplas janelas consecutivas automaticamente e concatena o resultado — não é preciso fazer isso manualmente.

Exemplos

using BacenBR
using Dates

# Série completa (sem nome — coluna chamada "433")
sgs_series(433)

# Série completa com nome na coluna
sgs_series("ipca" => 433)

# Últimos 12 meses de IPCA
sgs_series("ipca" => 433; last=12)

# IPCA de 2020 em diante
sgs_series("ipca" => 433; start_date="2020-01-01")

# IPCA num intervalo específico
sgs_series("ipca" => 433; start_date=Date(2022, 1, 1), end_date=Date(2022, 12, 31))

# Intervalo longo (30 anos) — fracionado automaticamente em janelas de 5 anos
sgs_series("selic" => 432; start_date="1995-01-01")

# Mesma coisa, com janelas menores (ex: para depurar/observar o fracionamento)
sgs_series("selic" => 432; start_date="1995-01-01", window_years=2)

# Múltiplas séries com nomes
sgs_series(["ipca" => 433, "selic" => 432]; last=12)

# Múltiplas séries com Dict (ordem não garantida)
sgs_series(Dict("ipca" => 433, "igpm" => 189); start_date="2023-01-01")

Séries úteis

Código Nome
433 IPCA (% ao mês)
189 IGP-M (% ao mês)
432 Taxa Selic (% ao dia)
1178 Taxa Selic Over (% a.a)
1 USD/BRL (câmbio)
21619 EUR/BRL (câmbio)
7478 IPCA-15 (% ao mês)
13522 INPC (% ao mês)

Para encontrar outros códigos, acesse: https://www3.bcb.gov.br/sgspub

Comportamento com múltiplas séries

Quando mais de um code é passado, o retorno é um Vector{DataFrame} — um DataFrame por série, na mesma ordem em que os códigos foram passados. Séries do SGS podem ter periodicidades diferentes (ex: IPCA mensal e Selic diária); juntar tudo num único DataFrame por date geraria uma explosão de missing, então cada série vem separada:

dfs = sgs_series(["ipca" => 433, "selic" => 432]; last=12)
ipca, selic = dfs   # cada um é um DataFrame independente, com sua própria frequência

focus_expectations — Expectativas de Mercado (Focus Report)

focus_expectations(period::Symbol; top5=false, indic=nothing, start_date=nothing,
                    end_date=nothing, top=nothing, skip=nothing)

Uma única função cobre as 8 categorias de expectativas da API OLINDA: o endpoint é escolhido pela combinação de period e top5.

period Endpoint aceita top5=true?
:annual Expectativas anuais sim
:quarterly Expectativas trimestrais não
:monthly Expectativas mensais sim
:inflation_12m Inflação para os próximos 12 meses não
:selic Taxa Selic (por reunião do COPOM) sim

Passar top5=true com :quarterly ou :inflation_12m gera erro — não existe endpoint Top 5 para essas periodicidades.

Parâmetros

Parâmetro Tipo Descrição
top5 Bool Retorna as estatísticas Top 5 em vez do agregado geral
indic String ou Vector{String} Indicador(es). Case-sensitive, com acentos.
start_date Date ou String Data inicial no formato "YYYY-MM-DD"
end_date Date ou String Data final no formato "YYYY-MM-DD"
top Int Máximo de linhas retornadas
skip Int Pular os primeiros N registros

Exemplos

using BacenBR
using Dates

# IPCA anual a partir de 2023
focus_expectations(:annual; indic="IPCA", start_date="2023-01-01")

# IPCA e Câmbio anuais — últimos 10 registros
focus_expectations(:annual; indic=["IPCA", "Câmbio"], top=10)

# Expectativas mensais de IPCA
focus_expectations(:monthly; indic="IPCA", start_date="2024-01-01")
# Nota: reference_date é convertida para Date (primeiro dia do mês)

# PIB Total trimestral
focus_expectations(:quarterly; indic="PIB Total", top=20)
# Nota: reference_date fica como String "Q/YYYY" (ex: "1/2025")

# Inflação 12 meses à frente — IPCA e IGP-M
focus_expectations(:inflation_12m; indic=["IPCA", "IGP-M"], start_date="2024-01-01")

# Top 5 IPCA mensal
focus_expectations(:monthly; indic="IPCA", top5=true, top=10)

# Selic — todas as reuniões previstas
focus_expectations(:selic; start_date="2025-01-01")

# Selic Top 5
focus_expectations(:selic; top5=true, start_date="2025-01-01", top=20)

Colunas retornadas (nomes em inglês)

Coluna Descrição
date Data de divulgação da expectativa
indic Nome do indicador
reference_date Período de referência da expectativa
mean Média das expectativas
median Mediana das expectativas
sd Desvio padrão
min Mínimo
max Máximo
respondents Número de respondentes
coefvar Coeficiente de variação
smoothed Expectativa suavizada (S/N)
meeting Reunião do COPOM (endpoint :selic)
typeCalc Tipo de cálculo (endpoints Top 5)

Câmbio — fx_currency, fx_currencies, fx_all_currencies, fx_cross_rates

fx_currency — série diária ou intraday de uma moeda

fx_currency(symbol, start_date, end_date=start_date; intraday=false, parity=false)
  • intraday=false (padrão): série diária de fechamento via PTAX legado. Para "USD" — removido pelo BCB da interface PTAX legada — a função redireciona automaticamente para OLINDA, retornando a cotação de fechamento diária no mesmo formato.
  • intraday=true: todos os boletins do dia via API OLINDA. Aceita parity=true (só válido junto com intraday=true) para retornar a paridade da moeda em relação ao USD em vez da cotação em BRL.
using BacenBR
using Dates

# Série diária — PTAX (fechamento)
fx_currency("USD", "2024-01-01", "2024-01-31")
fx_currency("EUR", "2024-01-01", "2024-01-31")
fx_currency("JPY", Date(2024,1,1), Date(2024,1,31))

# Série intraday — OLINDA (todos os boletins do dia)
fx_currency("USD", "2024-01-02", "2024-01-05"; intraday=true)

# Com paridade em relação ao USD (requer intraday=true)
fx_currency("EUR", "2024-01-02", "2024-01-05"; intraday=true, parity=true)

Retorno: DataFrame com date (intraday=false) ou datetime (intraday=true), mais bid e ask.

fx_currencies — listar moedas disponíveis

fx_currencies(; source=:ptax)
  • source=:ptax (padrão): lista mestre do PTAX legado. Colunas: symbol, name, code, country_name, country_code, currency_type.
  • source=:olinda: lista da API OLINDA. Colunas: symbol, name, currency_type.
fx_currencies()
fx_currencies(; source=:olinda)

fx_all_currencies — todas as moedas numa data

fx_all_currencies(date)

Retorna DataFrame com date, symbol, bid, ask (em BRL) para todas as moedas cotadas numa data.

fx_all_currencies(Date(2024, 1, 2))

fx_cross_rates — matriz de cross-rates

fx_cross_rates(date; ref=:ask)

Retorna DataFrame com coluna :symbol + uma coluna por moeda (incluindo BRL). Cada célula [linha, coluna] = 1 unidade da moeda da linha em unidades da moeda da coluna.

m = fx_cross_rates(Date(2024, 1, 2))          # ask (padrão)
m = fx_cross_rates(Date(2024, 1, 2); ref=:bid)

# quantos USD vale 1 EUR?
m[m.symbol .== "EUR", :USD]