API Reference / Examples

実例ガイド

公開 API を curl / Python / MCP で使う具体例です。全エンドポイントの一覧は APIリファレンス、対話的な仕様は /docs にあります。

1. まず匿名で試す

公開エンドポイントはキーなしで叩けます（1 分あたり 60 回まで）。東京都の自治体一覧:

curl "https://national-os.jp/api/v1/municipalities?pref=13"

2. キーで上限を上げる

/api-access でキーを取得し（一般枠は即時発行）、X-API-Key ヘッダーに付けます。キーは認証のためではなく、レート上限を引き上げるためのものです。

curl -H "X-API-Key: nos_g_xxxxxxxx…" \
  "https://national-os.jp/api/v1/fiscal/131032"

応答には X-RateLimit-Limit と X-RateLimit-Remaining が付き、残り回数が分かります。

3. 出典（provenance）を読む

X-Data-Format: v2 を付けると、対応するエンドポイントの応答に provenance（原典 URL・ sha256・取得日時・状態）が加わります。

curl -H "X-Data-Format: v2" \
  "https://national-os.jp/api/v1/budget-tree?year=2024"

応答（抜粋）:

{
  "…": "…",
  "provenance": {
    "source_url": "https://www.mof.go.jp/…/2024.xlsx",
    "source_type": "excel",
    "source_hash": "3a7f…（64桁）",
    "confirmed_at": "2026-05-26T02:11:00Z",
    "data_status": "confirmed",
    "confidence": "confirmed",
    "human_review_required": false,
    "original_label": "（項）地方交付税交付金",
    "normalized_label": "地方交付税交付金"
  }
}

各フィールドの意味はリファレンスの出典フィールドを参照してください。行が無い項目は捏造せず null になります。

4. 契約を横断検索する

受注者名・件名・府省・年度・金額帯で政府調達契約を検索します（重い集計枠）。

curl -H "X-API-Key: nos_g_xxxxxxxx…" \
  "https://national-os.jp/api/v1/procurement/award-search?contractor_name=○○&fiscal_year=2024&amount_min=100000000"

5. Python から使う

requests の例。出典付きで受け取り、レート制限（429）に当たったら Retry-After 秒だけ待って再試行します。

import time
import requests

BASE = "https://national-os.jp"
HEADERS = {"X-API-Key": "nos_g_xxxxxxxx…", "X-Data-Format": "v2"}

def get(path, **params):
    while True:
        r = requests.get(f"{BASE}{path}", headers=HEADERS, params=params, timeout=30)
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", "1")))
            continue
        r.raise_for_status()
        return r.json()

data = get("/api/v1/fiscal/131032")
prov = data.get("provenance")
print(prov and prov["source_url"])

6. レート制限に当たったら

429 が返ったら、Retry-After ヘッダー（秒）だけ待って再試行してください。継続的に上限が足りない場合は /api-access から研究・報道枠を申請できます。

7. AIクライアントから MCP で接続する

MCP（Model Context Protocol）で接続すると、AI クライアントが検索ツールを直接使えます。接続先は 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 nos_g_xxxxxxxx…"

使えるツール（search_municipality / search_contracts / search_corporation / search_source_documents / get_data_freshness）の一覧は /api-docs の MCP セクションにあります。ツールは検索と記録の写像だけを返し、評価・論評はしません。