郵便番号検索API

郵便番号検索APIとは

郵便番号検索APIは、日本郵便が公開している郵便番号データを検索する機能をRESTで提供しています。
現在使用しているデータは、「2024年10月31日更新分の全国一括データ（加工済バージョン）」です。

» 全国一括データ（加工済バージョン）とは

リクエストURL

ベースとなるURLは以下になります。

https://zipcloud.ibsnet.co.jp/api/search

このURLにリクエストパラメータを加え、リクエストを行います。

リクエストパラメータ

パラメータ名	項目名	必須	備考
zipcode	郵便番号	○	7桁の数字。ハイフン付きでも可。完全一致検索。
callback	コールバック関数名	-	JSONPとして出力する際のコールバック関数名。UTF-8でURLエンコードした文字列。
limit	最大件数	-	同一の郵便番号で複数件のデータが存在する場合に返される件数の上限値（数字）　※デフォルト：20

（例）郵便番号「7830060」で検索する場合
https://zipcloud.ibsnet.co.jp/api/search?zipcode=7830060

レスポンスフィールド

フィールド名		項目名	備考
status		ステータス	正常時は 200、エラー発生時にはエラーコードが返される。
message		メッセージ	エラー発生時に、エラーの内容が返される。
results	--- 検索結果が複数存在する場合は、以下の項目が配列として返される ---
	zipcode	郵便番号	7桁の郵便番号。ハイフンなし。
	prefcode	都道府県コード	JIS X 0401 に定められた2桁の都道府県コード。
	address1	都道府県名
	address2	市区町村名
	address3	町域名
	kana1	都道府県名カナ
	kana2	市区町村名カナ
	kana3	町域名カナ

※文字コードはUTF-8です。

レスポンスサンプル
{ "message": null, "results": [ { "address1": "北海道", "address2": "美唄市", "address3": "上美唄町協和", "kana1": "ﾎｯｶｲﾄﾞｳ", "kana2": "ﾋﾞﾊﾞｲｼ", "kana3": "ｶﾐﾋﾞﾊﾞｲﾁｮｳｷｮｳﾜ", "prefcode": "1", "zipcode": "0790177" }, { "address1": "北海道", "address2": "美唄市", "address3": "上美唄町南", "kana1": "ﾎｯｶｲﾄﾞｳ", "kana2": "ﾋﾞﾊﾞｲｼ", "kana3": "ｶﾐﾋﾞﾊﾞｲﾁｮｳﾐﾅﾐ", "prefcode": "1", "zipcode": "0790177" } ], "status": 200 }

エラー

エラーが発生した場合には、"status"フィールドに下記のエラーコードがセットされ、エラーの内容が"message"フィールドにセットされます。

エラーコード	説明
400	入力パラメータエラー
500	API内部で発生したエラー

エラー発生時のサンプル
{ "message": "必須パラメータが指定されていません。", "results": null, "status": 400 }

ライセンスについて

郵便番号検索APIを利用することにより利用規約の内容に同意いただいたものとみなされますので、利用規約の内容をよくお読みください。
利用規約に同意いただけない場合は、郵便番号検索APIを使用するライセンスは許諾されませんのでご注意ください。

» API利用規約