bcb_focus_expectativas
Query Focus market expectations for an economic indicator across monthly, quarterly, annual, or rolling 12/24-month horizons. Returns mean, median, standard deviation, min, max, respondent count.
Instructions
Consulta as expectativas de mercado do boletim Focus para UM indicador, com o horizonte como parâmetro: mensal, trimestral, anual, inflação nos próximos 12 meses e nos próximos 24 meses. Devolve média, mediana, desvio padrão, mínimo, máximo e número de respondentes por data de coleta. Quando usar: para expectativa de IPCA, IGP-M, PIB, câmbio e afins em um mês, trimestre ou ano específico, ou para a inflação rolante. Quando NÃO usar: para expectativa de Selic por reunião do Copom use bcb_focus_selic; para o valor REALIZADO (não esperado) use bcb_serie_valores. Regras do contrato: referencia é obrigatória nos horizontes de calendário (mensal, trimestral, anual) e recusada nos rolantes; suavizada só vale nos rolantes; top5: true traz as expectativas das cinco instituições mais assertivas e existe nos cinco horizontes. Se não souber o texto exato do indicador ou da referência, chame bcb_focus_referencias primeiro — o conjunto de indicadores MUDA por horizonte, e pedir um indicador no horizonte em que a fonte não o publica é a causa mais comum de resposta vazia. Retorna: indicador, horizonte, base (consenso|top5), filtro (referencia, dataInicial, dataFinal, janelaPadrao, suavizada), totalRegistros, expectativas (array normalizado), urlConsulta, consultadoEm e, quando aplicável, observacao. Sem datas, a janela padrão é de 30 dias. Fonte: Expectativas de Mercado (Focus) do Banco Central do Brasil, via Olinda OData. O Focus é vintage por construção: coletadoEm é a data da coleta e referencia é o alvo da expectativa — a mesma referência aparece em muitas coletas, e é isso que permite ver a expectativa mudar no tempo. A contagem é feita do nosso lado porque a fonte ignora $count; e o filtro é obrigatório por construção porque consulta sem filtro não completa na origem. Microdados por instituição NÃO são expostos: a fonte desativou esse recurso por risco de quebra de confidencialidade.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| top5 | No | Expectativas do Top 5 (as cinco instituições mais assertivas) em vez do consenso; existe nos cinco horizontes | |
| limite | No | Máximo de coletas a devolver (1-500, padrão 50) | |
| dataFinal | No | Fim da janela de COLETA (yyyy-MM-dd ou dd/MM/yyyy). Padrão: hoje. | |
| horizonte | Yes | mensal, trimestral e anual usam `referencia`; inflacao_12m e inflacao_24m são rolantes e não usam | |
| indicador | Yes | Indicador exatamente como a fonte publica (ex.: 'IPCA', 'IGP-M', 'PIB Total', 'Câmbio'). Veja bcb_focus_referencias. | |
| suavizada | No | Só nos horizontes rolantes: série suavizada (true) ou não suavizada (false) | |
| referencia | No | Alvo da expectativa: MM/yyyy (mensal), T/yyyy (trimestral) ou yyyy (anual). Obrigatória nesses três; proibida nos rolantes. | |
| dataInicial | No | Início da janela de COLETA (yyyy-MM-dd ou dd/MM/yyyy). Padrão: 30 dias antes do fim. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| base | Yes | ||
| filtro | Yes | Filtro efetivamente aplicado na origem; nulo onde o parâmetro não foi informado | |
| horizonte | Yes | ||
| indicador | Yes | ||
| observacao | No | ||
| provenance | Yes | Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença | |
| attribution | Yes | URLs canônicas das fontes desta resposta (lista de atribuição) | |
| urlConsulta | Yes | URL OData consultada, reproduzível no navegador | |
| consultadoEm | Yes | Timestamp ISO 8601 da consulta | |
| expectativas | Yes | ||
| totalRegistros | Yes | Coletas encontradas (contagem client-side) |