Consultar valores da série
bcb_serie_valoresFetch historical values for one BCB SGS time series by code, with optional start and end dates to retrieve a full history or a specific window.
Instructions
Consulta o histórico de valores de UMA série temporal do BCB pelo código SGS, opcionalmente limitado por um intervalo de datas (dataInicial/dataFinal). Quando usar: para obter a série histórica completa ou uma janela de datas específica. Quando NÃO usar: para apenas os pontos mais recentes use bcb_serie_ultimos; para a variação percentual use bcb_variacao; para comparar várias séries use bcb_comparar; se não souber o código, descubra-o antes com bcb_buscar_serie ou bcb_series_populares. Retorna: objeto serie (codigo, nome, categoria, periodicidade), totalRegistros, periodoInicial, periodoFinal e dados (array de {data, valor}); quando não há dados, totalRegistros = 0 e uma observacao explicativa. Períodos longos: a API do BCB limita séries DIÁRIAS a 10 anos por consulta e recusa janela aberta (HTTP 406). Isso é tratado automaticamente — a janela é fatiada em requisições de até 3 anos e o resultado vem fundido e ordenado, com chunking na resposta dizendo quantas janelas foram usadas; se o período pedido estava aberto numa série diária, janelaAplicada diz qual janela foi usada e por quê. Harmonização: frequencia (mensal|trimestral|anual) reamostra a série antes de responder, com a convenção escolhida em agregacao; a resposta traz harmonizacao com derived: true e a nota do cálculo. O que cada número é: data é a data de referência na convenção do SGS — em série mensal, trimestral ou anual, o PRIMEIRO dia do período (01/03/2026 = março de 2026). Algumas séries já chegam ACUMULADAS da origem e só o nome diz isso: acumulado no ano (PIB 4381, 4386) e acumulado em 12 meses (13522, 4382, 5793) — o valor numa data é o acumulado até aquele período, então não some esses valores nem subtraia um do outro; para o valor de um mês, use a série mensal. Revisões: o valor é o que o SGS publica no instante da extração (retrieved_at na proveniência). O BCB revisa séries como PIB, IBC-Br, balanço de pagamentos e crédito, e o SGS não guarda a versão originalmente divulgada — um ponto passado pode mudar entre duas consultas, e este servidor não tem como devolver o número da primeira divulgação. Comportamento: consome a API pública SGS do Banco Central do Brasil — sem autenticação, chave de API ou cadastro, e sem limite de requisições divulgado (uso é best-effort). Em falha transitória ou timeout a chamada é repetida automaticamente (até 3 tentativas, backoff exponencial); persistindo o erro, retorna isError: true com mensagem em português (HTTP 404 = série inexistente ou sem dados no período solicitado). O resultado vem como JSON tanto em texto quanto em structuredContent (conforme o outputSchema); datas no formato dd/MM/yyyy e valores numéricos (ponto decimal).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| codigo | Yes | Código da série no SGS/BCB (ex: 433 para IPCA mensal, 11 para Selic) | |
| agregacao | No | Como agregar os valores de cada período quando `frequencia` é informada. `ultimo` (padrão) serve a nível de preço, taxa e índice; `soma` a fluxo; `acumulada` a séries que JÁ SÃO variação percentual (IPCA mensal, por exemplo), compondo geometricamente — somar 12 variações mensais NÃO dá a inflação do ano. | ultimo |
| dataFinal | No | Data final no formato yyyy-MM-dd ou dd/MM/yyyy (opcional) | |
| frequencia | No | Opcional: reamostra a série para esta frequência antes de responder (só agrega para períodos MAIORES; pedir frequência mais fina que a da série é recusado). Útil para comparar séries de periodicidades diferentes. | |
| dataInicial | No | Data inicial no formato yyyy-MM-dd ou dd/MM/yyyy (opcional) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dados | Yes | Observações históricas | |
| serie | Yes | Identificação da série temporal | |
| chunking | No | Presente quando a consulta foi fatiada em várias requisições à origem, por causa do limite de 10 anos por janela em séries diárias. As fatias são fundidas e ordenadas antes de responder. | |
| observacao | No | Mensagem informativa (ex.: quando não há dados) | |
| provenance | Yes | Bloco de proveniência: fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando há o que dizer, de onde veio cada parte, avisos da fonte, o que o servidor calculou e se o dado ainda pode mudar | |
| attribution | Yes | URLs canônicas das fontes desta resposta (lista de atribuição) | |
| harmonizacao | No | Presente quando `frequencia` foi informada: descreve a reamostragem aplicada. Valor DERIVADO — calculado por este servidor, não publicado pelo Banco Central. | |
| periodoFinal | No | Data da última observação | |
| janelaAplicada | No | Presente quando o período pedido estava aberto numa série diária e o servidor aplicou uma janela própria (a origem recusa janela aberta em série diária com HTTP 406). | |
| periodoInicial | No | Data da primeira observação | |
| totalRegistros | Yes | Quantidade de observações retornadas |