住所→郵便番号API リファレンス

エンドポイント一覧この見出しへのリンク

共通仕様この見出しへのリンク

検索クエリの2モードこの見出しへのリンク

本APIには2種類の検索クエリがあり、用途で使い分けます。

両者は併用可能です。t と q を同時に指定すると暗黙的に AND で結合されます (例: フリーテキストで検索しつつ _structure:1 でエリア郵便番号のみに絞る)。

GET /v1/postalcode/この見出しへのリンク

与えられた検索クエリを元に、該当する郵便区画のリソースを取得します。さらに、検索クエリに含まれる住所文字列を正規化します。

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

https://api.kenall.jp/v1/postalcode/?q=...&t=...&offset=...&limit=...&facet=...&version=...

クエリパラメータこの見出しへのリンク

フリーテキスト検索の仕様この見出しへのリンク

フリーテキスト検索は、入力した住所文字列を自動で分割して検索を実行します。同時に、入力住所が正規化された結果がレスポンスに含まれます。

curl サンプルこの見出しへのリンク

curl -H "Authorization: Token YOUR_API_KEY" \
  "https://api.kenall.jp/v1/postalcode/?t=東京都千代田区麹町三丁目12-14麹町駅前ヒルトップ8F&limit=1"

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

{
  "version": "2022-01-31",
  "data": [
    {
      "jisx0402": "13101",
      "old_code": "102",
      "postal_code": "1020083",
      "prefecture_kana": "トウキョウト",
      "city_kana": "チヨダク",
      "town_kana": "コウジマチ",
      "town_kana_raw": "コウジマチ",
      "prefecture": "東京都",
      "city": "千代田区",
      "town": "麹町",
      "koaza": "",
      "kyoto_street": "",
      "building": "",
      "floor": "",
      "town_partial": false,
      "town_addressed_koaza": false,
      "town_chome": true,
      "town_multi": false,
      "town_raw": "麹町",
      "town_jukyohyoji": false,
      "update_status": 0,
      "update_reason": 0,
      "corporation": null
    }
  ],
  "query": {
    "q": null,
    "t": "東京都千代田区麹町三丁目12-14麹町駅前ヒルトップ8F",
    "prefecture": "東京都",
    "county": null,
    "city": "千代田区",
    "city_ward": null,
    "town": "麹町",
    "kyoto_street": null,
    "block_lot_num": "3-12-14",
    "building": "麹町駅前ヒルトップ",
    "floor_room": "8F"
  },
  "count": 1280,
  "offset": 0,
  "limit": 1,
  "facets": null
}

住所正規化機能 (query.* フィールド)この見出しへのリンク

t パラメータで送信した住所文字列を、項目別に分解した結果が query オブジェクトに格納されます。住所マスタクレンジング目的で本APIを使う場合は、この query だけ取り出して使えます。

t が入力クエリで、prefecture 以降のフィールドが正規化された住所要素です。q は構文検索用のクエリのため、住所正規化機能では使用しません (フリーテキスト検索時は null)。上記の例では、三丁目12-14 という番地文字列が "3-12-14" という形に正規化されています。

構文検索の仕様この見出しへのリンク

基本文法この見出しへのリンク

• 検索ワードは2文字以上で、部分一致します
• 検索ワード間は半角スペース・タブ・改行で区切る
• キーワードなし → OR として扱い BM25 スコアで順位付け (短いテキストが対象のため全ワード一致が実質 AND と同等の結果になる)
• AND: 「両方を含む」 / OR: 「いずれかを含む」
• -キーワード: 「キーワードを含まない」(NOT検索・マイナス演算子)

項目別検索 (識別子:値)この見出しへのリンク

特定の項目だけを対象に検索したい場合、項目名:キーワード の形式を使います。

例: 京都市上京区で通り名に「上る」を含む住所この見出しへのリンク

q=city:京都市上京区 AND kyoto_street:上る

構文検索クエリのレスポンス例この見出しへのリンク

構文検索で大口事業所個別番号データが合致した場合、data[].corporation に事業所情報が格納されます (フリーテキスト検索のレスポンスと異なり query の正規化フィールドは null)。

{
  "version": "2022-01-31",
  "data": [
    {
      "jisx0402": "14131",
      "old_code": "210",
      "postal_code": "2108797",
      "prefecture": "神奈川県",
      "city": "川崎市川崎区",
      "town": "榎町",
      "corporation": {
        "name": "日本郵便　株式会社　南関東支社",
        "name_kana": "ニツポンユウビン　カブシキガイシヤ　ミナミカントウシシヤ",
        "block_lot": "１－２",
        "block_lot_num": "1-2",
        "post_office": "川崎港",
        "code_type": 0
      }
    }
  ],
  "query": {
    "q": "神奈川県 AND 日本郵便",
    "t": null,
    "prefecture": null,
    "county": null,
    "city": null,
    "city_ward": null,
    "town": null,
    "kyoto_street": null,
    "block_lot_num": null,
    "building": null,
    "floor_room": null
  },
  "count": 3,
  "offset": 0,
  "limit": 1,
  "facets": null
}

ファセット指定 (_facet:/…)この見出しへのリンク

特定の都道府県・市区町村の階層以下だけを対象に検索したい場合、_facet:/... を使います。

検索対象データの種類この見出しへのリンク

本APIの検索対象データは3種類です。

デフォルトでは上記すべてが検索対象です。絞り込みたい場合は構文検索の _type / _structure オプションを使います。

検索対象の絞り込みオプション (_type / _structure)この見出しへのリンク

検索対象を特定のデータ種類に絞り込みたい場合は、構文検索クエリ (q パラメータ) で以下のオプションを指定してください。

よくある検索パターンこの見出しへのリンク

郵便番号逆引き検索を活用するために、実際に役立つクエリ例を紹介します。

① フリーテキストでエリア郵便番号のみ検索この見出しへのリンク

ビル郵便番号を検索対象から外し、エリア郵便番号のみを対象としてフリーテキスト検索を行う場合、t と q の両方を組み合わせます。

• t: 検索対象の住所文字列を入力します。例: 東京都千代田区麹町三丁目12-14麹町駅前ヒルトップ8F
• q: _structure:1 でエリア郵便番号のみを指定します。

curl -H "Authorization: Token YOUR_API_KEY" \
  "https://api.kenall.jp/v1/postalcode/?t=東京都千代田区麹町三丁目12-14麹町駅前ヒルトップ8F&q=_structure:1"

② 事業所名で大口事業所個別番号を検索この見出しへのリンク

フリーテキスト検索は住所文字列のみを検索するため、事業所名での検索には利用できません。事業所名で検索したい場合は構文検索のみを使用します。例えば 東京都庁 の大口事業所個別番号を検索したい場合、q に検索対象文字列 東京都庁 を入力し、さらに _type:2 で大口事業所個別番号データのみを指定し、この2つを AND で結合します。

curl -H "Authorization: Token YOUR_API_KEY" \
  "https://api.kenall.jp/v1/postalcode/?q=東京都庁+AND+_type:2"

③ 特定の自治体内の郵便番号のみ検索この見出しへのリンク

_facet を使うことで、特定の自治体内に絞って郵便番号を検索できます。例えば 東京都千代田区 以下を対象にして 本町 を含む住所を検索する場合、以下のようにクエリを組み立てます。

• t: 検索対象の住所文字列である 本町 を入力します。
• q: _facet:/東京都/千代田区 を入力します。エリア郵便番号のみを指定する場合は _structure:1 も追加し、これらを AND で結合します。

curl -H "Authorization: Token YOUR_API_KEY" \
  "https://api.kenall.jp/v1/postalcode/?t=本町&q=_facet:/東京都/千代田区+AND+_structure:1"

レスポンス (GET /v1/postalcode/)この見出しへのリンク

トップレベルフィールドこの見出しへのリンク

data 配列内のレコードこの見出しへのリンク

フィールド仕様は 郵便番号→住所API リファレンス の「data 配列内・郵便区画レコードのフィールド仕様」と同じです (jisx0402 / postal_code / prefecture / city / town / corporation 他。詳細は郵便番号→住所APIリファレンス参照)。

ファセット機能この見出しへのリンク

検索インデックスは「都道府県名」「市区町村名」で階層化されており、検索結果にファセット (合致レコードの件数を階層ごとに数え上げた結果) を含められます。

例えば /東京都 というファセットの配下にある /東京都/中央区・/東京都/港区、/神奈川県 というファセットの配下にある /神奈川県/横浜市・/神奈川県/川崎市 のような副階層を考えたとき、/東京都 パスのファセットに合致するレコード数は配下の合計、/神奈川県 パスのファセットに合致するレコード数は配下の合計、となります。

ファセットパスこの見出しへのリンク

• 必ず / で始まる
• 各階層は / で区切る (例: /東京都/中央区)
• ルート階層は /

使い方この見出しへのリンク

facet パラメータで取得したい階層を指定すると、レスポンスの facets に件数ペア配列が返ります。

# 東京都配下の市区町村ごとの件数を取得
curl -H "Authorization: Token YOUR_API_KEY" \
  "https://api.kenall.jp/v1/postalcode/?t=本町&facet=/東京都"

POST /v1/batch/postalcode/search (バッチAPI)この見出しへのリンク

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

https://api.kenall.jp/v1/batch/postalcode/search?version=...

クエリパラメータこの見出しへのリンク

リクエストボディこの見出しへのリンク

queries 配列内の問い合わせレコードこの見出しへのリンク

curl サンプルこの見出しへのリンク

curl -X POST -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "default_q": "",
    "default_limit": 1,
    "queries": [
      {"t": "東京都千代田区麹町三丁目12-14麹町駅前ヒルトップ8F"}
    ]
  }' \
  "https://api.kenall.jp/v1/batch/postalcode/search"

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

{
  "version": "2023-01-31",
  "params": {
    "default_limit": 1,
    "default_q": ""
  },
  "records": [
    {
      "data": [
        {
          "jisx0402": "13101",
          "old_code": "102",
          "postal_code": "1020083",
          "prefecture_kana": "トウキョウト",
          "city_kana": "チヨダク",
          "town_kana": "コウジマチ",
          "town_kana_raw": "コウジマチ",
          "prefecture": "東京都",
          "city": "千代田区",
          "town": "麹町",
          "koaza": "",
          "kyoto_street": "",
          "building": "",
          "floor": "",
          "town_partial": false,
          "town_addressed_koaza": false,
          "town_chome": true,
          "town_multi": false,
          "town_raw": "麹町",
          "town_jukyohyoji": false,
          "update_status": 0,
          "update_reason": 0,
          "corporation": null
        }
      ],
      "query": {
        "q": null,
        "t": "東京都千代田区麹町三丁目12-14麹町駅前ヒルトップ8F",
        "prefecture": "東京都",
        "county": null,
        "city": "千代田区",
        "city_ward": null,
        "town": "麹町",
        "kyoto_street": null,
        "block_lot_num": "3-12-14",
        "building": "麹町駅前ヒルトップ",
        "floor_room": "8F"
      },
      "count": 100,
      "offset": 0,
      "limit": 1,
      "facets": null
    }
  ]
}

レスポンスフィールド (バッチ)この見出しへのリンク

HTTP ステータス・エラーこの見出しへのリンク

共通HTTPステータス仕様は API共通仕様 — HTTPステータスコード へ。

SDK で呼び出すこの見出しへのリンク

JavaScript SDKこの見出しへのリンク

import { KENALL } from '@ken-all/kenall';
 
const api = new KENALL('YOUR_API_KEY');
 
// 住所正規化 (住所文字列をフリーテキスト検索)
const result = await api.searchAddress({
  t: '東京都千代田区麹町三丁目12-14麹町駅前ヒルトップ8F',
  limit: 1,
});
console.log(result.query.block_lot_num); // => "3-12-14"
console.log(result.data[0].postal_code);  // => "1020083"
 
// 構文検索 (事業所名)
const corp = await api.searchAddress({
  q: '東京都庁 AND _type:2',
});

Python (requestsで代替)この見出しへのリンク

import os, requests
 
API_KEY = os.environ["KENALL_API_KEY"]
HEADERS = {"Authorization": f"Token {API_KEY}"}
BASE = "https://api.kenall.jp/v1/postalcode/"
 
# フリーテキスト検索 (住所正規化)
res = requests.get(BASE, headers=HEADERS, params={
    "t": "東京都千代田区麹町三丁目12-14麹町駅前ヒルトップ8F",
    "limit": 1,
}, timeout=10)
res.raise_for_status()
data = res.json()
print(data["query"]["block_lot_num"])      # => "3-12-14"
print(data["data"][0]["postal_code"])      # => "1020083"
 
# 構文検索 (特定自治体内)
res = requests.get(BASE, headers=HEADERS, params={
    "t": "本町",
    "q": "_facet:/東京都/千代田区 AND _structure:1",
}, timeout=10)

→ SDK 一覧

OpenAPI スキーマこの見出しへのリンク

OpenAPI スキーマ (YAML): 2023-09-01 / 2024-01-01 / 2025-01-01

注意事項・制限事項この見出しへのリンク

フリーテキスト検索の制限この見出しへのリンク

• 構文検索のクエリ構文 (AND/OR/項目別/ファセット) は使えません
• 住所文字列のみ検索可能で、事業所名では検索できません (事業所名検索は構文検索を使用)
• 大口事業所個別番号・ビル郵便番号もデフォルトで対象になります (除外したい場合は _type/_structure)

構文検索の制限この見出しへのリンク

• 検索ワードは2文字以上、部分一致
• 検索ワード間は半角スペース・タブ・改行で区切る
• キーワードなしは OR として扱われ BM25 スコアで順位付け (短いテキストが対象のため全ワード一致が実質 AND と同等の結果になる)
• マイナス演算子 (-) で対象ワードを除外可能 (例: -ビル)

バッチAPIの制限この見出しへのリンク

• バッチAPIオプションご購読のお客様のみ利用可
• シークレットキー必須 (公開キーでは利用不可)
• 処理時間が 1分以上のリクエストは自動打ち切り

デフォルト値この見出しへのリンク

• offset: 省略時 0
• limit: 省略時 100(範囲: 1〜100)
• version: 省略時は最新
• バッチAPI default_limit: 省略時 1

このAPIに関する技術FAQこの見出しへのリンク

関連リファレンスこの見出しへのリンク

• ⚠️ 既知の問題 (このAPIに該当する制約・破壊的変更)
• API共通仕様 — Token認証 / HTTPステータス / バージョニング / リクエスト回数の制限
• 郵便番号→住所API — 順引き (郵便番号から住所)
• JavaScript SDK ドキュメント

最終更新: 2026-07-16