PlaceEngine API JavaScriptライブラリ

PlaceEngine API JavaScriptライブラリは、PlaceEngineの位置取得機能をjavascriptから利用できるようにしたライブラリです。位置利用のWebアプリケーションが容易に構築できるようになります。

Tutorial

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

PlaceEngine API JavaScriptライブラリを利用するにはアプリケーションキーが必要です。 PlaceEngine連携サイト用アプリケーションキー取得ページで、アプリケーションキーを取得して下さい。

Sample1: Hello Location

ボタンを押すと、現在位置を表示するだけの単純なWebページです。 [ 実行 ]

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Hello Location</title>
<script src="http://www.placeengine.com/javascripts/pengine.js" type="text/javascript"></script>  *1
<style type="text/css">
.peui input {margin:0 0 -4px 0;}
</style>
</head>

<body>
<h1>Hello Location</h1>

<div class="peui">
<input alt="位置を教える" src="/images/wide_bt2.png" type="image"
    onclick="pe.registerLocation()" />  *2
<input alt="現在地を取得" src="/images/wide_bt1.png" type="image"
    onclick="pe.getLocation()" />     *3
<span id="pestatus"></span>   *4
</div>

<script type="text/javascript">
var pe = new PEngine({
    idstatus:"pestatus",   *5
    appkey:"......."       *6
});
</script>

</body>
</html>

*1: PlaceEngine javascriptライブラリを読み込みます。

*2: 位置登録用のボタンを定義しています。このボタンを押すと、PlaceEngineの位置登録ページに移動します。

*3: 現在地取得ボタンを定義しています。このボタンをクリックすると、PEngineオブジェクト(pe)のgetLocationメソッドが起動します。このメソッドは、PlaceEngineクライアントと通信し、WiFi電測情報を取得し、それをPlaceEngineサーバーで位置情報に変換します。

*4: 得られた位置情報を表示する領域です。"pestatus"というidをつけています。

*5: *4で定義した領域に位置情報を表示するようにidを設定しています。

*6: 上で取得したアプリケーションキーが入ります。

Sample2: PlaceEngine + Google Maps

最初の例では、位置を取得すると、idstatusとしてタグIDを指定した場所に、位置情報が表示されます。これ以外に、コールバック関数を設定することで、位置取得のタイミングでユーザ定義関数を起動することができます。

次の例は、コールバック関数を使って地図(Google Maps)と連動する例です。ボタンを押すと、地図の中心が現在位置になるようにスクロールします。 [ 実行 ]

(Google Maps APIについては関連サイト (Google Maps API ) 等を参照して下さい。)

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>PlaceEngine + Google Maps</title>
<script src="http://maps.google.com/maps?file=api&v=2&key=...."  *1
      type="text/javascript"></script>
<script src="http://www.placeengine.com/javascripts/pengine.js" type="text/javascript"></script>
<script type="text/javascript">  *2
    //<![CDATA[
    var map = null;
    function load() {
      if (GBrowserIsCompatible()) {
        map = new GMap2(document.getElementById("map"));
        map.addControl(new GLargeMapControl());
        map.addControl(new GScaleControl());
        map.setCenter(new GLatLng(35.67134, 139.76516), 17);
      }
    }
    //]]>
</script>
<style type="text/css">
.peui input {margin:0 0 -4px 0;}
</style>
</head>

<body onload="load()" onunload="GUnload()">

<h1>PlaceEngine + Google Maps</h1>

<div id="map" style="width: 500px; height: 300px"></div>

<div class="peui">
<input alt="位置を教える" src="http://www.placeengine.com/images/wide_bt2.png" type="image"
        onclick='pe.registerLocation(map)' />  *3
<input alt="現在地を取得" src="http://www.placeengine.com/images/wide_bt1.png" type="image"
        onclick='pe.getLocation()' />
<span id="pestatus"></span>
</div>

<script type="text/javascript">
var pe = new PEngine({
  onGetLocation: function(x, y, r, info) {   *4
    if (map != null) map.panTo(new GLatLng(y, x));
    if (document.getElementById("pestatus")!=null) {
      document.getElementById("pestatus").innerHTML = info.addr;
    }
  },
  idstatus:"pestatus",
  appkey:"....."  *5
});
</script>

</body>
</html>

*1: Google Maps用のAPI Keyを設定します。

*2: Google Mapsの地図設定用スクリプトです。

*3: 位置登録ボタンを定義しています。Google Mapsオブジェクト(map)を引数として指定すると、位置登録ボタンを押した時点でのmapの表示位置を中心に登録ページが開くようになります。

*4: onGetLocation という引数としてコールバック関数を設定しています。ここで、コールバック関数に渡される引数の意味は以下の通りです。

function(x, y, r, info)
  x    経度
  y    緯度
  r    エラーコード. > 0 であれば正常終了,  < 0 の場合はエラー
  info その他の属性情報。 info.addr に住所が格納される

この例では, 取得した緯度経度に応じてmapをスクロールさせ、住所を表示しています。

*5: PlaceEngine用のアプリケーションキーを設定します。

Sample3: Yahoo地図 + PlaceEngine

Yahoo地図情報Webサービスを利用した例です。 [ 実行 ]

Sample4: Greasemonkey

greasemonkeyは、Firefoxで利用できるスクリプトで、既存のWebページに対して機能を付加することが可能です。 PlaceEngineAPIとgreasemonkeyを組み合わせることで、既存の地図系サービスに現在位置取得の機能を付与することが可能になります。ここでは「はてなマップ 」での例を示します。

※ greasemonkeyの性質上、対象となるWebページの仕様が変更された場合動作しなくなる可能性があります。at-your-own-riskでお使い下さい。

placeenginehatenamap.user.js

PlaceEngine for FON Maps greasemonkey

placeengineforfonmap.user.js

Reference

PEngineオブジェクト

var pe = new PEngine({ オプション名:値, オプション名:値, .... });

のようにしてPEngineオブジェクトを生成します。生成時に渡すことのできるオプションは、以下の通りです。

オプション名	値	説明
idstatus	タグ名	PlaceEngineからのメッセージ表示先のタグ名
appkey	文字列	アプリケーションキー
onFindClient	コールバック関数	PlaceEngineクライアントを発見した時に呼ばれる
onGetLocation	コールバック関数	現在位置を取得した時に呼ばれる
onMessage	コールバック関数	PlaceEngineからのメッセージが表示されるときに呼ばれる
debug	true/false	デバッグモード(省略時 false)

PEngineオブジェクトのメソッド

pe.getLocation()

位置を取得します。まず、PlaceEngineクライアントと通信し、WiFi電波測情報を取得します。次にそれをPlaceEngineサーバーに送信し、位置情報を得ます。得られた位置情報はonGetLocationコールバック関数の呼び出し、あるいはidstatusで指定した領域への表示になります。通常は「現在位置を取得」ボタンを押したときのアクションとして指定します。

pe.registerLocation([map])

PlaceEngineの位置登録ページを開きます。GoogleMaps を利用している場合は、mapを指定すると、mapの中心位置と拡大率が、PlaceEngine位置登録ページの地図に反映されます。

pe.pingClient([ message ])

PlaceEngineクライアントの有無を確認します。PlaceEngineクライアントにメッセージを送り、その返事が返って来ることでPlaceEngineクライアントの有無を確認しています。返事が返って来た場合、onFindClientコールバック関数が設定してある場合、その関数が呼び出されます。

※ PlaceEngineクライアントが存在しない場合、onFindClientコールバック関数は呼び出されません。

messageを指定すると、その文字列がidstatusで指定される領域に表示されます。

コールバック関数

onFindClient

function(version)

PlaceEngineクライアントを発見したときに呼び出されます。

引数	値
version	バージョン文字列 (ex: "w061214")

onGetLocation

function(x, y, r, info)

引数	値
x	経度 (float)
y	緯度 (float)
r	リザルトコード > 0 であれば正常終了, < 0 の場合はエラー
info	属性情報

位置を取得した時点で呼び出されます。緯度(y)・経度(x)の座標系は世界測値系(WGS)です。xが正の場合は東経を, 負の場合には西経を、yが正の場合は北緯を、負の場合は南緯を意味します。

x = 135.6789,  y = 35.1234  は 東経135.6789, 北緯35.1234
x = -47.91,    y = -15.78   は 西経47.91, 南緯15.78

info 属性名	説明
addr	住所文字列 (ex: "東京都中央区銀座四丁目")
msg	フィードバックメッセージ
floor	フロア情報 (ex: "2F")
t	タイムスタンプ

r 値	説明
> 0	正常終了。値は推定精度(m)を示す
-1	WiFi取得できず (無線LANがOFFなど)
-2	AP数0 (WiFi電測できたがAPが発見できなかった)
-4	電測が拒否された
-5	timeout
-6	アプリケーションキー未設定／不正
≤ -100	パラメタエラー
-110	位置未登録
-111	アプリケーションキー未登録／不正
-113	リクエスト形式不正
-115	タイムスタンプ不一致

-1..-99はPlaceEngineクライアントからのエラーコード、 -100以下はPlaceEngineサーバーからのエラーコードです。

onMessage

function(message)

PlaceEngineからのメッセージがあるときに呼び出されます。

引数	値
message	メッセージ文字列

活用テクニック

PlaceEngineクライアントを起動しているときと、そうでないときとでWebページの表示を切り分けたい

onFindClient コールバックを使います。これは、Webページを開いた直後に、PlaceEngineクライアントの存在を確認できたときに呼び出されるコールバック関数です。

var pe = new PEngine({onFindClient:function(v){...}});

PlaceEngineクライアントが存在しないときは、このコールバック関数は呼び出されませので、WebクライアントをPlaceEngineクライアントが存在しない場合の表示にしておき、（たとえば PlaceEngine関連の表示は invisible にしてユーザからは見えないようにしておき）、上のコールバック関数の処理で、表示をPlaceEngine向けに切替えるようにします。