Geolocation

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

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

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

Retorna

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

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

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

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

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

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

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

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

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

Constantes

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


geolocationOptions

Parámetros opcionales para personalizar la obtención de la geolocalización.

{ maximumAge: 3000, timeout: 5000, enableHighAccuracy: true };

Opciones

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 }