郵便番号・住所検索API Ver 1.0 マニュアル

API の利用

郵便番号・住所検索APIは、すぐにフォームに住所検索機能を組み込めるよう、オリジナルのユーザー・インタフェースをご用意しています。しかし、サイト・オーナー様によっては、独自のデザインや独自の機能を持ったユーザー・インタフェースを作りたい場合もあるでしょう。郵便番号・住所検索APIでは、名前の通り、住所検索用の API をご用意しております。所定のパラメータを付けて HTTP リクエストを送る方式(REST方式)によって、住所検索結果を JSON または XML フォーマットで取得することができます。

管理メニューの上にある「APIの利用」を使うと、どんなパラメータを指定すると、どのような結果が返ってくるのかを確認することができます。

APIの利用ボタン

「APIの利用」をクリックするとパラメータ選択フォームが表示されます。画面の説明に従って処理を進めてください。

リクエスト

API には、zip.cgi に対していくつかのパラメータを付けてリクエストします。

http://example.jp/zip/zip.cgi?format=json&code=utf8&kz=1&az=1&limit=10&offset=0&query=123
リクエスト URL の例

本画面には、パラメータを選択するためのフォームが用意されています。各パラメータの選択および入力をして、「リクエストURL確認」ボタンを押します。

パラメータ指定欄には、取得フォーマット、ページの文字コード、住所のカタカナの扱い、住所の英数字の扱いを選択するラジオボタンがあります。また、取得件数、取得開始オフセット、検索郵便番号を入力するテキスト入力フィールドがあります。選択および入力欄の下には「リクエストURL確認ボタンがあります。さらにその下にリクエストURLが表示されるテキストエリアがあります。

図:パラメータ指定欄

各パラメータの意味は、以下の通りです。

取得フォーマット

本 API が返す住所検索結果のフォーマットを、JSON フォーマット、XML フォーマットのいずれかから選択します。パラメータのキーは format です。値は、JSON フォーマットなら json、XML フォーマットなら xml です。

ページの文字コード

本 API が返す住所検索結果の文字コードを、UTF-8、Shift_JIS、EUC-JP のいずれかからら選択します。パラメータのキーは code です。値は、UTF-8 なら utf8、Shift_JIS なら sjis、EUC-JP なら euc です。

住所のカタカナの扱い

住所にカタカナが含まれる場合に、それを半角にするか全角にするのかを選択します。パラメータのキーは kz です。値は、半角なら 0、全角なら 1 です。

住所の英数字の扱い

住所に英数字が含まれる場合に、それを半角にするか全角にするのかを選択します。パラメータのキーは az です。値は、半角なら 0、全角なら 1 です。

取得件数

一度に取得できる住所の数を指定します。パラメータのキーは limit です。値は 1 ~ 100 までの半角数字です。

取得開始オフセット

検索結果のオフセット値を指定します。パラメータのキーは offset です。値は 0 ~ 100 までの半角数字です。

検索郵便番号

検索キーとなる郵便番号を指定します。パラメータのキーは query です。1 桁~ 7 桁の半角数字で指定してください。

各パラメータをセットしたら「リクエストURL確認」ボタンを押してください。その下にあるテキストエリアに、リクエスト URL が表示されます。

さらにその下にある「レスポンスの確認」欄にある「リクエスト送信」ボタンを押すと、実際に、そのリクエスト URL を使ってリクエストした結果を表示することができます。

レスポンス確認欄には「リクエスト送信」ボタンがあります。その下には、レスポンス結果を表示するテキストエリアがあります。さらにその下にはダウンロード・リンクが用意されています。

図:レスポンス確認欄

レスポンス・フォーマット

XML フォーマットの場合、ルート要素は zip となります。JSON フォーマットの場合は、ルートに相当するプロパティはありません。

いずれのフォーマットも、まず meta プロパティに各種メタ情報がハッシュ形式で格納されます。その次の addrs プロパティは、検索結果の個々のデータが配列形式で格納されます。

{
  "meta": {
    "query": "123",
    "hit": 33,
    "offset": 0,
    "limit": 10,
    "fetched": 10
  },
  "addrs": [
    {
      "offset": 0,
      "zc": "1230841",
      "z1": "123",
      "z2": "0841",
      "pc": "13",
      "pf": "東京都",
      "pfh": "とうきょうと",
      "pfk": "トウキョウト",
      "lc": "13121",
      "ct": "足立区",
      "cth": "あだちく",
      "ctk": "アダチク",
      "tw": "西新井",
      "twh": "にしあらい",
      "twk": "ニシアライ",
      "st": "",
      "og": "",
      "ogh": "",
      "ogk": ""
    },
    ...
  ]
}
JSON フォーマットの例
<?xml version="1.0" encoding="utf-8"?>
<zip>
  <meta>
    <query>123</query>
    <hit>33</hit>
    <offset>0</offset>
    <limit>10</limit>
    <fetched>10</fetched>
  </meta>
  <addrs>
    <addr>
      <offset>0</offset>
      <zc>1230841</zc>
      <z1>123</z1>
      <z2>0841</z2>
      <pc>13</pc>
      <pf>東京都</pf>
      <pfh>とうきょうと</pfh>
      <pfk>トウキョウト</pfk>
      <lc>13121</lc>
      <ct>足立区</ct>
      <cth>あだちく</cth>
      <ctk>アダチク</ctk>
      <tw>西新井</tw>
      <twh>にしあらい</twh>
      <twk>ニシアライ</twk>
      <st></st>
      <og></og>
      <ogh></ogh>
      <ogk></ogk>
    </addr>
    ...
  </addrs>
</zip>
XML フォーマットの例

各プロパティ(XML の場合は要素)と、その意味は、下表の通りです。

第一階層 第二階層 第三階層 説明 受信結果例
meta

検索結果のメタ情報を表します。この要素(またはプロパティ)は 1 回だけ現れます。

query

リクエスト時に送信した検索キーとなる郵便番号を表します。検索キーのうち数字以外の文字は除外されます。また全角数字は半角に変換されます。

1638
hit

検索にヒットした住所情報の総レコード数を表します。

24
offset

リクエスト時に送信したオフセット値を表します。半角数値で返します。

0
limit

リクエスト時に送信した検索取得個数を表します。半角数値で返します。

10
fetched

実際に取得した(このレスポンスに含まれている)住所情報のレコード数を表します。半角数値で返します。

10
addrs

検索結果はすべてこの要素(またはプロパティ)の中に格納されます。この要素(またはプロパティ)は 1 回だけ現れます。

addr

検索結果の 1 レコードを表します。取得された住所情報のレコード数だけ繰り返し現れます。

offset

該当レコードの検索キーに対するオフセット値を表します。例えば、リクエスト・パラメータ offset10 だった場合、その得られる結果の最初のレコードの offset10 となります。つまり 11 番目のレコードであることを意味します。

0
zc

該当レコードの郵便番号 7 桁を表します。ハイフンは含まれません。半角数値で返します。

1638001
z1

該当レコードの郵便番号上 3 桁を表します。半角数値で返します。

163
z2

該当レコードの郵便番号下 4 桁を表します。半角数値で返します。

8001
pc

該当レコードの都道府県コードを表します。半角数値で返します。

13
pf

該当レコードの都道府県名を表します。

東京都
pfh

該当レコードの都道府県名のひらがな表記を表します。

とうきょうと
pfk

該当レコードの都道府県名のカタカナ表記を表します。カタカナの全角・半角はリクエスト・パラメータ kz に依存します。

トウキョウト
lc

該当レコードの市区町村コードを表します。半角数値で返します。

13104
ct

該当レコードの市区町村名を表します。

新宿区
cth

該当レコードの市区町村名のひらがな表記を表します。

しんじゅくく
ctk

該当レコードの市区町村名カタカナ表記を表します。カタカナの全角・半角はリクエスト・パラメータ kz に依存します。

シンジュクク
tw

該当レコードの町域名を表します。カタカナの全角・半角はリクエスト・パラメータ kz に依存します。英数字の全角・半角はリクエスト・パラメータ az に依存します。

西新宿
twh

該当レコードの町域名のひらがな表記を表します。

にししんじゅく
twk

該当レコードの町域名のカタカナ表記を表します。カタカナの全角・半角はリクエスト・パラメータ kz に依存します。英数字の全角・半角はリクエスト・パラメータ az に依存します。

ニシシンジュク
st

該当レコードの番地を表します。このレコードは事業所の個別郵便番号に該当する住所の場合にのみセットされます。もし番地情報が存在しない場合は空文字列がセットされます。カタカナの全角・半角はリクエスト・パラメータ kz に依存します。英数字の全角・半角はリクエスト・パラメータ az に依存します。

2丁目8-1
og

該当レコードの事業所名を表します。このレコードは事業所の個別郵便番号に該当する住所の場合にのみセットされます。もし事業所名情報が存在しない場合は空文字列がセットされます。カタカナの全角・半角はリクエスト・パラメータ kz に依存します。英数字の全角・半角はリクエスト・パラメータ az に依存します。

東京都庁
ogh

該当レコードの事業所名のひらがな表記を表します。このレコードは事業所の個別郵便番号に該当する住所の場合にのみセットされます。もし事業所名情報が存在しない場合は空文字列がセットされます。英数字の全角・半角はリクエスト・パラメータ az に依存します。

とうきようとちよう
ogk

該当レコードの事業所名のカタカナ表記を表します。このレコードは事業所の個別郵便番号に該当する住所の場合にのみセットされます。もし事業所名情報が存在しない場合は空文字列がセットされます。カタカナの全角・半角はリクエスト・パラメータ kz に依存します。英数字の全角・半角はリクエスト・パラメータ az に依存します。

トウキヨウトチヨウ