RESTful Zip Search API Specification

目次

概要

この文書では ricollab で提供している郵便番号検索サービスの API 仕様について解説します。主に API を利用するプログラマの方を対象としています。

この API は本サービスで提供している郵便番号情報にブラウザやプログラムからアクセスするためのインターフェースです。この API を利用することで、郵便番号から住所を引いたり、住所の一部から郵便番号を検索することができます。

本 API の特徴は以下のとおりです。

  • RESTful な URI/API 設計
  • 人間にもプログラムにも可読なフォーマットとしての XHTML の採用
  • クロスドメイン対応の JSON/JSONP API

リソース

このサービスでは以下の2種類のリソースを提供します。

郵便番号リソース
"1120002" のように、一つの郵便番号に対応するリソースです
リストリソース
複数の郵便番号リソースへのリンクが含まれるリソースです。以下の二つのリソースに分類できます
検索結果リソース
「大手町を含む住所一覧」「"11200"で始まる郵便番号一覧」などのように、特定のキーワードにマッチする郵便番号の検索結果を表現するリソースです
地域リソース
「東京都」や「沖縄県那覇市」などに対応するリソースです。その地域に含まれる、下位の地域リソースまたは郵便番号リソースへのリンクのリストです
表1 リソース一覧
リソース名URIHTTP メソッド
郵便番号リソースhttp://zip.ricollab.jp/{郵便番号}GET, HEAD, OPTIONS
検索結果リソースhttp://zip.ricollab.jp/search?q={検索キーワード}GET, HEAD, OPTIONS
地域リソースhttp://zip.ricollab.jp/{県名}/{市区町村名}/{町域名}GET, HEAD, OPTIONS

各リソースの URI、リソースの表現とその構造、適用可能な HTTP メソッドについてはこのあとに詳細な解説があります。

各リソース間のリンク関係を図に示します。

リンク関係

JSON/JSONP 表現には必要最低限のリンクが入っています。XHTML には、より豊富なリンクが入っています。どちらの表現を利用する場合でも、リソース間を移動するときはリンクを辿るようにしてください。

URI

各リソースは以下のような URI を持ちます。

郵便番号リソース

http://zip.ricollab.jp/{郵便番号}

郵便番号パラメータは 7桁の数字と3桁の数字と"-"と4桁の数字を連結した文字列の両者に対応します。リソースの正式な URI は 7桁の数字ですので、"-" 付きの URI は 301 Moved Permanently でリダイレクトされます。また、UTF-8 で %エンコードされた(いわゆる)全角数字の場合も同様にリダイレクトされます

検索結果リソース

http://zip.ricollab.jp/search?q={キーワード}

キーワードは UTF-8 で%エンコーディングされなければなりません。検索結果リソースは q 以外のパラメータを持つこともできます。各パラメータの詳細は後述します。

地域リソース

http://zip.ricollab.jp/{県名}

http://zip.ricollab.jp/{県名}/{市区町村名}

http://zip.ricollab.jp/{県名}/{市区町村名}/{町域名}

県名、市区町村名、町域名をそれぞれ UTF-8 で %エンコーディングした文字列を階層化した URI です。

ここで、市区町村名には東京の23区や政令指定都市の区までが含まれます。

JSON/JSONP 用 URI パラメータ

全てのリソースは JSON/JSONP 表現を持ちます。 JSON/JSONP 表現を取得するためには、以下のパラメータが必要になります。

".json" 拡張子

郵便番号リソースの末尾に ".json" という拡張子を付与した URI は、そのリソースの JSON 表現になります。検索結果リソースの場合は type パラメータ(後述)を利用します

http://zip.ricollab.jp/1120002.json

地域リソースの場合も URI の末尾に ".json" を付けることで、JSON 表現を取得できます

http://zip.ricollab.jp/東京都/文京区.json

callback クエリパラメータ

".json" 拡張子を付与した URI に callback クエリパラメータを指定すると、callback パラメータの値を関数名に持つ JSONP 表現が取得できます

http://zip.ricollab.jp/1120002.json?callback=foobar

http://zip.ricollab.jp/東京都/文京区.json?callback=foobar

検索結果リソースは、以下のクエリパラメータを付与することで検索結果をカスタマイズすることが可能です。必須のパラメータは "q" のみです。検索キーワード以外の全てのパラメータおよび値は小文字でなければなりません。

q={検索キーワード}
検索キーワードが入ります。指定できる文字列は郵便番号、住所、事業者名の一部です。and や or 検索はできません
count={整数値}
1ページに表示する件数を指定します。デフォルトは10件です
page={整数値}
表示するページを指定します。デフォルトは1ページです
type={json｜html}
表現形式を指定します。JSON形式(json) または XHTML形式(html) が指定できます。デフォルトは html です
callback={コールバック関数名}
type=json のときにこのパラメータを指定すると、callback パラメータの値を関数名に持つ JSONP 表現が取得できます
sort={town｜yomi｜zipcode}
表示順を決めるキーを指定します: デフォルトは town (地域、事業者別に郵便ホームページウェブサイトにより配布されているデータの順)です
order={desc｜asc}
ソート時の降順か昇順かを指定します。デフォルトはasc(昇順)になります。

表現

このサービスで提供するリソースは、以下の3種類の表現を持ちます。

XHTML

Media Type: application/xhtml+xml; charset=utf-8

標準的な Web ブラウザで表示することのできる形式です。ブラウザで表示させることが可能なので、人間が読みやすいのが特徴です。この表現は整形式の XML であるため、XML パーサーでパースして、プログラムから扱うことも可能です。住所の構造情報は class 属性で表現されています。全てのリソースのデフォルト表現になっています。

この表現は妥当な XHTML 1.1 になるはずですが、あえて DOCTYPE 宣言は付けていません。文字エンコーディングスキームは UTF-8 です。

JSON

Media Type: application/json; charset=utf-8

RFC 4627 形式の表現です。XHTML よりも軽いフォーマットで、プログラムからのアクセスに適しています。文字エンコーディングスキームは UTF-8 です。

JSONP

Media Type: application/json; charset=utf-8

JSON 表現の URI にコールバック関数名を付けると JSONP 表現になります。この表現を利用すると、zip.ricollab.jp 以外の Web サイトとのクロスドメイン通信を行えるようになります。文字エンコーディングスキームは UTF-8 です。

リソースの構造

郵便番号リソース

郵便番号リソースは以下の情報を持ちます。

  • 郵便番号(zipcode)
  • 住所(address)
    • 県名
    • 市区町村名
    • 町域名
  • 住所の「ヨミ」(yomi)
    • 県名のヨミ
    • 市区町村名のヨミ
    • 町域名のヨミ

XHTML 表現

XHTMLでは郵便番号リソースを以下のように表現します。

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="ja">
  <head>
    <title>〒112-0002</title>
  </head>
  <body>
    <h1>〒112-0002</h1>
    <dl>
      <dt>番号</dt>
      <dd class="zipcode">1120002</dd>
      <dt>住所</dt>
      <dd class="address">
        <a href="/東京都" class="prefecture">東京都</a>
        <a href="/東京都/文京区" class="city">文京区</a>
        <a href="/東京都/文京区/小石川" class="town">小石川</a>
      </dd>
      <dt>フリガナ</dt>
      <dd class="yomi">
        <span class="prefecture">トウキョウト</span>
        <span class="city">ブンキョウク</span>
        <span class="town">コイシカワ</span>
      </dd>
    </dl>
  </body>
</html>

各要素・属性の定義は以下のとおりです。

/html/head/title, /html/body/h1
「〒」に続けて郵便番号が "-" 付きで入ります
例: 〒112-0002
/html/body/dl
郵便番号情報はこの定義リストに入ります
dt
dt には、その直後に出現する dd 要素の内容を説明する文字列が日本語で入ります
dd[class="zipcode"]
郵便番号が "-" なしで入ります
例: 1120002
dd[class="address"]/a[class="prefecture"]
県名が、対応する地域リソースへのリンク付きで入ります
例: <a href="/東京都" class="prefecture">東京都</a>
dd[class="address"]/a[class="city"]
市区町村名が、対応する地域リソースへのリンク付きで入ります
例: <a href="/東京都/文京区" class="city">文京区</a>
dd[class="address"]/a[class="town"]
町域名が、対応する地域リソースへのリンク付きで入ります
例: <a href="/東京都/文京区/小石川" class="town">小石川</a>
dd[class="yomi"]/span[class="prefecture"]
県名のヨミが入ります
例: トウキョウト
dd[class="yomi"]/span[class="city"]
市区町村名のヨミが入ります
例: ブンキョウク
dd[class="yomi"]/span[class="town"]
町域名のヨミが入ります
例: コイシカワ

JSON/JSONP 表現

JSON では郵便番号リソースを以下のように表現します。

{
 "zipcode": "1120002",
 "address": {
   "prefecture": "東京都",
   "city": "文京区",
   "town": "小石川"
 },
 "yomi":  {
   "prefecture": "トウキョウト",
   "city": "ブンキョウク",
   "town": "コイシカワ"
 }
}

各プロパティの定義は以下のとおりです。

zipcode
郵便番号が "-" なしで入ります
例: 1120002
address
住所情報の構造体です
address.prefecture
県名が入ります
例: 東京都
address.city
市区町村名が入ります
例: 文京区
address.town
町域名が入ります
例: 小石川
yomi.prefecture
県名のヨミが入ります
例: トウキョウト
yomi.city
市区町村名のヨミが入ります
例: ブンキョウク
yomi.town
町域名のヨミが入ります
例: コイシカワ

検索結果リソース

検索結果リソースは以下の情報を持ちます。

  • キーワード(query)
  • 検索結果総数(totalResults)
  • 1ページに含まれる検索結果数(itemsPerPage)
  • 次のページの URI(next)
  • 前のページの URI(prev)
  • 郵便番号リソースへのリンクのリスト(result)
    • 郵便番号(zipcode)
    • 住所(address)
    • 郵便番号リソースへのリンク(link)

XHTML 表現

XHTML では検索結果リソースを以下のように表現します。

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="ja">
 <head>
   <title>「112」の検索結果</title>
 </head>
 <body>
   <h1>「<span class="query">112</span>」の検索結果</h1>
   <p><span class="totalResults"
        >101</span>件中1件目から<span class="itemsPerPage"
        >10</span>件</p>
   <ul class="result">
     <li>
       <span class="zipcode">1120000</span>
       <a href="http://zip.ricollab.jp/1120000" class="address">東京都文京区以下に掲載がない場合</a>
     </li>
     <li>
       <span class="zipcode">1120001</span>
       <a href="http://zip.ricollab.jp/1120001" class="address">東京都文京区白山（２〜５丁目）</a>
     </li>
     ...
     <li>
       <span class="zipcode">1120013</span>
       <a href="http://zip.ricollab.jp/1120013" class="address">東京都文京区音羽</a>
     </li>
   </ul>
   <p><a href="http://zip.ricollab.jp/search?q=112&page=2" rel="next">次へ</a></p>
 </body>
</html>

各要素・属性の定義は以下のとおりです。

span[class="query"]
検索キーワードが入ります
例: 112
span[class="totalResults"]
検索結果総数が入ります
例: 101
span[class="itemsPerPage"]
各ページあたりに含まれる最大検索結果数が入ります。最後のページにはこの値に満たない検索結果しか含まれない可能性がありますが、その場合でもここには最大値が入ります。そのページに含まれている検索結果数は、XHTML のリストの子要素の数で判断してください
例: 10
a[rel="next"]
次の検索結果へのリンクが入ります。次がない場合はこのプロパティは含まれません
a[rel="prev"]
前の検索結果へのリンクが入ります。前がない場合はこのプロパティは含まれません
ul[class="result"]
検索結果のリストです
ul[class="result"]/li/span[class="zipcode"]
郵便番号が入ります
例: 1120002
ul[class="result"]/li/a[class="address"]
住所が入ります
例: 東京都文京区小石川
ul[class="result"]/li/a[class="address"]/@href
郵便番号リソースの URI が入ります
例: http://zip.ricollab.jp/1120002

JSON/JSONP 表現

JSON では検索結果リソースを以下のように表現します。

{
  "query": "112",
  "totalResults": 101,
  "itemsPerPage": 10,
  "next": "http://zip.ricollab.jp/search?q=112&type=json&page=2",
  "result": [{
    "zipcode": "1120000",
    "address": "東京都文京区以下に掲載がない場合",
    "link": "http://zip.ricollab.jp/1120000"
  },
  {
    "zipcode": "1120001",
    "address": "東京都文京区白山（２〜５丁目）",
    "link": "http://zip.ricollab.jp/1120001"
  },
  ...
  {
    "zipcode": "1120013",
    "address": "東京都文京区音羽",
    "link": "http://zip.ricollab.jp/1120013"
  }]
}

各プロパティの定義は以下のとおりです。

query
検索キーワードが入ります
例: 112
totalResults
検索結果総数が入ります
例: 101
itemsPerPage
各ページあたりに含まれる最大検索結果数が入ります。最後のページにはこの値に満たない検索結果しか含まれない可能性がありますが、その場合でもここには最大値が入ります。そのページに含まれている検索結果数は、JSON の配列の要素数で判断してください
例: 10
next
次の検索結果へのリンクが入ります。次がない場合はこのプロパティは含まれません
prev
前の検索結果へのリンクが入ります。前がない場合はこのプロパティは含まれません
result
検索結果の配列です
result[n].zipcode
郵便番号が入ります
例: 1120002
result[n].address
住所が入ります
例: 東京都文京区小石川
result[n].link
郵便番号リソースの URI が入ります
例: http://zip.ricollab.jp/1120002

地域リソース

地域リソースは以下の情報を持ちます。

  • 地域情報(area)
    • 県名(prefecture)
    • 市区町村名(city)
    • 町域名(town)
  • 下位の地域リソースのリスト。町域リソースの場合は郵便番号リソースのリストになる
    • 名前(name)
    • ヨミ(yomi)
    • リソースの URI (link)

XHTML 表現

XHTML では地域リソースを以下のように表現します。

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="ja">
 <head>
   <title>東京都の一覧</title>
 </head>
 <body>
   <h1 class="area"><span class="prefecture">東京都</span>の一覧</h1>
   <ul class="result">
     <li>
       <a href="/東京都/千代田区" class="name">千代田区</a>
       (<span class="yomi">チヨダク</span>)
     </li>
     <li>
       <a href="/東京都/中央区" class="name">中央区</a>
       (<span class="yomi">チュウオウク</span>)
     </li>
     ...
     <li>
       <a href="/東京都/小笠原村" class="name">小笠原村</a>
       (<span class="yomi">オガサワラムラ</span>)
     </li>
   </ul>
 </body>
</html>

各要素・属性の定義は以下のとおりです。

h1[class="area"]/span[class="prefecture"]
このリソースの県名が入ります
例: 東京都
h1[class="area"]/span[class="city"]
このリソースの市区町村名が入ります。県までしか選択されていない場合は省略されます
例: 文京区
h1[class="area"]/span[class="town"]
このリソースの町域名が入ります。市区町村までしか選択されていない場合は省略されます
例: 小石川
ul[class="result"]
この地域リソースに含まれる地域リソースのリストです。町域リソースの場合は郵便番号リソースのリストになります
ul[class="result"]/a[class="name"]
地域リソースの名前です。町域リソースの場合は郵便番号リソースの住所になります
例: 文京区
ul[class="result"]/span[class="yomi"]
地域リソースのヨミです。町域リソースの場合は郵便番号リソースの住所のヨミになります
例: ブンキョウク
ul[class="result"]/a[class="name"]/@href
地域リソースの URI です。町域リソースの場合は郵便番号リソースの URI になります
例: http://zip.ricollab.jp/東京都/文京区
例: http://zip.ricollab.jp/1120002

JSON/JSONP 表現

JSON では地域リソースを以下のように表現します。

{
  "area": {
    "prefecture": "東京都"
  },
  "result": [{
    "name": "千代田区",
    "yomi": "チヨダク",
    "link": "http://zip.ricollab.jp/東京都/千代田区.json"
  },
  {
    "name": "中央区",
    "yomi": "チュウオウク",
    "link": "http://zip.ricollab.jp/東京都/中央区.json"
  },
  ...
  {
    "name": "小笠原村",
    "yomi": "オガサワラムラ",
    "link": "http://zip.ricollab.jp/東京都/小笠原村.json"
  }]
}

各プロパティの定義は以下のとおりです。

area.prefecture
このリソースの県名が入ります
例: 東京都
area.city
このリソースの市区町村名が入ります。県までしか選択されていない場合は省略されます
例: 文京区
area.town
このリソースの町域名が入ります。市区町村までしか選択されていない場合は省略されます
例: 小石川
result
この地域リソースに含まれる地域リソースの配列です。町リソースの場合は郵便番号リソースの配列になります
result[n].name
地域リソースの名前です。町リソースの場合は郵便番号リソースの住所になります
例: 文京区
result[n].yomi
地域リソースのヨミです。町リソースの場合は郵便番号リソースの住所のヨミになります
例: ブンキョウク
result[n].link
地域リソースの URI です。町リソースの場合は郵便番号リソースの URI になります
例: http://zip.ricollab.jp/東京都/文京区
例: http://zip.ricollab.jp/1120002

HTTP メソッド

全てのリソースは以下の三つの HTTP メソッドに応答します。以下のメソッド以外の場合は 405 Method Not Allowed が返ります。

GET

リソースのその時点での最新表現を取得します。

GET /1120002.json HTTP/1.1
Host: zip.ricollab.jp


HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Etag: "46506c4d607a60c78b256c1c22490674"

{
 "zipcode": "1120002",
 "address": {
   "prefecture": "東京都",
   "city": "文京区",
   "town": "小石川"
 },
 "yomi":  {
   "prefecture": "トウキョウト",
   "city": "ブンキョウク",
   "town": "コイシカワ"
 }
}

レスポンスに含まれる ETag の値を If-Non-Match に入れて、 条件付き GET を発行することも可能です。 この場合、ステータスコード 304 Not Modified が返ります。

GET /1120002.json HTTP/1.1
Host: zip.ricollab.jp
If-None-Match: "46506c4d607a60c78b256c1c22490674"


HTTP/1.1 304 Not Modified
Content-Type: application/json; charset=utf-8
Etag: "46506c4d607a60c78b256c1c22490674"

HEAD

リソースのその時点でのメタデータ(HTTP ヘッダ)のみを取得します。

HEAD /1120002.json HTTP/1.1
Host: zip.ricollab.jp


HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Etag: "46506c4d607a60c78b256c1c22490674"

OPTIONS

リソースに適用できる HTTP メソッドのリストを Allow ヘッダで返します。

OPTIONS /1120002.json HTTP/1.1
Host: zip.ricollab.jp


HTTP/1.1 200 OK
Allow: GET, HEAD

エラーケース

クライアントからの要求に何らかの形で正常に返答できない場合は 4xx または 5xx 台の HTTP ステータスコードが返ります。本サービスのクライアントは HTTP 1.1 で定められたいかなるステータスコードにも対応できるように作成されるべきです。以下ではクライアント作成者の便宜のために、代表的なエラーケースを列挙します。

存在しない URI を指定した
404 Not Found
例: http://zip.ricollab.jp/1234567
必須パラメータが指定されていない
400 BadRequest
例: http://zip.ricollab.jp/search?count=10
サポートしない HTTP メソッドを使用した
405 Method Not Allowed
例: DELETE http://zip.ricollab.jp/1120002 HTTP/1.1