郵便番号逆引き検索API (住所正規化API)

GET /v1/postalcode/?q=...&t=...&offset=...&limit=...&facet=...&version=...

与えられた検索クエリを元に、該当する郵便区画のリソースを取得します。 さらに、検索クエリに含まれる住所文字列を正規化します。 郵便番号逆引き検索APIの概要については、ケンオールAPI概要をご参照ください。

リソースURL

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

パラメーター

名前	型	必須かどうか	説明	値の例
q	string	qとtのいずれかが必須	構文検索クエリ。詳細は構文検索クエリの仕様を参照のこと。	"神奈川県 AND 日本郵便"
t	string	qとtのいずれかが必須	フリーテキスト検索クエリ。詳細はフリーテキスト検索クエリの仕様を参照のこと。	"東京都千代田区麹町３丁目１２－１４麹町駅前ヒルトップ８階"
offset	number	省略可	結果を取得するオフセット値。省略した場合は0と見なされる。	0
limit	number	省略可	最大取得件数を指定する。1以上100以下の値を指定できる。省略した場合は100と見なされる。	50
facet	string	省略可	取得したいファセットの階層を指定する。	"/宮城県"
version	string	省略可	取得したい郵便番号データのバージョンを指定します。省略した場合は、リクエスト時点での最新バージョンを指定したものとみなされます。	"2021-02-26"

検索クエリの種類

検索クエリは以下の2パターンを利用できます。

• フリーテキスト検索クエリ (パラメーターtで与える): 住所文字列で検索を行う、シンプルな検索クエリです。
• 構文検索クエリ (パラメーターqで与える): 検索用のクエリ構文を用いた複雑な検索を行います。

フリーテキスト検索クエリと構文検索クエリの両方を指定することも可能です。その場合は、両者の条件は暗黙的にANDで結合されます。

フリーテキスト検索クエリの仕様

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

住所正規化機能については住所正規化機能を参照してください。

tip

住所正規化を行うためだけに郵便番号逆引きAPIを利用することもできます。

フリーテキスト検索クエリは、構文検索クエリと異なる点があります。

• 構文検索クエリの仕様に記載されたクエリ構文は利用できません。
• 個別事業所番号データ、ビル郵便番号はデフォルトで検索対象に含まれます。これらを除外する場合は郵便番号データと個別事業所番号データやエリア郵便番号とビル郵便番号を参考にしてください。
• 住所文字列のみ検索可能です。個別事業所番号データが対象外のため、事業所名での検索はできません。

構文検索クエリオプションqを組み合わせることで、上記の制約を解決することができます。検索クエリの種類も参照してください。

フリーテキスト検索クエリのリクエスト

以下はフリーテキスト検索のリクエストの一例です。

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
}

レスポンスのデータは以下のような構成になっています。

名前	型	説明	例
version	string	データのバージョン番号。YYYY-MM-DD形式の、データ作成日付となっている。
data	array	郵便区画レコードの配列
query	object	qパラメーターまたはtパラメーターに指定されたクエリ文字列のパース結果	(後述)
count	number	クエリに合致したレコードの総数 (dataプロパティに与えられるレコードの数ではなく、合致したすべてのレコードの件数)	42
offset	number	offsetパラメーターに与えられたオフセット	0
limit	number	limitパラメーターに与えられた最大取得件数	50
facets	arrayまたはnull	facetパラメーターが与えられた場合のみ、パラメーターで示されたファセット階層配下のファセットとそのファセットに含まれるレコードの数のペアの配列	[[""/東京都"", 1], [""/神奈川県"", 3]]

郵便区画レコードの仕様は、郵便番号APIのレコードと同一です。

queryに与えられるフリーテキスト検索クエリのパース結果は以下のような構成となっています。

名前	型	説明	例
q	stringまたはnull	リクエストパラメーターのqとして与えられた文字列	"神奈川県 AND 日本郵便"
t	stringまたはnull	リクエストパラメーターのtとして与えられた文字列	"神奈川県横浜市"
prefecture	stringまたはnull	正規化された都道府県名	"東京都"
county	stringまたはnull	正規化された郡名	"西多摩郡"
city	stringまたはnull	正規化された市区町村名	"瑞穂町"
city_ward	stringまたはnull	正規化された政令指定都市の行政区名	"美浜区"
town	stringまたはnull	正規化された町域名 (大字または街区名)	"大桑町"
kyoto_street	stringまたはnull	正規化された京都市特有の通り名	"先斗町通四条上る"
block_lot_num	stringまたはnull	正規化された番地。住居表示の行われている地域では丁目・番地・号を、そうでない地域では番地の部分を半角算用数字およびハイフン繋ぎにしたものを与える	"3-12-14"
building	stringまたはnull	正規化された建物名	"麹町駅前ヒルトップ"
floor_room	stringまたはnull	正規化された階名/部屋番号	"8階801号"

住所正規化機能

フリーテキスト検索を用いる際に送信する住所文字列を正規化した結果がレスポンスに含まれます。

フリーテキスト検索クエリのレスポンスのquery内に、正規化された結果が格納されています。

  "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"
  },

tが入力クエリで、prefecture以降のフィールドが正規化された住所要素となります。

qは構文検索用のクエリのため、住所正規化機能では使用しません。

この例では、三丁目12-14という番地文字列が"3-12-14"という形に正規化されています。

構文検索クエリの仕様

• 検索ワードは2文字以上で、部分一致します。

• 検索ワードは一つ以上の半角スペース、タブまたは改行文字で区切ります。

• 検索ワードの間に AND もしくは OR といったキーワード文字列を挟むと、「かつ」「もしくは」といった条件で検索が可能です。キーワード文字列がない場合は「かつ」となります。

  (例1) 神奈川県 AND 日本郵便 → 「神奈川県」「日本郵便」の両方を含むレコードを検索する。

  (例2) 神奈川県 OR 日本郵便 → 「神奈川県」もしくは「日本郵便」 (またはその両方) を含むレコードを検索する。

  (例3) 神奈川県 日本郵便 → 「神奈川県」「日本郵便」の両方を含むレコードを検索する。

• 特定の項目のみを対象に検索を行いたいときは、項目名に続けて : (半角コロン) を記述し、その後にキーワード文字列を記載します。

  (例) 京都の通り名に「上る」を含む京都市上京区の住所を取得する

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

• 特定のファセットの階層以下の情報を取得したい場合は下記のクエリを使用します。

  (例1)_facet:/宮城県

  (例2)_facet:/宮城県/仙台市宮城野区

上記において、項目名として指定できる識別子は以下の通りです。

識別子	意味
prefecture	都道府県
city	市区町村
town	町域
koaza	小字
kyoto_street	京都市特有の通り名
building	建物名
floor	階数
block_lot	個別事業所番号の場合、町域以下の住所
corporation	個別事業所番号の場合、事業所名
corporation_kana	個別事業所番号の場合、事業所名の読み仮名 (全角カタカナ)

ファセット

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

例えば /東京都 というファセットの配下にある /東京都/中央区 /東京都/港区 、 /神奈川県 というファセットの配下にある /神奈川県/横浜市 /神奈川県/川崎市 のような副階層を考えた時、合致した 8 件のレコードのファセットごとの内訳が/東京都/中央区 については 1 件、 /東京都/港区 については 2 件、/神奈川県/横浜市 については 2 件、 /神奈川県/川崎市 については 3 件だとしたら、 /東京都というパスのファセットに合致するレコード数は 3 件、/神奈川県というパスのファセットに合致するレコード数は 5 件、となります。

ファセットのパス名は必ず / で始まり、各階層は / で区切られます。ルート階層は /で表されます。

郵便番号データと個別事業所番号データ

デフォルトでは、郵便番号データと個別事業所番号データの両方を検索します。どちらか片方を検索する場合は、以下の検索オプションを指定してください。

• 郵便番号データのみを検索する場合: _type:1
  • 例: 東京都 AND _type:1
• 個別事業所番号データのみを検索する場合: _type:2
  • 例: prefecture:神奈川県 AND city:横浜市中区 AND _type:2

エリア郵便番号とビル郵便番号

デフォルトでは、郵便番号データのうちエリア郵便番号 (ある地域を対象とする郵便番号) とビル郵便番号 (高層ビルの階層ごとに付与された郵便番号) の両方を検索します。どちらか片方を検索する場合は、以下の検索オプションを指定してください。

• エリア郵便番号のみを検索する場合: _structure:1
  • 例: 東京都 AND _structure:1
• ビル郵便番号のみを検索する場合: _structure:2
  • 例: prefecture:神奈川県 AND city:横浜市中区 AND _structure:2

構文検索クエリのリクエスト

以下は構文検索のリクエストの一例です。

curl -H "Authorization: Token $YOUR_API_KEY" \
"https://api.kenall.jp/v1/postalcode/?q=神奈川県+AND+日本郵便&limit=1"

構文検索クエリのレスポンス

以下は構文検索のレスポンスの一例です。

{
  "version": "2022-01-31",
  "data": [
    {
      "jisx0402": "14131",
      "old_code": "210",
      "postal_code": "2108797",
      "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": false,
      "town_multi": false,
      "town_raw": "榎町",
      "town_jukyohyoji": false,
      "update_status": 0,
      "update_reason": 0,
      "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
}

検索クエリの使用例

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

フリーテキスト検索でエリア郵便番号のみを指定する

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

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

POST /v1/batch/postalcode/search

info

本APIは、バッチAPIオプションご購読のお客様のみが利用できます。

caution

郵便番号逆引き検索バッチAPIは、シークレットキーでのみ利用できます。公開キーでは利用できませんのでご注意ください。

郵便番号逆引き検索APIをバッチで実行することができます。

処理時間が1分以上となるようなリクエストは自動的に打ち切られますので、リクエスト内容にはご注意ください。

リソースURL

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

パラメーター

クエリーパラメーター

名前	型	必須かどうか	説明	値の例
version	string	省略可	検索の対象とする郵便番号データのバージョンを指定します。省略した場合は、リクエスト時点での最新バージョンを指定したものとみなされます。	"2021-02-26"

リクエストボディ

リクエストボディには、郵便番号逆引き検索APIのパラメーターに指定していたような問い合わせのレコードを複数個指定することができます。

リクエストボディはJSON形式です。Content-Type ヘッダには application/json を指定してください。

以下はリクエストボディの一例です。

{
  "default_q": "(省略可)",
  "default_limit": 1,
  "queries": [
    {
      "t": "横浜1",
      "q": "_facet:/青森県",
      "limit": 3
    }
  ]
}

リクエストボディは以下のような構造となっています。

名前	型	必須かどうか	説明	値の例
default_q	string	省略可	各問い合わせレコードでqオプションが指定されなかった時にデフォルト値となる文字列を指定します。	"仙台市"
default_limit	number	省略可	limit	各問い合わせレコードのlimitオプションに指定するデフォルトの数値を指定します。このデフォルト値も指定がなかった場合の最終的なデフォルトは1となります。
queries	array	必須	問い合わせレコードの配列を指定します。

問い合わせレコードは以下のような構造となっています。

名前	型	必須かどうか	説明	値の例
t	string	必須	郵便番号逆引き検索APIのtパラメータに相当する住所文字列を指定します。	"三重県津市"
q	string	省略可	郵便番号逆引き検索APIのqパラメータに相当する構文検索クエリを指定します。	"_facet:/奈良県"
limit	number	省略可	郵便番号逆引き検索APIのlimitパラメータに相当する検索結果の最大数を指定します。	1

レスポンス

レスポンスには各問い合わせレコードに対応する住所正規化結果と郵便番号データの検索結果が含まれています。レスポンスはJSON形式です。

以下はレスポンスの一例です。

{
  "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
    }
  ]
}

レスポンスのデータは以下のような構成になっています。

名前	型	説明	例
version	string	データのバージョン番号。YYYY-MM-DD形式の、データ作成日付となっている。
params	object	リクエストボディのdefault_qとdefault_limitに指定された値と同じもの。
records	array	結果レコードの配列。結果レコードの出現順は問い合わせレコードの出現順に対応している。

結果レコードの形式は、フリーテキスト検索クエリのレスポンスで説明されているものと同一です。