2012/04/16更新

[HTML5] HTML5の位置情報取得機能の使い方のまとめ

HTML5の関連機能であるGeoLocation APIを使いました。何個かオブジェクトがあるようですが、まとまった情報があまり無かったので、自分なりに纏めてみました。指定するオプションの内容など、知りたかった情報を集めることが出来ました。

HTML5 Geolocation API Summary

目次は以下の通りです。
１、位置情報取得のためのGeoLocationオブジェクト
２、PositionOptionsについて
３、Positionについて
４、Coordinatesについて
５、PositionErrorについて

位置情報取得のためのGeoLocationオブジェクト

navigatorのgeolocationプロパティについてです。geolocationが位置情報取得機能の中心的存在となります。

interface Geolocation {
   void getCurrentPosition(in PositionCallback successCallback,
                           in optional PositionErrorCallback errorCallback,
                           in optional PositionOptions options);

   long watchPosition(in PositionCallback successCallback,
                      in optional PositionErrorCallback errorCallback,
                      in optional PositionOptions options);

   void clearWatch(in long watchId);
 };

 [Callback=FunctionOnly, NoInterfaceObject]
 interface PositionCallback {
   void handleEvent(in Position position);
 };

 [Callback=FunctionOnly, NoInterfaceObject]
 interface PositionErrorCallback {
   void handleEvent(in PositionError error);
 };

Geolocationには、3つのメソッドが定義されています。

メソッド名	引数1	引数2	引数3	メソッドの振る舞い
getCurrentPosition	処理成功時のコールバック関数	処理失敗時のコールバック関数	メソッドの振る舞いを指定するオプション	位置情報を1回取得する
watchPosition	処理成功時のコールバック関数	処理失敗時のコールバック関数	メソッドの振る舞いを指定するオプション	位置情報を継続的に取得する
clearWatch	watchPositionの戻り値のID	watchPositionを終了する

getCurrentPosition, watchPositionの第2第３引数はoptionalということで、指定しなくても良いようですね。

getCurrentPositionのサンプルは、HTML5で位置情報を取得する＠YoheiM.NETを参照ください。

watchPosition, clearWatchのサンプルは、HTML5で位置情報を継続的に取得する＠YoheiM.NETを参照ください。

処理成功時のコールバック関数には、positionというオブジェクトを引数で受け取ることが出来るようです。

処理失敗時のコールバック関数には、errorというオブジェクトを引数で受け取ることが出来るようです。

PositionOptionsについて

getCurrentPosition, watchPositionメソッドの第３引数に指定する内容です。

interface PositionOptions {
    attribute boolean enableHighAccuracy;
    attribute long timeout;
    attribute long maximumAge;
  };

３種類のオプションを設定出来るようですね。使い方などは、以下のようです。

オプション名	意味	設定値	備考
enableHighAccuracy	より高い精度を求める	true / false	GPSなどを用いてより精度の高い位置情報を取得出来る。位置情報取得に時間やバッテリーがかかるので注意
timeout	タイムアウト時間	ミリ秒	例：3000(=3秒)
maximumAge	位置情報をキャッシュする時間ミリ秒	ミリ秒	0を設定すると、毎回新しい位置情報を得る

Positionについて

処理成功時のコールバック関数で受け取れる内容です。

interface Position {
    readonly attribute Coordinates coords;
    readonly attribute DOMTimeStamp timestamp;
  };

2つのプロパティを保持しているようです。

プロパティ名	内容
coords	様々な位置情報を保持するオブジェクト
timestamp	位置情報を取得したタイムスタンプ(=時間)

Coordinatesについて

ひとつ上のPositionのプロパティであるcoordsに様々な位置情報が格納されています。その位置情報を格納しているのが、Coordinatesインターフェース。

interface Coordinates {
    readonly attribute double latitude;
    readonly attribute double longitude;
    readonly attribute double? altitude;
    readonly attribute double accuracy;
    readonly attribute double? altitudeAccuracy;
    readonly attribute double? heading;
    readonly attribute double? speed;
  };

保持しているプロパティは、以下の通りです。

プロパティ名	内容	備考
latitude	緯度
longitude	経度
altitude	高度
accuracy	位置精度	どれだけ正確な位置情報かを表す。単位はMeter
altitudeAccuracy	高度精度	高度の正確性を表す。単位はMeter。高度が提供されていない場合にはnull
heading	方角	北から時計回りで0<=heading<360の値で示される。動いていない場合には、NaN
speed	移動速度	1秒間あたりの水平方向への移動距離。単位はMeter。

hading,speedについては、実装されていないブラウザーもあり、その場合には、nullが返されるようです（仕様上は）。

PositionErrorについて

これは、位置情報取得に失敗した際に呼ばれるコールバック関数の引数に渡される内容です。

interface PositionError {
    const unsigned short PERMISSION_DENIED = 1;
    const unsigned short POSITION_UNAVAILABLE = 2;
    const unsigned short TIMEOUT = 3;
    readonly attribute unsigned short code;
    readonly attribute DOMString message;
  };

エラーコードとエラーメッセージを保持しています。また保持している定数は、エラーコードの値の意味を保持しているようです。

具体的な利用方法は、HTML5で位置情報を取得するを参考にしてみて下さい。

参考にしたサイト

以下のサイトを参考にしてみました。良き情報をありがとうございます。

W3C - Geolocation API Specification

位置情報を連続して取得してみる Waste Of Time

位置情報サービスの始め方：第３回（後編）

最後に

色々と調べてみて、すっきりした。これでようやく色々と出来そう(*ﾟ▽ﾟ)ﾉ良かったヨカッタ。