いつもNAVI CGI から API3.0へ切り替え

概要

基本的なWebAPIの使用方法には違いはありませんが、 入出力について互換性はありません。
ここでは、例としてsearchaddr.cgiをAPI3.0の代替機能のaddress/wordへ移行します。
その他のCGIとAPI3.0の機能比較はCGI機能比較表(excel)をご参照ください。
移行に関連する点は以下の3点です。
  1. 入力値
  2. 出力形式
  3. 出力値

入力値

使用方法はCGIと変わりませんが以下について変更する必要があります。

URI、ドメイン

CGIのURI
http://cgi.e-map.ne.jp(DOMAIN)/cgi/searchaddr.cgi?key=xxx&pos=1&cnt=10&enc=UTF8&tod=13&frewd=新橋&outf=XML

API3.0 WebAPIのURI
https://core.its-mo.com/zmaps/api/apicore/core/v1_0/address/word?if_clientid=JSZxxxxxxxxxx|xxxxx&if_auth_type=ip&word=新橋

ドメイン、指定可能なパラメータはAPI3.0に合わせて変更してください。

認証方式

API3.0の認証方式はip認証,oauth認証を利用できます。
API3.0の認証方式についてはAPI利用時の認証についてをご確認ください。
oauth認証の手順はOauth署名の生成手順をご確認ください。

キー設定

認証方式と認証キーの2つを指定する必要があります。

CGI必須パラメータ API3.0必須パラメータ 変更内容
key if_clientid キーを指定するパラメータ名が変更します。
- if_auth_type 認証方式を指定します。

CGIで発行したキーをAPI3.0の認証キーとしてお使いいただけません。
新規でAPI3.0用の認証キーの発行をお願い致します。

リクエストパラメータの指定方法に変更はありません。必須項目以外であれば、省略することが可能です。
省略されたパラメータはサーバ側でデフォルト値を適用し処理を行います。
通信方式はhttpsをご利用ください。

 

出力形式

出力形式のサンプルです。出力形式がTSV/XML からJSONに変わります。
TSVについては割愛します。
 

CGI(searchaddr.cgi):xml


<searchaddr>
    <status>
        <returncode>
          21000000
            </returncode>
        <reccount>2</reccount>
        <hitcount>2</hitcount>
    </status>
    <result>
    <item id="1">
         <address>
         東京都港区北青山
           </address>
        <lat>128379930</lat>
        <lon>502968330</lon>
       <addrcode>13103008</addrcode>
       <matchflg>1</matchflg>
       <addrflg>0</addrflg>
    </item>
    <item id="2">
         <address>
          東京都港区南青山
            </address>
         <lat>128383460</lat>
         <lon>502985530</lon>
        <addrcode>13103025</addrcode>
        <matchflg>1</matchflg>
        <addrflg>0</addrflg>
    </item>
    </result>
</searchaddr>

WebAPI(address/word):json


{
  "status":{"code":"0000","text":"OK"},
  "info":{"hit":202},
  "item":[
    {
      "text":"東京都港区北青山",
      "code":"13103008",
      "point":{
        "lat":35.6610917,
        "lon": 139.713425},
      "parts":["東京都","港区","北青山"],
      "kana":
"トウキヨウトミナトクキタアオヤマ",
      "zipcode":"107-0061",
      "end": false,
      "bounds":{
        "sw":{
          "lat": 35.6595872,
          "lon":139.7119789},
        "ne":{
          "lat":35.6758983,
          "lon":139.7273892}},
      "kanaParts":[
"トウキヨウト","ミナトク","キタアオヤマ"],
      "level":"oaz",
      "language":null},
    {
      "text":"東京都港区南青山",
      "code":"13103025",...
     "language":null } ]
}

出力キー

取得できる情報数、キー名は違います。
searchaddr.cgiとaddress/wordの対応表です。

searchaddr.cgi address/word 説明
status   status   ステータス情報
キー名に変更はありませんが、
返却値は異なります。
  returncode   code ステータスコード
コード内容が変更になります。
  -   text ステータステキスト
テキスト情報が出力されるようになります。
  reccount   - 取得レコード数
3.0にはありません。
    info   検索結果の情報
hitcountからhitに変更
  hitcount   hit ヒット件数
キー名が変更されています。
result/item   item   住所の配列
resultキーがなくなります。
  address   text 住所文字列
キー名が変更されています。
  addrcode   code 住所コード
キー名に変更があります。
      point 代表点緯度経度
pointオブジェクト内に格納されます。
  lat   point:lat 緯度
緯度が入ります。
  lon   point:lon 経度
経度が入ります。
      parts 住所名カナ
新しく追加されています。
      zipcode 郵便番号
新しく追加されています。
  matchflg   - 入力文字列の包含可否
3.0にはありません。
  addrflg   end 該当住所より下の階層があるか
キー名が変更されています。
      bounds 緯度経度矩形範囲
新しく追加されています。
      kanaParts 住所階層区切りの読み仮名
新しく追加されています。
  matchLevelName   level 住所階層コード
キー名が変更されています。
返却値が大文字→小文字に変更
mlflgを指定しなくても出力されるようになります。
      language 多言語情報
新しく追加されています。
※有料オプション

キー毎の詳細は該当のマニュアルページでご確認ください。

さいごに

他のWebAPIについては移行先のマニュアルページでご確認ください。

不明点、質問事項がある場合はこちらにお問い合わせください。