RESTful Zip Search API Tutorial

目次

概要

この文書では、本サービスの 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の配列が返るので、それをチェックしていることに注意してください。