La API de Maps JavaScript te permite personalizar los mapas con tus propias imágenes y contenido para mostrarlos en páginas web y dispositivos móviles. La API de Maps JavaScript cuenta con cuatro tipos de mapas básicos (mapa de rutas, satélite, híbrido y terreno), los cuales puedes modificar mediante capas y diseños, controles y eventos, y varios servicios y bibliotecas.
Público
Esta documentación está diseñada para las personas que están familiarizadas con la programación en JavaScript y los conceptos de programación orientada a objetos. También debes estar familiarizado con Google Maps como usuario. Hay muchos instructivos de JavaScript disponibles en la Web.
Esta documentación conceptual está diseñada para que puedas comenzar rápidamente a explorar y desarrollar aplicaciones con la API de Maps JavaScript. También publicamos la referencia de la API de Maps JavaScript.
Hello World
La forma más fácil de comenzar a aprender sobre la API de Maps JavaScript es con un ejemplo simple. En el siguiente ejemplo, se muestra un mapa centrado en Sídney, Nueva Gales del Sur, Australia.TypeScript
let map: google.maps.Map;
function initMap(): void {
map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
center: { lat: -34.397, lng: 150.644 },
zoom: 8,
});
}
declare global {
interface Window {
initMap: () => void;
}
}
window.initMap = initMap;
JavaScript
let map;
function initMap() {
map = new google.maps.Map(document.getElementById("map"), {
center: { lat: -34.397, lng: 150.644 },
zoom: 8,
});
}
window.initMap = initMap;
CSS
/*
* Always set the map height explicitly to define the size of the div element
* that contains the map.
*/
#map {
height: 100%;
}
/*
* Optional: Makes the sample page fill the window.
*/
html,
body {
height: 100%;
margin: 0;
padding: 0;
}
HTML
<html>
<head>
<title>Simple Map</title>
<script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
</head>
<body>
<div id="map"></div>
<!--
The `defer` attribute causes the callback to execute after the full HTML
document has been parsed. For non-blocking uses, avoiding race conditions,
and consistent behavior across browsers, consider loading using Promises
with https://www.npmjs.com/package/@googlemaps/js-api-loader.
-->
<script
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
defer
></script>
</body>
</html>
Prueba la muestra
Incluso en este ejemplo simple, debes tener en cuenta algunos aspectos:
- Se declara la aplicación como HTML5 mediante la declaración
<!DOCTYPE html>. - Se crea un elemento
divllamado "map" para que contenga el mapa. - Se define una función de JavaScript que crea un mapa en el
div. - Se carga la API de Maps JavaScript con una etiqueta
script.
Estos pasos se explican a continuación.
Cómo declarar tu aplicación como HTML5
Te recomendamos que declares un DOCTYPE verdadero en tu aplicación web. En estos ejemplos, declaramos nuestras aplicaciones como HTML5 con la declaración DOCTYPE HTML5 simple, como se muestra a continuación:
<!DOCTYPE html>
La mayoría de los navegadores actuales renderizarán el contenido declarado con este DOCTYPE en el "modo estándar", lo que significa que tu aplicación tendrá una mayor compatibilidad en varios navegadores. El DOCTYPE también está diseñado para degradarse gradualmente. Los navegadores que no lo comprendan lo ignorarán y usarán el "modo no estándar" para mostrar su contenido.
Ten en cuenta que parte del código CSS que funciona en el modo no estándar no es válido en el modo estándar. En términos específicos, todos los tamaños basados en porcentajes deben heredar sus valores de elementos de bloque primarios y, si cualquiera de estos elementos principales no especifica un tamaño, se supondrá que tienen un tamaño de 0 x 0 píxeles. Por ese motivo, incluimos la siguiente declaración <style>:
<style>
#map {
height: 100%;
}
html, body {
height: 100%;
margin: 0;
padding: 0;
}
</style>
Esta declaración de CSS indica que el contenedor de mapa <div> (con el ID map) debe ocupar el 100% de la altura del cuerpo HTML. Ten en cuenta que también se deben declarar de forma específica esos porcentajes para <body> y <html>.
Cómo cargar la API de Maps JavaScript
La API de Maps JavaScript se carga con una etiquetascript, que se puede agregar de forma intercalada en tu archivo HTML o de forma dinámica con un archivo JavaScript independiente. Te recomendamos que revises ambos enfoques y elijas el más adecuado para la forma en que se estructura el código de tu proyecto.
Carga intercalada
Para cargar la API de Maps JavaScript de forma intercalada en un archivo HTML, agrega una etiqueta script, como se muestra a continuación.
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>
Carga dinámica
Para cargar dinámicamente la API de Maps JavaScript de forma intercalada en un archivo JavaScript independiente, consulta el siguiente ejemplo. Este enfoque te permite controlar todo el código para trabajar con la API desde un archivo .js independiente y equivale a agregar la etiqueta de secuencia de comandos de forma intercalada.
// Create the script tag, set the appropriate attributes
var script = document.createElement('script');
script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap';
script.async = true;
// Attach your callback function to the `window` object
window.initMap = function() {
// JS API is loaded and available
};
// Append the 'script' element to 'head'
document.head.appendChild(script);
Carga dinámica
El paquete @googlemaps/js-api-loader está diseñado para ayudar a que la experiencia de carga dinámica sea más sencilla. Se puede instalar a través de NPM con lo siguiente:
npm install @googlemaps/js-api-loader
Este paquete se puede importar a la aplicación con lo siguiente:
import { Loader } from "@googlemaps/js-api-loader"
El cargador expone una promesa y una interfaz de devolución de llamada. A continuación, se muestra el uso del método de promesa predeterminado load().
TypeScript
const loader = new Loader({
apiKey: "YOUR_API_KEY",
version: "weekly",
...additionalOptions,
});
loader.load().then(() => {
map = new google.maps.Map(document.getElementById("map") as HTMLElement, {
center: { lat: -34.397, lng: 150.644 },
zoom: 8,
});
});
JavaScript
const loader = new Loader({
apiKey: "YOUR_API_KEY",
version: "weekly",
...additionalOptions,
});
loader.load().then(() => {
map = new google.maps.Map(document.getElementById("map"), {
center: { lat: -34.397, lng: 150.644 },
zoom: 8,
});
});
Atributos de la etiqueta de secuencia de comandos
En los ejemplos anteriores, puede ver que se configuraron varios atributos en la etiqueta script, lo cual está recomendado. A continuación, se incluye una explicación de cada atributo.
src: Es la URL desde la que se carga la API de Maps JavaScript, incluidos todos los símbolos y las definiciones que necesitas para usar la API de Maps JavaScript. La URL de este ejemplo tiene dos parámetros:key, en el que proporcionas tu clave de API, ycallback, en el que especificas el nombre de una función global a la que se debe llamar una vez que la API de Maps JavaScript se cargue completamente. Obtén más información acerca de los parámetros de URL.async: Solicita al navegador que descargue y ejecute la secuencia de comandos de manera asíncrona. Cuando se ejecute la secuencia de comandos, llamará a la función especificada mediante el parámetrocallback.
Bibliotecas
Cuando cargues la API de Maps JavaScript mediante la URL, tienes la opción de cargar bibliotecas adicionales mediante el parámetro de URL libraries. Las bibliotecas son módulos de código que proporcionan una funcionalidad adicional a la API de Maps JavaScript principal, pero no se cargan a menos que lo solicites específicamente. Para obtener más información, consulta el artículo Bibliotecas de la API de Maps JavaScript.
Cómo cargar la API de manera síncrona
En la etiqueta script que carga la API de Maps JavaScript, se pueden omitir el atributo defer y el parámetro callback. Esto hará que se bloquee la carga de la API hasta que se complete la descarga.
Esto probablemente demore la carga de tu página. No obstante, significa que puedes escribir etiquetas de secuencia de comando posteriormente sabiendo que la API ya está cargada.
Elementos del DOM del mapa
<div id="map"></div>
A fin de que el mapa aparezca en una página web, se debe reservar un lugar para él.
Por lo general, se crea un elemento div con nombre y se obtiene una referencia a este elemento en el modelo de objetos del documento (DOM) del navegador.
En el ejemplo anterior, se usó código CSS para establecer la altura del elemento div del mapa en "100%". De esta manera, el mapa se expande para adecuar su tamaño en dispositivos móviles. Es posible que debas ajustar los valores de ancho y altura según el tamaño de la pantalla y el padding del navegador. Ten en cuenta que los elementos div generalmente obtienen su ancho del elemento que los contiene, y que el valor de altura de los elementos div vacíos suele ser de "0". Por este motivo, siempre debes configurar una altura en <div> de forma explícita.
Opciones de mapas
Hay dos opciones obligatorias para todos los mapas: center y zoom.
map = new google.maps.Map(document.getElementById('map'), {
center: {lat: -34.397, lng: 150.644},
zoom: 8
});
Niveles de zoom
La resolución inicial con la que se muestra el mapa se establece con la propiedad zoom, en la que el valor de zoom 0 corresponde a un mapa de la Tierra completamente alejado y los niveles de zoom más altos acercan el mapa con una resolución más alta.
zoom: 8
Para ofrecer un mapa de toda la Tierra en una sola imagen, se necesitaría un mapa enorme o un mapa muy pequeño con una resolución muy baja. Es por eso que las imágenes de mapas en Google Maps y la API de Maps JavaScript se dividen en "mosaicos" de mapas y "niveles de zoom". En los niveles de zoom bajos, un conjunto reducido de mosaicos de mapas abarca un área amplia. En los niveles de zoom superiores, los mosaicos tienen una resolución más alta y abarcan un área más reducida. En la siguiente lista, se muestra el nivel aproximado de detalle que puedes esperar ver en cada nivel de zoom:
- 1: Mundo
- 5: Tierra firme y continente
- 10: Ciudad
- 15: Calles
- 20: Edificios
Las tres imágenes que se incluyen a continuación reflejan la misma ubicación de Tokio con niveles de zoom 0, 7 y 18.
Para obtener información sobre cómo carga mosaicos la API de Maps JavaScript según el nivel de zoom, consulta la guía sobre coordenadas de mapas y de mosaicos.
El objeto Map
map = new google.maps.Map(document.getElementById("map"), {...});
La clase de JavaScript que representa un mapa es la clase Map.
Los objetos de esta clase definen un solo mapa en una página. (Puedes crear más de una instancia de esta clase; cada objeto definirá un mapa independiente en la página). Se crea una instancia nueva de esta clase con el operador new de JavaScript.
Cuando creas una nueva instancia de mapa, especificas un elemento HTML <div> en la página como un contenedor del mapa. Los nodos HTML son elementos secundarios del objeto document de JavaScript. Se obtiene una referencia a este elemento a través del método document.getElementById().
Este código define una variable (llamada map) y la asigna a un objeto Map nuevo. La función Map() se conoce como constructor y su definición se muestra a continuación:
| Constructor | Descripción |
|---|---|
Map(mapDiv:Node, opts?:MapOptions
) |
Crea un mapa nuevo dentro del contenedor HTML en cuestión, que suele ser un elemento DIV, mediante cualquier parámetro (opcional) que se haya pasado. |
Solución de problemas
Errores de la clave de API y la facturación
En determinadas circunstancias, es posible que se muestre un mapa oscuro, o una imagen "negativa" de Street View, que incluya una marca de agua con el texto "solo para fines de desarrollo". Este comportamiento generalmente indica que hay problemas con una clave de API o la facturación. Para usar los productos de Google Maps Platform, debes tener la facturación habilitada en tu cuenta y todas las solicitudes deben incluir una clave de API válida. El siguiente flujo de preguntas y respuestas te ayudará a solucionar el problema:
Si tu código no funciona:
Para ayudarte a lograr que tus códigos de mapas funcionen, Brendan Kenny y Mano Marks señalan algunos errores comunes y cómo corregirlos en este video.
- Busca errores de ortografía. Recuerda que JavaScript es un lenguaje que distingue mayúsculas de minúsculas.
- Verifica los puntos básicos. Algunos de los problemas más comunes se producen en el momento inicial de la creación de mapas. Por ejemplo:
- Confirma si especificaste las propiedades
zoomycenteren las opciones del mapa. - Asegúrate de haber declarado un elemento div según el cual el mapa aparecerá en la pantalla.
- Asegúrate de que se haya especificado una altura para el elemento div del mapa. De manera predeterminada, los elementos div se crean con una altura de 0, por lo que son invisibles.
- Confirma si especificaste las propiedades
- Usa un depurador de JavaScript para identificar problemas, como el que está disponible en las herramientas para desarrolladores de Chrome. Primero busca errores en la Consola de JavaScript.
- Publica tus preguntas en Stack Overflow. Los lineamientos para publicar preguntas de calidad están disponibles en la página de asistencia.