住所の表記をそろえるAPI
「東京都千代田区一番町1-2-3」「千代田区一番町一丁目」「東京千代田区霞ヶ関2丁目1番2号」のような住所の書き方の違いを、郵便番号データの正式な書き方にそろえて返すAPIです。都道府県・市区町村・町域・丁目・番地・建物名に分け、郵便番号と市区町村コードも一緒に返します。
- できること
- 住所の書き方をそろえる / 都道府県・市区町村・町域・丁目・番地・建物名に分ける / 郵便番号と市区町村コード(5桁・検査数字付き6桁)を出す / 都道府県名・郡名・区名を省いた住所を補う
- 費用・登録
- 無料・登録不要・APIキー不要(提供条件は利用状況で変わることがあります)
- 向いている用途
- 会員・顧客の住所データで重複を見つける・名寄せする、入力フォームで住所の書き方を統一する、住所の一覧に郵便番号や市区町村コードを付ける
- 気をつけること
- 番地・建物名が実在するかは確かめません(郵便番号データに番地は無いため)。かな書きの町名(かすみが関 など)は対象外です。止まらないことは保証していません。
データ: 日本郵便の郵便番号データ(郵便番号APIと同じもの・毎月更新)。応答の data_version で、いつの版か確かめられます。
はじめかた(3ステップ)
- ブラウザで開いてみる: https://api.shirugear.com/address/v1/normalize.json?q=東京都千代田区一番町1-2-3 を開くと、そろえた住所と、都道府県・市区町村・町域などに分けた結果が返ります。
q=のあとを調べたい住所に変えるだけです。 - 結果の段階を確かめる:
levelが3なら町域(町名)まで見つかっています。0〜2のときは途中までしか分かっていないので、candidates(候補)やrest(残りの部分)を見て、入力を見直してもらうなどしてください。見つかった段階に詳しく書いています。 - 利用規約を確かめる: 利用規約をご確認ください。登録や申し込みは要りません。
いろいろな言語から呼ぶ
住所は URLエンコードして q に入れてください(ほとんどの言語に関数があります)。どの例も「千代田区一番町一丁目」をそろえます。
const q = "千代田区一番町一丁目";
const res = await fetch("https://api.shirugear.com/address/v1/normalize.json?q=" + encodeURIComponent(q));
const a = await res.json();
if (a.level === 3) {
console.log(a.normalized, a.zipcode); // → 東京都千代田区一番町1丁目 1020082
} else {
console.log("町名まで見つかりませんでした", a.candidates);
}curl -sG https://api.shirugear.com/address/v1/normalize.json \
--data-urlencode "q=千代田区一番町一丁目"
# そろえた住所だけを出す(jq を使う場合)
curl -sG https://api.shirugear.com/address/v1/normalize.json \
--data-urlencode "q=千代田区一番町一丁目" | jq -r '.normalized'<?php
$q = '千代田区一番町一丁目';
$url = 'https://api.shirugear.com/address/v1/normalize.json?q=' . rawurlencode($q);
$a = json_decode(file_get_contents($url), true);
echo $a['level'] === 3 ? "{$a['normalized']}(〒{$a['zipcode']})\n" : "町名まで見つかりませんでした\n";import json
import urllib.parse
import urllib.request
q = "千代田区一番町一丁目"
url = "https://api.shirugear.com/address/v1/normalize.json?q=" + urllib.parse.quote(q)
with urllib.request.urlopen(url, timeout=10) as res:
a = json.load(res)
print(a["normalized"], a["zipcode"]) # → 東京都千代田区一番町1丁目 1020082その場で試す
住所の表記をそろえる
試しに:
| 項目 | 結果 |
|---|
URLと指定のしかた
URLを開く(GET)だけで JSON(UTF-8)が返ります。先頭は https://api.shirugear.com です。自分のサイトのJavaScriptから直接呼べます(CORS対応)。
| URL | 返すもの |
|---|---|
/address/v1/normalize.json?q={住所} | そろえた住所と、都道府県・市区町村・町域・丁目・番地・建物名に分けた結果、郵便番号・市区町村コード。1件 約0.5KB。中身 |
qには住所を 200文字まで、URLエンコードして入れます(例:?q=%E5%8D%83%E4%BB%A3%E7%94%B0%E5%8C%BA…)。全角・半角、空白はどちらでも構いません。- 先頭の郵便番号(
〒100-0001など)は外してから調べます。 qが無い・空・長すぎるときは 400 です。住所が見つからなくても 404 にはせず、200 でlevelを0にして返します。- 呼び出しは
GET(またはHEAD)だけです。独自のヘッダを付けずに呼んでください。
応答の中身
応答の例
GET https://api.shirugear.com/address/v1/normalize.json?q=東京都千代田区一番町1-2-3
{
"input": "東京都千代田区一番町1-2-3",
"level": 3,
"normalized": "東京都千代田区一番町1-2-3",
"prefecture": "東京都",
"prefecture_kana": "トウキョウト",
"prefcode": "13",
"city": "千代田区",
"city_kana": "チヨダク",
"jiscode": "13101",
"lgcode": "131016",
"town": "一番町",
"town_kana": "イチバンチョウ",
"street": null,
"chome": null,
"banchi": "1-2-3",
"building": null,
"rest": null,
"zipcode": "1020082",
"zipcodes": [{ "zipcode": "1020082", "note": null }],
"candidates": [],
"data_version": "2026-10"
}
各項目
項目はいつも全部そろって返ります。分からない項目は null(配列は空の [])です。
| 項目 | 型 | 内容 |
|---|---|---|
input | 文字列 | 受け取った住所。全角の英数字・記号を半角にし、前後の空白と先頭の郵便番号を外したもの |
level | 数値 | どこまで見つかったか。0=見つからない(または決まらない)、1=都道府県まで、2=市区町村まで、3=町域まで。見つかった段階 |
normalized | 文字列 または null | そろえた住所。level が 3 なら「都道府県+市区町村+(通り名)+町域+丁目+番地」に、建物名などを半角の空白1つで続けます。1・2 のときは、分かったところまでに残りの部分をそのまま続けます。0 のときは null |
prefecture・prefecture_kana | 文字列 または null | 都道府県名と読み(カタカナ) |
prefcode | 文字列 または null | 都道府県コード(2桁。例: "13") |
city・city_kana | 文字列 または null | 市区町村名と読み(カタカナ)。郡や政令指定都市の区を含む書き方です(例: "西多摩郡奥多摩町"・"横浜市中区") |
jiscode | 文字列 または null | 市区町村コード(5桁。全国地方公共団体コードの検査数字を除いたもの) |
lgcode | 文字列 または null | 検査数字付きの6桁の地方公共団体コード。地方公共団体コードAPIで引けます |
town・town_kana | 文字列 または null | 町域名と読み(郵便番号データの書き方。読みは全角のカタカナで、数字が全角のこともあります)。町域が見つからないときは null |
street | 文字列 または null | 京都市の通り名(例: "河原町通二条下る")。ほかの住所では null |
chome | 数値 または null | 丁目の数。「1丁目」「一丁目」のように丁目と書いてあるときだけ入ります |
banchi | 文字列 または null | 番地・号を半角の数字と - でつないだもの(例: 「1番2号」→ "1-2"、「1-2-3」→ "1-2-3") |
building | 文字列 または null | 番地のあとに残った部分(建物名・部屋番号など)。中身は確かめません |
rest | 文字列 または null | 町域が見つからなかったときの、残りの部分(level が 3 のときは null) |
zipcode | 文字列 または null | 郵便番号(7桁)。1つに決まったときだけ入ります。郵便番号の選び方 |
zipcodes | 配列 | その町域の郵便番号すべて。zipcode(7桁)と note(「1〜19丁目」などの郵便番号データの但し書き。無ければ null) |
candidates | 配列 | 市区町村が1つに決まらないときの候補。prefecture・city・jiscode |
data_version | 文字列 | 郵便番号データの版(取り込んだ日本郵便の月次データの年月。例: "2026-10") |
見つかった段階(level)
| level | 意味 | 例 |
|---|---|---|
3 | 町域(町名)まで見つかった。town と zipcodes が入ります | 「横浜市山下町279」→ 神奈川県横浜市中区山下町279 |
2 | 市区町村まで見つかったが、町域が見つからない。残りは rest に入ります | 「東京都千代田区かすみが関」→ 千代田区まで(rest は「かすみが関」) |
1 | 都道府県まで見つかった。市区町村の候補が同じ都道府県の中に複数あるときは candidates に入ります | 「東京都あいうえお」→ 東京都まで(rest は「あいうえお」) |
0 | 見つからない。または、都道府県をまたいで候補があり決まらない(candidates に入ります) | 「府中市」→ 東京都府中市と広島県府中市が候補 |
「府中市」のように同じ名前の市区町村が複数あるときは、都道府県名から書いてもらうと決まります(「東京都府中市宮町1丁目」なら level 3)。
そろえ方のきまり
同じものとして照らし合わせる違い
次の違いは、郵便番号データと照らし合わせるときに同じものとして扱います。返す名前は、いつも郵便番号データの正式な書き方です(「霞ヶ関」と書いても town は「霞が関」)。
- 全角・半角(「1-2-3」→「1-2-3」)と、空白の有無
- 「ヶ」「ケ」「ヵ」「が」、「の」「ノ」「之」
- 住所によく出る旧字体・異体字(澤・沢、髙・高、﨑・崎、邊・邉・辺 など)
- 漢数字と算用数字(「一丁目」と「1丁目」、「北一条西」と「北1条西」)
- ハイフンの種類(「-」「-」「ー」「―」など)
省いてもよいもの
- 都道府県名: 「千代田区一番町一丁目」→ 東京都千代田区一番町1丁目。「東京千代田区…」のように都・府・県を省いた書き方も使えます。
- 郡名: 「奥多摩町氷川215」→ 東京都西多摩郡奥多摩町氷川215
- 政令指定都市の区名: 「横浜市山下町279」→ 神奈川県横浜市中区山下町279(町名から区が1つに決まるときだけ)
- 先頭の郵便番号: 「〒100-0001 東京都千代田区千代田1-1」→ 郵便番号を外して調べます
丁目・番地・建物名の分け方
- 町名のすぐあとに「◯丁目」(「◯丁」も)があれば、その数を
chomeに入れます。「二丁目」のような漢数字も数にします。 - 続く「1番2号」「1-2」「1の2」などの数を、
-でつないでbanchiに入れます。 - 残った部分(建物名・部屋番号など)は、頭のハイフンや読点を外して
buildingに入れます。 - 「1-2-3」の最初の数が丁目かどうかは推測しません。丁目か番地かは住所によって違うためです。この場合は
chomeはnull、banchiは"1-2-3"になります。
京都市の通り名
京都市の「河原町通二条下る」のような通り名を含む住所は、町名を住所の途中から探します。「京都市中京区河原町通二条下る一之船入町537」なら、street が「河原町通二条下る」、town が「一之船入町」、banchi が "537" です。
郵便番号の選び方
1つの町域に郵便番号が1つだけなら、それを zipcode に入れます。丁目や番地で郵便番号が分かれている町域では、次の順に選びます。
- 郵便番号データの但し書き(
zipcodesのnote)が「1〜19丁目」「1、3番地」のような範囲なら、chome(丁目の範囲のとき)やbanchiの最初の数(番地の範囲のとき)と照らし合わせます。例: 「北海道札幌市中央区北一条西二丁目」→ 0600001(但し書き「1〜19丁目」)、「札幌市中央区北1条西20丁目」→ 0640821(「20〜28丁目」)。 - 高層ビルの階ごとの郵便番号(但し書きに「◯階」とあるもの)は選びません。
- それでも1つに決まらなければ
nullにします。そのときもzipcodesに町域の郵便番号がすべて入っているので、利用者に選んでもらうなどしてください。
丁目で郵便番号が分かれる町域では、「北1条西2-3」のように丁目と書いていない住所は丁目が分からないため、zipcode は null になります。
できないこと・注意
- 番地・建物名が実在するかは確かめません。もとにしている郵便番号データには番地が無いためです。町域(町名)までは郵便番号データと照らし合わせています。
- かな書きの町名は対象外です(「かすみが関」など)。町域が見つからず、
levelは2になります。 - 高層ビルの階ごとの郵便番号は選びません(郵便番号の選び方)。
- 郵便番号データにない町名(通称の地名など)は見つかりません。
- 結果は目安です。郵送や登記など正確さが必要な用途では、利用者に確かめてもらってください。
入力した住所の扱い
入力した住所は、シルギアの利用の記録には残しません(記録するのは URL のパス /address/v1/normalize.json だけで、?q= 以降は残しません)。ただし、サーバー会社の標準のアクセスログには URL が一定期間残ります。
エラー
うまくいかないときは、HTTPの状態コードと、次の形の JSON を返します。code は固定の値なので、プログラムで見分けるときはこれを使ってください(message は説明文で、言い回しが変わることがあります)。
{"error":{"status":400,"code":"invalid_query","message":"住所の指定が正しくありません。q に住所を200文字以内で指定してください(…)。"}}
| 状態 | code | いつ |
|---|---|---|
| 400 | invalid_query | q が無い・空・200文字を超える(先頭の郵便番号だけの場合も空とみなします) |
| 404 | not_found | /address/v1/ の下の normalize.json 以外のURL |
| 403 | region_not_allowed | 日本国内以外から呼んだ(データは日本国内からのアクセスに限っています。説明ページは海外からも見られます) |
| 405 | method_not_allowed | GET / HEAD 以外で呼んだ |
住所が見つからないときはエラーではなく、200 で level が 0 の応答を返します。
データの出典・更新・キャッシュ
- 出典: 日本郵便の郵便番号データ(郵便番号APIと同じもの)の、都道府県・市区町村・町域の一覧と照らし合わせています。
- 更新: 日本郵便のデータは月1回更新されます。郵便番号APIのデータが更新されると、このAPIの結果も同時に変わります。
- データの版(
data_version): 取り込んだ日本郵便の月次データの年月です(例:"2026-10")。 - キャッシュ: 応答は1日(エラーは1時間)キャッシュしてかまいません。
ETag/Last-Modifiedに対応しているので、変わっていなければ 304 が返ります。 - 呼び出し回数の目安: 決まった上限はありませんが、1つの利用元から1秒あたり10回程度までにしてください。たくさんの住所をまとめてそろえるときは、間を空けて順に呼んでください。
変更の方針と更新履歴
- v1 の中では、項目を追加することはあっても、今ある項目の名前や意味は変えません。知らない項目が増えていても無視するように作ってください。
- そろえ方(同じとみなす字や、省いてよい書き方)は、よりうまく見つかるように変えることがあります。そのため、同じ入力でも結果が変わることがあります。
- 互換性のない変更は、URLの版を分けて(
/address/v2/など)行います。v1 を終わらせるときは、できるかぎり6か月以上前にこのページでお知らせします。 - 提供条件(無料・登録不要・アクセス回数の上限など)は、利用状況に応じて変えることがあります(利用規約第4条)。
更新履歴
- 2026年11月20日
- 公開。
機械で読める仕様(型定義・OpenAPI)
- TypeScript の型定義:
/address/types.d.ts - OpenAPI 3.1:
/address/openapi.json
このデータを使っているツール
シルギアの次のツールは、このAPIと同じデータで動いています。APIの答えを画面で確かめたいときや、使い方のイメージをつかみたいときにどうぞ。
このAPIと同じデータから作ったツール
よくある質問
本当に無料ですか?登録は必要ですか?
現在は無料で、登録やAPIキーも要りません。個人・法人、営利・非営利を問わず使えます。ただし利用状況に応じて提供条件を変えることがあり、そのときはできるかぎりこのページでお知らせします。
入力した住所は記録されますか?
入力した住所は、シルギアの利用の記録には残しません(記録するのは URL のパス /address/v1/normalize.json だけで、?q= 以降は残しません)。ただし、サーバー会社の標準のアクセスログには URL が一定期間残ります。
番地が実在するかも確かめられますか?
確かめられません。もとにしている郵便番号データには番地が無いため、番地や建物名は書き方をそろえて分けるだけです。町域(町名)までは郵便番号データと照らし合わせています。
「1-2-3」の最初の数は丁目になりますか?
なりません。最初の数が丁目か番地かは住所によって違うため、推測しません。「1丁目」と書いてあるときだけ chome に入れ、「1-2-3」は banchi にそのまま "1-2-3" として返します。
郵便番号が null になるのはどんなときですか?
町域が見つからないとき(level が 0〜2)と、町域に郵便番号が複数あって丁目・番地から1つに決まらないときです。後者のときも zipcodes に町域の郵便番号がすべて入っています。郵便番号から住所を出したいときは郵便番号APIをお使いください。
市区町村について、もっと詳しく知りたいときは?
応答の lgcode(または jiscode)を地方公共団体コードAPIに渡すと、名前・読み・種類や、廃止されたコードなら今のコードへのたどり方が分かります。
アクセス数に上限はありますか?
決まった上限はありませんが、目安として1つの利用元から1秒あたり10回程度までにしてください。同じ住所の結果は、取ったものを使い回してください。
ご利用にあたって
ご利用の前に利用規約をご確認ください。データの正確さや、止まらないことは保証していません。正式な住所・郵便番号は、日本郵便の郵便番号検索や各市区町村の案内でご確認ください。ご質問・不具合のご連絡は、シルギアのお問い合わせ窓口から、件名に「API」と入れてお送りください。