Expectativas de mercado (Focus)
bcb_focus_expectativasQueries market expectations from Brazil's Focus survey for one indicator, returning mean, median, and dispersion by collection date. Use it to track expected IPCA, GDP, or exchange rates.
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 | consenso (todas as instituições) ou top5 (as cinco mais assertivas) | |
| filtro | Yes | Filtro efetivamente aplicado na origem; nulo onde o parâmetro não foi informado | |
| horizonte | Yes | Horizonte consultado | |
| indicador | Yes | Indicador consultado, como pedido | |
| observacao | No | Presente quando `expectativas` foi cortado por `limite` ou quando a janela voltou vazia, com o que fazer | |
| 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) | |
| urlConsulta | Yes | URL OData consultada, reproduzível no navegador | |
| consultadoEm | Yes | Timestamp ISO 8601 da consulta | |
| expectativas | Yes | Expectativas por data de coleta, da mais recente para a mais antiga, até `limite` | |
| totalRegistros | Yes | Coletas encontradas (contagem client-side) |