ZENRIN Maps API 郵便番号検索API - 仕様・実装・活用・UX向上ガイド

Last updated at 2025-07-10Posted at 2025-07-10

はじめに

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-urlencoded
- x-api-key: <あなたのAPIキー>
- 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の機能を実際にお試しいただけます！