diff options
Diffstat (limited to 'StoneIsland/plugins/cordova-plugin-geolocation/README.md')
| -rw-r--r--[-rwxr-xr-x] | StoneIsland/plugins/cordova-plugin-geolocation/README.md | 479 |
1 files changed, 472 insertions, 7 deletions
diff --git a/StoneIsland/plugins/cordova-plugin-geolocation/README.md b/StoneIsland/plugins/cordova-plugin-geolocation/README.md index eb10b9f8..77a3c9a7 100755..100644 --- a/StoneIsland/plugins/cordova-plugin-geolocation/README.md +++ b/StoneIsland/plugins/cordova-plugin-geolocation/README.md @@ -1,3 +1,7 @@ +--- +title: Geolocation +description: Access GPS data. +--- <!-- # license: Licensed to the Apache Software Foundation (ASF) under one # or more contributor license agreements. See the NOTICE file @@ -17,17 +21,23 @@ # under the License. --> -# cordova-plugin-geolocation +|Android|iOS| Windows 8.1 Store | Windows 8.1 Phone | Windows 10 Store | Travis CI | +|:-:|:-:|:-:|:-:|:-:|:-:| +|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=android,PLUGIN=cordova-plugin-geolocation/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=ios,PLUGIN=cordova-plugin-geolocation/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-8.1-store,PLUGIN=cordova-plugin-geolocation/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-8.1-phone,PLUGIN=cordova-plugin-geolocation/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-10-store,PLUGIN=cordova-plugin-geolocation/)|[](https://travis-ci.org/apache/cordova-plugin-geolocation)| -[](https://travis-ci.org/apache/cordova-plugin-geolocation) +# cordova-plugin-geolocation This plugin provides information about the device's location, such as -latitude and longitude. Common sources of location information include +latitude and longitude. + +Common sources of location information include Global Positioning System (GPS) and location inferred from network signals such as IP address, RFID, WiFi and Bluetooth MAC addresses, and GSM/CDMA cell IDs. There is no guarantee that the API returns the device's actual location. +> To get a few ideas, check out the [sample](#sample) at the bottom of this page or go straight to the [reference](#reference) content. + This API is based on the [W3C Geolocation API Specification](http://dev.w3.org/geo/api/spec-source.html), and only executes on devices that don't already provide an implementation. @@ -45,7 +55,7 @@ accesses geolocation data (if the device operating system doesn't do so already). That notice should provide the same information noted above, as well as obtaining the user's permission (e.g., by presenting choices for __OK__ and __No Thanks__). For more information, please -see the Privacy Guide. +see the [Privacy Guide](http://cordova.apache.org/docs/en/latest/guide/appdev/privacy/index.html). This plugin defines a global `navigator.geolocation` object (for platforms where it is otherwise missing). @@ -53,11 +63,15 @@ where it is otherwise missing). Although the object is in the global scope, features provided by this plugin are not available until after the `deviceready` event. +```javascript + document.addEventListener("deviceready", onDeviceReady, false); function onDeviceReady() { console.log("navigator.geolocation works well"); } +``` +## <a id="reference"></a>Reference ## Installation This requires cordova 5.0+ ( current stable 1.0.0 ) @@ -81,7 +95,6 @@ It is also possible to install via repo url directly ( unstable ) - iOS - Tizen - Windows Phone 7 and 8 -- Windows 8 - Windows ## Methods @@ -118,6 +131,8 @@ error, the `geolocationError` callback is passed a ### Example +```javascript + // onSuccess Callback // This method accepts a Position object, which contains the // current GPS coordinates @@ -142,6 +157,13 @@ error, the `geolocationError` callback is passed a navigator.geolocation.getCurrentPosition(onSuccess, onError); +``` + +### Android Quirks + +If Geolocation service is turned off the `onError` callback is invoked after `timeout` interval (if specified). +If `timeout` parameter is not specified then no callback is called. + ## navigator.geolocation.watchPosition Returns the device's current position when a change in position is detected. @@ -168,6 +190,8 @@ there is an error, the `geolocationError` callback executes with a ### Example +```javascript + // onSuccess Callback // This method accepts a `Position` object, which contains // the current GPS coordinates @@ -190,6 +214,7 @@ there is an error, the `geolocationError` callback executes with a // var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { timeout: 30000 }); +``` ## geolocationOptions @@ -208,7 +233,8 @@ Optional parameters to customize the retrieval of the geolocation ### Android Quirks -Android 2.x emulators do not return a geolocation result unless the `enableHighAccuracy` option is set to `true`. +If Geolocation service is turned off the `onError` callback is invoked after `timeout` interval (if specified). +If `timeout` parameter is not specified then no callback is called. ## navigator.geolocation.clearWatch @@ -223,6 +249,8 @@ Stop watching for changes to the device's location referenced by the ### Example +```javascript + // Options: watch for changes in position, and use the most // accurate position acquisition method available. // @@ -232,6 +260,8 @@ Stop watching for changes to the device's location referenced by the navigator.geolocation.clearWatch(watchID); +``` + ## Position Contains `Position` coordinates and timestamp, created by the geolocation API. @@ -240,7 +270,7 @@ Contains `Position` coordinates and timestamp, created by the geolocation API. - __coords__: A set of geographic coordinates. _(Coordinates)_ -- __timestamp__: Creation timestamp for `coords`. _(Date)_ +- __timestamp__: Creation timestamp for `coords`. _(DOMTimeStamp)_ ## Coordinates @@ -291,3 +321,438 @@ callback function when an error occurs with navigator.geolocation. - Returned when the device is unable to retrieve a position. In general, this means the device is not connected to a network or can't get a satellite fix. - `PositionError.TIMEOUT` - Returned when the device is unable to retrieve a position within the time specified by the `timeout` included in `geolocationOptions`. When used with `navigator.geolocation.watchPosition`, this error could be repeatedly passed to the `geolocationError` callback every `timeout` milliseconds. + + +## <a id="sample"></a>Sample: Get the weather, find stores, and see photos of things nearby with Geolocation ## + +Use this plugin to help users find things near them such as Groupon deals, houses for sale, movies playing, sports and entertainment events and more. + +Here's a "cookbook" of ideas to get you started. In the snippets below, we'll show you some basic ways to add these features to your app. + +* [Get your coordinates](#coords). +* [Get the weather forecast](#weather). +* [Receive updated weather forecasts as you drive around](#receive). +* [See where you are on a map](#see). +* [Find stores near you](#find). +* [See pictures of things around you](#see). + +## <a id="coord"></a>Get your geolocation coordinates + +```javascript + +function getWeatherLocation() { + + navigator.geolocation.getCurrentPosition + (onWeatherSuccess, onWeatherError, { enableHighAccuracy: true }); +} + +``` +## <a id="weather"></a>Get the weather forecast + +```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'); +} + +``` + +## <a id="receive"></a>Receive updated weather forecasts as you drive around + +```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); + } +} + +``` + +## <a id="see"></a>See where you are on a map + +Both Bing and Google have map services. We'll use Google's. You'll need a key but it's free if you're just trying things out. + +Add a reference to the **maps** service. + +```HTML + + <script src="https://maps.googleapis.com/maps/api/js?key=Your_API_Key"></script> + +``` +Then, add code to use it. + +```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 }); +} + +``` + +## <a id="find"></a>Find stores near you + +You can use the same Google key for this. + +Add a reference to the **places** service. + +```HTML + +<script src= +"https://maps.googleapis.com/maps/api/js?key=Your_API_Key&libraries=places"> +</script> + +``` + +Then, add code to use it. + +```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 }); +} + +``` + +## <a id="pictures"></a>See pictures of things around you + +Digital photos can contain geo coordinates that identify where the picture was taken. + +Use Flickr API's to find pictures that folks have taken near you. Like Google services, you'll need a key, but it's free if you just want to try things out. + +```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 }); +} + +``` |