DOCS
ドキュメント
Kiten API の概念・リファレンス・ガイドを日本語でまとめています。最初のリクエストまでは、クイックスタートから。
FIRST REQUEST
$ curl https://api.zorynto.com/v1/parse \ -H "Authorization: Bearer $KITEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{"text":"東京都品川区東品川2-2-20"}'
- ベース URL
- https://api.zorynto.com
- 認証
- Authorization: Bearer kiten_live_…
- 1コール
- 住所1件（バッチも1件ずつ）
GET STARTED
はじめに
最初のリクエストまで、認証・上限・エラーの基本。
クイックスタート
APIキーを用意して、最初の住所を解析するまでの手順です。cURL のコピー用コードと、応答の読み方をまとめています。認証とキーの管理
APIキーの形式、送り方、ローテーション、保管のしかたをまとめています。キーは作成時に一度だけ表示されます。上限と 429
秒間リクエスト数と月間の上限、リクエストが拒否される順番、429 のときの再試行の目安をまとめています。エラー
ステータスコードごとの意味と、原因・対処の一覧です。403 は課金されません。429 は待てば成功することがあります。プランごとに使える機能
エンドポイントと応答の項目が、プランによってどう変わるかの一覧です。使えない機能を呼ぶと 403 を返し、課金はされません。バージョンと互換性
API のバージョンの付け方と、互換性を保つ変更・破壊的な変更の扱い、非推奨の知らせ方を説明します。
APIキーを用意して、最初の住所を解析するまでの手順です。cURL のコピー用コードと、応答の読み方をまとめています。認証とキーの管理
APIキーの形式、送り方、ローテーション、保管のしかたをまとめています。キーは作成時に一度だけ表示されます。上限と 429
秒間リクエスト数と月間の上限、リクエストが拒否される順番、429 のときの再試行の目安をまとめています。エラー
ステータスコードごとの意味と、原因・対処の一覧です。403 は課金されません。429 は待てば成功することがあります。プランごとに使える機能
エンドポイントと応答の項目が、プランによってどう変わるかの一覧です。使えない機能を呼ぶと 403 を返し、課金はされません。バージョンと互換性
API のバージョンの付け方と、互換性を保つ変更・破壊的な変更の扱い、非推奨の知らせ方を説明します。
CONCEPTS
概念
ラベル・検証レベル・精度の階段など、Kiten の考え方。
ラベル（27種）
Kiten が住所の各文字に付ける27種類のラベルと、住所の要素との対応です。BIO 形式で、要素の始まりと続きを区別します。検証レベル（L1〜L5）
Kiten が住所に付ける5段階の検証レベルの意味と、受け入れる・確認する・却下するの使い分けを説明します。精度の段
座標の精度を示す7段（住居・街区・地番・ISJ・GSI・重心・なし）の意味と、どの段が使われるかを説明します。訂正と補足
Kiten が入力を直した箇所（corrections）と補った箇所（annotations）の違い、種類、扱い方を説明します。欠けている要素
住所に欠けている要素を missing と warnings で返す仕組み。階が未入力の多床ビル（U7）など、配送で問題になる点の扱いです。時間による変化
市町村合併・町名変更・住居表示の実施など、住所が時間とともに変わることを、Kiten がどう扱うかを説明します。住所の体系（5つ）
日本の住所には複数の体系があります。住居表示・地番・条丁目・京都の通り名・郡部の大字小字を Kiten がどう見分けるかを説明します。正規化
全角・半角の統一、旧字体の置き換え、ハイフンの扱いなど、Kiten が解析の前に行う住所の正規化を説明します。用語集
Zorynto と Kiten のドキュメントで使う用語を、五十音順ではなく、使う場面の順にまとめています。各用語から、詳しいページへ移れます。地域メッシュ（JIS X 0410）
緯度経度から求める地域メッシュコード（1次・2次・3次）の仕組みと、Kiten の応答での扱いを説明します。地番の指紋（fingerprint）
階・部屋・表記が違っても同じ地番に同じ値を付ける、16桁の指紋の仕組みと使いどころ、できないことを説明します。データの出典
Kiten が住所の照合と座標の決定に使う公開データ（アドレス・ベース・レジストリ、位置参照情報、国土地理院、郵便番号データ）の一覧です。住所データの扱い
送信された住所のテキストを保存しないこと、記録される項目、バッチ結果の保持期間を、技術面から説明します。
Kiten が住所の各文字に付ける27種類のラベルと、住所の要素との対応です。BIO 形式で、要素の始まりと続きを区別します。検証レベル（L1〜L5）
Kiten が住所に付ける5段階の検証レベルの意味と、受け入れる・確認する・却下するの使い分けを説明します。精度の段
座標の精度を示す7段（住居・街区・地番・ISJ・GSI・重心・なし）の意味と、どの段が使われるかを説明します。訂正と補足
Kiten が入力を直した箇所（corrections）と補った箇所（annotations）の違い、種類、扱い方を説明します。欠けている要素
住所に欠けている要素を missing と warnings で返す仕組み。階が未入力の多床ビル（U7）など、配送で問題になる点の扱いです。時間による変化
市町村合併・町名変更・住居表示の実施など、住所が時間とともに変わることを、Kiten がどう扱うかを説明します。住所の体系（5つ）
日本の住所には複数の体系があります。住居表示・地番・条丁目・京都の通り名・郡部の大字小字を Kiten がどう見分けるかを説明します。正規化
全角・半角の統一、旧字体の置き換え、ハイフンの扱いなど、Kiten が解析の前に行う住所の正規化を説明します。用語集
Zorynto と Kiten のドキュメントで使う用語を、五十音順ではなく、使う場面の順にまとめています。各用語から、詳しいページへ移れます。地域メッシュ（JIS X 0410）
緯度経度から求める地域メッシュコード（1次・2次・3次）の仕組みと、Kiten の応答での扱いを説明します。地番の指紋（fingerprint）
階・部屋・表記が違っても同じ地番に同じ値を付ける、16桁の指紋の仕組みと使いどころ、できないことを説明します。データの出典
Kiten が住所の照合と座標の決定に使う公開データ（アドレス・ベース・レジストリ、位置参照情報、国土地理院、郵便番号データ）の一覧です。住所データの扱い
送信された住所のテキストを保存しないこと、記録される項目、バッチ結果の保持期間を、技術面から説明します。
API
API リファレンス
エンドポイントごとの入力・応答・エラー。
POSTPOST /v1/parse
住所の文字列を分解・検証し、座標まで返します。1コールは住所1件です。応答の項目はプランによって変わります。POSTPOST /v1/validate
住所の検証だけが目的のときの入口です。実装では /v1/parse と同じ処理に転送されます。GETGET /v1/suggest
入力途中の文字列から、前方一致の住所の候補を返す GET /v1/suggest の仕様です。フォームの入力補完に使えます。GETGET /v1/zip
郵便番号から住所の候補を引きます。Growth 以上で使えます。それ未満のプランでは 403 を返し、課金しません。POSTPOST /v1/reverse
緯度経度から住所を引く逆ジオコーディングです。実装にはありますが、料金表に未掲載のため、内容は要確認です。POSTPOST /v1/batch
複数の住所をまとめて非同期で処理します。202 とポーリング用の URL を返します。Growth 以上で使えます。GETGET /v1/batch/{id}
バッチの進捗と結果を取得します。作成したキーの持ち主だけが読めます。結果は 1 時間で破棄されます。GETGET /v1/usage
当月の利用量を返します。基本の項目は全プラン、パス別の内訳は Growth 以上です。GETGET /health
生存確認（liveness）と準備確認（readiness）のエンドポイントです。認証は不要で、課金もされません。共通のオブジェクト
検証レベル・精度・住所の要素・訂正・警告など、複数のエンドポイントで共通して現れる値の意味をまとめています。
住所の文字列を分解・検証し、座標まで返します。1コールは住所1件です。応答の項目はプランによって変わります。POSTPOST /v1/validate
住所の検証だけが目的のときの入口です。実装では /v1/parse と同じ処理に転送されます。GETGET /v1/suggest
入力途中の文字列から、前方一致の住所の候補を返す GET /v1/suggest の仕様です。フォームの入力補完に使えます。GETGET /v1/zip
郵便番号から住所の候補を引きます。Growth 以上で使えます。それ未満のプランでは 403 を返し、課金しません。POSTPOST /v1/reverse
緯度経度から住所を引く逆ジオコーディングです。実装にはありますが、料金表に未掲載のため、内容は要確認です。POSTPOST /v1/batch
複数の住所をまとめて非同期で処理します。202 とポーリング用の URL を返します。Growth 以上で使えます。GETGET /v1/batch/{id}
バッチの進捗と結果を取得します。作成したキーの持ち主だけが読めます。結果は 1 時間で破棄されます。GETGET /v1/usage
当月の利用量を返します。基本の項目は全プラン、パス別の内訳は Growth 以上です。GETGET /health
生存確認（liveness）と準備確認（readiness）のエンドポイントです。認証は不要で、課金もされません。共通のオブジェクト
検証レベル・精度・住所の要素・訂正・警告など、複数のエンドポイントで共通して現れる値の意味をまとめています。
GUIDES
ガイド
CSV の清掃、チェックアウト、再試行など、目的別の手順。
CSV の住所を整える
住所の列を持つ CSV を読み、1件ずつ検証して、検証レベル・正規化した住所・座標の列を足して書き出す手順です。チェックアウトで住所を確認する
EC の注文画面で、住所を入力した直後に検証し、確認や再入力を促す実装の考え方と、フロント・サーバーの分担です。建物の階が無いときの扱い
多床ビルで階や部屋番号が未入力のときの警告（U7）の見方と、確認を促す実装の例です。古い名簿を更新する
合併や町名変更の前の表記が残る古い住所録を、検証して現在の表記にそろえる手順と、人が確認すべき範囲です。バッチ処理のしかた
大量の住所を非同期で処理する手順です。送信・ポーリング・結果の取得までを、Python のコードで示します。Growth 以上で使えます。再試行と 429
429・503 を再試行してよいか、どれだけ待つか、いつ諦めるか。指数バックオフの書き方と、再試行してはいけないエラーを整理します。
住所の列を持つ CSV を読み、1件ずつ検証して、検証レベル・正規化した住所・座標の列を足して書き出す手順です。チェックアウトで住所を確認する
EC の注文画面で、住所を入力した直後に検証し、確認や再入力を促す実装の考え方と、フロント・サーバーの分担です。建物の階が無いときの扱い
多床ビルで階や部屋番号が未入力のときの警告（U7）の見方と、確認を促す実装の例です。古い名簿を更新する
合併や町名変更の前の表記が残る古い住所録を、検証して現在の表記にそろえる手順と、人が確認すべき範囲です。バッチ処理のしかた
大量の住所を非同期で処理する手順です。送信・ポーリング・結果の取得までを、Python のコードで示します。Growth 以上で使えます。再試行と 429
429・503 を再試行してよいか、どれだけ待つか、いつ諦めるか。指数バックオフの書き方と、再試行してはいけないエラーを整理します。
この内容に誤りや不足があれば、お知らせください。