9- API Geolocation
Encontrando su lugar
La API Geolocation fue diseñada para que los navegadores puedan proveer un mecanismo
de detección por defecto que permita a los desarrolladores determinar la ubicación física
real del usuario. Previamente solo contábamos con la opción de construir una gran base
de datos con información sobre direcciones IP y programar códigos exigentes dentro del
servidor que nos darían una idea aproximada de la ubicación del usuario (generalmente
tan imprecisa como su país).
Esta API aprovecha nuevos sistemas, como triangulación de red y GPS, para retornar una
ubicación precisa del dispositivo que está accediendo a la aplicación. La valiosa información
retornada nos permite construir aplicaciones que se adaptarán a las particulares
necesidades del usuario o proveerán información localizada de forma automática.
Tres métodos específicos son provistos para usar la API:
getCurrentPosition(ubicación, error, configuración) Este es el método utilizado para
consultas individuales. Puede recibir hasta tres atributos: una función para procesar la
ubicación retornada, una función para procesar los errores retornados, y un objeto
para configurar cómo la información será adquirida. Solo el primer atributo es
obligatorio para que el método trabaje correctamente.
watchPosition(ubicación, error, configuración) Este método es similar al anterior, excepto
que comenzará un proceso de vigilancia para la detección de nuevas ubicaciones.
Trabaja de forma similar que el conocido método setInterval() de Javascript,
repitiendo el proceso automáticamente en determinados períodos de tiempo de
acuerdo a la configuración por defecto o a los valores de sus atributos.
clearWatch(id) El método watchPosition() retorna un valor que puede ser almacenado en
una variable para luego ser usado como referencia pro el método clearWatch() y así
detener la vigilancia. Este método es similar a clearInterval() usado para detener los
procesos comenzados por setInterval().
getCurrentPosition(ubicación)
Como dijimos, solo el primer atributo es requerido para que trabaje correctamente el
método getCurrentPosition(). Este atributo es una función que recibirá un objeto
llamado Position, el cual contiene toda la información retornada por los sistemas de
ubicación.
El objeto Position tiene dos atributos:
coords Este atributo contiene un grupo de valores que establecen la ubicación del
dispositivo y otros datos importantes. Los valores son accesibles a través de siete
atributos internos: latitude (latitud), longitude (longitud), altitude (altitud en
metros), accuracy (exactitud en metros), altitudeAccuracy (exactitud de la
altitud en metros), heading (dirección en grados) y speed (velocidad en metros por
segundo).
timestamp Este atributo indica el momento en el que la información fue adquirida (en
formato timestamp).
Este objeto, como dijimos, es pasado a la función que definimos como atributo del
método getCurrentPosition() y luego sus datos son accedidos y procesados en esta
función. Veamos un ejemplo práctico de cómo usar este método:
<!DOCTYPE html>
<html lang="es">
<head>
<title>Geolocation</title>
<script src="geolocation.js"></script>
</head>
<body>
<section id="ubicacion">
<button id="obtener">Obtener mi Ubicación</button>
</section>
</body>
</html>
Documento HTML para la API Geolocation.
El Listado 9-1 será nuestra plantilla HTML para el resto de este capítulo. Es lo más
elemental posible, con tan solo un elemento <button> dentro de un elemento
<section> que vamos a usar para solicitar y mostrar la información retornada por el
sistema de ubicación.
function iniciar(){
var boton=document.getElementById('obtener');
boton.addEventListener('click', obtener, false);
}
function obtener(){
navigator.geolocation.getCurrentPosition(mostrar);
}
function mostrar(posicion){
var ubicacion=document.getElementById('ubicacion');
var datos='';
datos+='Latitud: '+posicion.coords.latitude+'<br>';
datos+='Longitud: '+posicion.coords.longitude+'<br>';
datos+='Exactitud: '+posicion.coords.accuracy+'mts.<br>';
ubicacion.innerHTML=datos;
}
window.addEventListener('load', iniciar, false);
Obteniendo información sobre la localización del usuario.
Una implementación de la API Geolocation es sencilla: declaramos el método
getCurrentPosition() y creamos una función que mostrará los valores retornados por
el mismo. El método getCurrentPosition() es un método del objeto geolocation.
Este es un nuevo objeto que es parte del objeto navigator, un objeto Javascript que fue
anteriormente implementado para retornar información acerca del navegador y el sistema.
Por lo tanto, para acceder al método getCurrentPosition() la sintaxis a usar es
navigator.geolocation.getCurrentPosition(función), donde función es una
función personalizada que recibirá el objeto Position y procesará la información que
contiene.
En el código del Listado 9-2, llamamos a esta función mostrar(). Cuando el método
getCurrentPosition() es llamado, un nuevo objeto Position es creado con la
información de la ubicación actual del usuario y es enviado a la función mostrar().
Referenciamos este objeto dentro de la función con la variable posicion, y luego usamos
esta variable para mostrar los datos.
El objeto Position tiene dos importantes atributos: coords y timestamp. En
nuestro ejemplo solo usamos coords para acceder a la información que queremos
mostrar (latitud, longitud y exactitud). Estos valores son grabados en la variable datos y
luego mostrados en la pantalla como el nuevo contenido del elemento ubicacion.
Hágalo usted mismo: Cree archivos con los códigos de los Listados 9-1 y 9-2, suba
los archivos a su servidor y luego abra el documento HTML en su navegador.
Cuando haga clic en el botón, el navegador le preguntará si desea activar o no el
sistema de ubicación geográfica. Si le permite a la aplicación acceder a esta
información, entonces su ubicación, incluyendo longitud, latitud y exactitud, será
mostrada en pantalla.
getCurrentPosition(ubicación, error)
¿Pero qué ocurre si usted no permite al navegador acceder a información acerca de su
ubicación? Agregando un segundo atributo al método getCurrentPosition(), con otra
función, podremos capturar los errores producidos en el proceso. Uno de esos errores,
por supuesto, ocurre cuando el usuario no acepta compartir sus datos.
Junto con el objeto Position, el método getCurrentPosition() retorna el objeto
PositionError si un error es detectado. Este objeto es enviado al segundo atributo de
getCurrentPosition(), y tiene dos atributos internos, error y message, para proveer
el valor y la descripción del error. Los tres posibles errores son representados por las
siguientes constantes:
PERMISSION_DENIED (permiso denegado) - valor 1. Este error ocurre cuando el usuario
no acepta activar el sistema de ubicación para compartir su información.
POSITION_UNAVAILABLE (ubicación no disponible) - valor 2. Este error ocurre cuando la
ubicación del dispositivo no pudo determinarse por ninguno de los sistemas de
ubicación disponibles.
TIMEOUT (tiempo excedido) - valor 3. Este error ocurre cuando la ubicación no pudo ser
determinada en el período de tiempo máximo declarado en la configuración.
function iniciar(){
var boton=document.getElementById('obtener');
boton.addEventListener('click', obtener, false);
}
function obtener(){
navigator.geolocation.getCurrentPosition(mostrar, errores);
}
function mostrar(posicion){
var ubicacion=document.getElementById('ubicacion');
var datos='';
datos+='Latitud: '+posicion.coords.latitude+'<br>';
datos+='Longitud: '+posicion.coords.longitude+'<br>';
datos+='Exactitud: '+posicion.coords.accuracy+'mts.<br>';
ubicacion.innerHTML=datos;
}
function errores(error){
alert('Error: '+error.code+' '+error.message);
}
window.addEventListener('load', iniciar, false);
Mostrando mensajes de error.
Los mensajes de error son ofrecidos para uso interno. El propósito es ofrecer un
mecanismo para que la aplicación reconozca la situación y proceda de acuerdo al error
recibido. En el código del Listado 9-3, agregamos un segundo atributo al método
getCurrentPosition() (otra función) y creamos la función errores() para mostrar la
información de los atributos code y message. El valor de code será un número entre 0 y
3 de acuerdo al número de error (listado anteriormente).
El objeto PositionError es enviado a la función errores() y representado en esta
función por la variable error. Para propósitos didácticos, usamos un método alert() que
muestra los datos recibidos, pero usted debería procesar esta información en silencio, si es
posible, sin alertar al usuario de nada. Podemos también controlar por errores de forma
individual (error.PERMISSION_DENIED, por ejemplo) y actuar solo si ese error en particular
ocurrió.
getCurrentPosition(ubicación, error, configuración)
El tercer atributo que podemos usar en el método getCurrentPosition() es un objeto
conteniendo hasta tres posibles propiedades:
enableHighAccuracy Esta es una propiedad booleana para informar al sistema que
requerimos de la información más exacta que nos pueda ofrecer. El navegador intentará
obtener esta información a través de sistemas como GPS, por ejemplo, para retornar la
ubicación exacta del dispositivo. Estos son sistemas que consumen muchos recursos, por
lo que su uso debería estar limitado a circunstancias muy específicas. Para evitar
consumos innecesarios, el valor por defecto de esta propiedad es false (falso).
timeout Esta propiedad indica el tiempo máximo de espera para que la operación finalice.
Si la información de la ubicación no es obtenida antes del tiempo indicado, el error
TIMEOUT es retornado. Su valor es en milisegundos.
maximumAge Las ubicaciones encontradas previamente son almacenadas en un caché en
el sistema. Si consideramos apropiado recurrir a la información grabada en lugar de
intentar obtenerla desde el sistema (para evitar consumo de recursos o para una
respuesta rápida), esta propiedad puede ser declarada con un tiempo límite específico.
Si la última ubicación almacenada es más vieja que el valor de este atributo entonces
una nueva ubicación es solicitada al sistema. Su valor es en milisegundos.
function iniciar(){
var boton=document.getElementById('obtener');
boton.addEventListener('click', obtener, false);
}
function obtener(){
var geoconfig={
enableHighAccuracy: true,
timeout: 10000,
maximumAge: 60000
};
navigator.geolocation.getCurrentPosition(mostrar, errores,
geoconfig);
}
function mostrar(posicion){
var ubicacion=document.getElementById('ubicacion');
var datos='';
datos+='Latitud: '+posicion.coords.latitude+'<br>';
datos+='Longitud: '+posicion.coords.longitude+'<br>';
datos+='Exactitud: '+posicion.coords.accuracy+'mts.<br>';
ubicacion.innerHTML=datos;
}
function errores(error){
alert('Error: '+error.code+' '+error.message);
}
window.addEventListener('load', iniciar, false);
Configuración del sistema.
El código del Listado 9-4 intentará obtener la ubicación más exacta posible del
dispositivo en no más de 10 segundos, pero solo si no hay una ubicación previa en el caché
capturada menos de 60 segundos atrás (si existe una ubicación previa con menos de 60
segundos de antigüedad, éste será el objeto Position retornado).
El objeto conteniendo los valores de configuración fue creado primero y luego
referenciado desde el método getCurrentPosition(). Nada cambió en el resto del
código. La función mostrar() mostrará la información en la pantalla independientemente
de su origen (si proviene del caché o es nueva).
Conceptos básicos: Javascript provee diferentes formas de construir un objeto. Por
propósitos de claridad, elegimos crear el objeto primero, almacenarlo en la variable
geoconfig y luego usar esta referencia en el método getCurrentPosition().
Sin embargo, podríamos haber insertado el objeto directamente en el método
como un atributo. En aplicaciones pequeñas, objetos normalmente pueden ser
evitados, pero no es el caso de códigos más complejos. Para aprender más sobre
objetos y programación orientada a objetos en Javascript, visite nuestro sitio web y
siga los enlaces correspondientes a este capítulo.
Con el último código, podemos apreciar el propósito real de la API Geolocation y cuál
fue la intención de sus desarrolladores. Las funciones más efectivas y prácticas están
orientadas hacia dispositivos móviles. El valor true (verdadero) para la propiedad
enableHighAccuracy, por ejemplo, le solicitará al navegador usar sistemas como GPS
para obtener la ubicación más exacta posible (un sistema casi exclusivo de dispositivos
móviles), y los métodos watchPosition() y clearWatch(), que veremos a
continuación, trabajan sobre ubicaciones actualizadas constantemente, algo solo posible,
por supuesto, cuando el dispositivo que está accediendo la aplicación es móvil (y se está
moviendo). Esto trae a la luz dos asuntos importantes. Primero, la mayoría de nuestros
códigos tendrán que ser probados en un dispositivo móvil para saber exactamente cómo
trabajan en una situación real. Y segundo, deberemos ser responsables con el uso de esta
API. GPS y otros sistemas de localización consumen muchos recursos y en la mayoría de
los casos pueden acabar pronto con la batería del dispositivo si no somos cautelosos.
Con respecto al primer punto, disponemos de una alternativa. Simplemente visite el
enlace dev.w3.org/geo/api/test-suite/ y lea acerca de cómo experimentar y probar
Geolocation API. Con respecto al segundo punto, solo un consejo: configure la propiedad
enableHighAccuracy como true solo cuando es estrictamente necesario, y no abuse
de esta posibilidad.
watchPosition(ubicación, error, configuración)
Similar a getCurrentPosition(), el método watchPosition() recibe tres atributos y
realiza la misma tarea: obtener la ubicación del dispositivo que está accediendo a la
aplicación. La única diferencia es que el primero realiza una única operación, mientras que
watchPosition() ofrece nuevos datos cada vez que la ubicación cambia. Este método
vigilará todo el tiempo la ubicación y enviará información a la función correspondiente
cuando se detecte una nueva ubicación, a menos que cancelemos el proceso con el
método clearWatch().
Este es un ejemplo de cómo implementar el método watchPosition() basado en
códigos previos:
function iniciar(){
var boton=document.getElementById('obtener');
boton.addEventListener('click', obtener, false);
}
function obtener(){
var geoconfig={
enableHighAccuracy: true,
maximumAge: 60000
};
control=navigator.geolocation.watchPosition(mostrar, errores,
geoconfig);
}
function mostrar(posicion){
var ubicacion=document.getElementById('ubicacion');
var datos='';
datos+='Latitud: '+posicion.coords.latitude+'<br>';
datos+='Longitud: '+posicion.coords.longitude+'<br>';
datos+='Exactitud: '+posicion.coords.accuracy+'mts.<br>';
ubicacion.innerHTML=datos;
}
function errores(error){
alert('Error: '+error.code+' '+error.message);
}
window.addEventListener('load', iniciar, false);
Probando el método watchPosition().
No notará ningún cambio en un ordenador de escritorio usando este código, pero en
un dispositivo móvil nueva información será mostrada cada vez que haya una modificación
en la ubicación del dispositivo. El atributo maximumAge determina qué tan seguido la
información será enviada a la función mostrar(). Si la nueva ubicación es obtenida 60
segundos (60000 milisegundos) luego de la anterior, entonces será mostrada, en caso
contrario la función mostrar() no será llamada.
Note que el valor retornado por el método watchPosition() fue almacenado en la
variable control. Esta variable es como un identificador de la operación. Si más adelante
queremos cancelar el proceso de vigilancia, solo debemos ejecutar la línea
clearWatch(control) y watchPosition() dejará de actualizar la información.
Si ejecuta este código en un ordenador de escritorio, el método watchPosition()
funcionará como el anterior estudiado getCurrentPosition(); la información no será
actualizada. La función mostrar() es solo llamada cuando la ubicación cambia.
Usos prácticos con Google Maps
Hasta el momento hemos mostrado la información sobre la ubicación exactamente como
la recibimos. Sin embargo, estos valores normalmente no significan nada para la gente
común. La mayoría de nosotros no podemos inmediatamente decir cuál es nuestra actual
ubicación en valores de latitud y longitud, y mucho menos identificar a partir de estos
valores una ubicación en el mundo. Disponemos de dos alternativas: usar esta
información internamente para calcular posiciones, distancias y otros valores que nos
permitirán ofrecer resultados específicos a nuestros usuarios (como productos o servicios
en el área), o podemos ofrecer la información obtenida por medio de la API Geolocation
en un medio mucho más comprensible. ¿Y qué más comprensible que un mapa para
representar una ubicación geográfica?
Más atrás en este libro hablamos acerca de la API Google Maps. Esta es una API
Javascript externa, provista por Google, que nada tiene que ver con HTML5 pero es
incluida extraoficialmente dentro de la especificación y es ampliamente utilizada en sitios
webs modernos estos días. Ofrece una variedad de alternativas para trabajar con mapas
interactivos e incluso vistas reales de lugares muy específicos a través de la tecnología
StreetView.
Vamos a mostrar un ejemplo simple de utilización aprovechando una parte de la API
llamada Static Maps API. Con esta API específica, solo necesitamos construir una URL con
la información de la ubicación para obtener en respuesta la imagen de un mapa con el
área seleccionada.
function iniciar(){
var boton=document.getElementById('obtener');
boton.addEventListener('click', obtener, false);
}
function obtener(){
navigator.geolocation.getCurrentPosition(mostrar, errores);
}
function mostrar(posicion){
var ubicacion=document.getElementById('ubicacion');
var mapurl='https://maps.google.com/maps/api/staticmap?center='+
posicion.coords.latitude+','+posicion.coords.longitude+'&zoom=
12&size=400x400&sensor=false&markers='+posicion.coords.latitude+
','+posicion.coords.longitude;
ubicacion.innerHTML='<img src="'+mapurl+'">';
}
function errores(error){
alert('Error: '+error.code+' '+error.message);
}
window.addEventListener('load', iniciar, false);
Representando la ubicación en un mapa.
El código es simple. Usamos el método getCurrentPosition() y enviamos la
información a la función mostrar() como siempre, pero ahora en esta función los valores del
objeto Position son agregados a una URL de Google y luego la dirección obtenida es
insertada como la fuente de un elemento <img> para mostrar el mapa en pantalla.
Hágalo usted mismo: Pruebe el código del Listado 9-6 en su navegador usando la
plantilla del Listado 9-1. Cambie los valores de los atributos zoom y size en la URL
para modificar el mapa retornado por la API. Visite la página de Google Maps API para
estudiar las diferentes alternativas provistas por esta API: code.google.com/
apis/maps/.
Referencia rápida
Determinar la ubicación física del usuario se ha vuelto crítico en aplicaciones web
modernas. El reciente éxito de los dispositivos móviles ofrece nuevas posibilidades para
crear aplicaciones que aprovechan esta información.
Métodos
La API Geolocation provee tres métodos para obtener la ubicación de un dispositivo:
getCurrentPosition(ubicación, error, configuración) Este método retorna información
sobre la ubicación del dispositivo que está accediendo a la aplicación. El primer
atributo es una función destinada a procesar la información, el segundo atributo es
otra función para procesamiento de errores, y el tercer atributo es un objeto con
valores de configuración (vea Objeto Configuración debajo).
watchPosition(ubicación, error, configuración) Este método retorna información sobre la
ubicación del dispositivo que está accediendo a la aplicación cada vez que la ubicación
cambia. El primer atributo es una función destinada a procesar la información, el
segundo atributo es otra función para procesamiento de errores, y el tercer atributo es
un objeto con valores de configuración (vea Objeto Configuración debajo).
clearWatch(id) Este método cancela el proceso que ha sido empezado por el método
watchPosition(). El atributo id es el valor de identificación retornado por el método
watchPosition() cuando es llamado.
Objetos
Los métodos getCurrentPosition() y watchPosition() generan dos objetos para
comunicar la información retornada por el sistema de ubicación y el estado de la operación.
Objeto Position Este objeto es generado para contener la información acerca de la ubicación
detectada. Tiene dos atributos: coords y timestamp.
coords Este es un atributo del objeto Position. Tiene siete atributos internos para
retornar la información de la ubicación: latitude (latitud), longitude (longitud),
altitude (altitud en metros), accuracy (exactitud en metros),
altitudeAccuracy (exactitud de la altitud en metros), heading (dirección en
grados) y speed (velocidad en metros por segundo).
timestamp Este es un atributo del objeto Position. Retorna el momento en el que
la ubicación fue detectada.
Objeto PositionError Este objeto es generado cuando un error ocurre. Ofrece dos atributos
generales con el valor y el mensaje del error, y tres valores específicos para identificación
de errores individuales (listados debajo).
message Este es un atributo del objeto PositionError. Retorna un mensaje
describiendo el error detectado.
error Este es un atributo del objeto PositionError. Contiene el valor del error
detectado. Los posibles valores son listados debajo:
PERMISSION_DENIED (permiso denegado) - valor 1 en el atributo error. Esta
constante es true (verdadero) cuando el usuario no permite a la aplicación
acceder a la información sobre su ubicación.
POSITION_UNAVAILABLE (ubicación no disponible) - valor 2 en el atributo
error. Esta constante es true (verdadero) cuando la ubicación del dispositivo
no puede ser determinada.
TIMEOUT (tiempo excedido) - valor 3 en el atributo error. Esta constante es
true (verdadero) cuando la ubicación no puede ser determinada antes del
periodo de tiempo declarado en la configuración.
El siguiente objeto es requerido por los métodos getCurrentPosition() y
watchPosition() para propósitos de configuración.
Objeto Configuración Este objeto provee valores de configuración correspondientes para
los métodos getCurrentPosition() y watchPosition().
enableHighAccuracy Esta es una de las posibles propiedades del Objeto
Configuración. Si es declarada como true (verdadero), le solicitará al navegador
obtener la ubicación más precisa posible.
timeout Esta es una de las propiedades del Objeto Configuración. Indica el máximo
tiempo disponible que tiene la operación para realizarse.
maximumAge Esta es una de las propiedades del Objeto Configuración. Indica por
cuánto tiempo la última ubicación detectada será válida.