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
• エージェントインストーラー： 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 件）。使いやすい既存の v1 系列 ID 32 件との互換性も維持されています。

ディスカバリー、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 では、月次勘定階層と、above-the-line の現金・実効支払に関する規則が保持されます。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	inflationやinterest-ratesなどの正規化されたカテゴリ ID
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に未来の日付は指定できません。SGS 側で同じ上限が適用されるため、BCB の日次リクエストは10年間に制限されています。

すべての 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があります。

設定されている場合、API は正常に正規化されたソースレスポンスを D1 にキャッシュします。更新に失敗し、一致する以前のスナップショットがある場合は、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：直近 4 週間または月次の燃料・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 のもとで公開されています。 上流データには、各公開元独自の利用条件とライセンスが適用されます。