strata
Overview
Strata API 1.0.0
Section titled “Strata API 1.0.0”行政区域・郵便番号・最低賃金を、日付を指定して取得する API。決めた理由は docs/decisions/public-api.md にある。
日付（at）
どのエンドポイントも、at で日付を指定する。形式は YYYY-MM-DD（日本の暦の日付）だけで、時刻を含むと 400 になる。
省略すると日本時間の今日を使う。応答の at には、実際に使った日付が必ず入る。
有効期間
有効期間は valid_since の日を含み、valid_until の日を含まない。valid_until が null なら、データを更新した時点では終了日が分かっていない。
有効期間は応答の 1 件ごとに付き、その 1 件のどの値も変わらない期間のうち、at を含むものになる。
まだ効力のない値
答申された最低賃金や、告示済みでまだ施行されていない行政区域の変更のように、まだ効力のない値も、at に将来の日付を指定すれば返る。
応答の 1 件ごとに付く scheduled は、その 1 件の valid_since が日本時間の今日より後なら true になる。基準は at ではなく、呼び出した日である。
どの日付までのデータがあるかと見込み
sources[].known_through は、そのデータでどの日付まで分かっているかを示す。郵便番号は取り込んだ最新の更新の公開日、行政区域は最後に確認した日、最低賃金は最も遅い発効日になる。
at が sources のどれかの known_through より後なら、応答の projected が true になる。この応答は、今分かっている最新の状態がその日まで続くと仮定したもので、新しいデータを取り込むと変わることがある。
projected は 404 の本文にも付き、同じエンドポイントが 200 で返す sources のデータで決まる。
履歴の範囲外
履歴の起点はデータの種類ごとに違う。行政区域は 1970-04-01、郵便番号は 2023-04-28、最低賃金は都道府県ごとの 2002 年度の発効日。
起点より前の at には 422 out-of-coverage を返し、存在しない場合の 404 と区別する。
データの訂正
取り込んだデータの誤りを訂正すると、過去の日付に対する応答も変わる。訂正の履歴は https://strata.lambdado.com/corrections に載せ、sources[].updated_on も変わる。
バージョニング
フィールド・エンドポイント・列挙値を追加しても、バージョンは上げない。利用者は、知らないフィールドと列挙値を無視すること。
後方互換性のない変更では /v2 を新設し、/v1 も一定期間並行して提供する。
認証
公開サイトで組織ごとに発行した API キーを、Authorization: Bearer <API キー> で渡す。キーがない・正しくない・失効している場合と、組織が停止されている場合は 401 になる。
利用上限
上限は組織ごとに、日本時間の暦月あたり 10,000 回と、1 分（毎分 0 秒で区切る）あたり 60 回。超えると 429 を返し、Retry-After に次に呼び出せるまでの秒数を入れる。
認証を通り、上限で拒否されなかった呼び出しはすべて数える（400・404・422 も数える）。401 と 429 は数えない。
エラー
エラーはすべて application/problem+json（RFC 9457）で返す。種類は type で見分ける。
例について
例に載せた行政区域・郵便番号・最低賃金は、データ源にある実際の値である。ただし sources[].updated_on と sources[].known_through は、サービスの運用開始前のため、形式を示すための仮の値である。
Authentication
Section titled “Authentication”apiKey
Section titled “apiKey”公開サイトで組織ごとに発行する API キー
Security scheme type: http