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]);
パラメータ
- geolocationSuccess: 現在位置取得成功時に呼ばれるコールバック関数です
- geolocationError: (オプション) エラー発生時に呼ばれるコールバック関数です
- geolocationOptions: (オプション) geolocationのオプションです
概要
geolocation.getCurrentPositon
は Position
オブジェクトをパラメータとして geolocationSuccess
コールバック関数にデバイスの現在位置を返す非同期関数です。
また、エラーが発生した場合 geolocationError
コールバック関数を PositionError
オブジェクトとともに呼び出します。
サポートされているプラットフォーム
- Android
- BlackBerry (OS 4.6)
- BlackBerry WebWorks (OS 5.0 以上)
- iPhone
使用例
// 成功時のコールバック関数
// このメソッドは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]);
パラメータ
- geolocationSuccess: 現在位置取得成功時に呼ばれるコールバック関数です
- geolocationError: (オプション) エラー発生時に呼ばれるコールバック関数です
- geolocationOptions: (オプション) geolocation のオプションです
返り値
-
String: 位置変化を参照するウォッチIDを返します。
geolocation.clearWatch
に適用することで位置変化の監視を中止することができます。
概要
geolocation.watchPosition
は位置情報に変化があった場合にデバイスに現在位置情報を返す非同期関数です。
デバイスが新しい位置情報を取得した場合、 geolocationSuccess
コールバック関数が Position
オブジェクトをパラメータとして呼び出されます。
エラー発生時には geolocationError
コールバック関数が PositionError
オブジェクトとともに呼ばれます。
サポートされているプラットフォーム
- Android
- BlackBerry (OS 4.6)
- BlackBerry WebWorks (OS 5.0 以上)
- iPhone
使用例
// 成功時のコールバック関数
// 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);
パラメータ
-
watchID:
watchPosition
の位置間隔をクリアするためのidです (String)
概要
geolocation.clearWatch
関数は watchID
に参照される geolocation.watchPosition
をクリアすることでデバイスの位置情報の監視を停止します。
サポートされているプラットフォーム
- Android
- BlackBerry (OS 4.6)
- BlackBerry WebWorks (OS 5.0 以上)
- iPhone
使用例
// オプションにて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
位置情報で使用される座標を格納します。
プロパティ
- latitude: 緯度を数値を表します (Number)
- longitude: 経度を数値で表します (Number)
- altitude: 海抜からの高度を表します (Number)
- accuracy: 位置の精度をメートル単位で表します(Number)
- altitudeAccuracy: 高度の精度をメートル単位で表します (Number)
- heading: 北から時計回りに図ったときのデバイスの方位を角度(数値)で表します (Number)
- speed: 現在のデバイスのスピードをメートル/秒で表します (Number)
概要
Coordinates
オブジェクトは Position
オブジェクトのプロパティとして作成されます。
Position
オブジェクトはコールバック関数を通してユーザーに渡されます。
サポートされているプラットフォーム
- Android
- BlackBerry (OS 4.6)
- BlackBerry WebWorks (OS 5.0 以上)
- iPhone
使用例
// 成功時のコールバック
//
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
)を扱うオブジェクトです。
プロパティ
- coords: 地理座標を表します。 (Coordinates)
-
timestamp: ミリ秒単位で表される
coords
のタイムスタンプです。 (DOMTimeStamp)
概要
Position
オブジェクトはPhoneGapにより作成され、コールバック関数を通してユーザーに返されます。
サポートされているプラットフォーム
- Android
- BlackBerry (OS 4.6)
- BlackBerry WebWorks (OS 5.0 以上)
- iPhone
使用例
// 成功時のコールバック
//
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 に関する注意点
-
timestamp: このプロパティーはサポートされていますが、ミリ秒ではなく通常の秒単位で記述されます。対処法としては、手動でマイクロ秒に変換することが考えられます。
var onSuccess = function(position) { alert('緯度: ' + position.coords.latitude + '\n' + '経度: ' + position.coords.longitude + '\n' + 'タイムスタンプ: ' + new Date(position.timestamp * 1000) + '\n'); };
PositionError
PositionError
オブジェクトはエラーが発生した場合に、geolocationError コールバック関数に渡されます。
プロパティ
- code: 下のリストの中のあらかじめ定義されたエラーコードのいずれかが格納されます
- message: エラーの内容を表すエラーメッセージが格納されます
定数
PositionError.PERMISSION_DENIED
PositionError.POSITION_UNAVAILABLE
PositionError.TIMEOUT
概要
PositionError
オブジェクトは、geolocationに関するエラーが発生したときに geolocationError
コールバック関数を通して、ユーザーに返されます。
geolocationSuccess
位置情報取得に成功したときに呼び出されるコールバック関数です。
function(position) {
// 任意のコード
}
パラメータ
-
position: デバイスによって返される位置情報です。 (
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) {
// エラー時の対応
}
パラメータ
-
error: デバイスから返されるエラー (
PositionError
)
geolocationOptions
geolocationの取得方法をカスタマイズするためのオプションパラメータです。
{ maximumAge: 3000, timeout: 5000, enableHighAccuracy: true };
オプション
- frequency: 位置情報の取得頻度をミリ秒単位で変更するパラメータです。このオプションはW3Cの仕様に含まれておらず、将来的には実装が廃止されます。そのため代わりにmaximumAge を使用してください。 (Number) (デフォルト: 10000)
- enableHighAccuracy: より精度の高い位置情報を取得するためのヒントを提供します。 (Boolean)
-
timeout:
geolocation.getCurrentPosition
またはgeolocation.watchPosition
が呼び出された時に、それぞれに対応するgeolocationSuccess
コールバック関数が呼ばれるまでの最大経過時間をミリ秒単位で表します。 (Number) - maximumAge: ミリ秒単位で指定した時間以内でキャッシュされた位置情報を再利用します。 (Number)
Android に関する注意点
The Android 2.x のシミュレータは enableHighAccuracy オプションがtrueにセットされるまでgeolocationの結果は通知されません。
{ enableHighAccuracy: true }