ジオどすⅡ API 解説

ジオどすⅡ・京都通り名ジオコーダＡＰＩ

「ジオどす I APIの解説」はこちら

●概要
「四条河原町上ル」「下ル」「東入ル」など、京都市内で広く使われている独特の住所表記「通り名住所」を緯度経度に変換（ジオコード）するAPIです。

●制限

• 通り名はその性質上、ある程度の範囲を表すもので、ジオどすⅡAPIはその範囲の中心点を便宜的に返すようになっています。
  そのため、店舗などの通り名住所からジオコードした緯度経度が、その店舗をピンポイントに示している保証はありません。あくまでも店舗の付近（実用上、十分近くですが）を指すことを念頭に置いてください。
• ジオどすⅡAPI単体では「京都の通り名」以外に対応していませんので、他社ジオコーダとの串刺し検索をご利用下さい。すぐに使えるサンプルコード等はこちらにあります。

●取得できるデータ

• 入力された通り名に対応する緯度経度
• 入力された通り名に対応するエリア（予測範囲）の矩形エリア。
• 通り名住所の　漢字表記、ひらがな表記（読み）、ローマ字表記

● リクエスト形式
GETまたはPOST

●URI
http://api.geodosu.com/v2/geodosu2?

●必須パラメータ
apikey　　　　　　登録時に発行するAPIキー文字列。全国ジオコーダ前処理APIのキーと共通です。こちらより登録（無料）ください。

address 　　　　　UTF8形式の住所をURLエンコードしたもの。住所は下記のものが使用できます。

• 日本語（漢字、ひらがな）、
• 英語（英語式住所表記、日本住所のローマ字）、
• 中国語（簡体字、繁体字）に対応します。(注：中国語対応は現在ベータ版です。)

●オプションパラメータ
datum

• wgs84(default) 世界測地系で返します
• tokyo 日本測地系で返します

format

• degree(default) 小数点付の度で返します
• dms 度/分/小数点付の秒　で返します

output

• xml(default) XMLで返す
• json json形式で返す

callback
　　output=jsonの時に指定するとJSONP 形式となります。コールバック関数の名前です。

preprocess
　　preprocess=trueの時、ジオコーダ前処理APIを同時実行し、その結果を含めます。

●レスポンス例

ジオどすⅡ全国・ジオコーダ前処理API

●概要
他社のジオコーダでジオコードする前に、住所文字列に以下の処理を行い、検出率をアップします。

• ビル名と思われる文字列を取り除きます。
• 「5丁目３番地」などを「5-3」のような半角数字とハイフンに置き換えます。
• 5番町など町名は「五番町」のように漢数字に直します。
• 京都市内の住所で、「通り名住所」と「郵便住所」が混合している場合、郵便住所のみに整形します。
  • 例 「京都市中京区寺町通御池上ル上本能寺前町488番地」⇒「京都市中京区上本能寺前町488番地」
• 京都市内の住所で、ひらがな、カタカナ、英語、中国語で表記されたものの場合、日本語漢字の郵便住所に変換します。（「ジオどすⅡ京都・通り名ジオコーダー」は郵便住所には対応していませんが）、この機能と組み合わせれば外国語表記された京都市内の郵便住所でも他社ジオコーダで検索できます。

●制限

• 住所の外国語表記を漢字の郵便住所に変換する機能は、京都市内の住所にのみ有効です。
• 住所の前処理をするとジオコーダの検出率は概ね向上しますが、これを保証するものではありません。
• 処理前の住所でジオコード、前処理後の住所でジオコード、ジオどすⅡの3つを組み合わせるとかなりカバーできる範囲が拡がります。すぐに使えるサンプルコード等はこちらにあります。

●取得できるデータ

• 入力された住所を前処理した住所

● リクエスト形式
GETまたはPOST

●URI
http://api.geodosu.com/v2/geo_pp?

●必須パラメータ
apikey　　　　　　登録時に発行するAPIキー文字列。京都通り名ジオコーダAPIのキーと共通です。こちらより登録（無料）ください。

address 　　　　　UTF8形式の住所をURLエンコードしたもの

●オプションパラメータ
output

• xml(default) XMLで返す
• json json形式で返す

callback
　　 output=jsonの時に指定するとJSONP 形式となります。コールバック関数の名前です。

●レスポンス例

ジオどすⅡAPI　すぐに使えるサンプル＆コード

1．グーグルマップスAPI(javascript)から使うライブラリ

グーグルマップスAPI（JavaScript ）をお使いの方に。グーグルマップスAPIのクライアント・ジオコーダにジオどすⅡAPIの機能をアドオンするライブラリを用意しました。

クライアントジオコーダ･オブジェクトのインスタンス生成部分を一箇所変更するだけで、GClientGeocoder.getLatLng()関数が京都の住所に対応します。
メソッドの仕様もそのままですので、既存のGppgleMapsAPIを使ったアプリケーションにほとんど手を加える必要がありません。
実装サンプルはこちら

使い方
i) javaScriptライブラリgclientgeocoder_geodosu2extension.jsを読込む。
<script src="http://api.geodosu.com/v2/gclientgeocoder_geodosu2extension.js?apikey={APIキー}"
type="text/javascript"></script>

ii) ジオコーダオブジェクトのインスタンス生成の際、GClientGeocoder()クラスの代わりにGClientGeocoderWithGeodosu()クラスを使用する
動作は京都の通り名に対応している以外全く変わりません。getLatLng()のみ対応しています。getLocation()には対応していません。

変更前　geocoder = new GClientGeocoder();
変更後　geocoder = new GClientGeocoderWithGeodosu(preprocessor);

パラメータ preprocessor:オプション。デフォルトはfalse。trueの時は、グーグルのジオコーダに渡す前に、ジオどすⅡジオコーダー前処理APIの処理を行います。

getLatLng()メソッドの動作：
１． オプション指定のある場合は、Googleのジオコーダに渡す住所文字列に前処理を行います。
２ ．先に本来の GClientGeocoder.getLatLng()を実行します。
３ ．結果がnullで返ってきたとき（検出失敗）は「ジオどす」で検索します。
４ ．結果を第二引数の関数に返します（失敗ならnull、成功ならGLatLngオブジェクト）

注）GoogleMapsAPIの利用規約内の利用しかできません。

2．ジオどすⅡAPIと他社ジオコーダとの串刺し検索をするサンプルPHPコード

ジオどすⅡAPIと他社のジオコーダを組み合わせると、ジオコーダを京都対応にすることができます。

注）利用するAPI（GoogleMapsAPI、Yahoo!ローカルサーチAPI）の利用規約の範囲内の利用しかできません。
各社ジオコーダの利用APIキーはご自身で取得し、サンプルファイル上部のPHP定数を書き換えてください。

リンク：
グーグルマップスAPI登録画面、グーグルマップスAPI利用規約

Yahoo!ディベロッパーネットワーク
アプリケーションID登録、Yahooディベロッパーネットワーク利用ガイド

使い方：
クラスファイルをダウンロード・解凍して、適当な場所に配置してください。

呼び出すコード (PHP)
//ライブラリの読込
require_once("geodosu2CascadeGeocoder_class.php");//ライブラリへのパスは環境に合わせて調整してください。

//串刺しジオコーダのインスタンスを生成します。利用するジオコーダのAPIキーを連想配列で指定してください。
//使えるのはgoogle, yahoo, geodosu2 の三つです。
$gcg = new geodosu2CascadeGeocoder(Array('google'=>'xxxxxxxxx', 'yahoo'=>'xxxxxxx',
'geodosu2'=>'xxxxxxxx' ));

//検索するジオコーダを指定して呼び出し。第三パラメータはジオコード前処理APIの実行の有無。trueで実行。
$res = $gcg->callGeocoders($searchaddress,'google,yahoo,geodosu2',true);

//ジオコード結果の表示
var_dump($res);

結果の例（var_dumpで出力した結果）

3．ジオコーダ・プロキを構成するサンプルPHPコード

既にYahoo!ローカルサーチAPI、またはGoogleMaps HTTP ジオコーダーAPI をお使いの場合、それぞれのAPIのInput/Output仕様そのままにジオどすⅡAPIの機能を組み込むサンプルコード（PHP)です。

このサンプルをご利用になられているサーバーに設置頂き、元のAPIを呼ぶリクエストのURIを（パラメータはそのままで）設置したURIに書き換えれば、既存のアプリケーションをすぐに京都対応にすることができます。
サンプルコードの先頭にジオどすⅡのAPIキーと、ジオコード前処理をする・しないを以下のように設定してください。

    $gpxy = new geodosu2GeocoderProxy('XXXXXXXX');//ジオどすⅡAPIキーセット
    $gpxy->geocoder_proxy(true);//住所の前処理を行う
    //$gpxy->geocoder_proxy(false);//住所の前処理を行わない

注）利用するAPI（GoogleMapsAPI、Yahoo!ローカルサーチAPI）の利用規約の範囲内の利用しかできません。
各社ジオコーダの利用APIキーはご自身で取得し、サンプルファイル上部のPHP定数を書き換えてください。

設置後のジオコード・プロキシの動作確認はこちらから行えます。

リンク
利用するジオコーダのAPIキーの取得、および利用契約はそれぞれ行ってください。
グーグルマップスAPI登録画面、グーグルマップスAPI利用規約

Yahoo!ディベロッパーネットワーク
アプリケーションID登録、Yahooディベロッパーネットワーク利用ガイド

このサンプルコードの動作
Yahoo!ローカルサーチへのプロキシにする
（[p]と[appid]のパラメータが存在すると、Yahoo!ローカルサーチへのプロキシとして動作します）

Yahoo!ローカルサーチへの本来のリクエストURI
http://map.yahooapis.jp/LocalSearchService/V1/LocalSearch?appid=XXXXXX&p=XXXXXX・・・・・・・・・・

Yahoo!ローカルサーチへのジオコーダー・プロキシにするには、引数部分はそのままで、
http://map.yahooapis.jp/LocalSearchService/V1/LocalSearch?appid=XXXXXX&p=XXXXXX・・・・・・・・・・

　 ↓
上記取り消し線の部分を設置したファイルに変更する
http;//【あなたがファイルを設置した場所 】/geodosu_geocoder_proxy.php?appid=XXXXXX&p=XXXXXX・・・・・・・・・・

動作
１．一旦受け取ったパラメータをそのままスルーして、Yahoo!ローカルサーチAPIへ転送します。
（前処理がONになっているときは、前処理後の住所を渡します）
２．Yahoo!結果にかかわらず、
キーワード検索、かつ、
検索対象に住所を含む、かつ
キーワードが「京都市」を含む
場合、「ジオどす」で検索
３．「ジオどす」で検索が成功している場合は、ローカルサーチが返す<Item>の先頭アイテムとして結果を挿入します。カテゴリは「address」精度は「5」としています。本来のItemは繰り下げます。引数「n」の個数制限がある場合、本来のレスポンスの最後のアイテムは押し出されて返されない場合があります。

Google HTTP ジオコーダへのプロキシにする
（[q]と[key]のパラメータが存在すると、Google HTTPジオコーダーへのプロキシとして動作します）

Yahoo!ローカルサーチへの本来のリクエストURI
http://maps/google.com/maps/geo?key=XXXXXX&q=XXXXXX・・・・・・・・・・

Yahoo!ローカルサーチへのジオコーダー・プロキシにするには、引数部分はそのままで、
http://maps/google.com/maps/geo?key=XXXXXX&q=XXXXXX・・・・・・・・・・
　 ↓
上記取り消し線の部分を設置したファイルに変更する
http;//【あなたがファイルを設置した場所 】/geodosu_geocoder_proxy.php?key=XXXXXX&q=XXXXXX・・・・・・・・・・

動作
１．一旦受け取ったパラメータをそのままスルーして、グーグルのHTTPジオコードサービスへ転送します。
（前処理がONになっているときは、前処理後の住所を渡します）
２．ジオコーディングが成功している場合は、そのままレスポンスをスルーして返します。
３．グーグルのジオコーダが検出失敗のとき、かつ「京都市」を検出したとき「ジオどす」で検出を試みます。
４．「ジオどす」でも検出に失敗した場合は２で受け取ったグーグルの失敗レスポンスをそのまま返します。
５．「ジオどす」で検出に成功した場合は、Googleの成功時のXML/JSON/KML/CSVのフォーマットをエミュレートして返します。