APIドキュメント

ベースURL: https://yadozei.jp/v1。JSONのみ。すべてのレスポンスに X-Data-Version ヘッダが付きます。

認証とレート制限

X-API-Key ヘッダでキーを送ります。匿名は 100req/日 + 10req/分（IP単位）。Pro/Vendorは月次クォータ（10万/100万）+ 60req/分。/v1/data は有料プラン限定。超過時は 429 と Retry-After を返します。

GET /v1/areas

curl https://yadozei.jp/v1/areas

const res = await fetch("https://yadozei.jp/v1/areas");
const { areas } = await res.json(); // [{ id, name, prefecture, level, taxBase }]

GET /v1/areas/:id

curl https://yadozei.jp/v1/areas/kyoto

POST /v1/calculate

本文: { areaId, ratePerNight, date?, nights?, guests?, basis? }（本文は1KBまで）。

curl -X POST https://yadozei.jp/v1/calculate \
  -H 'content-type: application/json' \
  -d '{"areaId":"tokyo","ratePerNight":15000,"date":"2026-06-13","guests":2}'

// { perNightTax: 200, basis: "per_person",
//   stayTotal: { perPerson: 200, total: 400 }, breakdown: [...] }

basis（課税単位）

basis は宿泊税が「1人あたり」か「1室/1棟あたり」か。per_person の地域は人数を掛けます。per_unit は掛けません。variable（倶知安町）は施設の課金方法によるため、任意の basis（"per_person"|"per_unit"、既定は per_unit）で指定します。レスポンスの basis は適用された区分を返します。

GET /v1/changes?since_seq=N

seq より新しい変更を昇順で返します。匿名は最新5件のみ。

curl 'https://yadozei.jp/v1/changes?since_seq=0' -H 'x-api-key: yz_...'

GET /v1/data（有料）

curl https://yadozei.jp/v1/data -H 'x-api-key: yz_...'
// { dataVersion: "2026.06", areas: [ ...full dataset... ] }

GET /healthz

curl https://yadozei.jp/healthz // { status: "ok", dataVersion, db: "ok" }

エラー

形式: { "error": { "code": "...", "message": "..." } }。コード: 400(検証) / 401(キー) / 403(プラン) / 404(エリア、候補付き) / 413(本文過大) / 429(制限)。