陽気に郵便番号検索 - 仕様

トップ | サンプル | AJAX Control Extender 対応 | 仕様 | ダウンロード | インストール | ライセンス | 購入

　
  1. 検索文字列
  2. JavaScriptインターフェイス仕様
    グローバル変数
    検索ダイアログ（YZipCodeLookup)
    自動補完クラス(YZipCodeAutoComplete)
  3. WebService（SOAP)
  4. 郵便番号XMLデータ
    郵便番号XMLデータ作成プログラム
  5. ブラウザ互換性

共通仕様

■検索文字列

検索の実行はLookupメソッドの呼び出しによって行います。検索キーワードは文字列で指定し、郵便番号、住所文字列の一部、読み仮名のいずれか が指定可能です。（事業所名での検索はできません）3種類の文字列種の違いは、メソッドの呼び出し時に自動的に判別されます。

郵便番号文字列：

半角および全角の数字（漢数字を除く）と半角と全角のハイフンまたは「ー」「−」から構成される文字列。桁数は任意ですが、7桁の場合には完全一致で検索が実行され、それ以外の場合は前方一致の郵便番号による検索と なります。

例） 123-4567,  1234567,  12-34567,  ９８７−６５４３, 98７-６５４３, １２３, １２３４５

住所文字列：

県名または、市町村名から始まる住所文字列。住所の構成要素は

[都道府県名] + [市区町村名] + [町域名] + [町域名詳細]

であるが、検索のキーワードとなる住所文字列では[都道府県名]が省略されていてもかまいません。また市区町村名に続く文字列が不完全である場合には、前方に一致する住所が検索され ます。

住所カナ文字列：

県名または市区町村名から始まる住所の読み仮名。構成要素は漢字による文字列と同様です。なお、読み仮名は全角または半角のカタカナ、または、全角ひらがなです。

検索結果文字列：

検索結果の1レコードは１文字列として返され、それぞれの項目は１つの文字列に次の規則で連結されます。なお、郵便番号は半角数字でハイフンを含まない形式で出力されます。いずれの場合も、結果文字列を取得後プログラムによって再度分解して用途に合った方法で使用されることを想定しています。

[郵便番号];[住所];[住所カナ];[事業所名];[事業所名カナ];[私書箱]

例） "1230865;東京都足立区新田;トウキョウトアダチクシンデン"　"1230864;東京都 足立区 鹿浜;トウキョウト アダチク シカハマ"

データによっては、住所カナなどの一部の文字列が不完全または、欠落しているデータも存在することに注意してください。 また、オリジナルの郵政公社のデータでは住所の読み仮名は半角カタカナです。

■JavaScript インターフェイス仕様

HTMLフォームへの組み込みに使われるJavaScriptオブジェクトについて解説します。陽気に郵便番号検索にはINPUTテキストボックスで自動補完のためのYZipCodeAutoCompleteというオブジェクトと、検索候補を別ウィンドウで選択させるための関数が用意されています。

JavaScriptソースファイル: YZipCodeJS.aspx

HTML内の<HEAD>内（あるいは<BODY>の先頭部分）に

<script language="javascript" src="YZipCodeJS.aspx"></script>

を記述します。古いブラウザでの誤動作、非互換性を気にする場合は

<script language="javascript1.2" src="YZipCodeJS.aspx"></script>

としてもよいでしょう.パッケージを配置したパスによっては、YZipCodeJS.aspxへの正しいパスを指定します。また、パッケージがコンテンツとは別のサーバーにインストールされた場合は src="http://...." とURLをフルに記述します.なお、設定するフォームがHTTPS（SSL)で暗号化されている場合は、srcによって指定したURLがHTTPだとブラウザが警告を出す場合があります.それを回避するには、パッケージを配置したサーバー自身もHTTPSで接続できる必要があります。

カスタマイズ可能なグローバル変数：

これらの変数への代入操作は YZipCodeJS.aspxを読み込んだ後、または、window.onloadイベントの処理中、YZipCodeAutoCompleteオブジェクトの初期化前に設定します。

例）

<script language="javascript" src="YZipCodeJS.aspx"></script>
<script language="javascript">
YZipCodeShowIndicator = false;
</script>

パラメータ名 デフォルト値 内容
YZipCodeAutoExpand false 自動補完機能が設定されたフォームに入力フォーカスがあるときに積極的に自動的に候補表示を行うかを設定します。サーバーとの通信が常に発生することから、遅いネットワークからの接続の負荷を考慮して true にすることをお勧めします。
YZipCodeShowIndicator true 自動補完機能動作中のインジケーターを表示する場合は true 表示しない場合は false
YZipCodeDelimiter "-" 郵便番号の区切り文字です。７桁の郵便番号を前３桁、後ろ４桁で分割しその間に文字を挟む場合に設定します。""を設定すると７桁すべてつながった形式で文字列がフォーマットされます。
YZipCodeMaxLatency 250 自動補完機能で候補の項目を表示するための処理時間の最大値を設定します。単位はms(ミリ秒)です。
候補住所データはバックグランドでサーバーとの間で通信されその間、ユーザーの操作が中断されることはありません。しかし、データが受信されてから候補を表示するまでの間データのHTML化 処理で短時間ユーザーの操作をさえぎることになります。大量の候補がある場合、ユーザーのCPUが遅い場合など長時間操作がロックされるとユーザーのストレスとなります。そのため、候補の書式を作成中にある時間経過してもまだデータがある場合は、書式化をそこで中断してその時間内で用意できた候補だけをユーザーに提示します。

関数: YZipCodeLookup  

function YZipCodeLookup( keyword, zipcodeControl, addressControl, addressKanaControl, addressPlaceControl, addressPlaceKanaControl, pobControl );

パッケージ： YZipCodeHelper.js

検索キーワードを元に 選択ダイアログ（別ウィンドウ）を開きユーザーの選択を受け付けます。ユーザーの選択結果は引数に指定されたコントロールへ文字列として挿入されます。

パラメータ：

パラメータ名 型 内容
keyword string 検索のキーとなる文字列。郵便番号、郵便番号の一部の文字列、住所、住所の一部の文字列
zipcodeControl string
control
array
null		 検索結果の郵便番号を書き込むコントロール。郵便番号が１つのINPUTコントロールの場合は、コントロール自身を、３桁＋４桁の２つに分かれる場合は２つのコントロールをArrayにしたArrayオブジェクトを指定する。getElementByIdで取得したコントロールそのものか、あるいは文字列で指定した場合は暗黙にコントロールIDとみなされます。
例1： "ZIP"
例２： document.getElementById("ZIP");
例３： new Array( "ZIP1", "ZIP2" )
addressControl string
control
array
null		 検索結果の住所文字列を書き込むコントロール。コントロールが県名とそれ以下に分割される場合はコントロールをArrayにしたものを渡す。県名部分のコントロールは <input type="text">または<select>でもよい。
例１： "ADDRESS"
例２： document.getElementById("ADDRESS");
例３： new Array( "PREFECTURE", "ADDRESS" );
addressKanaControl string
control
null		 検索結果の住所かなを書き込むコントロール
addressPlaceControl string
control
null		 検索結果の事業所名を書き込むコントロール
addressPlaceKanaControl string
control
null		 検索結果の事業所名かなを書き込むコントロール
pobControl string
control
null		 検索結果の事業所の私書箱を書き込むコントロール

オブジェクト： YZipCodeAutoComplete

function YZipCodeAutoComplete( oText, zipcodeControl, addressControl, addressKanaControl, addressPlaceControl, addressPlaceKanaControl, pobControl )

HTMLフォームのテキストコントロールに自動補完機能を付加する。YZipCodeAutoCompleteはオブジェクトとして使用され、通常は new によって作成されます。

例）
<script language="javascript" src="YZipCodeJS.aspx"></script>
<script language="javascript">
    new YZipCodeAutoComplete( "zipcode", "zipcode", "address" );
</script>

オブジェクトのプロパティを設定する必要がない場合は new で生成したオブジェクトは変数によって代入しないまま放置します.

コンストラクタパラメータ：

パラメータ名 型 内容
oText string
control
array		 検索のキーとなる文字列を持つテキストボックスINPUTコントロール 。２つのコントロールを指定する場合はコントロールを new Array(...)にしたもの。
zipcodeControl string
control
array
null		 検索結果の郵便番号を書き込むコントロール。郵便番号が１つのINPUTコントロールの場合は、コントロール自身を、３桁＋４桁の２つに分かれる場合は２つのコントロールをArrayにしたArrayオブジェクトを指定する。getElementByIdで取得したコントロールそのものか、あるいは文字列で指定した場合は暗黙にコントロールIDとみなされます。
例1： "ZIP"
例２： document.getElementById("ZIP");
例３： new Array( "ZIP1", "ZIP2" )
addressControl string
control
array
null		 検索結果の住所文字列を書き込むコントロール。コントロールが県名とそれ以下に分割される場合はコントロールをArrayにしたものを渡す。県名部分のコントロールは <input type="text">または<select>でもよい。
例１： document.getElementById("ADDRESS");
例２： new Array( document.getElementById("PREFECTURE"), document.getElementById("ADDRESS") );
addressKanaControl string
control
null		 検索結果の住所かなを書き込むコントロール
addressPlaceControl string
control
null		 検索結果の事業所名を書き込むコントロール
addressPlaceKanaControl string
control
null		 検索結果の事業所名かなを書き込むコントロール
pobControl string
control
null		 検索結果の事業所の私書箱を書き込むコントロール

■SOAP(Webサービス）

パッケージに含まれる YZipCode.asmx がASP.NETでいうウェブサービス（SOAP)のアドレスとなります。

YZipCodeWebService
LookupNextLevelAddress
検索キーワードに対して住所の次のレベルの候補を一覧します。ユーザーの県名から、市町村へと住所を入力する順序に合わせて次のレベルの候補を検索します。候補には必ずしも、郵便番号が決定できない住所も含まれます。
Lookup
検索キーワードに対して、可能なすべての住所を列挙します。列挙される住所はすべて、郵便番号が割り当てられたものになります。

WSDLは直接 YZipCode.asmxページをブラウザで開いて参照することができます。当サイトではこちらになります。

■郵便番号XMLデータベース

本システムでは、郵政公社から配布されている郵便番号データを加工することでプログラマが扱いやすいデータ形式に変換しています。以前のバージョンではデータをACCESSのデータファイルに持たせていましたが、昨今の技術動向と住所というデータの特殊性からXMLでデータを保持するのが最適だと判断しました。

XMLに関しては、その認知度が非常に高くなったことに加え、さまざまなプラットフォームでプログラミングのためのライブラリも充実しています。特定のOS、特定のデータベースに依存しないという点でも優れています。また、あとで述べるように、郵政公社からはいまだCSV形式でデータが提供され続けていますが、それよりも、住所とはXMLが表現する階層構造がぴったりのデータ構造であると いえます。

郵政公社の配布する郵便番号データ

全国の郵便番号は郵政公社から著作権フリーでCSV形式のデータが配布されています。データの更新も毎月のようにされており、郵便番号や住所を取り扱うソフトウェアの製作者は 頻繁にデータのアップデートに追従していかなければならないのは負担でもあります。

CSV形式であること自体は今の時代も問題になることはありません。CSVファイルは現在も異種プラットフォーム間のデータの移行形態として有効な手段です。ただ、郵政公社のCSVデータがそのままでは使えない理由がいくつかあります。

以上のような事情をふまえて、郵政公社配布のデータを一般的なプログラムから再利用しやすい形式に変換することにします。当然、住所データは頻繁に更新されるものであることから、手作業によって変換処理をすることはせけ変換用に用意したプログラムで一度に処理できるようにします。

XMLデータファイルの作成ポリシー

先に述べたようにいくつかの特徴的な点を踏まえてCSVファイルをXMLファイルとして作り直す方針は次のようになります。

XMLスキーマ

郵便番号XMLデータファイルのスキーマを公開します。

  <?xml version="1.0" encoding="utf-8" ?>
- <xs:schema xmlns="" xmlns:xs="http://www.w3.org/2001/XMLSchema">
- <xs:element name="area">
- <xs:complexType>
- <xs:sequence>
- <xs:element name="place" minOccurs="0" maxOccurs="unbounded">
- <xs:complexType>
  <xs:attribute name="jis-code" type="xs:string" />
  <xs:attribute name="name" type="xs:string" />
  <xs:attribute name="name-kana" type="xs:string" />
  <xs:attribute name="POB" type="xs:string" />
  </xs:complexType>
  </xs:element>
  <xs:element ref="area" minOccurs="0" maxOccurs="unbounded" />
  </xs:sequence>
  <xs:attribute name="name" type="xs:string" />
  <xs:attribute name="post-code" type="xs:string" />
  <xs:attribute name="post-code5" type="xs:string" />
  <xs:attribute name="name-kana" type="xs:string" />
  <xs:attribute name="local-entity-code" type="xs:string" />
  <xs:attribute name="date-created" type="xs:string" />
  <xs:attribute name="date-of-ken_all" type="xs:string" />
  <xs:attribute name="date-of-jigyosyo" type="xs:string" />
  </xs:complexType>
  </xs:element>
  </xs:schema>

　

郵政公社CSV => XML 変換プログラム

を一括して処理するためのコマンドライン実行ファイルです。

プログラム名 　
YZipCode.MakeXML.exe .NET 1.1/ .NET 2.0共通バイナリ
UNLHA32.DLL LZHファイル解凍ライブラリ。YZipCode.MakeXML.exeと同じディレクトリに配置するか、システムディレクトリにインストールします。
※UNLHA32.DLLは本パッケージ（有償版）に含まれていません。
別途入手してください。入手には次のアドレスを参照して下さい。http://www2.nsknet.or.jp/~micco/micindex.html

パラメータ解説

パラメータ名 　
（なし） デフォルト動作で、XML作成を実行します。
-xml <ファイルパス> 完成したPostCodeData.xmlファイルを指定したパス名でファイルコピーします。（デフォルト動作ではEXEファイルと同じディレクトリへ PostCodeData.xml ファイルを 作成します。）
-? ヘルプを表示します。
　 　

例）　YZipCode.MakeXML.exe -xml "c:\program files\yzipcode\PostCodeData.xml"

なお、YZipCode.MakeXML.exeのあるディレクトリはファイルのダウンロードの作業用としても使用されるため、実行される環境で、書き込み権限が必要です。

データの定期的な自動更新

郵政公社の郵便番号データは毎月のように更新されています。これに自動的に対応するためには、Windowsサーバーのタスクスケジューラ機能を使用します。 まずは、コマンドライン上で動作が正常なことを確認して、タスクスケジューラへ同じコマンドを登録します。このとき、登録する実行アカウントが、YZipCode.MakeXML.exeのあるディレクトリに適切な書き込み権限があるいことを確認して下さい。

XSLTによる検索

XMLに対する検索の手段は良く知られているとおり、SQLではなく、XPathです。したがって、検索自体は簡単なXPathで実行可能になります。この限りでは、検索機能は特定のプラットフォームに依存しないソリューションであるといえます。

XMLノードの検索はXPathひとつで簡単に実現はできますが、実際上要請されるのはさまざまな検索条件の元に、あるときは特定の１ノードを抜き出したり、あるときは、住所の一部の文字列などから複数の候補を抽出したりすることになるので、この処理には、データXML⇒検索結果XMLの変換処理、すなわち、XSL変換を用います。