API / MCP

API・MCPで使う

公共データを、出典付きで安全に参照するためのAPIです。研究・報道・公共目的での利用を歓迎します。一般利用は無料枠で提供し、研究・報道目的の利用は申請により広く開放します。

National OSは、AIによる評価や論評を公金データに混ぜません。返すのは記録 (数値・出典・ハッシュ・日時) だけです。

クイックスタート

/api-access でキーを取得します (無料。一般枠は送信後すぐ発行されます)。
取得したキーを X-API-Key ヘッダーに付けてリクエストします。

curl -H "X-API-Key: <発行されたキー>" \
  "https://national-os.jp/api/v1/municipalities?pref=13"

キーなしでも 1 分あたり 60 回まで試せます (下の「レート制限」参照)。

エンドポイント一覧

カテゴリ別の網羅リファレンスは APIリファレンス、手を動かす例は実例ガイドにあります。機械可読な仕様の正本は Swagger UI (/docs) と openapi.json です。

出典フィールドの読み方

レスポンスの provenance には、その数値がどの一次資料に由来するかが付きます。主なフィールド:

フィールド	意味
source_url	原典の URL。数値の最終根拠は、常にこの一次資料です。
source_hash	原典ファイルの sha256 ハッシュ (64 桁)。取得時点の原本と照合できます。
confirmed_at	当方が原典を実際に取得・観測した日時。
data_status	データ状態。confirmed (確定) / provisional (暫定) / under_review (レビュー中) / unavailable (取得不能) の 4 値。
confidence	確信度。confirmed / probable / estimated / missing の 4 値。
human_review_required	人手レビュー待ちかどうか (true / false)。
original_label	原典の生ラベル (例: （項）地方交付税交付金)。
normalized_label	正規化後のラベル (例: 地方交付税交付金)。

これらのフィールドは enum・ハッシュ・URL・日時・原典の生ラベルだけで構成され、自由文の評価フィールドは置いていません。National OSは、AIによる評価や論評を公金データに混ぜません。行が無い項目は捏造せず null で返します。

レート制限

区分	通常 (回/分)	重い集計 (回/分)	上限 (回/日)
キーなし (匿名)	60	10	5,000
一般 (無料枠)	600	30	50,000
研究・報道	1,200	120	上限なし

「重い集計」は検索・ランキングなど負荷の大きい一部エンドポイントの別枠です (対象は 429 になったときのレスポンスで分かります)。
制限を超えると 429 が返り、 Retry-After ヘッダーに再試行までの秒数が入ります。

MCPで接続する

AI クライアントからは MCP (Model Context Protocol) で接続できます。接続先は https://national-os.jp/api/v1/mcp (POST のみ)、認証は Authorization: Bearer <キー> です (キーなしでは接続できません)。

claude mcp add --transport http nos https://national-os.jp/api/v1/mcp \
  --header "Authorization: Bearer <キー>"

Tool	内容
search_municipality	自治体を名称 / JIS コードで検索し、財政プロフィールを返します。
search_contracts	政府調達契約を件名・事業者・府省・年度・金額帯で検索します (最大 50 件)。
search_corporation	法人を名称 / 法人番号 (13 桁) で検索し、受注記録を返します。
search_source_documents	原資料 (一次資料 snapshot) を検索します。sha256 / 取得日時 / ライセンス付き。
get_data_freshness	データソース別の最終更新と鮮度ラベルを返します (収集運用の経過日数区分であり、品質評価ではありません)。

研究・報道での利用

研究・報道目的の利用は、申請により高いレート制限を開放します (上の表の「研究・報道」区分)。所属と利用目的を添えて /api-access から申請してください。

論文・記事等の成果物では、元の政府資料と本サイトの両方が辿れる形で出典を明記していただくようお願いします (形式は利用規約の「出典と帰属表示」参照)。

利用条件

キーの取り扱い・禁止事項・免責は利用規約にまとめています。