目次
概要
この文書では、本サービスの API を利用する方法を示します。 JavaScript を使ったほとんど全ての例で、Ajax ライブラリとして jQuery を利用しています。
郵便番号から住所を取得
API の特徴をつかむためにまずは簡単なサンプルを見てみましょう。 郵便番号を入力して、対応する住所を表示するサンプルです。
注：エラー処理はコードの読みやすさの確保のため省略してあるので、実際にサイトに組み込む際にはご注意ください。
ソース
<script type="text/javascript">
// <!--
$(document).ready(function(){
$("#address1").ajaxStart(function(){
$(this).text("読み込み中…");
});
$("#form1").submit(function(e){
search($("#zip1").val());
return false;
});
function search(zip){
$.getJSON("http://zip.ricollab.jp/" + zip + ".json?callback=?",
function(json){
if (json.address == null) {
$("#address1").text("正しい郵便番号を入れてください");
} else {
$("#address1").text(json.address.prefecture +
json.address.city +
json.address.town);
}
}
);
}
// -->
</script>
<form id="form1" class="sample" action="">
<p>
<input type="text" id="zip1" value="1120002" />
<input type="submit" value="住所を取得" />
</p>
<div>住所: <span id="address1">ここに表示します</span></div>
</form>
$#getJSONメソッドで、郵便番号リソースを取得します。 ".json" 拡張子が付いているため、JSON 表現が取得できます。 "callback" パラメータを付けることで、クロスドメイン通信を行っています。
正しい7桁の郵便番号が入力されなかった場合は、 検索結果リソースにリダイレクトされ検索結果が返るので、 その場合は JSON の構造を見てエラーメッセージを出すようにします。
また、7桁の数字が入力されても存在する郵便番号ではない場合、エラーとして 404 Not Found が返るのでそれを見て表示をする必要がありますが、今回のサンプルでは省略してあります。
住所から郵便番号を検索
今度は逆に、住所から郵便番号を引いてみましょう。 この場合は検索結果リソースを利用します。
注：上で住所の検索をした場合、このサンプルにすでに「読み込み中...」と表示されています。リロードすれば正常に表示されますが、この現象を回避するコードは省略してあるため、実際にサイトに組み込む際にはご注意ください。
ソース
<script type="text/javascript">
// <!--
$(document).ready(function(){
$("#ziplist2").ajaxStart(function(){
$(this).html("<li>読み込み中…</li>");
});
$("#form2").submit(function(e){
search($("#zip2").val());
return false;
});
function search(q){
$.getJSON("http://zip.ricollab.jp/search?q=" + q +
"&type=json&callback=?",
function(json){
$("#ziplist2").empty();
if (json.result.length == 0) {
$("#ziplist2").html("<li>検索結果はありませんでした</li>");
} else {
$.each(json.result, function(i, item){
$("#ziplist2").append("<li><a href='" + item.link + "'>" +
item.zipcode + "</a></li>");
});
}
}
);
}
});
// -->
</script>
<form id="form2" class="sample" action="">
<p>
<input type="text" id="zip2" value="小石川" />
<input type="submit" value="郵便番号を検索" />
</p>
<ul id="ziplist2"><li>ここに表示します</li></ul>
</form>
検索結果が0件だったときは、長さ0の配列が返るので、それをチェックしていることに注意してください。