Geolocation
El objeto
geolocation
proporciona acceso al sensor GPS del dispositivo.
La API Geolocation proporciona información sobre la localización del dispositivo, como la latitud y la longitud. Los orígenes de datos sobre localización pueden ser el Global Position System (GPS) o la localización obtenida por medio de la red, como la dirección IP, RFID, dirección MAC de dispositivos WiFi/Bluetooth, y los IDs de células GSM/CDMA. No hay garantía de que la API retorne la localización actual.
Esta API esta basada en la W3C Geo location API Specification. Algunos dispositivos ya incluyen una implementación de esta API. En esos dispositivos se usara la API incluida en vez de la PhoneGap. Para dispositivos que no tienen soporte de geolocalización, La implementación PhoneGap debe ser compatible con las especificaciones W3C.
Métodos
Argumentos
Objetos (Solo Lectura)
geolocation.getCurrentPosition
Retorna la geolocalización actual en un objeto Position
.
navigator.geolocation.getCurrentPosition(geolocationSuccess,
[geolocationError],
[geolocationOptions]);
Argumentos
- geolocationSuccess: La función 'callback' que sera llamada con la posición actual.
- geolocationError: (Opcional) la función 'callback' que sera llamada si ocurriera un error.
- geolocationOptions: (Opcional) Opciones de geolocalización.
Descripción
La función geolocation.getCurrentPositon
es asíncrona. Retornara la actual posición del dispositivo a la función 'callback' geolocationSuccess
con el objeto Position
como argumento. Si ocurriese un error, se llamara a geolocationError
pasándole el objeto PositionError
como argumento.
Plataformas Soportadas
- Android
- BlackBerry (OS 4.6)
- BlackBerry WebWorks (OS 5.0 y superior)
- iPhone
Ejemplo Rápido
// función 'callback' onSuccess
// Este método acepta objeto un objeto `Position`
// que contiene las coordenadas GPS actuales.
//
var onSuccess = function(position) {
alert('Latitud: ' + position.coords.latitude + '\n' +
'Longitud: ' + position.coords.longitude + '\n' +
'Altitud: ' + position.coords.altitude + '\n' +
'Precisión: ' + position.coords.accuracy + '\n' +
'Precisión altitud' + position.coords.altitudeAccuracy + '\n' +
'Dirección: ' + position.coords.heading + '\n' +
'Velocidad: ' + position.coords.speed + '\n' +
'Timestamp: ' + new Date(position.timestamp) + '\n');
};
// La función 'callback' onError recibe un objeto `PositionError`.
//
function onError(error) {
alert('código: ' + error.code + '\n' +
'mensaje: ' + error.message + '\n');
}
navigator.geolocation.getCurrentPosition(onSuccess, onError);
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de Geolocation</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Espere a que PhoneGap se inicie
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap esta listo
//
function onDeviceReady() {
navigator.geolocation.getCurrentPosition(onSuccess, onError);
}
// onSuccess Geolocation
//
function onSuccess(position) {
var element = document.getElementById('geolocation');
element.innerHTML = 'Latitud: ' + position.coords.latitude + '<br />' +
'Longitud: ' + position.coords.longitude + '\n' +
'Altitud: ' + position.coords.altitude + '\n' +
'Precisión: ' + position.coords.accuracy + '\n' +
'Precisión altitud' + position.coords.altitudeAccuracy + '\n' +
'Dirección: ' + position.coords.heading + '\n' +
'Velocidad: ' + position.coords.speed + '\n' +
'Timestamp: ' + new Date(position.timestamp) + '\n');
}
// La función 'callback' onError recibe un objeto `PositionError`.
//
function onError(error) {
alert('código: ' + error.code + '\n' +
'mensaje: ' + error.message + '\n');
}
</script>
</head>
<body>
<p id="geolocation">Buscando geolocalización...</p>
</body>
</html>
geolocation.watchPosition
Observa los cambios en la actual geolocalización del dispositivo.
var watchId = navigator.geolocation.watchPosition(geolocationSuccess,
[geolocationError],
[geolocationOptions]);
Argumentos
- geolocationSuccess: La función 'callback' a la que se le entregara la posición actual.
- geolocationError: (Opcional) La función 'callback' que sera llamada si ocurriera un error.
- geolocationOptions: (Opcional) Opciones de geolocalización.
Retorna
-
String: Un ID es retornado por la función, ese ID apunta a este observador de geolocalización, puedes usarlo en la función
geolocation.clearWatch
para dejar de observar la geolocalización.
Descripción
La función geolocation.watchPosition
es una función asíncrona. Esta función retorna la actual posición cada vez que se detecta un cambio. Cuando el dispositivo retorna la nueva localización, automáticamente llamara a la función geolocationSuccess
pasándole el argumento Position
. Si en caso contrario hubiera un error, se llamaría a la función geolocationError
y se le pasara el objeto PositionError
.
Plataformas Soportadas
- Android
- BlackBerry (OS 4.6)
- BlackBerry WebWorks (OS 5.0 y superior)
- iPhone
Ejemplo Rápido
// Función 'callback' onSuccess
// Esta función acepta un argumento del tipo `Position`,
// quien contiene las coordenadas GPS actuales.
//
function onSuccess(position) {
var element = document.getElementById('geolocation');
element.innerHTML = 'Latitud: ' + position.coords.latitude + '<br />' +
'Longitud: ' + position.coords.longitude + '<br />' +
'<hr />' + element.innerHTML;
}
// Función 'callback' onError. Esta función recibe un objeto PositionError.
//
function onError(error) {
alert('código: ' + error.code + '\n' +
'mensaje: ' + error.message + '\n');
}
// Opciones: retorna la geolocalización cada 3 segundos
//
var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { frequency: 3000 });
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de Geolocation</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Espere a que PhoneGap se inicie
//
document.addEventListener("deviceready", onDeviceReady, false);
var watchID = null;
// PhoneGap esta lista
//
function onDeviceReady() {
// Actualizar cada 3 segundos
var options = { frequency: 3000 };
watchID = navigator.geolocation.watchPosition(onSuccess, onError, options);
}
// Función onSuccess
//
function onSuccess(position) {
var element = document.getElementById('geolocation');
element.innerHTML = 'Latitude: ' + position.coords.latitude + '<br />' +
'Longitude: ' + position.coords.longitude + '<br />' +
'<hr />' + element.innerHTML;
}
// Función onError
//
function onError(error) {
alert('código: ' + error.code + '\n' +
'mensaje: ' + error.message + '\n');
}
</script>
</head>
<body>
<p id="geolocation">Observando geolocalización...</p>
</body>
</html>
geolocation.clearWatch
Deja de observar los cambios en la geolocalización (Geolocation
) con ese watchID
.
navigator.geolocation.clearWatch(watchID);
Argumentos
-
watchID: El ID retornado por
geolocation.watchPosition
. (String)
Descripción
La función geolocation.clearWatch
interrumpe el observador de localización al que apunta el watchID
que se le pasa por argumento.
Plataformas Soportadas
- Android
- BlackBerry (OS 4.6)
- BlackBerry WebWorks (OS 5.0 y superior)
- iPhone
Ejemplo Rápido
// Opciones: Recuperar la localización cada 3 segundos
//
var watchID = navigator.geolocation.watchPosition(onSuccess, onError, { frequency: 3000 });
// ...mas tarde...
navigator.geolocation.clearWatch(watchID);
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de Geolocation</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Espera a que PhoneGap se inicie
//
document.addEventListener("deviceready", onDeviceReady, false);
var watchID = null;
// PhoneGap esta listo
//
function onDeviceReady() {
// Actualiza cada 3 segundos
var options = { frequency: 3000 };
watchID = navigator.geolocation.watchPosition(onSuccess, onError, options);
}
// onSuccess Geolocation
//
function onSuccess(position) {
var element = document.getElementById('geolocation');
element.innerHTML = 'Latitud: ' + position.coords.latitude + '<br />' +
'Longitud: ' + position.coords.longitude + '<br />' +
'<hr />' + element.innerHTML;
}
// Para el observador que acaba de iniciarse
//
function clearWatch() {
if (watchID != null) {
navigator.geolocation.clearWatch(watchID);
watchID = null;
}
}
// La función 'callback' onError recibe un objeto `PositionError`.
//
function onError(error) {
alert('código: ' + error.code + '\n' +
'mensaje: ' + error.message + '\n');
}
</script>
</head>
<body>
<p id="geolocation">Observando Geolocalización...</p>
<button onclick="clearWatch();">Dejar de observar</button>
</body>
</html>
Coordinates
Un conjunto de atributos que describe las coordenadas geográficas de una posición.
Argumentos
- latitude: Latitud en grados decimales. (Number)
- longitude: Longitud en grados decimales. (Number)
- altitude: Altura de la posición en metros por encima del elipsoide. (Number)
- accuracy: Nivel de precisión (en metros) de la latitud y longitud. (Number)
- altitudeAccuracy: Nivel de precisión (en metros) de la altitud. (Number)
- heading: Dirección de travesía (en grados) contando como las agujas del reloj y relativo al norte (real). (Number)
- speed: Velocidad actual del dispositivo (metros por segundo). (Number)
Descripción
El objeto Coordinates
es creado y compuesto por PhoneGap, y atribuido al objeto Position
. El objeto Position
es entonces retornado al usuario mediante una función 'callback'.
Plataformas Soportadas
- Android
- BlackBerry (OS 4.6)
- BlackBerry WebWorks (OS 5.0 y superior)
- iPhone
Ejemplo Rápido
// Función 'callback' onSuccess
//
var onSuccess = function(position) {
alert('Latitud: ' + position.coords.latitude + '\n' +
'Longitud: ' + position.coords.longitude + '\n' +
'Altitud: ' + position.coords.altitude + '\n' +
'Precisión: ' + position.coords.accuracy + '\n' +
'Precisión Altitud: ' + position.coords.altitudeAccuracy + '\n' +
'Dirección: ' + position.coords.heading + '\n' +
'Velocidad: ' + position.coords.speed + '\n' +
'Timestamp: ' + new Date(position.timestamp) + '\n');
};
// Función 'callback' onError
//
var onError = function() {
alert('onError!');
};
navigator.geolocation.getCurrentPosition(onSuccess, onError);
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de Geolocation</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Espere a que PhoneGap se inicie
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap esta listo
//
function onDeviceReady() {
navigator.geolocation.getCurrentPosition(onSuccess, onError);
}
// Muestra los atributos de `Position`.
//
function onSuccess(position) {
var div = document.getElementById('myDiv');
div.innerHTML = 'Latitud: ' + position.coords.latitude + '<br/>' +
'Longitud: ' + position.coords.longitude + '<br/>' +
'Altitud: ' + position.coords.altitude + '<br/>' +
'Precisión: ' + position.coords.accuracy + '<br/>' +
'Precisión Altitud: ' + position.coords.altitudeAccuracy + '<br/>' +
'Dirección: ' + position.coords.heading + '<br/>' +
'Velocidadd: ' + position.coords.speed + '<br/>';
}
// Muestra una alerta si ocurre un problema obteniendo la geolocalización
//
function onError() {
alert('onError!');
}
</script>
</head>
<body>
<div id="myDiv"></div>
</body>
</html>
Peculiaridades Android
altitudeAccuracy: Este atributo no esta soportado en dispositivos Android, y siempre retornara null
.
Position
Contiene las coordenadas que fueron creados por la API Geolocation.
Atributos
- coords: Un conjunto de coordenadas geográficas. (Coordinates)
- timestamp: Un registro de la fecha y hora cuando se crearon las coordenadas (en milisegundos). (DOMTimeStamp)
Descripción
El objeto Position
es creado y distribuido por PhoneGap, luego es retornado al usuario a través de una función 'callback'.
Plataformas Soportadas
- Android
- BlackBerry (OS 4.6)
- BlackBerry WebWorks (OS 5.0 y superior)
- iPhone
Ejemplo Rápido
// Función 'callback' onSuccess
//
var onSuccess = function(position) {
alert('Latitud: ' + position.coords.latitude + '\n' +
'Longitud: ' + position.coords.longitude + '\n' +
'Altitud: ' + position.coords.altitude + '\n' +
'Precisión: ' + position.coords.accuracy + '\n' +
'Precisión Altitud: ' + position.coords.altitudeAccuracy + '\n' +
'Dirección: ' + position.coords.heading + '\n' +
'Velocidad: ' + position.coords.speed + '\n' +
'Timestamp: ' + new Date(position.timestamp) + '\n');
};
// La función 'callback' onError recibe un objeto `PositionError`.
//
function onError(error) {
alert('código: ' + error.code + '\n' +
'mensaje: ' + error.message + '\n');
}
navigator.geolocation.getCurrentPosition(onSuccess, onError);
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de Geolocation</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Espera a que PhoneGap se inicie
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap esta listo
//
function onDeviceReady() {
navigator.geolocation.getCurrentPosition(onSuccess, onError);
}
// Función 'callback' onSuccess
//
function onSuccess(position) {
var element = document.getElementById('geolocation');
element.innerHTML = 'Latitud: ' + position.coords.latitude + '<br />' +
'Longitud: ' + position.coords.longitude + '<br />' +
'Altitud: ' + position.coords.altitude + '<br />' +
'Precisión: ' + position.coords.accuracy + '<br />' +
'Precisión Altitud: ' + position.coords.altitudeAccuracy + '<br />' +
'Dirección: ' + position.coords.heading + '<br />' +
'Velocidad: ' + position.coords.speed + '<br />' +
'Timestamp: ' + new Date(position.timestamp) + '<br />';
}
// La función 'callback' onError recibe un objeto `PositionError`.
//
function onError(error) {
alert('código: ' + error.code + '\n' +
'mensaje: ' + error.message + '\n');
}
</script>
</head>
<body>
<p id="geolocation">Buscando geolocalización...</p>
</body>
</html>
peculiaridades iPhone
- timestamp: Usa segundos en vez de milisegundos.
Una solución a mano seria convertirlo a milisegundos (x 1000):
var onSuccess = function(position) {
alert('Latitud: ' + position.coords.latitude + '\n' +
'Longitud: ' + position.coords.longitude + '\n' +
'Timestamp: ' + new Date(position.timestamp * 1000) + '\n');
};
PositionError
Un objeto PositionError
es retornado por la función 'callback' geolocationError
cada vez que ocurre un error.
Atributos
- code: Uno de los códigos de error predefinidos en la lista inferior.
- message: Mensaje describiendo el motivo del error.
Constantes
PositionError.PERMISSION_DENIED
PositionError.POSITION_UNAVAILABLE
PositionError.TIMEOUT
Descripción
El objeto PositionError
es retornado al usuario por medio de la función 'callback' geolocationError
cada vez que ocurre un error en la geolocalización.
geolocationSuccess
La función 'callback' que sera llamada pasándole los datos de geolocalización.
function(position) {
// Hacer algo
}
Argumentos
Ejemplo
function geolocationSuccess(position) {
alert('Latitud: ' + position.coords.latitude + '\n' +
'Longitud: ' + position.coords.longitude + '\n' +
'Altitud: ' + position.coords.altitude + '\n' +
'Precisión: ' + position.coords.accuracy + '\n' +
'Precisión Altitud: ' + position.coords.altitudeAccuracy + '\n' +
'Dirección: ' + position.coords.heading + '\n' +
'Velocidad: ' + position.coords.speed + '\n' +
'Timestamp: ' + new Date(position.timestamp) + '\n');
}
geolocationError
La función 'callback' que sera llamada cuando ocurra un error en los métodos de la API de geolocalización.
function(error) {
// Maneja el error
}
Argumentos
-
error: El error retornado por el dispositivo. (
PositionError
)
geolocationOptions
Parámetros opcionales para personalizar la obtención de la geolocalización.
{ maximumAge: 3000, timeout: 5000, enableHighAccuracy: true };
Opciones
- frequency: Cada cuanto obtener la posición (en milisegundos). Esta opción no pertenece a las especificaciones W3C y sera eliminado en el futuro. Debería usarse maximumAge en su lugar. (Number) (Por defecto: 10000)
- enableHighAccuracy: Indica que la aplicación debe recibir los solo los resultados mas precisos. (Boolean)
-
timeout: El tiempo máximo de espera (milisegundos) que los métodos
geolocation.getCurrentPosition
ygeolocation.watchPosition
pueden esperar mientras se obtienen los datos y se llama ageolocationSuccess
. (Number) - maximumAge: El tiempo máximo de vida (milisegundos) que se permite en tener una posición en memoria cache. (Number)
Peculiaridades Android
Los emuladores Android 2.x no retornaran ningún resultado de geolocalización a menos que la opción enableHighAccuracy sea true
.
{ enableHighAccuracy: true }