# Geolocation プラグイン

テスト環境 ( バージョン番号 ) :[4.0.2](https://github.com/apache/cordova-plugin-geolocation/releases/tag/4.0.2)

このプラグインの詳細は、 [こちらの原文 ( GitHub )](https://github.com/apache/cordova-plugin-geolocation) をご確認ください。

このプラグインは、緯度や経度などのデバイスの場所に関する情報を提供します。

一般的な位置情報源には、GPS、IPアドレス、RFID、WiFi、Bluetooth MACアドレス、GSM / CDMAセルIDなどのネットワーク信号から推測される位置情報などがあります。 なお、この API が返す結果が、端末の正しい位置を示す保証はありません。

この API は [W3C Geolocation API の仕様 ( 外部サイト )](http://dev.w3.org/geo/api/spec-source.html) に準拠しています。

このプラグインは、グローバルな `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)にします。

### 対象プラットフォーム

* Android
* iOS

### 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` ファイルの `<edit-config>` タグに以下のように設定します。

```markup
<edit-config target="NSLocationWhenInUseUsageDescription" file="*-Info.plist" mode="merge">
    <string>need location access to find things nearby</string>
</edit-config>
```

**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
//   This method accepts a `Position` object, which contains
//   the current GPS coordinates
//
function onSuccess(position) {
    var element = document.getElementById('geolocation');
    element.innerHTML = 'Latitude: '  + position.coords.latitude      + '<br />' +
                        'Longitude: ' + position.coords.longitude     + '<br />' +
                        '<hr />'      + 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` を作成したときのタイムスタン&#x30D7;*(DOMTimeStamp)*

#### Coordinates

`Coordinates` オブジェクトは、ドット ( 「 . 」 ) を使用して、`Position` オブジェクトに連結させて使用できます。連結させたオブジェクトは、現在位置を取得したリクエストのコールバック関数内で使用できます。このオブジェクトには、現在位置の座標を示したプロパティが格納されています。

**プロパティ**

* **latitude**: 10 進法形式で示す緯度 *(Number)*
* **longitude**: 10 進法形式で示す経度 *(Number)*
* **altitude**: メートル単位で示す楕円体高 ( ellipsoid height )*(Number)*
* **accuracy**: メートル単位で示す座標 ( 緯度と経度 ) の精&#x5EA6;*(Number)*
* **altitudeAccuracy**: メートル単位で示す楕円体高の精度 *(Number)*
* **heading**: 真方位を基準とする時計回りの方位角を使用した進行方&#x5411;*(Number)*
* **speed**: 1秒あたりのスピードをメートル単位で示す、端末の現在の対地速&#x5EA6;*(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` コールバックに、このエラーコードが渡されることになります。

## サンプル

このプラグインを使用すると、Groupon のお得な情報、販売用の住宅、映画の再生、スポーツやエンターテイメントのイベントなど、近くのものを見つけるのに役立ちます。

ここにアイデアの "料理本" があります。 以下のサンプルでは、これらの機能をアプリに追加するための基本的な方法をいくつか紹介します。

* [座標を取得する](/reference/core-cordova-plugins/cordova_10.0/geolocation.md#wosuru)
* [天気予報を入手する](/reference/core-cordova-plugins/cordova_10.0/geolocation.md#wosuru-1)
* [ドライブしたときに更新された天気予報を受信する](/reference/core-cordova-plugins/cordova_10.0/geolocation.md#doraibushitatokinisaretawosuru)
* [地図上のどこにいるか見る](/reference/core-cordova-plugins/cordova_10.0/geolocation.md#nodokoniirukaru)
* [近くのお店を探す](/reference/core-cordova-plugins/cordova_10.0/geolocation.md#kunoowosu)
* [周りのものの写真を見る](/reference/core-cordova-plugins/cordova_10.0/geolocation.md#rinomononoworu)

### 座標を取得する

```javascript
function getWeatherLocation() {

    navigator.geolocation.getCurrentPosition
    (onWeatherSuccess, onWeatherError, { enableHighAccuracy: true });
}
```

### 天気予報を入手する

```javascript
// Success callback for get geo coordinates

var onWeatherSuccess = function (position) {

    Latitude = position.coords.latitude;
    Longitude = position.coords.longitude;

    getWeather(Latitude, Longitude);
}

// Get weather by using coordinates

function getWeather(latitude, longitude) {

    // Get a free key at http://openweathermap.org/. Replace the "Your_Key_Here" string with that key.
    var OpenWeatherAppKey = "Your_Key_Here";

    var queryString =
      'http://api.openweathermap.org/data/2.5/weather?lat='
      + latitude + '&lon=' + longitude + '&appid=' + OpenWeatherAppKey + '&units=imperial';

    $.getJSON(queryString, function (results) {

        if (results.weather.length) {

            $.getJSON(queryString, function (results) {

                if (results.weather.length) {

                    $('#description').text(results.name);
                    $('#temp').text(results.main.temp);
                    $('#wind').text(results.wind.speed);
                    $('#humidity').text(results.main.humidity);
                    $('#visibility').text(results.weather[0].main);

                    var sunriseDate = new Date(results.sys.sunrise);
                    $('#sunrise').text(sunriseDate.toLocaleTimeString());

                    var sunsetDate = new Date(results.sys.sunrise);
                    $('#sunset').text(sunsetDate.toLocaleTimeString());
                }

            });
        }
    }).fail(function () {
        console.log("error getting location");
    });
}

// Error callback

function onWeatherError(error) {
    console.log('code: ' + error.code + '\n' +
        'message: ' + error.message + '\n');
}
```

### ドライブしたときに更新された天気予報を受信する

```javascript
// Watch your changing position

function watchWeatherPosition() {

    return navigator.geolocation.watchPosition
    (onWeatherWatchSuccess, onWeatherError, { enableHighAccuracy: true });
}

// Success callback for watching your changing position

var onWeatherWatchSuccess = function (position) {

    var updatedLatitude = position.coords.latitude;
    var updatedLongitude = position.coords.longitude;

    if (updatedLatitude != Latitude && updatedLongitude != Longitude) {

        Latitude = updatedLatitude;
        Longitude = updatedLongitude;

        // Calls function we defined earlier.
        getWeather(updatedLatitude, updatedLongitude);
    }
}
```

### 地図上のどこにいるか見る

BingとGoogleの両方に地図サービスがあります。 今回は、Googleを使用します。 鍵が必要ですが、無料で試すことができます。

\**maps*\* サービスへの参照を追加します。

```javascript
<script src="https://maps.googleapis.com/maps/api/js?key=Your_API_Key"></script>
```

次に、それを使用するコードを追加します。

```javascript
var Latitude = undefined;
var Longitude = undefined;

// Get geo coordinates

function getMapLocation() {

    navigator.geolocation.getCurrentPosition
    (onMapSuccess, onMapError, { enableHighAccuracy: true });
}

// Success callback for get geo coordinates

var onMapSuccess = function (position) {

    Latitude = position.coords.latitude;
    Longitude = position.coords.longitude;

    getMap(Latitude, Longitude);

}

// Get map by using coordinates

function getMap(latitude, longitude) {

    var mapOptions = {
        center: new google.maps.LatLng(0, 0),
        zoom: 1,
        mapTypeId: google.maps.MapTypeId.ROADMAP
    };

    map = new google.maps.Map
    (document.getElementById("map"), mapOptions);


    var latLong = new google.maps.LatLng(latitude, longitude);

    var marker = new google.maps.Marker({
        position: latLong
    });

    marker.setMap(map);
    map.setZoom(15);
    map.setCenter(marker.getPosition());
}

// Success callback for watching your changing position

var onMapWatchSuccess = function (position) {

    var updatedLatitude = position.coords.latitude;
    var updatedLongitude = position.coords.longitude;

    if (updatedLatitude != Latitude && updatedLongitude != Longitude) {

        Latitude = updatedLatitude;
        Longitude = updatedLongitude;

        getMap(updatedLatitude, updatedLongitude);
    }
}

// Error callback

function onMapError(error) {
    console.log('code: ' + error.code + '\n' +
        'message: ' + error.message + '\n');
}

// Watch your changing position

function watchMapPosition() {

    return navigator.geolocation.watchPosition
    (onMapWatchSuccess, onMapError, { enableHighAccuracy: true });
}
```

### 近くのお店を探す

これには同じGoogleから取得した鍵を使用できます。

**places** サービスへの参照を追加します。

```javascript
<script src=
"https://maps.googleapis.com/maps/api/js?key=Your_API_Key&libraries=places">
</script>
```

次に、それを使用するコードを追加します。

```javascript
var Map;
var Infowindow;
var Latitude = undefined;
var Longitude = undefined;

// Get geo coordinates

function getPlacesLocation() {
    navigator.geolocation.getCurrentPosition
    (onPlacesSuccess, onPlacesError, { enableHighAccuracy: true });
}

// Success callback for get geo coordinates

var onPlacesSuccess = function (position) {

    Latitude = position.coords.latitude;
    Longitude = position.coords.longitude;

    getPlaces(Latitude, Longitude);

}

// Get places by using coordinates

function getPlaces(latitude, longitude) {

    var latLong = new google.maps.LatLng(latitude, longitude);

    var mapOptions = {

        center: new google.maps.LatLng(latitude, longitude),
        zoom: 15,
        mapTypeId: google.maps.MapTypeId.ROADMAP

    };

    Map = new google.maps.Map(document.getElementById("places"), mapOptions);

    Infowindow = new google.maps.InfoWindow();

    var service = new google.maps.places.PlacesService(Map);
    service.nearbySearch({

        location: latLong,
        radius: 500,
        type: ['store']
    }, foundStoresCallback);

}

// Success callback for watching your changing position

var onPlacesWatchSuccess = function (position) {

    var updatedLatitude = position.coords.latitude;
    var updatedLongitude = position.coords.longitude;

    if (updatedLatitude != Latitude && updatedLongitude != Longitude) {

        Latitude = updatedLatitude;
        Longitude = updatedLongitude;

        getPlaces(updatedLatitude, updatedLongitude);
    }
}

// Success callback for locating stores in the area

function foundStoresCallback(results, status) {

    if (status === google.maps.places.PlacesServiceStatus.OK) {

        for (var i = 0; i < results.length; i++) {

            createMarker(results[i]);

        }
    }
}

// Place a pin for each store on the map

function createMarker(place) {

    var placeLoc = place.geometry.location;

    var marker = new google.maps.Marker({
        map: Map,
        position: place.geometry.location
    });

    google.maps.event.addListener(marker, 'click', function () {

        Infowindow.setContent(place.name);
        Infowindow.open(Map, this);

    });
}

// Error callback

function onPlacesError(error) {
    console.log('code: ' + error.code + '\n' +
        'message: ' + error.message + '\n');
}

// Watch your changing position

function watchPlacesPosition() {

    return navigator.geolocation.watchPosition
    (onPlacesWatchSuccess, onPlacesError, { enableHighAccuracy: true });
}
```

### 周りのものの写真を見る

デジタル写真には、写真の撮影場所を特定する地理座標が含まれています。

Flickr API を使用すると、あなたの近くで撮影した写真を見つけることができます。 Google サービスと同様に鍵が必要ですが、無料で試すことができます。

```javascript
var Latitude = undefined;
var Longitude = undefined;

// Get geo coordinates

function getPicturesLocation() {

    navigator.geolocation.getCurrentPosition
    (onPicturesSuccess, onPicturesError, { enableHighAccuracy: true });

}

// Success callback for get geo coordinates

var onPicturesSuccess = function (position) {

    Latitude = position.coords.latitude;
    Longitude = position.coords.longitude;

    getPictures(Latitude, Longitude);
}

// Get pictures by using coordinates

function getPictures(latitude, longitude) {

    $('#pictures').empty();

    var queryString =
    "https://api.flickr.com/services/rest/?method=flickr.photos.search&api_key=Your_API_Key&lat="
    + latitude + "&lon=" + longitude + "&format=json&jsoncallback=?";

    $.getJSON(queryString, function (results) {
        $.each(results.photos.photo, function (index, item) {

            var photoURL = "http://farm" + item.farm + ".static.flickr.com/" +
                item.server + "/" + item.id + "_" + item.secret + "_m.jpg";

            $('#pictures').append($("<img />").attr("src", photoURL));

           });
        }
    );
}

// Success callback for watching your changing position

var onPicturesWatchSuccess = function (position) {

    var updatedLatitude = position.coords.latitude;
    var updatedLongitude = position.coords.longitude;

    if (updatedLatitude != Latitude && updatedLongitude != Longitude) {

        Latitude = updatedLatitude;
        Longitude = updatedLongitude;

        getPictures(updatedLatitude, updatedLongitude);
    }
}

// Error callback

function onPicturesError(error) {

    console.log('code: ' + error.code + '\n' +
        'message: ' + error.message + '\n');
}

// Watch your changing position

function watchPicturePosition() {

    return navigator.geolocation.watchPosition
    (onPicturesWatchSuccess, onPicturesError, { enableHighAccuracy: true });
}
```

関連項目:

* [サードパーティー製プラグイン](/reference/third_party_phonegap.md)
* [基本プラグイン](/reference/core-cordova-plugins.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ja.docs.monaca.io/reference/core-cordova-plugins/cordova_10.0/geolocation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.