Open Economics

Servidor MCP gratuito, sem autenticação, para dados econômicos oficiais brasileiros, descoberta semântica e consultas que preservam a fonte.

GitHubExperimente este MCPPatrocinado

Documentação

API Open Economics

Uma camada de roteamento semântico gratuita e somente leitura para dados econômicos brasileiros oficiais.

Faça uma pergunta econômica real → · Conecte o servidor MCP →

O Open Economics 2.0 começa com uma necessidade real de informação econômica, resolve seu significado independentemente da cobertura atual e, em seguida, a roteia para dados oficiais. Seu catálogo sincronizado expõe atualmente 12.875 séries do BCB SGS e agregados do IBGE, além de acesso direto a relatórios fiscais do SICONFI, Comex Stat do MDIC e preços de combustíveis da ANP, e dados versionados de consumo de eletricidade da EPE, Novo Caged do MTE, fundos de investimento da CVM, RTN fiscal do Tesouro e Dívida Pública Federal do RMD (12.886 conjuntos de dados oficiais no total). Os 32 IDs de séries v1 convenientes permanecem compatíveis.

Descoberta, REST, o produto existente e o MCP compartilham um núcleo semântico. Um conceito resolvido é mantido separado da disponibilidade, portanto uma necessidade não suportada é relatada explicitamente em vez de ser mapeada silenciosamente para uma série próxima. Unidades, dimensões, períodos de referência, identificadores de fonte, valores brutos, links de metodologia e proveniência de recuperação viajam com os dados.

Comece pela necessidade econômica

curl --fail --silent \
  "https://open-economics-data.knbf982hkn.chatgpt.site/api/v2/search?q=desemprego%20desde%202015"

curl --fail --silent \
  "https://open-economics-data.knbf982hkn.chatgpt.site/api/v2/datasets/ibge-aggregates%3A6381/schema"

Para o BCB, /api/v2/datasets/bcb-sgs:{code}/observations fornece acesso direto a séries com metadados oficiais de frequência, unidade, fonte, cobertura, fórmula e avisos. Para o IBGE, inspecione /schema e envie seleções explícitas de variable, periods, locality e classification para /observations. SICONFI DCA, RREO e RGF usam as mesmas rotas de conjuntos de dados, mantendo entidade, período de relatório, anexo, conta, coluna e valor bruto. A estrutura multidimensional oficial é preservada em vez de achatada. O Comex Stat preserva dimensões e métricas de fluxo comercial. Consultas de preços de combustíveis da ANP retornam agregados de período/geografia/produto calculados a partir de observações oficiais de postos, com contagens de fontes e a transformação divulgada, enquanto identidade do posto e campos de endereço são excluídos. EPE e MTE servem instantâneos compactos e versionados de planilhas oficiais: eletricidade mantém geografia/classe/mercado, enquanto os estoques e fluxos ajustados do Novo Caged mantêm seus desdobramentos separados por total nacional, região/estado ou atividade econômica. Relatórios diários de fundos da CVM mantêm identidade de fundo/classe e valores de cota; agregados de classificação somam apenas medidas aditivas e identificam datas de arquivamento incompletas. O RTN mantém sua hierarquia mensal de contas e convenções de pagamento efetivo/acima da linha. As estatísticas de dívida do RMD mantêm tabelas separadas de composição, detentores, vencimento e custo, com suas unidades oficiais, definições e safra de publicação.

Quando usar o Open Economics

Se você já conhece o identificador oficial exato e o contrato de fonte, chamar o publicador diretamente continua sendo o caminho mais curto. O Open Economics é útil quando a necessidade começa em linguagem humana, abrange convenções de publicadores, exige dimensões explícitas ou deve manter um modelo consistente de proveniência e erro.

Um contrato para fontes oficiais

O mesmo envelope de observação pode recuperar o IBC-Br do BCB (SGS 24363) e o crescimento real do PIB do IBGE (SIDRA 5932/6561), sem manter dois analisadores de data e resposta:

curl --fail --silent "https://open-economics-data.knbf982hkn.chatgpt.site/api/v1/indicators/br-ibc-br/observations?start=2024-01-01"
curl --fail --silent "https://open-economics-data.knbf982hkn.chatgpt.site/api/v1/indicators/br-gdp-real-yoy/observations?start=2024-01-01"

O exemplo Python multi-fonte executável usa ambas as séries e imprime sua proveniência oficial e estado de atualização.

Comece pelo catálogo

curl --fail --silent "https://open-economics-data.knbf982hkn.chatgpt.site/api/v1"
curl --fail --silent "https://open-economics-data.knbf982hkn.chatgpt.site/api/v1/indicators?q=ipca&source=ibge"
curl --fail --silent "https://open-economics-data.knbf982hkn.chatgpt.site/api/v1/indicators/br-ipca-monthly"

GET /api/v1/indicators é o endpoint de descoberta. Seu campo meta.available_filters lista todos os valores canônicos de category, frequency e source. Ele aceita:

ParâmetroSignificado
qBusca sem diferenciar maiúsculas/minúsculas em IDs, nomes, aliases e códigos oficiais
categoryUm ID de categoria canônico como inflation ou interest-rates
frequencydaily, monthly, quarterly ou annual
sourcebcb ou ibge
limit1–500, padrão 100

Filtros inválidos são rejeitados com uma resposta de problema estruturada; eles nunca se tornam silenciosamente um conjunto de resultados vazio.

Recuperar uma série

curl --fail --silent \
  "https://open-economics-data.knbf982hkn.chatgpt.site/api/v1/indicators/br-ipca-monthly/observations?start=2024-01-01&end=2024-12-31"

curl --fail --silent \
  "https://open-economics-data.knbf982hkn.chatgpt.site/api/v1/indicators/br-selic-target/observations?start=2025-01-01&order=desc&limit=12"

curl --fail --silent \
  "https://open-economics-data.knbf982hkn.chatgpt.site/api/v1/indicators/br-selic-target/latest"

Solicitações de observação aceitam start, end, order=asc|desc, limit=1..5000 e format=json|csv. Datas usam YYYY-MM-DD e end não podem estar no futuro. Solicitações diárias do BCB são limitadas a dez anos porque o SGS aplica o mesmo limite upstream.

Todas as respostas JSON de séries usam o mesmo envelope:

{
  "data": [
    {
      "date": "2024-01-01",
      "period": "2024-01",
      "source_date": "202401",
      "value": 0.42,
      "raw_value": "0.42",
      "status": "observed"
    }
  ],
  "meta": {
    "indicator": { "id": "br-ipca-monthly", "unit_symbol": "%" },
    "provenance": { "upstream_url": "…", "retrieved_at": "…" },
    "returned": 1,
    "available": 1,
    "truncated": false
  }
}

date é a data de início normalizada para o período de referência; period é o identificador ciente de frequência (YYYY-MM-DD, YYYY-MM, YYYY-QN ou YYYY). source_date e raw_value são mantidos exatamente como no publicador oficial. Leia meta.indicator.date_semantics antes de interpretar séries de estoque, fluxo ou média móvel trimestral.

Use format=csv para um download simples. Linhas CSV repetem indicator_id, source_id, source_url e upstream_url, portanto os valores exportados mantêm sua proveniência fora do envelope JSON.

Superfície da API

EndpointFinalidade
GET /api/v1Descoberta de API legível por máquina
GET /api/v1/indicatorsBuscar e filtrar o catálogo de indicadores
GET /api/v1/indicators/:idMetadados completos do indicador, unidades, semântica e links
GET /api/v1/indicators/:id/observationsValores históricos normalizados
GET /api/v1/indicators/:id/latestObservação mais recente disponível
GET /api/v1/sourcesMetadados de publicador, atribuição e licença
GET /api/v1/openapi.jsonDescrição OpenAPI 3.1
GET /api/v1/healthProntidão do roteador e catálogo (não chama publicadores)

Todos os endpoints suportam CORS e GET, HEAD e OPTIONS. Respostas de sucesso e erro incluem X-Request-Id; clientes de navegador também podem ler cache, temporização e cabeçalhos de resposta obsoleta.

Erros e atualização

Erros usam application/problem+json com um code estável, HTTP status, title legível por humanos, detail explicativo e request_id. Casos comuns incluem INVALID_DATE, INVALID_CATEGORY, INDICATOR_NOT_FOUND, UPSTREAM_CONNECTION_ERROR e UPSTREAM_TIMEOUT.

A API armazena em cache respostas de fonte normalizadas com sucesso no D1 quando configurado. Se uma atualização falhar e um instantâneo correspondente anterior existir, ele é retornado com meta.stale: true, meta.cache: "stale" e HTTP Warning: 110. Uma falha de leitura ou gravação de cache é tratada como bypass de cache, nunca como falha de dados.

O serviço é atualmente de melhor esforço e não tem SLA de disponibilidade. Veja RELIABILITY.md para a política explícita de disponibilidade, atualização, gerenciamento de mudanças e relatório de incidentes.

Fontes e correção

  • Agregados IBGE/SIDRA: preços, PIB, indústria, varejo, serviços, trabalho. O adaptador solicita os IDs de período oficiais exatos necessários para cada consulta; símbolos de zero, supressão, disponibilidade e qualidade do IBGE mantêm valores distintos de status.
  • BCB SGS: taxas, câmbio, atividade, crédito, fiscal, setor externo e séries de commodities. Linhas são normalizadas, ordenadas e deduplicadas porque a ordenação upstream não é garantida.
  • Tesouro Nacional / SICONFI: contas anuais, execução orçamentária, limites fiscais, gastos com pessoal, dívida e o registro de entidades governamentais.
  • Tesouro Nacional / RTN: receita central do Governo em valor corrente mensal, transferências, despesas e contas de resultado fiscal desde 1997, na hierarquia oficial e unidade de R$ milhões.
  • Tesouro Nacional / RMD: composição mensal da Dívida Pública Federal, detentores da DPMFi, prazo médio e custo. Cada tabela oficial mantém sua própria unidade, cobertura, definições, notas de rodapé e safra de publicação.
  • MDIC / Comex Stat: exportações e importações por produto, parceiro, estado, modal de transporte, unidade aduaneira e classificações internacionais.
  • ANP / Levantamento de Preços de Combustíveis: observações móveis de quatro semanas ou mensais de postos de combustíveis e GLP, agregadas por período explícito, produto e geografia com proveniência de cálculo.
  • EPE / Consumo Mensal de Energia Elétrica: consumo mensal e contagens de consumidores desde 2004 por UF, região, classe e mercado cativo/livre, com a versão oficial da planilha anexada.
  • MTE / Novo Caged: estoque de emprego mensal ajustado, admissões, desligamentos, saldo e variação relativa desde 2020 por total nacional, região/estado ou atividade econômica, com a safra exata da planilha oficial anexada e dimensões de tabela incompatíveis mantidas separadas.
  • CVM / Informe Diário de Fundos: valor diário da carteira, patrimônio líquido, aplicações, resgates, valores de cota e detentores informados. Consultas podem comparar classificações oficiais ou resolver o relatório mais recente de fundo/classe por CNPJ ou nome; valores de cota nunca são agregados e totais de detentores não são representados como pessoas únicas.

Há 32 indicadores selecionados em inflação, taxas de juros, moedas, atividade, trabalho, crédito, fiscal, externo e mercados. Valores nunca são fabricados, preenchidos para frente ou invertidos de sinal silenciosamente. Séries fiscais de NFSP do BCB mantêm a convenção de sinal de necessidade de financiamento do BCB.

Dados do catálogo do BCB são publicados sob ODbL; preserve sua atribuição e obrigações de compartilhamento igual ao distribuir bancos de dados adaptados. Atribua o IBGE como IBGE/SIDRA e mantenha seus links de fonte e termos. Cada resposta de indicador tem as URLs autoritativas e a licença aplicável àquela série.

Executar localmente

Node.js 22.13+ é necessário.

npm install
npm run dev
npm run lint
npm test
npm run catalog:epe-sync
npm run catalog:mte-sync
npm run catalog:cvm-sync
npm run catalog:rtn-sync
npm run catalog:dpf-sync

Exemplos estão disponíveis em examples/python.py, examples/multi_source_python.py e examples/javascript.mjs. A migração D1 em drizzle/ é o registro de implantação para instantâneos de cache.

Licença

A implementação da API é lançada sob a Licença MIT. Os dados upstream permanecem regidos pelos próprios termos e licenças de cada publicador.