はじめに
ECサイトや会員登録フォームなど、多くのWebサービスで「郵便番号から住所を自動入力」する機能は、ユーザーの入力負担を減らし、入力ミスも防げる重要な仕組みです。
ZENRIN Maps APIの「search/postcode」エンドポイントは、郵便番号に関する多様な検索機能を提供しています。主な利用方法は以下の3つです。
-
郵便番号検索
- 入力された郵便番号やその一部から該当する住所情報を検索します
-
郵便番号リスト取得
- 住所コード（address_code）を指定して、該当する郵便番号情報を取得します
-
緯度経度検索
- 指定した中心座標や半径から、該当範囲内の郵便番号情報を検索します
どの利用方法を採用するかによって、送信するリクエストパラメータが異なります。本記事では、最も一般的な「郵便番号検索」の使い方を中心に解説します。
ZENRIN Maps API 2ヶ月無料お試しID
ZENRIN Maps APIを実際に試してみたい方は、2ヶ月無料のお試しIDをご利用いただけます！
📝 お申し込みはこちら
👉 ZENRIN Maps APIの始め方
お試し期間中は、本記事で紹介する機能をはじめ、ZENRIN Maps APIの豊富な機能をご利用いただけます。
「search/postcode」APIの特徴
- 郵便番号から都道府県・市区町村・町域まで、正規化された住所を取得
- 住所コードや緯度経度も同時に取得でき、地図連携や他API連携が容易
- サジェストやバリデーションと組み合わせてUXを大幅に向上できる
- 他のZENRIN Maps API（ac_premium, building_name等）と連携し、建物名・部屋番号まで自動補完も実現可能
API仕様
エンドポイント
GET/POST https://[domain]/search/postcode
Content-Type: application/x-www-form-urlencoded
主なリクエストパラメータ
| パラメータ名 | 型 | 必須 | 内容・例 |
|---|---|---|---|
| post_code | string | ○ *1 |
検索したい郵便番号（例: “100-0001”, “1000001”） |
| proximity | array[number] | *2 | 緯度経度・半径指定（例: [139.7,35.6,5000]） |
| address_code_list | array[string] | *3 | 住所コードリスト |
| pastmap_year | array[integer] | プレミアム機能：過去地図年指定 | |
| sort | array[string] | 並び順（例: post_code, address_code, address_read, distance など） | |
| limit | array[integer] | 取得範囲（例: [0,100]） | |
| datum | string | 座標系（JGD, TOKYO, TOKYO_NAVI） |
- 必須項目について
- *1: 「郵便番号検索」利用時に必須
- *2: 「緯度経度検索」利用時に指定
- *3: 「郵便番号リスト取得」利用時に指定
- ヘッダー例:
Content-Type: application/x-www-form-urlencodedx-api-key:Authorization: ip
レスポンスデータの構成
{
"status": "OK",
"result": {
"info": {
"hit": 10804
},
"item": [
{
"post_code": "100-0001",
"post_code_name": null,
"post_level": 1,
"post_type": 1,
"floor": null,
"address_code": "13101045",
"address": "",
"address_read": "",
"address_code1": "JPN",
"address1": "",
"address_read1": "",
"address_code2": "13",
"address2": "",
"address_read2": "",
"address_code3": "101",
"address3": "",
"address_read3": "",
"address_code4": "045",
"address4": "",
"address_read4": "",
"address_code5": null,
"address5": null,
"address_read5": null,
"address_detail_code1": null,
"address_detail1": null,
"address_detail_read1": null,
"address_detail_code2": null,
"address_detail2": null,
"address_detail_read2": null,
"position": [139.753946126302, 35.6837999131944],
"pastmap_id": null,
"pastmap_year": null,
"distance": null
}
// ...他の住所情報
]
}
}
各項目の説明
| フィールド名 | 型 | 説明 |
|---|---|---|
| status | string | レスポンスステータス（例: “OK”） |
| result.info.hit | integer | ヒット件数（該当する住所情報の総数） |
| result.item | array | 住所情報の配列 |
| post_code | string | 郵便番号（例: “100-0001″） |
| post_code_name | string/null | 郵便番号名称（未使用の場合null） |
| post_level | integer | 郵便番号レベル（1:大口事業所, 2:町域, 3:小字等） |
| post_type | integer | 郵便番号種別（1:通常, 2:大口, 3:事業所, 4:その他, 9999:不明） |
| floor | string/null | 建物階層情報（該当時のみ） |
| address_code | string | 住所コード |
| address | string | 住所（都道府県・市区町村・町名など） |
| address_read | string | 住所の読み仮名 |
| address_code1〜5 | string/null | 階層ごとの住所コード（国/都道府県/市区町村/町域/丁目等） |
| address1〜5 | string/null | 階層ごとの住所 |
| address_read1〜5 | string/null | 階層ごとの住所読み仮名 |
| address_detail_code1/2 | string/null | 詳細住所コード |
| address_detail1/2 | string/null | 詳細住所 |
| address_detail_read1/2 | string/null | 詳細住所読み仮名 |
| position | array[number] | 緯度・経度（[経度, 緯度]） |
| pastmap_id | integer/null | 過去地図ID（プレミアム機能） |
| pastmap_year | integer/null | 過去地図年（プレミアム機能） |
| distance | number/null | 検索中心からの距離（proximity指定時） |
実装例
JavaScript（fetch）によるリクエスト例
const apiPath = 'https://test-web.zmaps-api.com/search/postcode';
const apiParams = {
post_code: '108-0023',
sort: 'address_code',
};
const queryString = new URLSearchParams(apiParams).toString();
const header = {
'Content-Type': 'application/x-www-form-urlencoded',
'x-api-key': 'あなたのAPIキー',
'Authorization': 'ip',
};
fetch(`${apiPath}?${queryString}`, {
method: 'GET',
headers: header,
})
.then(res => res.json())
.then(data => {
// 住所情報を取得
console.log(data.result.item);
});
Vue.jsを使った住所自動入力例
const getAddressesFromPostCode = async () => {
if (!state.form.post_code || state.form.post_code.length 7) return;
const apiPath = state.api.domain + state.api.postcode.path;
const apiParams = state.api.postcode.params;
apiParams.post_code = state.form.post_code;
const queryString = new URLSearchParams(apiParams).toString();
const header = state.api.header;
header['x-api-key'] = state.api.key;
try {
const response = await fetch(apiPath + '?' + queryString, { headers: header });
const result = await response.json();
if(result.result.item.length === 1) {
// APIの戻り値から得られた住所をフォームに設定
state.form.address = result.result.item[0].address;
}
} catch (error) {
console.log('[error]getAddressesFromPostCode:', error);
}
};
運用・UXのポイント
- 郵便番号入力時に自動でハイフンを補完（例: 1080023 → 108-0023）
- 7桁未満やハイフンなしの場合はバリデーションや補完処理を推奨
- 住所欄は自動入力後にユーザーによる編集を可能にすると便利
- 住所コードや緯度経度を活用し、地図表示や建物名補完APIと連携も可能
導入のメリット
ユーザーにとってのメリット
- 入力の手間が大幅に削減
- 住所の入力ミスが減少
- 正確な住所情報を簡単に入力
サービス提供者にとってのメリット
- 住所データの精度向上
- 不正確な住所による配送トラブルの減少
- ユーザー離脱率の低下
- 顧客体験の向上
まとめ
ZENRIN Maps APIの郵便番号検索APIを使えば、郵便番号から正確な住所を簡単に取得できます。
フロントエンドフレームワークと組み合わせることで、ユーザー体験の良い住所入力フォームを実現できます。
- 郵便番号入力→API呼び出し→住所自動入力
- サジェストやバリデーションでUX向上
- 住所コードや緯度経度を活用し建物名・部屋番号まで自動補完も可能
ECサイトや会員登録フォームなど、正確な住所入力が求められる場面でぜひ活用してください！
ZENRIN Maps API 2ヶ月無料お試しIDのご案内
本記事でご紹介したZENRIN Maps APIの機能を実際にお試しいただけます！
📝 お申し込みはこちら
👉 ZENRIN Maps APIの始め方
お試し期間中は、ZENRIN Maps APIの豊富な機能をご利用いただけるので、本格導入前の検証にぜひご活用ください。
関連記事
※本記事で使用しているAPIキーやURLはサンプルです。実際の導入時には、公式サイトから取得した正式なAPIキーを使用してください。
Views: 0
