郵便番号検索APIは、日本郵便が公開している郵便番号データを検索する機能をRESTで提供しています。
現在使用しているデータは、「2024年11月29日更新分の全国一括データ(加工済バージョン)」です。
» 全国一括データ(加工済バージョン)とは
ベースとなる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です。
レスポンスサンプル
エラーが発生した場合には、"status"フィールドに下記のエラーコードがセットされ、エラーの内容が"message"フィールドにセットされます。
エラーコード | 説明 |
---|---|
400 | 入力パラメータエラー |
500 | API内部で発生したエラー |
エラー発生時のサンプル
郵便番号検索APIを利用することにより利用規約の内容に同意いただいたものとみなされますので、利用規約の内容をよくお読みください。
利用規約に同意いただけない場合は、郵便番号検索APIを使用するライセンスは許諾されませんのでご注意ください。
» API利用規約