TOP | TOOL | API | MAP

PlaceEngine API ローカルアプリケーションプログラミング

PlaceEngineをWebサービスとしてではなく、ローカルアプリケーションから直接利用するための機能です。現状ではとくにライブラリは提供していません。以下では java を使った例を示しますが、他のプログラム言語からでも同様に利用することが可能です。

全体の流れ

ローカルアプリケーションを利用する際にも、電測用にPlaceEngineクライアントを起動して下さい。PlaceEngineクライアントとはHTTPプロトコル経由で通信することができます。位置情報取得は、

• PlaceEngineクライアント(http://localhost:5448)から電測情報を取得し、
• それをPlaceEngineサーバー(http://www.placeengine.com)に送信して位置情報を得る

という流れになります。

アプリケーションキーの取得

PlaceEngineクライアントおよびPlaceEngineサーバーを利用するために、アプリケーションキーが必要です。

PlaceEngine連携サイト用アプリケーションキー取得ページ で、アプリケーションキーを取得して下さい。URLの欄にはローカルアプリケーションの実行イメージ名を入れて下さい。たとえば abcd.exe なら abcd を。Javaプログラムの場合は、java (javawで実行する場合はjavaw) を指定して下さい。

プログラム例1 : Hello Location in Java

実行すると、現在位置を標準出力に書き出すだけのjavaプログラムです ( ソースコード ) (プログラムを簡略化するためにエラー処理を省いています)。

import java.net.*;
import java.io.*;
import java.util.*;

/** 
 *   PlaceEngine API Sample    
 */
public class PeTest {
    public static final String appk = "......";   //アプリケーションキー

    /** HTTPリクエストを発行し、レスポンスを文字列で返す **/
    public static String getURL(String urlstr) throws MalformedURLException, ProtocolException, IOException { 
	URL url = new URL(urlstr);
	HttpURLConnection urlc = (HttpURLConnection)url.openConnection();
	urlc.connect();
	BufferedReader reader = new BufferedReader(new InputStreamReader(urlc.getInputStream(), "UTF-8"));
	String s = "";
	for (String line = null; (line = reader.readLine()) != null; ) {
	    s += line;
	}
	reader.close();
	urlc.disconnect();
	return s;
    }

    /** locリクエストのリターン値(json形式)を分析 **/
    public static void printInfo(String s) {
	s = s.substring(1,s.length()-1);
	String param[] = s.split(",");
	String param2[] = s.split("\\{");

	if (param.length >= 4 && param2.length >= 2) {
	    System.out.println("Lat\t" + param[1]);
	    System.out.println("Lon\t" + param[0]);

	    String info[] = param2[1].substring(0, param2[1].length()-1).split(",");
	    for (int i = 0; i < info.length; i++) {
		String tk[] = info[i].split(":");
		String name = tk[0].substring(1,tk[0].length()-1);
		String value = tk[1];
		System.out.println(name + "\t" + value);
	    }
	}
    }

    public static void main(String[] argv) throws MalformedURLException, ProtocolException, IOException {
	/*        
	System.setProperty("http.proxyHost", "....");		// 必要があればproxyの設定
	System.setProperty("http.proxyPort", "....");
	*/
	System.setProperty("http.nonProxyHosts", "localhost");	//ローカルホストは除外

        // 電測情報を取得する
	long t = System.currentTimeMillis() / 1000;
        String req = "http://localhost:5448/rtagjs?t=" + t + "&appk=" + appk;
	System.out.println("-->PlaceEngineClient\n" + req + "\n");
	String res = getURL(req);
	System.out.println("PlaceEngineClient-->\n" + res + "\n");

        // 電測情報から位置情報を得る
	String v[] = res.substring(9, res.length()-2).split(", *");
	String rtag = v[0].substring(1, v[0].length()-1);
	int numap = Integer.parseInt(v[1]);

	if (numap > 0) {
	    String req2 = "http://www.placeengine.com/api/loc?t=" + t + "&rtag=" + rtag + "&appk=" + appk + "&fmt=json";
	    System.out.println("-->PlaceEngineServer\n" + req2 + "\n");
	    String res2 = getURL(req2);
	    System.out.println("PlaceEngineServer-->\n" + res2 + "\n");
	
	    // 得られた位置情報(json形式)の表示
	    printInfo(res2);
	}
    }
}

この例では、PlaceEngineサーバーに位置を問い合わせる際に、JSON (javascript object notation)形式を要求しています(fmt=json)。JSON形式については www.json.org 等を参照して下さい。

proxyの設定をする場合は, PlaceEngineクライアントと通信できるようにローカルホストを除外するようにして下さい。

実行結果:

C:\>java PeTest
-->PlaceEngineClient		PlaceEngineクライアントへのリクエスト	
http://localhost:5448/rtagjs?t=1165321003&appk=S7Rk0Bm3D....

PlaceEngineClient-->		PlaceEngineクライアントからの戻り値
recvRTAG("CgS4isZH-BPX....",6,1165321003,null,null);

-->PlaceEngineServer		PlaceEngineサーバーへのリクエスト	
http://www.placeengine.com/api/loc?t=1165321003&rtag=CgS4isZH-BPX....&appk=S7Rk0Bm3D....&fmt=json

PlaceEngineServer-->		PlaceEngineサーバーから戻り値	
[139.730472,35.625954,15,{'addr':'東京都品川区東五反田三丁目','msg':'位置が取得できました','floor':'2F','t':1165321003}]

Lat	35.625954
Lon	139.730472
addr	'東京都品川区東五反田三丁目'
msg	'位置が取得できました'
floor	'2F'
t	1165321003

プログラム例2 ： Hello Location Local 版 in Java

現在位置(緯度・経度)を、LocalDB機能を用いて推定します。PlaceEngineサーバーとの接続は必要ありません。 ( LocalTest.java ソースコード)

PlaceEngineクライアント インタフェース

PlaceEngineクライアントへのリクエストはhttp://localhost:5448 へのGETリクエストの形式を取ります。

http://localhost:5448/ackjs?パラメタ

PlaceEngineクライアントの存在を確認します。

パラメタ:

パラメタ名	値	必須/オプション
t	タイムスタンプ	必須

タイムスタンプは、秒で測定した、現在時刻と協定世界時の UTC 1970年1月1日 午前0時 との差です。Javaでは System.currentTimeMillis()/1000 で求めることができます。

戻り値:

ackRTAG(version);

値	説明
version	バージョン文字列 ("w061130" など)

http://localhost:5448/rtagjs?パラメタ

WiFi電測を行います。

パラメタ:

パラメタ名	値	必須/オプション
t	タイムスタンプ	必須
appk	アプリケーションキー	必須

戻り値:

recvRTAG(rtag,numap,t);

値	説明
rtag	電測情報文字列
numap	観測できたアクセスポイント数, あるいはエラーコード
t	タイムスタンプ

numap 値	説明
> 0	観測できたアクセスポイント数
-1	WiFi取得できず (無線LANがOFFなど)
-2	AP数0 (WiFi電測できたがAPが発見できなかった)
-4	電測が拒否された
-5	timeout
-6	アプリケーションキー未設定／不正

PlaceEngineクライアントインタフェース (LocalDB機能)

以下の機能はPlaceEngineクライアントw070606,m070606,o080131以降で導入された LocalDB機能 に関するものです。それ以前のクライアントでは利用できません。

LocalDBによる位置推定は、単純に緯度経度のみを求めるもので、以下の情報は提供されません：

• 住所
• フロア情報
• 推定精度
• 推定に利用されたアクセスポイント数

LocalDBによる位置推定は、ローカルアプリケーションからのみ利用可能です。Webアプリケーションでは従来通り PlaceEngineサーバーの機能をご利用下さい。

http://localhost:5448/listdb

利用できるLocalDB名を列挙します。

パラメタ:

パラメタ名	値	必須/オプション
check	1:データベース更新のチェック	オプション

戻り値:

以下のようにLocalDB名を列挙したリストが返されます。

["all", "tokyo"]

checkdb=1 を指定すると、ダウンロードされているLocalDBが最新のものかどうかを確認します。LocalDB名、タイムスタンプ、最新かどうか（1:最新、0:サーバーにより新しいLocalDBが存在する）を列挙したリストが返されます：

 [["all",1192479058,1],["tokyo",1192478712,1]]

※ LocalDBは、PlaceEngineクライアントの設定→LocalDB→アップデートで最新版をダウンロードすることができます。

http://localhost:5448/locdb?パラメタ

WiFi電測を行い、PlaceEngineクライアントが保持するローカル位置データベース(LocalDB)を利用して位置推定を行います。(PlaceEngineサーバとは通信しません)

パラメタ:

パラメタ名	値	必須/オプション
t	タイムスタンプ	必須
appk	アプリケーションキー	必須

戻り値:

以下のように経度、緯度、エラーコード, 付加情報からなる文字列

[x,y,result,info]

値	説明
x	経度
y	緯度
result	位置推定に成功した場合(>= 0), エラーコード(<0の場合)
info	属性情報

現状では、infoは常に"{}"です。

resultの意味は以下の通りです

0	電測が成功し、位置がx,yに取得できた
-1	WiFi取得できず (無線LANがOFFなど)
-2	AP数0 (WiFi電測できたがAPが発見できなかった)
-4	電測が拒否された
-5	timeout
-6	アプリケーションキー未設定／不正
-110	位置取得できず(データベース未登録) ※

※ 電測が成功しても、LocalDBに対応するアクセスポイント情報が存在しない場合、x,yも0,0となります。

PlaceEngineサーバーインタフェース

PlaceEngineサーバーへのリクエストは、 http://www.placeengine.com/api へのGETリクエストの形式をとります。

http://www.placeengine.com/api/loc?パラメタ

電測情報から位置を推定ます。

パラメタ:

パラメタ名	値	必須/オプション
rtag	電測文字列	必須
t	タイムスタンプ	必須
appk	アプリケーションキー	必須
fmt	省略、あるいはjson	オプション

戻り値:

recvLoc(x,y,range,info);   -- fmtが省略された場合
[x,y,range,info]           -- fmt=json の場合

値	説明
x	経度
y	緯度
range	推定誤差(>0の場合), エラーコード(<0の場合)
info	属性情報

info は {"属性名1":値1,"属性名2":値2,...} といった形式をもつ文字列で、以下の属性があります：

info 属性名	説明
addr	住所文字列
msg	フィードバックメッセージ
floor	フロア情報("2F"など)
t	タイムスタンプ