Open Economics

Open Economics API

一个免费、只读的语义路由层，用于获取权威的巴西经济数据。

• 语义 API： https://open-economics-data.knbf982hkn.chatgpt.site/api/v2
• 稳定序列 API： https://open-economics-data.knbf982hkn.chatgpt.site/api/v1
• MCP： https://open-economics-data.knbf982hkn.chatgpt.site/api/mcp
• 询问数据： https://open-economics-data.knbf982hkn.chatgpt.site/en/ask
• MCP 设置： https://open-economics-data.knbf982hkn.chatgpt.site/en/mcp
• Agent 安装程序： llms-install.md
• 文档： https://open-economics-data.knbf982hkn.chatgpt.site/en/docs
• 可运行示例： https://open-economics-data.knbf982hkn.chatgpt.site/en/guides
• 源代码和问题跟踪器： https://github.com/felipegambettadesouza6-jpg/open-economics
• 可靠性政策： RELIABILITY.md
• 2.0 版发布证据： benchmarks/RELEASE-READINESS.md
• 贡献： CONTRIBUTING.md
• 安全： SECURITY.md

提出一个真实的经济问题 → · 连接 MCP 服务 →

Open Economics 2.0 从真实的经济信息需求出发，独立解析其含义，不受当前数据覆盖范围影响，然后将其路由至官方数据。 其同步目录目前公开了 12,875 个 BCB SGS 序列和 IBGE 汇总数据，以及直接访问 SICONFI 财政报告、MDIC Comex Stat 和 ANP 燃油价格数据的功能，并提供已版本化的 EPE 电力消费、MTE Novo Caged、CVM 投资基金、Tesouro RTN 财政数据和 RMD 联邦公共债务数据（总计 12,886 个官方数据集）。32 个便捷的 v1 序列 ID 仍保持兼容。

发现、REST、现有产品和 MCP 共用一个语义核心。解析出的概念与可用性彼此分离，因此对于不受支持的需求，系统会明确报告，而不是悄悄映射到相近序列。数据中包含单位、维度、参考期间、来源标识符、原始值、方法说明链接和检索溯源信息。

从经济需求出发

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"

对于 BCB，/api/v2/datasets/bcb-sgs:{code}/observations 可直接访问序列，并提供权威的频率、单位、来源、覆盖范围、公式和警告元数据。对于 IBGE，请先检查 /schema，然后向 /observations 发送明确的 variable、periods、locality 和 classification 选择。SICONFI DCA、RREO 和 RGF 使用相同的数据集路由，同时保留实体、报告期间、附表、科目、列和原始值。官方多维结构会完整保留，而不会被压平。Comex Stat 保留贸易流向维度和指标。ANP 燃油价格查询返回根据官方加油站观测计算的期间/地理位置/产品汇总数据，并说明来源数量和转换方式，同时排除加油站身份和地址字段。EPE 和 MTE 提供官方工作簿的精简、已版本化快照：电力数据保留地理位置/类别/市场维度，而经调整的 Novo Caged 存量和流量数据则分别保留全国、区域/州或经济活动分类。CVM 每日基金报告保留基金/类别标识和份额价值；分类汇总仅对可加总指标求和，并标明申报日期不完整的情况。RTN 保留其月度科目层级，以及线以上现金/实际付款惯例。RMD 债务统计将构成、持有人、期限和成本表分别呈现，并保留其官方单位、定义和发布版本。

何时使用 Open Economics

如果你已知确切的官方标识符和数据源契约，直接调用发布方仍是最短路径。当需求以自然语言描述、涉及不同发布方的约定、需要明确维度，或必须保留一致的来源信息和错误模型时，Open Economics 会很有用。

多个官方数据源使用同一套契约

同一观测数据封装即可获取 BCB IBC-Br（SGS 24363）和 IBGE 实际 GDP 增长率（SIDRA 5932/6561），无需分别维护两个日期解析器和响应解析器：

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"

可运行的多数据源 Python 示例使用这两个时间序列，并打印其官方来源信息和最新状态。

从目录开始

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 是发现端点。其 meta.available_filters 字段列出了所有规范的 category、frequency 和 source 值。它接受以下参数：

参数	含义
q	不区分大小写地搜索 ID、名称、别名和官方代码
category	规范的类别 ID，例如 inflation 或 interest-rates
frequency	daily、monthly、quarterly 或 annual
source	bcb 或 ibge
limit	1–500，默认值为 100

无效筛选条件会被拒绝，并返回结构化的问题响应；不会悄悄变成空结果集。

获取时间序列

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"

观测请求接受 start、end、order=asc|desc、limit=1..5000 和 format=json|csv。日期使用 YYYY-MM-DD 格式，且 end 不能是未来日期。每日 BCB 请求的时间跨度最多为十年，因为 SGS 对上游请求也施加了相同限制。

所有 JSON 时间序列响应都使用相同的封装：

{
  "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 是参考期的标准化起始日期；period 是与频率对应的标识符（YYYY-MM-DD、YYYY-MM、YYYY-QN 或 YYYY）。source_date 和 raw_value 会完整保留官方发布方提供的值。解读存量、流量或滚动季度时间序列前，请先查看 meta.indicator.date_semantics。

使用 format=csv 可下载扁平数据。CSV 行会重复包含 indicator_id、source_id、source_url 和 upstream_url，因此导出的值在 JSON 封装之外仍保留其来源信息。

API 接口

端点	用途
GET /api/v1	机器可读的 API 发现信息
GET /api/v1/indicators	搜索和筛选指标目录
GET /api/v1/indicators/:id	完整的指标元数据、单位、语义和链接
GET /api/v1/indicators/:id/observations	标准化的历史值
GET /api/v1/indicators/:id/latest	最新可用观测值
GET /api/v1/sources	发布方、署名和许可证元数据
GET /api/v1/openapi.json	OpenAPI 3.1 描述
GET /api/v1/health	路由器和目录就绪状态（不会调用发布方）

所有端点都支持 CORS 以及 GET、HEAD 和 OPTIONS。成功和错误响应均包含 X-Request-Id；浏览器客户端还可以读取缓存、耗时和过期响应标头。

错误和最新状态

错误使用 application/problem+json，包含稳定的 code、HTTP status、易读的 title、说明性的 detail 和 request_id。常见情况包括 INVALID_DATE、INVALID_CATEGORY、INDICATOR_NOT_FOUND、UPSTREAM_CONNECTION_ERROR 和 UPSTREAM_TIMEOUT。

配置 D1 后，API 会缓存经过成功标准化的来源响应。如果刷新失败，且存在匹配的历史快照，则会返回该快照，并附带 meta.stale: true、meta.cache: "stale" 和 HTTP Warning: 110。缓存读取或写入失败会被视为绕过缓存，而不会被视为数据故障。

该服务目前尽力提供服务，不承诺正常运行时间 SLA。请参阅 RELIABILITY.md，了解明确的可用性、最新状态、变更管理和事件报告政策。

数据来源与准确性

• IBGE Aggregates/SIDRA：价格、GDP、工业、零售、服务业和劳动力数据。 适配器会针对每次查询请求所需的准确官方期间 ID； IBGE 的零值、抑制、可用性和质量标记各自保留不同的 status 值。
• BCB SGS：利率、外汇、经济活动、信贷、财政、外部部门和 大宗商品序列。由于上游顺序不作保证，数据行会经过标准化、排序和去重。
• Tesouro Nacional / SICONFI：年度账户、预算执行、财政限制、 人员支出、债务和政府实体登记信息。
• Tesouro Nacional / RTN：自 1997 年起按月记录的政府中央收入、 转移支付、支出和财政结果账户，采用现值、官方层级结构及雷亚尔百万（R$ million）单位。
• Tesouro Nacional / RMD：联邦公共债务月度构成、DPMFi 持有人、 平均期限和成本。每张官方表格均保留其自身的单位、覆盖范围、定义、脚注和发布版本。
• MDIC / Comex Stat：按产品、贸易伙伴、州、运输方式、海关办事处和国际分类统计的出口与进口数据。
• ANP / Levantamento de Preços de Combustíveis：滚动四周或按月统计的燃料和 GLP 加油站观测数据，按明确的期间、产品和地理区域汇总，并记录计算溯源信息。
• EPE / Consumo Mensal de Energia Elétrica：自 2004 年起按州（UF）、地区、类别和自由/受监管市场划分的月度用电量及消费者数量，并附上官方工作簿版本。
• MTE / Novo Caged：自 2020 年起按全国总量、地区/州或经济活动划分的调整后月度就业存量、录用人数、解雇人数、净变化和相对变化，并附上准确的官方工作簿版本；维度不兼容的表格会分别保留。
• CVM / Informe Diário de Fundos：每日投资组合价值、净资产、申购、赎回、份额价值和报告的持有人数量。查询可比较官方分类，或按 CNPJ 或名称查找最新的基金/类别报告；份额价值绝不会被汇总，持有人总数也不会被表述为独立人数。

涵盖通胀、利率、货币、经济活动、劳动力、信贷、财政、外部部门和市场的精选指标共 32 项。数据值绝不会伪造、向前填充或在无提示的情况下反转符号。BCB NFSP 财政序列保留 BCB 的融资需求符号约定。

BCB 目录数据以 ODbL 发布；分发改编后的数据库时，请保留其署名和相同方式共享义务。将 IBGE 标注为 IBGE/SIDRA，并保留其来源链接和条款。每项指标的响应都包含适用于该序列的权威 URL 和许可证。

本地运行

需要 Node.js 22.13+。

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

示例见 examples/python.py、 examples/multi_source_python.py 和 examples/javascript.mjs。drizzle/ 中的 D1 迁移记录了缓存快照的部署信息。

许可证

API 实现以 MIT License 发布。 上游数据仍受各发布方自身条款和许可证约束。