Introducción a Google Maps API v3: fundamentos
- ,
El documento HTML
Para crear nuestro primer mapa con la APIv3 de Google Maps necesitaremos crear un documento HTML. Este documento puede estar en XHTML o HTML5 (también en versiones anteriores) y debe tener una estructura mínima, similar a la que reproducimos a continuación:
<!DOCTYPE html>
<head>
<meta charset="utf-8">
<title>GoogleMaps APIv3</title>
</head>
<body>
<div id="map"></div>
</body>
</html>
En el ejemplo anterior y en el resto del tutorial, utilizaremos HTML5. El primero de los elementos es la declaración de tipo de documento (DOCTYPE) y se utiliza para explicarle al navegador cómo interpretar la página. En el caso de que quisiéramos utilizar XHTML la declaración de documento sería:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
El segundo de los elementos es la etiqueta <head>. Esta sección de la página contiene un serie de elementos muy importantes. En primer lugar encontramos la etiqueta <meta charset> que dice qué tipo de codificación de caracteres estamos utilizando. En este caso utilizaremos UTF-8, ya que incluye caracteres especiales para todos los idiomas. A continuación podemos observar la etiqueta <title>, que establece el título de la página web. Ambos son elementos obligatorios que debemos incluir en nuestro código para poder validar el documento.
Finalmente, la etiqueta <body> contiene los diferentes elementos que serán visibles en nuestra página web. En nuestro caso, de momento sólo tenemos un elemento <div> con el atributo id y el valor «map». Por si sólo, este elemento no mostrará nada, pero una vez creemos la hoja de estilo e incorporemos algo de JavaScript, el valor «map» nos ayudará a identificar y conectar los tres documentos (HTML, CSS y JavaScript).
La hoja de estilos
Para fijar el tamaño del mapa debemos establecer el estilo del elemento <div> que contendrá el mapa. El tamaño de este contenedor define el tamaño del mapa. Una buena práctica consiste en mantener separados el código HTML y el CSS, por lo tanto, crearemos otro archivo con extensión .css llamado «estilo.css». Además, para mantener una estructura ordenada, crearemos una carpeta con el nombre css en la que guardaremos las diferentes hojas de estilo que vayamos creando.
Vamos a trabajar con un mapa que ocupe todo el ancho de la página y 500 píxels de alto. Además, agregaremos un borde de 1 píxel de color negro a nuestro contenedor.
#map {
width: 100%;
height: 500px;
border: 1px solid #000;
}
Una vez creado el fichero CSS con los estilos, es necesario hacer una referencia en el archivo HTML apuntando al archivo CSS. Esta referencia se hace con el elemento <link> dentro de la sección <head>. Aprovecharemos también, para definir el idioma de nuestra página con la etiqueta <html lang=»es»>:
<!DOCTYPE html>
<html lang="es">
<head>
<meta charset="utf-8">
<link type="text/css" href="css/estilo.css" rel="stylesheet" media="all" />
<title>GoogleMaps APIv3</title>
</head>
<body>
<div id="map"></div>
</body>
</html>
Referencia a la API de Google Maps
Desde octubre de 2016, es necesario obtener una clave de API para poder acceder a los servicios de la API de Google Maps. Aquellos sitios o aplicaciones que no la venían utilizando han ido viendo progresivamente como les aparecía el error “MissingKeyMapError”. Más información en la entrada Cómo obtener una clave API para Google Maps.
La API de Google Maps se encuentra alojada en los servidores de Google. Para poder cargar la API de Google Maps debemos hacer una referencia desde nuestro archivo HTML hacia el lugar en el que se encuentra ésta. La referencia se ha de incluir en la sección <head> del documento. La cargaremos con el elemento <script>. Este elemento tiene dos atributos que debemos utilizar. El primero es el tipo de script que deseamos utilizar y el otro es la URL que apunta a la API.
<!DOCTYPE html>
<html lang="es">
<head>
<meta charset="utf-8">
<link type="text/css" href="css/estilo.css" rel="stylesheet" media="all" />
<script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=false"></script>
<title>GoogleMaps APIv3</title>
</head>
<body>
<div id="map"></div>
</body>
</html>Sensor
La API de Google Maps requiere que se indique si la aplicación que estamos creando utiliza algún tipo de sensor, por ejemplo para determinar la ubicación del usuario a través de un localizador de GPS. Esto es especialmente útil en las aplicaciones pensadas para dispositivos móviles. En nuestro caso no utilizaremos ningún tipo de sensor por lo que el valor utilizado será «false». En caso contrario utilizaríamos el valor «true»
Localización (idioma)
La API de Google Maps intentará determinar automáticamente qué idioma utiliza la interfaz de usuario. No obstante, también podemos indicarlo en el <script> que hemos utilizado para referenciar la API de Google Maps. Para hacerlo, debemos añadir el parámetro (opcional) &language=»codigo_del_idioma» al final de la cadena:
<script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=false&language=es"></script>Localización (región)
Al cargar la API de Google Maps desde maps.googleapis.com se aplica un sesgo por defecto hacia los Estados Unidos. Si deseamos modificar este comportamiento predeterminado, lo podemos hacer mediante la adición de un nuevo parámetro a la etiqueta <script>: «region». Los valores válidos para este parámetro son los de la ISO 3166-1 alpha-2 code. El valor para España es «ES».
<script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=false®ion=ES"></script>Crear nuestro primer mapa
Ahora que ya tenemos nuestro fichero HTML vinculado a la API de Google Maps y a la hoja de estilos, ya podemos empezar a escribir código JavaScript para inicializar nuestro mapa. De la misma manera que con las hojas de estilo, también es una buena práctica separar el código JavaScript de nuestro HTML. Así que crearemos un fichero llamado «map.js» y lo guardaremos en una carpeta con nombre «js».
Una vez creada esa estructura, debemos referenciar el fichero «map.js» desde nuestra página HTML. Para ello, utilizaremos de nuevo la etiqueta <script>, pero esta vez referenciando un fichero ubicado en nuestro PC o servidor:
<!DOCTYPE html>
<html lang="es">
<head>
<meta charset="utf-8">
<link type="text/css" href="css/estilo.css" rel="stylesheet" media="all" />
<script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=false&language=es"></script>
<script type="text/javascript" src="js/map.js"></script>
<title>GoogleMaps APIv3</title>
</head>
<body>
<div id="map"></div>
</body>
</html>La posición de esta nueva etiqueta no es trivial. Debe estar ubicada a continuación de la referencia a la API de Google Maps, y no antes. De esta manera nos aseguramos de que la API de Google Maps sea cargada antes de que la página HTML intente usarla.
El contenedor del Mapa
Llegados a este punto, inicializaremos un mapa dentro del <div> que anteriormente habíamos creado en nuestra página HTML. Para ello, haremos una referencia desde nuestro fichero «map.js», utilizando el método «document.getElementById()». Este método busca el ID de un elemento HTML y devuelve una referencia al mismo elemento. Es imporante tener en cuenta que un mismo ID sólo puede ser utilizado una vez por página. En el caso de que no se pueda encontrar el ID indicado, el valor devuelto será «null» o lo que es lo mismo, nada.
Crearemos una variable llamada mapDiv usando el método getElementById() referenciando nuestro <div id=»map»>:
var mapDiv = document.getElementById('map');El objeto «mapOptions» es necesario y define las propiedades de visualización del mapa. Por lo tanto, crearemos una variable llamada «options» con las tres propiedades mínimas necesarias para que el mapa funcione:
- center: Define el centro del mapa mediante unas coordenadas.
- zoom: Define el nivel inicial de zoom del mapa. Debe ser un número comprendido entre 1 y 23.
- mapTypeId: Define el tipo de mapa que será cargado inicialmente. Los diferentes tipos de mapas los encontramos en el objeto google.maps.MapTypeId. Por ejemplo, google.maps.MapTypeId.ROADMAP o google.maps.MapTypeId.SATELLITE.
Antes de proporcionar los valores a nuestra variable «options», prepararemos los valores de la propiedad «center» mediante el objeto google.maps.LatLng:
var catalunya = new google.maps.LatLng(41.652393,1.691895);En esta variable hemos grabado las coordenadas de Cataluña, mediante las cuales centraremos posteriormente nuestro mapa en esa posición.
A continuación ya podemos añadir las tres opciones comentadas anteriormente:
var mapDiv = document.getElementById('map');
var catalunya = new google.maps.LatLng(41.652393,1.691895);
var options = {
center: catalunya,
zoom: 8,
mapTypeId: google.maps.MapTypeId.ROADMAP
};Como se puede observar en el código anterior, hemos utilizado el valor de la variable «catalunya» para establecer el centro de nuestro mapa, hemos establecido un nivel de 8 a nuestro zoom, y finalmente, hemos escogido el tipo de mapa ROADMAP como mapa que debe cargarse por defecto.
La propiedad «center» también la podemos definir utilizando directamente el objeto «google.maps.LatLng»:
var mapDiv = document.getElementById('map');
var options = {
center: new google.maps.LatLng(41.652393,1.691895),
zoom: 8,
mapTypeId: google.maps.MapTypeId.ROADMAP
};Ahora que ya hemos hecho referencia al elemento <div> mediante el «mapDiv» y hemos establecido las diferentes opciones, sólo nos falta pasarlas al objeto «Map»:
var mapa = new google.maps.Map(mapDiv, options);Ahora que lo tenemos todo, sólo nos queda poner en marcha el código cuando la página cargue. Para ello, abriremos y cerraremos el código de la siguiente manera:
window.onload = function() {
// Aquí el código que deseamos cargar
}El resultado final es:
window.onload = function() {
var mapDiv = document.getElementById('map');
var catalunya = new google.maps.LatLng(41.652393,1.691895);
var options = {
center: catalunya,
zoom: 8,
mapTypeId: google.maps.MapTypeId.ROADMAP
};
var mapa = new google.maps.Map(mapDiv, options);
}
Muy bueno. Pregunta ¿Cómo se puede insertar un marcador?