TOP | TOOL | API | MAP

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

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

全体の流れ

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

という流れになります。

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

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名を列挙します。

パラメタ:

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

戻り値:

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

["all", "tokyo"]

check=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オプション
quote戻り値の文字列形式*1を指定オプション
*1 … 省略時はシングルクォート、quote=double を指定した場合はダブルクォート形式で返却します。

戻り値:

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タイムスタンプ


PlaceEngineクライアントインタフェース (ハイブリッド測位)

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

GPS,ローカルDB,PlaceEngineサーバを使用したハイブリッド測位を行います。

パラメタ:

パラメタ名値必須/オプション
appkアプリケーションキー必須
fmtjson または jsonp、省略時は jsonpオプション
m測位メッソッド*1 をカンマ区切りで指定、省略時は g,l,pオプション
usecache1:測位結果キャッシュ*2 を使用する、0:使用しない、省略時は1オプション
restrict戻り値の型*3 を 0 または 1 で指定、省略時は 0オプション
*1 … g:GPS、l:ローカルDB、p:PlaceEngineサーバを利用した測位。指定した順に測位します。(usecacheが0場合、pはwww.placeengine.comにアクセスしますが、他のメソッドはインターネットアクセスはありません)
*2 … PlaceEngine が定期的に測位した結果をキャッシュに保持しその値を返す。
*3 … 測位メソッドを複数指定した場合、通常は複数の結果を返しますが、正常に測位できた最初の測位メソッドだけを返したい場合に restrict=1 を指定します。「詳しくは例をご参照ください。」

戻り値:

//結果が複数ある場合(mに複数の測位メソッドを指定した場合)
recvLoc2([result1,result2,...]);   -- fmt=jsonp または省略された場合
[result1,result2,...]              -- fmt=json の場合

  //result1,result2の形式
  {"r":result, "m":method, "t":t, "x":x, "y":y, "info":info}


//結果がひとつの場合
recvLoc2({"r":result, "m":method, "t":t, "x":x, "y":y, "info":info});   -- fmt=jsonp または省略された場合
{"r":result, "m":method, "x":x, "y":y, "info":info}                     -- fmt=json の場合

値説明
result測位成功(>=0), エラーコード(<0の場合 エラーコード一覧)
method測位メソッド
tタイムスタンプ
x経度
y緯度
info属性情報

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

info 属性名説明
addr住所文字列
floorフロア情報("2F"など)

例:

デフォルト測位
http://localhost:5448/getlocjs?appk=xxx 
recvLoc2({ "r": 0, "m": "p", "t": 1236336446, "x": 139.7659, "y": 35.6814, "info": { "addr": "東京都千代田区丸の内一丁目", "floor": "3F" } })

JSON形式を指定
http://localhost:5448/getlocjs?appk=xxx&fmt=json 
{ "r": 0, "m": "p", "t": 1236336446, "x": 139.7659, "y": 35.6814, "info": { "addr": "東京都千代田区丸の内一丁目", "floor": "3F" } }

PlaceEngineサーバを利用した測位でキャッシュを使わない
http://localhost:5448/getlocjs?appk=xxx&m=p&usecache=0 
recvLoc2({ "r": 0, "m": "p", "t": 1236336446, "x": 139.7659, "y": 35.6814, "info": { "addr": "東京都千代田区丸の内一丁目", "floor": "3F" } })

ローカルDBのみの測位でキャッシュを使わない
http://localhost:5448/getlocjs?appk=xxx&m=l&usecache=0 
recvLoc2({ "r": 0, "m": "l", "t": 1236336446, "x": 139.7659, "y": 35.6814, "info": { "addr": null, "floor": null } })

ローカルDB,PlaceEngineサーバ,GPSの複数測位
http://localhost:5448/getlocjs?appk=xxx&m=l,p,g&usecache=0&fmt=json 
//実際には改行はありません
//この結果はローカルDB、PlaceEngineサーバの測位は成功ですがGPS測位が失敗した例です
[
{ "r": 0, "m": "l", "t": 1236337593, "x": 139.7659, "y": 35.6814, "info": { "addr": null, "floor": null } },
{ "r": 0, "m": "p", "t": 1236337594, "x": 139.7659, "y": 35.6814, "info": { "addr": "東京都港区麻布十番四丁目", "floor": "3F" } }
]

ローカルDB,PlaceEngineサーバ,GPSの複数測位で結果がひとつだけ欲しい場合
http://localhost:5448/getlocjs?appk=xxx&m=l,p,g&restrict=1&usecache=0&fmt=json 
//測位メソッドはローカルDB、PlaceEngineサーバ、GPSの順で指定しています。
//restrict=1 が指定されているので結果がひとつだけ返りました。
//ローカルDBの測位に失敗し、PlaceEngineサーバの測位に成功した場合の結果となります。
{ "r": 0, "m": "p", "t": 1236337594, "x": 139.7659, "y": 35.6814, "info": { "addr": "東京都港区麻布十番四丁目", "floor": "3F" } }

エラーコード一覧

値説明
0成功
-1 WiFi取得できず （無線LANがOFFなど）
-2 AP数0 （WiFi電測できたがAPが発見できなかった）
-3 PlaceEngineサーバーへのアクセス失敗
-4 電測が拒否された
-5 通知画面の待ち受けタイムアウト
-6 アプリケーションキー未設定／不正
-7 Terminal Servicesサービスが無効のため機能せず（Windows XP,Vistaのみ）
-8 パラメータエラー（引数が不正）
-9 位置情報の信頼度が足りない（電波が弱いとか）
-10 PlaceEngine内部エラー
-11 WiFi情報の利用は法律で禁止されている
-12 言語IDが不正
-13 ローカルDBが見つかりませんでした
-110 ローカルDBから位置取得できず（ローカルDB位置未登録）
-111 要求に対してレファラーが正しくはない
-113 リクエスト形式不正
-115 タイムスタンプ不一致（パソコンの時計がずれ過ぎている）
©2007-2011 Koozyt, Inc. | 日本語 / English