> For the complete documentation index, see [llms.txt](https://ja.docs.monaca.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ja.docs.monaca.io/reference/core-cordova-plugins/cordova-12.0/geolocation-puraguin.md). # Geolocation プラグイン このプラグインは、緯度や経度などのデバイスの場所に関する情報を提供します。 なお、この API が返す結果が、端末の正しい位置を示す保証はありません。 このプラグインの詳細は、 [こちらの原文 ( GitHub )](https://github.com/apache/cordova-plugin-geolocation) をご確認ください。 このプラグインは、グローバルな `navigator.geolocation` オブジェクトを定義します。 このプラグインは、`deviceready` イベントの発火後まで使用できません。 ```javascript document.addEventListener("deviceready", onDeviceReady, false); function onDeviceReady() { console.log("navigator.geolocation works well"); } ``` ### プラグイン ID ```javascript cordova-plugin-geolocation ``` ### プラグインの追加方法 このプラグインを使用する場合には、Monaca クラウド IDE の \[ Cordova プラグインの管理 ] 上で、`Geolocation` プラグインを[有効](/products_guide/monaca_ide/dependencies/cordova_plugin.md#cordova-puraguin-noinpto)にします。 ### API の解説 #### メソッド * navigator.geolocation.getCurrentPosition * navigator.geolocation.watchPosition * navigator.geolocation.clearWatch #### navigator.geolocation.getCurrentPosition `Position` オブジェクトを引数として使用して、`geolocationSuccess` コールバックに、端末の現在位置が渡されます。エラーが発生した場合、 `PositionError` オブジェクトが `geolocationError` コールバックに渡されます。 ```javascript navigator.geolocation.getCurrentPosition(geolocationSuccess, [geolocationError], [geolocationOptions]); ``` **パラメーター** * **geolocationSuccess**: 現在位置を渡して実行するコールバック * **geolocationError**: *( 任意 )* エラーが発生した場合に実行するコールバック * **geolocationOptions**: *( 任意 )* オプション **例** ```javascript // onSuccess Callback // This method accepts a Position object, which contains the // current GPS coordinates // var onSuccess = function(position) { alert('Latitude: ' + position.coords.latitude + '\n' + 'Longitude: ' + position.coords.longitude + '\n' + 'Altitude: ' + position.coords.altitude + '\n' + 'Accuracy: ' + position.coords.accuracy + '\n' + 'Altitude Accuracy: ' + position.coords.altitudeAccuracy + '\n' + 'Heading: ' + position.coords.heading + '\n' + 'Speed: ' + position.coords.speed + '\n' + 'Timestamp: ' + position.timestamp + '\n'); }; // onError Callback receives a PositionError object // function onError(error) { alert('code: ' + error.code + '\n' + 'message: ' + error.message + '\n'); } navigator.geolocation.getCurrentPosition(onSuccess, onError); ``` **iOS 特有の動作** iOS 10以降、プライバシーに関連するデータにアクセスする場合は、 `info.plist` に使用の説明を設定することが必須になります。アクセスを許可するようにシステムに指示すると、この使用の説明はアクセス許可ダイアログボックスの一部として表示されますが、使用の説明を入力しない場合は、ダイアログが表示される前にアプリが強制終了します。また、Apple は個人データにアクセスするアプリをリジェクトしますが、使用の説明は提供していません。 このプラグインでは、次の使用の説明が必要になります。 * `NSLocationWhenInUseUsageDescription` では、アプリがユーザーの場所にアクセスする理由を記述します。 これらの設定を `info.plist` に追加するには、`config.xml` ファイルの `` タグに以下のように設定します。 ```markup need location access to find things nearby ``` **Android 特有の動作** このプラグインは、Androidデバイス上でGPSハードウェアを必要とするため、GPSハードウェアがないデバイスでは、アプリを実行することができません。 アプリでこのプラグインを使用したいが、デバイス上で実際のGPSハードウェアを必要としない場合は、変数 `GPS_REQUIRED` をfalseに設定してプラグインをインストールしてください。 ``` cordova plugin add cordova-plugin-geolocation --variable GPS_REQUIRED="false" ``` 位置情報の取得サービスがオフにされた場合、`timeout` に設定された時間の経過後 ( 設定されている場合 )、`onError` コールバックが実行されます。`timeout` が設定されていない場合、コールバックは実行されません。 #### navigator.geolocation.watchPosition 端末の位置の変化を検知したとき、最新の現在位置を返します。現在位置が変更された場合、`Position` オブジェクトを引数として使用し、 `geolocationSuccess` コールバックが実行されます。エラーが発生した場合、`PositionError` オブジェクトを引数として使用し、 `geolocationError` コールバックが実行されます。 ```javascript var watchId = navigator.geolocation.watchPosition(geolocationSuccess, [geolocationError], [geolocationOptions]); ``` **パラメーター** * **geolocationSuccess**: 現在位置を渡して実行するコールバック * **geolocationError**: *( 任意 )* エラーが発生した場合に実行するコールバック * **geolocationOptions**: *( 任意 )* オプション **戻り値** * **String**: watch id を返します。 watch id は、実行中の`watchPosition`を制御するときに使用します。位置の監視を停止する場合には、`navigator.geolocation.clearWatch`に、この watch id を渡します。 **例** ```javascript // onSuccess Callback function onSuccess(position) { var element = document.getElementById('geolocation'); element.innerHTML = 'Latitude: ' + position.coords.latitude + '
' + 'Longitude: ' + position.coords.longitude + '
' + '
' + element.innerHTML; } // onError Callback receives a PositionError object function onError(error) { alert('code: ' + error.code + '\n' + 'message: ' + error.message + '\n'); } // Options: throw an error if no update is received every 30 seconds. var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { timeout: 30000 }); ``` #### geolocationOptions `Position` の 「 取得 」 処理をカスタマイズするための任意のパラメーターです。 ```javascript { maximumAge: 3000, timeout: 5000, enableHighAccuracy: true }; ``` **オプション** * **enableHighAccuracy**: より精度の高い位置情報をアプリが必要としていることを、このオプションを使用して示します。デフォルトでは、ネットワーク関連の情報を使用して、`Position` の取得を行っています。このプロパティを `true` にした場合、より精度の高い方法 ( 例 ： 衛星測位情報 ) を使用するよう、フレームワークに対して命令します。 *(Boolean)* * **timeout**: `navigator.geolocation.getCurrentPosition` または`geolocation.watchPosition` を呼んでから、 対応する `geolocationSuccess` コールバックを実行するまでの最長待ち時間 ( ミリ秒 )。 `geolocationSuccess` コールバックを、この時間内に呼べない場合、 `PositionError.TIMEOUT` エラーコードが `geolocationError` コールバックに渡されます ( 注意 : `geolocation.watchPosition` と共に使用したとき、 `timeout` に設定したミリ秒単位間隔で、`geolocationError` コールバックを呼び出すことになる場合もあります )。 *(Number)* * **maximumAge**: キャッシュ内に置かれた、有効期間内 ( ミリ秒単位で指定 ) の位置情報のみ使用します。 *(Number)* **Android 特有の動作** 位置情報の取得サービスがオフにされた場合、`timeout` に設定された時間の経過後 ( 設定されている場合 )、`onError` コールバックが実行されます。`timeout` が設定されていない場合、コールバックは実行されません。 #### navigator.geolocation.clearWatch `watchID` パラメーターを使用して、端末の現在位置の監視を停止します。 ```javascript navigator.geolocation.clearWatch(watchID); ``` **パラメーター** * **watchID**: 停止する、実行中の `watchPosition` の id です。(String) **例** ```javascript // Options: watch for changes in position, and use the most // accurate position acquisition method available. // var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { enableHighAccuracy: true }); // ...later on... navigator.geolocation.clearWatch(watchID); ``` ### オブジェクト ( 読み取り専用 ) * Position * PositionError * Coordinates #### Position geolocation API 側で作成した、座標 ( coords ) とタイムスタンプ ( timestamp ) を格納するオブジェクトです。 **プロパティ** * **coords**: 地理座標 *(Coordinates)* * **timestamp**: `coords` を作成したときのタイムスタンプ*(DOMTimeStamp)* #### Coordinates `Coordinates` オブジェクトは、ドット ( 「 . 」 ) を使用して、`Position` オブジェクトに連結させて使用できます。連結させたオブジェクトは、現在位置を取得したリクエストのコールバック関数内で使用できます。このオブジェクトには、現在位置の座標を示したプロパティが格納されています。 **プロパティ** * **latitude**: 10 進法形式で示す緯度 *(Number)* * **longitude**: 10 進法形式で示す経度 *(Number)* * **altitude**: メートル単位で示す楕円体高 ( ellipsoid height )*(Number)* * **accuracy**: メートル単位で示す座標 ( 緯度と経度 ) の精度*(Number)* * **altitudeAccuracy**: メートル単位で示す楕円体高の精度 *(Number)* * **heading**: 真方位を基準とする時計回りの方位角を使用した進行方向*(Number)* * **speed**: 1秒あたりのスピードをメートル単位で示す、端末の現在の対地速度*(Number)* **Android 特有の動作** **altitudeAccuracy**: Android 端末では使用できません。 `null` を返します。 #### PositionError navigator.geolocation でエラーが起きた場合、`PositionError` オブジェクトが、`geolocationError` に渡されます。 **プロパティ** * **code**: 次のエラーコードのいずれか * **message**: エラーの詳細を記したメッセージ **定数** * `PositionError.PERMISSION_DENIED`: アプリによる位置情報の取得をユーザーが許可しなかった場合、このコードを返します。 プラットフォームにより、動作が異なります。 * `PositionError.POSITION_UNAVAILABLE`: 位置情報の取得を行えない場合、このコードを返します。一般的には、ネットワークに接続していない場合または衛星の「 Fix 」 が得られない場合が考えられます。 * `PositionError.TIMEOUT`: `geolocationOptions` の `timeout` で指定した時間内に、位置情報を取得できない場合、このコードを返します。`navigator.geolocation.watchPosition` と共に使用した場合、`timeout` で指定した時間になる度に、`geolocationError` コールバックに、このエラーコードが渡されることになります。 `geolocationOptions` の `timeout` で指定した時間内に、位置情報を取得できない場合、このコードを返します。`navigator.geolocation.watchPosition` と共に使用した場合、`timeout` で指定した時間になる度に、`geolocationError` コールバックに、このエラーコードが渡されることになります。