API共通仕様

要約: ケンオールの全APIで共通する仕様をまとめたページです。ベースURL は https://api.kenall.jp/v1/、認証は Authorization: Token YOUR_API_KEY、レスポンスは JSON、HTTP ステータスは標準的な REST 規約に従います。

ベースURLこの見出しへのリンク

全エンドポイントは以下のベースURL の配下にあります:

https://api.kenall.jp/v1/

/v1 の部分はAPIのメジャーバージョンを表しています。 (→APIバージョニング)

認証方式この見出しへのリンク

すべてのリクエストには Authorization ヘッダで Token 認証が必要です:

Authorization: Token YOUR_API_KEY

警告

OAuth Bearer ではなく Token スキームです。Authorization: Bearer ... を与えると 401 が返ります。AI ツールが Bearer 形式を生成した場合は手動で Token に置換してください。

APIキーの取得・再発行はダッシュボードから行えます。詳細はクイックスタートを参照してください。

リクエスト形式この見出しへのリンク

メソッド: 大半のAPIは GET のみ。バッチ系・レーダー登録など一部のAPIのみ POST を使用します
クエリパラメータは URL エンコード必須
パスパラメータ (郵便番号・法人番号など) はハイフン無し・桁数厳守 (例: 郵便番号は7桁数字)
Accept ヘッダの指定は不要 (JSON で固定返却)

レスポンス形式この見出しへのリンク

すべてのレスポンスは application/json; charset=utf-8 です。基本構造:

{
  "version": "2024-09-30",
  "data": [
    { "...": "結果オブジェクト" }
  ]
}

version: データソースの更新日 (YYYY-MM-DD)
data: 結果の配列。1件のみのAPIでも配列で返ります
該当データが無い場合は HTTP 404 (空配列ではない)

HTTPステータスコードこの見出しへのリンク

コード	意味	説明
200 OK	成功	処理は正常に完了しました
401 Unauthorized	認証エラー	APIキーが渡されていないか、正しくありません (`Authorization: Bearer ...` スキームを使用した場合も含む)
402 Payment Required	課金エラー	トライアル期間が切れているか、課金に失敗しています
403 Forbidden	権限エラー	購読中のプランでは実行できないAPIです。プランごとの機能の違いも参照してください
404 Not Found	データなし	与えられたパラメーターに対応する結果は存在しません
405 Method Not Allowed	メソッド不許可	許可されていないHTTPメソッドを実行しようとしています
429 Too Many Requests	リクエスト過多	APIのリクエスト量の制限に達しました。リクエストの頻度を減らしてください
500 Internal Server Error	サーバーエラー	システム側で問題が発生しました。サポートにお問い合わせください

エラーレスポンス形式この見出しへのリンク

4xx / 5xx のエラー時は以下の構造で返ります:

{
  "error": {
    "code": "INVALID_POSTAL_CODE",
    "message": "郵便番号は7桁の数字で指定してください"
  }
}

リクエスト回数の制限この見出しへのリンク

プランごとに一定期間あたりのリクエスト回数の上限が設定されています。上限に達した場合は HTTP 429 が返るので、リクエストの頻度を減らしてください。上限はプランによって異なります。詳細はプランと料金を参照してください。

プランごとに利用できるAPIこの見出しへのリンク

各APIがどのプランで利用できるかは、プランと料金およびプランごとの機能の違いを参照してください。契約中のプランに含まれないAPIにアクセスすると HTTP 403 が返ります。

ブラウザからの直接呼び出しに対応するため、CORS は許可されています。クライアント (ブラウザ) から呼び出す場合は公開キーを使用してください。公開キーはクライアントに配置される前提のキーで、ダッシュボードで許可ドメインを登録すると Origin ヘッダーで利用元が制限され、許可ドメイン以外からのリクエストは拒否されます。そのため値がクライアントに現れても差し支えありません。サーバーサイドで利用する場合や秘匿が必要な処理にはシークレットキーを使用し、サーバー内に厳重に保管してください。

ブラウザからアクセスするページでリクエストを発行する場合は、事前にそのドメインからのアクセスを許可する必要があります。許可するドメインの登録手順はクイックスタートを参照してください。

APIバージョニングこの見出しへのリンク

ケンオールはAPIレスポンスの互換性を重視しており、正規化ロジックの変更などペイロードの内訳が変わるケースに対応するため、APIバージョニングを導入しています。バージョンを指定することで、変更にすぐ追従できない場合でも、暫定措置として一定期間は旧仕様のまま利用を継続できます。

メジャーバージョンとマイナーバージョンこの見出しへのリンク

ケンオールのバージョンには メジャーバージョンとマイナーバージョンの2種類があります。

メジャーバージョン: エンドポイントURL に含まれる /v1 の部分に該当する文字列が指すものです。たとえば https://api.kenall.jp/v1/postalcode/1000001 というURL では、先頭の /v1 の部分がメジャーバージョンで、末尾の 1000001 は郵便番号 (パスパラメータ) です。マイナーバージョンが多数累積した場合や、変更事項が10点を超えるような大規模変更の際にアップグレードされます。
マイナーバージョン: その機能が導入された日付を反映した YYYY-MM-DD 形式の文字列です。本ドキュメントで「APIバージョン」と呼ぶ場合はこのマイナーバージョンを指します。正規化ロジックの変更などペイロードの内訳が変わる変更に対応するために導入されたもので、旧バージョンを指定することで、変更にすぐ追従できない場合でも暫定措置として一定期間は旧仕様のまま利用を継続できます。

バージョンが上がる変更 / 上がらない変更この見出しへのリンク

以下のケースでは マイナーバージョンが上がります。

APIリクエスト
- リクエストパラメータの意味に変更があった
- リクエストパラメータが削除された
- 必須のリクエストパラメータが追加された
APIレスポンス
- レスポンスの形式が変更された (プロパティの追加・削除・データ型の変更など)
- レスポンスプロパティの意味に変更があった

一方、以下のケースでは バージョンは上がりません。

APIリクエスト: 任意のリクエストパラメータが追加された
APIレスポンス: レスポンスの文字種など表面的な内容の変更のうち、用途を鑑みて互換性を損ねると言えないもの

マイナーバージョンの指定方法この見出しへのリンク

メジャーバージョンはリクエストURL のパスの一部として指定します (/v1/...)。マイナーバージョンは以下のいずれかの方法で指定できます。

HTTPリクエストヘッダ (推奨): KenAll-API-Version ヘッダにバージョンを指定します。
```
KenAll-API-Version: 2022-09-01
```
クエリパラメータ: -kenall-api-version パラメータにバージョンを指定します。
```
https://api.kenall.jp/v1/postalcode?q=...&-kenall-api-version=2022-09-01
```
APIキーごとのデフォルト値: 上記いずれの方法でも指定がなかった場合、APIキーごとに設定されたデフォルトのマイナーバージョンが使われます。設定方法は APIキー・認証を参照してください。

ツール・連携この見出しへのリンク

すぐに試したい開発者向けのコレクション・仕様書を配布しています。

📄 OpenAPI スキーマ (YAML): 2023-09-01 / 2024-01-01 / 2025-01-01 — SDK自動生成・Stoplight・Redocly 等で活用
📚 既知の問題 — 実装前に必ず確認