日本銀行「時系列統計データ検索サイト」API 非公式仕様書

0. ドキュメント情報

対象API: 日本銀行「時系列統計データ検索サイト」API機能
公開日（公式資料上）: 2026-02-18
APIバージョン: v1（URLパス /api/v1/）
エンドポイント数: 3（コードAPI / 階層API / メタデータAPI）
注意: 本書は公式資料を読みやすく再構成した「非公式仕様書」です。公式の停止・仕様変更の可能性を前提に実装してください。

1. 概要

本APIは、日本銀行「時系列統計データ検索サイト」で提供されている時系列統計データを、機械判読可能な形式（JSON / CSV）で取得するためのAPIです。

提供されるAPIは以下の3種類です。

コードAPI（getDataCode）: 系列コードを指定して時系列データを取得
階層API（getDataLayer）: 階層（カテゴリツリー）を指定して時系列データを取得
メタデータAPI（getMetadata）: DB単位のメタ情報（系列一覧・属性・階層情報など）を取得

2. ベースURL・エンドポイント一覧

2.1 ベースURL

https://www.stat-search.boj.or.jp/api/v1/

2.2 エンドポイント（パスは大文字小文字を区別）

コードAPI: GET https://www.stat-search.boj.or.jp/api/v1/getDataCode
階層API: GET https://www.stat-search.boj.or.jp/api/v1/getDataLayer
メタデータAPI: GET https://www.stat-search.boj.or.jp/api/v1/getMetadata

重要: エンドポイント（/api/v1/getDataCode 等）は大文字小文字を区別します。
一方、クエリパラメータ名・値（format=json 等）は大文字小文字を区別しません。

3. 認証・アクセス制御（重要）

3.1 認証（APIキー等）

公式資料上、APIキー発行や認証方式の記載はありません（= 典型的なAPIキー方式ではない運用です）。
代わりに「高頻度アクセス回避」「負荷状況に応じたアクセス制限」「接続遮断の可能性」が明記されています。

3.2 高頻度アクセスの禁止・遮断リスク

短時間での高頻度アクセスは避ける必要があります。
高頻度アクセス等により、接続遮断・利用停止となり得ます。

4. HTTP仕様（共通）

4.1 HTTPメソッド

公式資料はメソッド名（GET/POST）を明示していませんが、「URLのパラメータとして条件を指定する」形式で提示されているため、本書ではGETとして記載します。

4.2 圧縮（推奨）

通信量削減のため、HTTPレスポンスのgzip圧縮に対応しています。
推奨ヘッダ例:
- Accept-Encoding: gzip

4.3 Content-Type

format=json の場合: Content-Type: application/json
format=csv の場合: Content-Type: text/csv
ただし、エラー時はformat指定に関わらずJSONで返却されます。

5. 共通パラメータ仕様

5.1 パラメータ一覧（共通）

パラメータ	型	必須	対象API	説明	設定値 / 既定値
`format`	string	任意	全API	出力形式	`json` or `csv`（省略時`json`）
`lang`	string	任意	全API	言語	`jp` or `en`（省略時`jp`）
`db`	string	必須	全API	DB名	例: `CO`, `FM01` 等（DB一覧は後述）
`startDate`	string	任意	コード/階層	開始期	期種に応じた形式（後述）
`endDate`	string	任意	コード/階層	終了期	期種に応じた形式（後述）
`startPosition`	integer	任意	コード/階層	検索開始位置	1以上の整数（ページングに使用）

5.2 エンドポイント固有パラメータ

パラメータ	型	必須	対象API	説明
`code`	string	必須	コードAPI	系列コード（カンマ区切りで複数指定可）
`layer`	string	必須	階層API	階層情報（カンマ区切り、ワイルドカード`*`可）
`frequency`	string	必須	階層API	期種（略称）

6. 重要な入力ルール（実装でハマりやすい点）

6.1 禁止文字

以下の文字および全角文字は指定できません。

< > ” ! | \ ; '

6.2 `db`（DB名）一覧

DB名は以下の通りです（公式マニュアル記載）。
（実装上は、まずgetMetadataでDB単位のメタ情報を取得し、そこから系列を特定する運用が堅牢です。）

統計分野	DB名	DB名称
金利（預金・貸出関連）	IR01	基準割引率および基準貸付利率の推移
	IR02	預金種類別店頭表示金利の平均年利率等
	IR03	定期預金の預入期間別平均金利
	IR04	貸出約定平均金利
マーケット関連	FM01	無担保コールO/N物レート（毎営業日）
	FM02	短期金融市場金利
	FM03	短期金融市場残高
	FM04	コール市場残高
	FM05	公社債発行・償還および現存額
	FM06	公社債消化状況（利付国債）
	FM07	（参考）国債窓口販売額・窓口販売率
	FM08	外国為替市況
	FM09	実効為替レート
決済関連	PS01	各種決済
	PS02	フェイルの発生状況
預金・マネー・貸出	MD01	マネタリーベース
	MD02	マネーストック
	MD03	マネタリーサーベイ
	MD04	（参考）マネーサプライ増減と信用面の対応
	MD05	通貨流通高
	MD06	日銀当座預金増減要因と金融調節（実績）
	MD07	準備預金額
	MD08	業態別の日銀当座預金残高
	MD09	マネタリーベースと日本銀行の取引
	MD10	預金者別預金
	MD11	預金・現金・貸出金
	MD12	都道府県別預金・現金・貸出金
	MD13	貸出・預金動向
	MD14	定期預金の残高および新規受入高
	LA01	貸出先別貸出金
	LA02	日本銀行貸出
	LA03	その他貸出残高
	LA04	コミットメントライン契約額、利用額
	LA05	主要銀行貸出動向アンケート調査
金融機関バランスシート	BS01	日本銀行勘定
	BS02	民間金融機関の資産・負債
資金循環	FF	資金循環
その他の日本銀行関連	OB01	日本銀行の対政府取引
	OB02	日本銀行が受入れている担保の残高
短観	CO	短観
物価	PR01	企業物価指数
	PR02	企業向けサービス価格指数
	PR03	製造業部門別投入・産出物価指数
	PR04	＜サテライト指数＞最終需要・中間需要物価指数
財政関連	PF01	財政資金収支
	PF02	政府債務
国際収支・BIS関連	BP01	国際収支統計
	BIS	BIS 国際資金取引統計および国際与信統計の日本分集計結果
	DER	デリバティブ取引に関する定例市場報告の日本分集計結果
その他	OT	その他

6.3 系列コード（`code`）の注意

codeには「系列コード」を指定します（例: MADR1Z@D のような固有コード）。
検索画面で使う「データコード」（例: IR01'... のようにDB名が付与されたもの）を渡すとエラーになります。
codeはカンマ区切りで複数指定可能ですが、同一リクエスト内では同じ期種（frequency）の系列のみ指定可能です。

6.4 期種（`frequency`）の指定と出力値の違い

階層APIのfrequencyは以下の略称を指定します。
- CY（暦年）, FY（年度）, CH（暦年半期）, FH（年度半期）, Q（四半期）, M（月次）, W（週次）, D（日次）
重要: 出力（RESULTSET内のFREQUENCY）には正式名称（例: QUARTERLY 等）が表示されますが、リクエストでは正式名称を指定できません（指定するとエラー）。

6.5 `startDate` / `endDate` の形式

startDateとendDateは期種に応じて形式が変わります。

期種	形式	例
暦年 / 年度	`YYYY`	`2025`
暦年半期 / 年度半期	`YYYYHH`（HH=01/02）	`202501`（上期）
四半期	`YYYYQQ`（QQ=01..04）	`202502`（第2四半期）
月次	`YYYYMM`（MM=01..12）	`202512`
週次 / 日次	指定は`YYYYMM`（月次形式）	`202501`

追加制約:

年月は 1850年〜2050年 の範囲で数値指定が求められます。
startDate <= endDate の順序で指定する必要があります。

7. 制限値（レート制限と別の「出力上限」）

7.1 制限値一覧

API種類	制限内容	上限値	超過時の挙動
階層API	検索条件で抽出される系列数（系列コード数）	1,250	エラー（出力ファイルは作成されない）
コードAPI / 階層API	1回のリクエストで検索可能な系列数	250	上限まで出力し、続き位置を`NEXTPOSITION`に出力
コードAPI / 階層API	1回のリクエストで検索可能なデータ数（系列数×期数）	60,000	上限まで出力し、続き位置を`NEXTPOSITION`に出力

7.2 階層APIの「系列数カウント」の罠（重要）

階層APIは、指定frequencyで絞る前段階で系列数を数えるため、指定外の期種が混在すると合計が上限超過になり得ます。
例: 階層条件で「月次800系列 + 四半期500系列 = 合計1300系列」だと、frequency=Mを指定していても上限エラーになり得ます。

7.3 ページング（`startPosition` / `NEXTPOSITION`）

上限超過時に出力されるNEXTPOSITION（次回検索開始位置）を、次回リクエストのstartPositionに指定すると続きから取得できます。
NEXTPOSITIONが出力されない場合は全データ取得済みです。
- JSONの場合: NEXTPOSITION: null
- CSVの場合: 空欄

7.3.1 コードAPIの`startPosition`の意味

codeで指定した系列コードの「並び順」を1始まりの位置として扱います。
例: startPosition=160 なら、指定したコードリストの160番目以降から出力します。

7.3.2 階層APIの`startPosition`の意味（注意）

DB内の全系列を「階層1〜5で並べ替えた順序番号」で管理し、その番号をstartPositionとして使います。
重要: これは「検索条件で絞り込んだ結果内の通し番号」ではありません。

8. レスポンス仕様（共通）

8.1 文字コード

JSON: UTF-8
CSV:
- lang=jp（日本語）: Shift-JIS
- lang=en（英語）: UTF-8

8.2 共通フィールド（API処理結果情報）

全APIで処理結果情報が出力されます。

フィールド	型	説明
`STATUS`	integer	200=正常終了、200以外=エラー（400/500/503）
`MESSAGEID`	string	メッセージID（例: `M1810001I`）
`MESSAGE`	string	人間可読メッセージ
`DATE`	string	日付時刻（日本時間）

DATEの意味:

コードAPI/階層API: 出力ファイル作成日時
メタデータAPI: システム内部のデータ作成日時（出力ファイル作成日時とは限らない）

8.3 欠損値

欠損値（データがない）場合は、null が出力されます。
検索画面では NA / ND ですが、API出力は null です。

9. エンドポイント別仕様

------------------------------------------------------------

9.1 コードAPI（getDataCode）

9.1.1 概要

系列コード（code）で時系列データを取得します。
同一リクエスト内で指定する系列は同じ期種である必要があります。

9.1.2 リクエスト

URL: GET https://www.stat-search.boj.or.jp/api/v1/getDataCode
クエリ:
- 必須: db, code
- 任意: format, lang, startDate, endDate, startPosition

9.1.3 クエリ詳細

パラメータ	必須	形式	例	補足
`db`	必須	DB名	`CO`	DB一覧参照
`code`	必須	カンマ区切り	`TK99...,...`	最大1250件、同一期種のみ
`startDate`	任意	期種に応じた形式	`202401`	週次/日次はYYYYMM
`endDate`	任意	期種に応じた形式	`202504`	`startDate<=endDate`
`startPosition`	任意	1以上整数	`160`	指定コードリストの位置

9.1.3 レスポンス（JSON）

Content-Type: application/json（エラー時もJSON）

9.1.3.1 JSON構造（コードAPI）

トップレベル:

{
  "STATUS": 200,
  "MESSAGEID": "M1810001I",
  "MESSAGE": "...",
  "DATE": "YYYY-MM-DDThh:mm:ss.sss+09:00",
  "PARAMETER": {
    "FORMAT": "JSON|CSV|",
    "LANG": "JP|EN|",
    "DB": "CO",
    "STARTDATE": "202401|",
    "ENDDATE": "202504|",
    "STARTPOSITION": "160|"
  },
  "NEXTPOSITION": 255,
  "RESULTSET": [
    {
      "SERIES_CODE": "...",
      "NAME_OF_TIME_SERIES_J": "...",
      "UNIT_J": "...",
      "FREQUENCY": "QUARTERLY|MONTHLY|...",
      "CATEGORY_J": "...",
      "LAST_UPDATE": 20251002,
      "VALUES": {
        "SURVEY_DATES": [202401, 202402, ...],
        "VALUES": [11, 13, null, ...]
      }
    }
  ]
}

ポイント:

PARAMETERは「リクエストで指定したパラメータ情報」を返します。未指定項目は空欄になり得ます。
NEXTPOSITIONが数値の場合は「一部未取得」であり、続き取得が必要です。
VALUES.SURVEY_DATES と VALUES.VALUES は同じインデックス同士が対応します。

9.1.4 レスポンス（CSV）

Content-Type: text/csv
CSVは概ね以下の構造（概念図）です。
1. 先頭に処理結果（STATUS/MESSAGEID/MESSAGE/DATE）
2. 次にPARAMETER行（PARAMETER, KEY, VALUE のような形で複数行）
3. 次にNEXTPOSITION行
4. 次にヘッダ行（SERIES_CODE, NAME..., ... SURVEY_DATES, VALUES）
5. データ行（1行=1系列×1時点）で、系列メタ情報は行ごとに繰り返し出力される

9.1.5 例

https://www.stat-search.boj.or.jp/api/v1/getDataCode?format=json&lang=jp&db=CO&startDate=202401&endDate=202504&code=TK99F1000601GCQ01000,TK99F2000601GCQ01000

9.2 階層API（getDataLayer）

9.2.1 概要

DB内の「階層情報（layer）」に基づいて、該当系列の時系列データを取得します。
frequency（期種略称）とlayer（階層指定）が必須です。

9.2.2 リクエスト

URL: GET https://www.stat-search.boj.or.jp/api/v1/getDataLayer
クエリ:
- 必須: db, frequency, layer
- 任意: format, lang, startDate, endDate, startPosition

9.2.3 クエリ詳細

パラメータ	必須	形式	例	補足
`db`	必須	DB名	`BP01`	DB一覧参照
`frequency`	必須	期種略称	`M`	CY/FY/CH/FH/Q/M/W/D
`layer`	必須	カンマ区切り	`1,1,1` / `*`	最大5要素。`*`はワイルドカード
`startDate`	任意	期種に応じた形式	`202504`	週次/日次はYYYYMM
`endDate`	任意	期種に応じた形式	`202509`	`startDate<=endDate`
`startPosition`	任意	1以上整数	`255`	DB全系列の並び順番号（注意）

layer指定補足:

階層は1〜5の5段です。
階層1の指定は必須、階層2〜5は任意（ただし6つ以上は指定不可）。
ワイルドカード*で当該階層を全対象として指定できます。

9.2.4 レスポンス（JSON）

コードAPIと同じトップレベル構造（PARAMETER/NEXTPOSITION/RESULTSET）です。違いとして、PARAMETERにLAYER1..LAYER5およびFREQUENCYが含まれます。

9.2.5 レスポンス（CSV）

コードAPIと同様に、1行=1系列×1時点のロング形式で出力されます。

9.2.6 例

https://www.stat-search.boj.or.jp/api/v1/getDataLayer?format=csv&db=BP01&frequency=M&startDate=202504&endDate=202509&layer=1,1,1

------------------------------------------------------------

9.3 メタデータAPI（getMetadata）

9.3.1 概要

DB単位のメタ情報（系列コード・系列名・単位・期種・カテゴリ・階層・収録期間・注記等）を取得します。
コードAPI/階層APIのパラメータ作成に利用することが推奨されます。
メタ情報ファイルは日々定期的に更新されます。

9.3.2 リクエスト

URL: GET https://www.stat-search.boj.or.jp/api/v1/getMetadata
クエリ:
- 必須: db
- 任意: format, lang

9.3.3 レスポンス（JSON）

メタデータAPIは、コード/階層APIとトップレベル構造が異なります（PARAMETER/NEXTPOSITIONがありません）。

{
  "STATUS": 200,
  "MESSAGEID": "M1810001I",
  "MESSAGE": "...",
  "DATE": "YYYY-MM-DDThh:mm:ss.sss+09:00",
  "DB": "FM08",
  "RESULTSET": [
    {
      "SERIES_CODE": "FXERD01",
      "NAME_OF_TIME_SERIES_J": "...",
      "NAME_OF_TIME_SERIES": "...",
      "UNIT_J": "...",
      "UNIT": "...",
      "FREQUENCY": "DAILY|MONTHLY|...",
      "CATEGORY_J": "...",
      "CATEGORY": "...",
      "LAYER1": 1,
      "LAYER2": 1,
      "LAYER3": 0,
      "LAYER4": 0,
      "LAYER5": 0,
      "START_OF_THE_TIME_SERIES": "19990101",
      "END_OF_THE_TIME_SERIES": "20250114",
      "LAST_UPDATE": 20250116,
      "NOTES_J": "...",
      "NOTES": "..."
    }
  ]
}

補足:

言語により出力されるタグ（日本語/英語）が異なります（*_Jの有無など）。
階層情報のみの行が出力される場合、SERIES_CODEが空欄になり得ます。

9.3.4 レスポンス（CSV）

先頭に処理結果（STATUS/MESSAGEID/MESSAGE/DATE）とDBが出力され、その後にヘッダ行＋データ行が続きます。
出力例（概念）:
- SERIES_CODE, NAME_OF_TIME_SERIES_J, NAME_OF_TIME_SERIES, UNIT_J, UNIT, FREQUENCY, CATEGORY_J, CATEGORY, LAYER1..LAYER5, START_OF_THE_TIME_SERIES, END_OF_THE_TIME_SERIES, LAST_UPDATE, NOTES_J, NOTES

9.3.5 例

https://www.stat-search.boj.or.jp/api/v1/getMetadata?format=csv&lang=jp&db=fm08
https://www.stat-search.boj.or.jp/api/v1/getMetadata?db=pr01

10. メッセージID（STATUS別一覧）

10.1 STATUS=200（正常終了）

MESSAGEID	MESSAGE（要旨）	補足
M1810001I	正常に終了しました。	欠損値が含まれていても200になり得ます
M181030I	正常に終了しましたが、該当データはありませんでした。	収録期間外または全て欠損等

10.2 STATUS=400（入力・条件エラー）

MESSAGEID	MESSAGE（要旨）	補足
M181001E	Invalid input parameters	禁止文字/全角/データコード（DB名付き）指定など
M181002E	Invalid language setting	`lang`不正
M181003E	結果ファイル形式が正しくありません	`format`不正
M181004E	DBが指定されていません	`db`欠落
M181005E	DB名が正しくありません	`db`不正
M181006E	系列コードが指定されていません	`code`欠落（コードAPI）
M181007E	系列コードの数が1250を超えています	`code`件数上限
M181008E	指定した開始期が正しくありません	`startDate`不正
M181009E	指定した終了期が正しくありません	`endDate`不正
M181010E	時期は1850年から2050年までを数値で指定してください	範囲外
M181011E	開始期と終了期の順序を正しく指定してください	`startDate<=endDate`
M181012E	検索開始位置が正しくありません	`startPosition`は1以上整数
M181013E	指定した系列コードは存在しません	`*番目のコード`が表示される
M181014E	指定した系列コードの期種が一致しません	`*番目のコード`が表示される
M181015E	指定した開始期の設定形式が期種と一致しません	期種と形式不一致
M181016E	指定した終了期の設定形式が期種と一致しません	期種と形式不一致
M181017E	期種が指定されていません	階層APIで`frequency`欠落
M181018E	期種が正しくありません	`frequency`不正
M181019E	階層情報が指定されていません	階層1必須、2〜5任意、6つ以上不可
M181020E	階層情報設定が正しくありません	階層の指定方法不正

10.3 STATUS=500（サーバ側予期せぬエラー）

MESSAGEID	MESSAGE（要旨）
M181090S	予期しないエラーが発生しました。時間をおいてやり直してください。

10.4 STATUS=503（DBアクセス等の一時障害）

MESSAGEID	MESSAGE（要旨）
M181091S	データベースにアクセス中にエラーになりました。時間をおいてやり直してください。

11. 運用・実装ガイド（推奨）

11.1 大量取得の基本戦略

「スーパーで一度にカゴ山盛りにするとレジが止まる」のと同じで、制限値（系列数/データ数）を超えると途中で止まる設計です。そのため、以下のように分割取得が基本です。

まずメタデータAPIで系列一覧を取得（系列コードと期種を把握）
コードAPIで、同じ期種の系列を「最大250件ずつ」分割して取得
NEXTPOSITIONが出たら、startPositionで続き取得
リクエスト間隔を空ける（高頻度アクセス回避）

11.2 キャッシュ・バックオフ

同一データの繰り返し取得を避ける（ETLでキャッシュ）
エラー（特に500/503）は指数バックオフでリトライ（無限ループ禁止）
gzip圧縮を有効化（Accept-Encoding: gzip）

12. 公開サービスに組み込む際の留意点（準拠事項）

公開サービスとして提供する場合、公式の留意点に従い以下を実施してください。

公開時の連絡（調査統計局へのメール連絡）
クレジット表示（定型文の掲示）
高頻度アクセス等の禁止事項の遵守
予告なく停止・性能低下・仕様変更があり得る前提での設計（SLA前提にしない）

13. 問い合わせ先（公式）

照会先メール: post.rsd17@boj.or.jp
件名指定（公式案内に従うこと）

guruguruman/boj-time-series-data-search-api.md

日本銀行「時系列統計データ検索サイト」API 非公式仕様書

0. ドキュメント情報

1. 概要

2. ベースURL・エンドポイント一覧

2.1 ベースURL

2.2 エンドポイント（パスは大文字小文字を区別）

3. 認証・アクセス制御（重要）

3.1 認証（APIキー等）

3.2 高頻度アクセスの禁止・遮断リスク

4. HTTP仕様（共通）

4.1 HTTPメソッド

4.2 圧縮（推奨）

4.3 Content-Type

5. 共通パラメータ仕様

5.1 パラメータ一覧（共通）

5.2 エンドポイント固有パラメータ

6. 重要な入力ルール（実装でハマりやすい点）

6.1 禁止文字

6.2 db（DB名）一覧

6.3 系列コード（code）の注意

6.4 期種（frequency）の指定と出力値の違い

6.5 startDate / endDate の形式

7. 制限値（レート制限と別の「出力上限」）

7.1 制限値一覧

7.2 階層APIの「系列数カウント」の罠（重要）

7.3 ページング（startPosition / NEXTPOSITION）

7.3.1 コードAPIのstartPositionの意味

7.3.2 階層APIのstartPositionの意味（注意）

8. レスポンス仕様（共通）

8.1 文字コード

8.2 共通フィールド（API処理結果情報）

8.3 欠損値

9. エンドポイント別仕様

------------------------------------------------------------

9.1 コードAPI（getDataCode）

9.1.1 概要

9.1.2 リクエスト

9.1.3 クエリ詳細

9.1.3 レスポンス（JSON）

9.1.3.1 JSON構造（コードAPI）

9.1.4 レスポンス（CSV）

9.1.5 例

9.2 階層API（getDataLayer）

9.2.1 概要

9.2.2 リクエスト

9.2.3 クエリ詳細

9.2.4 レスポンス（JSON）

9.2.5 レスポンス（CSV）

9.2.6 例

------------------------------------------------------------

9.3 メタデータAPI（getMetadata）

9.3.1 概要

9.3.2 リクエスト

9.3.3 レスポンス（JSON）

9.3.4 レスポンス（CSV）

9.3.5 例

10. メッセージID（STATUS別一覧）

10.1 STATUS=200（正常終了）

10.2 STATUS=400（入力・条件エラー）

10.3 STATUS=500（サーバ側予期せぬエラー）

10.4 STATUS=503（DBアクセス等の一時障害）

11. 運用・実装ガイド（推奨）

11.1 大量取得の基本戦略

11.2 キャッシュ・バックオフ

12. 公開サービスに組み込む際の留意点（準拠事項）

13. 問い合わせ先（公式）

6.2 `db`（DB名）一覧

6.3 系列コード（`code`）の注意

6.4 期種（`frequency`）の指定と出力値の違い

6.5 `startDate` / `endDate` の形式

7.3 ページング（`startPosition` / `NEXTPOSITION`）

7.3.1 コードAPIの`startPosition`の意味

7.3.2 階層APIの`startPosition`の意味（注意）