Geolocation

Geolocation

Geolocation オブジェクトはデバイスのGPSセンサーへのアクセスを提供します。

Geolocation は緯度や経度といったデバイスの位置情報を提供します。 主にGlobal Positioning System(GPS)から位置情報を取得しますが、IPアドレスやRFID、WiFi、Bluetooth、MACアドレス、 基地局IDなどのソースからも現在位置を推測します。

ただし当APIがデバイスの正確の位置を特定する保障はありません。 当APIは W3C Geo location API Specification に基づいております。既にW3CのAPIの実装をサポートしているデバイスについては、PhoneGapの実装ではなくビルトインのサポートが実行されます。 GeolocationのサポートがなされていないデバイスについてはPhoneGapの実装は、W3Cの仕様と適合します。

メソッド

引数

オブジェクト (読み込み専用)


geolocation.getCurrentPosition

デバイスの現在位置を Position オブジェクトとして返します。

navigator.geolocation.getCurrentPosition(geolocationSuccess, 
                                         [geolocationError], 
                                         [geolocationOptions]);

パラメータ

概要

geolocation.getCurrentPositonPosition オブジェクトをパラメータとして geolocationSuccess コールバック関数にデバイスの現在位置を返す非同期関数です。 また、エラーが発生した場合 geolocationError コールバック関数を PositionError オブジェクトとともに呼び出します。

サポートされているプラットフォーム

使用例

// 成功時のコールバック関数
//  このメソッドはGPSの現在座標を保有する `Position` オブジェクトを引数とします
//
var onSuccess = function(position) {
    alert('緯度: '          + position.coords.latitude          + '\n' +
          '経度: '         + position.coords.longitude         + '\n' +
          '高度: '          + position.coords.altitude          + '\n' +
          '位置精度: '          + position.coords.accuracy          + '\n' +
          '高度精度: ' + position.coords.altitudeAccuracy  + '\n' +
          '方位: '           + position.coords.heading           + '\n' +
          '速度: '             + position.coords.speed             + '\n' +
          'タイムスタンプ: '         + new Date(position.timestamp)      + '\n');
};

// 失敗時のコールバックは、PositionErrorオブジェクトを受けとる
//
function onError(error) {
    alert('コード: '    + error.code    + '\n' +
          'メッセージ: ' + error.message + '\n');
}

navigator.geolocation.getCurrentPosition(onSuccess, onError);

詳細な使用例

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>位置情報の使用例</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // PhoneGapの読み込みを待機
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // PhoneGap準備完了
    //
    function onDeviceReady() {
        navigator.geolocation.getCurrentPosition(onSuccess, onError);
    }

    // onSuccess Geolocation
    //
    function onSuccess(position) {
        var element = document.getElementById('geolocation');
        element.innerHTML = '緯度: '           + position.coords.latitude              + '<br />' +
                            '経度: '          + position.coords.longitude             + '<br />' +
                            '高度: '           + position.coords.altitude              + '<br />' +
                            '位置精度: '           + position.coords.accuracy              + '<br />' +
                            '高度精度: '  + position.coords.altitudeAccuracy      + '<br />' +
                            '方位: '            + position.coords.heading               + '<br />' +
                            '速度: '              + position.coords.speed                 + '<br />' +
                            'タイムスタンプ: '          + new Date(position.timestamp)          + '<br />';
    }

    // 失敗時のコールバックは、PositionErrorオブジェクトを受けとる
    //
    function onError(error) {
        alert('コード: '    + error.code    + '\n' +
              'メッセージ: ' + error.message + '\n');
    }

    </script>
  </head>
  <body onload="onLoad()">
    <p id="geolocation"> 位置情報を取得中...</p>
  </body>
</html>

geolocation.watchPosition

デバイスの現在位置の変化を監視します。

var watchId = navigator.geolocation.watchPosition(geolocationSuccess,
                                                  [geolocationError],
                                                  [geolocationOptions]);

パラメータ

返り値

概要

geolocation.watchPosition は位置情報に変化があった場合にデバイスに現在位置情報を返す非同期関数です。 デバイスが新しい位置情報を取得した場合、 geolocationSuccess コールバック関数が Position オブジェクトをパラメータとして呼び出されます。

エラー発生時には geolocationError コールバック関数が PositionError オブジェクトとともに呼ばれます。

サポートされているプラットフォーム

使用例

// 成功時のコールバック関数
//   GPSの現在座標を保有するPositionオブジェクトを引数とする

//
function onSuccess(position) {
    var element = document.getElementById('geolocation');
    element.innerHTML = '緯度: '  + position.coords.latitude      + '<br />' +
                        '経度: ' + position.coords.longitude     + '<br />' +
                        '<hr />'      + element.innerHTML;
}

// 失敗時のコールバック関数はPositionErrorオブジェクトを取得
//
function onError(error) {
    alert('コード: '    + error.code    + '\n' +
          'メッセージ: ' + error.message + '\n');
}

// 3秒ごとに位置情報を取得する設定(オプション)
//
var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { frequency: 3000 });

詳細な使用例

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>位置情報の使用例</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // PhoneGapの読み込みを待機
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    var watchID = null;

    // PhoneGap準備完了
    //
    function onDeviceReady() {
        // 3秒毎に更新
        var options = { frequency: 3000 };
        watchID = navigator.geolocation.watchPosition(onSuccess, onError, options);
    }

    // onSuccess Geolocation
    //
    function onSuccess(position) {
        var element = document.getElementById('geolocation');
        element.innerHTML = '緯度: '  + position.coords.latitude      + '<br />' +
                            '経度: ' + position.coords.longitude     + '<br />' +
                            '<hr />'      + element.innerHTML;
    }

    // 失敗時のコールバックは、PositionErrorオブジェクトを受けとる
    //
    function onError(error) {
        alert('コード: '    + error.code    + '\n' +
              'メッセージ: ' + error.message + '\n');
    }

    </script>
  </head>
  <body onload="onLoad()">
    <p id="geolocation">位置情報を取得中...</p>
  </body>
</html>

geolocation.clearWatch

watchID パラメータによって参照されるデバイスの位置情報の監視を停止します。

navigator.geolocation.clearWatch(watchID);

パラメータ

概要

geolocation.clearWatch 関数は watchID に参照される geolocation.watchPosition をクリアすることでデバイスの位置情報の監視を停止します。

サポートされているプラットフォーム

使用例

// オプションにて3秒ごとに位置情報を取得するよう設定
//
var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { frequency: 3000 });

// ...後に続く...

navigator.geolocation.clearWatch(watchID);

詳細な使用例

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>位置情報の使用例</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // PhoneGapの読み込みを待機
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    var watchID = null;

    // PhoneGap準備完了
    //
    function onDeviceReady() {
        // 3秒毎に更新
        var options = { frequency: 3000 };
        watchID = navigator.geolocation.watchPosition(onSuccess, onError, options);
    }

    // 取得に成功した場合
    //
    function onSuccess(position) {
        var element = document.getElementById('geolocation');
        element.innerHTML = '緯度: '  + position.coords.latitude      + '<br />' +
                            '経度: ' + position.coords.longitude     + '<br />' +
                            '<hr />'      + element.innerHTML;
    }

    // 開始されたウォッチをクリア
    // 
    function clearWatch() {
        if (watchID != null) {
            navigator.geolocation.clearWatch(watchID);
            watchID = null;
        }
    }

    // 失敗時のコールバックは、PositionErrorオブジェクトを受けとる
    //
    function onError(error) {
      alert('コード: '    + error.code    + '\n' +
            'メッセージ: ' + error.message + '\n');
    }

    </script>
  </head>
  <body onload="onLoad()">
    <p id="geolocation">Geolocation 監視中...</p>
    <button onclick="clearWatch();">監視の停止</button>     
  </body>
</html>

Coordinates

位置情報で使用される座標を格納します。

プロパティ

概要

Coordinates オブジェクトは Position オブジェクトのプロパティとして作成されます。 Position オブジェクトはコールバック関数を通してユーザーに渡されます。

サポートされているプラットフォーム

使用例

// 成功時のコールバック
//
var onSuccess = function(position) {
    alert('緯度: '          + position.coords.latitude          + '\n' +
          '経度: '         + position.coords.longitude         + '\n' +
          '高度: '          + position.coords.altitude          + '\n' +
          '位置精度: '          + position.coords.accuracy          + '\n' +
          '高度精度: ' + position.coords.altitudeAccuracy  + '\n' +
          '方位: '           + position.coords.heading           + '\n' +
          '速度: '             + position.coords.speed             + '\n' +
          'タイムスタンプ: '         + new Date(position.timestamp)      + '\n');
};

// 失敗時のコールバック
//
var onError = function() {
    alert('エラーが発生しました。');
};

navigator.geolocation.getCurrentPosition(onSuccess, onError);

詳細な使用例

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>Geolocation Position の例</title>
    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // イベントをセットし、PhoneGapの読み込みを待機
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // PhoneGap準備完了
    //
    function onDeviceReady() {
        navigator.geolocation.getCurrentPosition(onSuccess, onError);
    }

    // `Position` プロパティーを表示
    //
    function onSuccess(position) {
        var div = document.getElementById('myDiv');

        div.innerHTML = '緯度: '             + position.coords.latitude  + '<br/>' +
                        '経度: '            + position.coords.longitude + '<br/>' +
                        '高度: '             + position.coords.altitude  + '<br/>' +
                        '位置精度: '             + position.coords.accuracy  + '<br/>' +
                        '高度精度: '    + position.coords.altitudeAccuracy  + '<br/>' +
                        '方位: '              + position.coords.heading   + '<br/>' +
                        '速度: '                + position.coords.speed     + '<br/>';
    }

    // 問題発生時に警告を表示
    //
    function onError() {
        alert('エラーが発生しました。');
    }

    </script>
  </head>
  <body onload="onLoad()">
    <div id="myDiv"></div>
  </body>
</html>

Android に関する注意点

altitudeAccuracy: このプロパティはAndroidではサポートされておらず、常にnullを返します。


Position

Geolocation APIによって作成された位置座標(Position)を扱うオブジェクトです。

プロパティ

概要

Position オブジェクトはPhoneGapにより作成され、コールバック関数を通してユーザーに返されます。

サポートされているプラットフォーム

使用例

// 成功時のコールバック
//
var onSuccess = function(position) {
    alert('緯度: '       + position.coords.latitude          + '\n' +
          '経度: '       + position.coords.longitude         + '\n' +
          '高度: '       + position.coords.altitude          + '\n' +
          '位置精度: '   + position.coords.accuracy          + '\n' +
          '高度精度: '   + position.coords.altitudeAccuracy  + '\n' +
          '方位: '       + position.coords.heading           + '\n' +
          '速度: '       + position.coords.speed             + '\n' +
          'タイムスタンプ: ' + new Date(position.timestamp)  + '\n');
};

// 失敗時のコールバックは、PositionErrorオブジェクトを取得
//
function onError(error) {
    alert('コード: '    + error.code    + '\n' +
          'メッセージ: ' + error.message + '\n');
}

navigator.geolocation.getCurrentPosition(onSuccess, onError);

詳細な使用例

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
  <head>
    <title>位置情報の使用例</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // PhoneGapの読み込みを待機
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // PhoneGap準備完了
    //
    function onDeviceReady() {
        navigator.geolocation.getCurrentPosition(onSuccess, onError);
    }

    // onSuccess Geolocation
    //
    function onSuccess(position) {
        var element = document.getElementById('geolocation');
        element.innerHTML = '緯度: '           + position.coords.latitude              + '<br />' +
                            '経度: '          + position.coords.longitude             + '<br />' +
                            '高度: '           + position.coords.altitude              + '<br />' +
                            '位置精度: '           + position.coords.accuracy              + '<br />' +
                            '高度精度: '  + position.coords.altitudeAccuracy      + '<br />' +
                            '方位: '            + position.coords.heading               + '<br />' +
                            '速度: '              + position.coords.speed                 + '<br />' +
                            'タイムスタンプ: '          + new Date(position.timestamp)          + '<br />';
    }

    // 失敗時のコールバックは、PositionErrorオブジェクトを受けとる
    //
    function onError(error) {
        alert('コード: '    + error.code    + '\n' +
              'メッセージ: ' + error.message + '\n');
    }

    </script>
  </head>
  <body onload="onLoad()">
    <p id="geolocation">位置情報を取得中...</p>
  </body>
</html>

iPhone に関する注意点


PositionError

PositionError オブジェクトはエラーが発生した場合に、geolocationError コールバック関数に渡されます。

プロパティ

定数

概要

PositionError オブジェクトは、geolocationに関するエラーが発生したときに geolocationError コールバック関数を通して、ユーザーに返されます。


geolocationSuccess

位置情報取得に成功したときに呼び出されるコールバック関数です。

function(position) {
    // 任意のコード
}

パラメータ

function geolocationSuccess(position) {
    alert('緯度: '         + position.coords.latitude          + '\n' +
          '経度: '         + position.coords.longitude         + '\n' +
          '高度: '         + position.coords.altitude          + '\n' +
          '位置精度: '     + position.coords.accuracy          + '\n' +
          '高度精度: '     + position.coords.altitudeAccuracy  + '\n' +
          '方位: '         + position.coords.heading           + '\n' +
          '速度: '         + position.coords.speed             + '\n' +
          'タイムスタンプ: ' + new Date(position.timestamp)    + '\n');
}

geolocationError

geolocation関数にエラーが発生した際に呼び出されるコールバック関数です。

function(error) {
    // エラー時の対応
}

パラメータ


geolocationOptions

geolocationの取得方法をカスタマイズするためのオプションパラメータです。

{ maximumAge: 3000, timeout: 5000, enableHighAccuracy: true };

オプション

Android に関する注意点

The Android 2.x のシミュレータは enableHighAccuracy オプションがtrueにセットされるまでgeolocationの結果は通知されません。

{ enableHighAccuracy: true }