Recientes

Seleccionar plataforma: Android iOS JavaScript

La API de Maps JavaScript te permite personalizar mapas con imágenes y contenido propios para mostrarlos en páginas web y dispositivos móviles. La API de Maps JavaScript cuenta con cuatro tipos básicos de mapas (mapa de rutas, satélite, híbrido y terreno) que puedes modificar mediante capas y estilos, controles y eventos, y varios servicios y bibliotecas.

Público

Esta documentación está diseñada para personas que estén familiarizadas con la programación en JavaScript y los conceptos de programación orientados a objetos. También debes estar familiarizado con Google Maps desde el punto de vista del usuario. Hay muchos instructivos de JavaScript disponibles en la Web.

Esta documentación conceptual está diseñada para que puedas comenzar a explorar y desarrollar aplicaciones rápidamente 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 ver un ejemplo simple. En el ejemplo siguiente 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>
Ver ejemplo

Probar la muestra

Incluso en este ejemplo simple, deben observarse algunos aspectos:

  1. Declaramos la aplicación como HTML5 mediante la declaración <!DOCTYPE html>.
  2. Creamos un elemento div llamado"map"para que contenga el mapa.
  3. Se define una función de JavaScript que crea un mapa en div.
  4. Cargamos la API de Maps JavaScript con una etiqueta script.

Estos pasos se explican a continuación:

Declarar tu aplicación como HTML5

Te recomendamos que declares un verdadero DOCTYPE dentro de tu aplicación web. En los ejemplos de esta página, declaramos nuestras aplicaciones como HTML5 con la DOCTYPE HTML5 simple, como se muestra a continuación:

<!DOCTYPE html>

La mayoría de los navegadores actuales procesarán contenido que se declare con este DOCTYPE en modo estándar, lo que significa que tu aplicación debe ser más compatible con varios navegadores. El DOCTYPE también está diseñado para degradarse de forma controlada; los navegadores que no lo entienden lo ignorarán y usarán el"modo de interpretación"para mostrar su contenido.

Ten en cuenta que algunos CSS que funcionan dentro del modo de interpretación no son válidos en el modo estándar. En concreto, todos los tamaños basados en porcentajes deben heredar elementos de bloque superiores y, si alguno de esos principales no especifica un tamaño, se supone 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 debemos declarar específicamente esos porcentajes para <body> y <html>.

Cómo cargar la API de Maps JavaScript

La API de Maps JavaScript se carga con una etiqueta script, que se puede agregar intercalado 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.

Cargando en línea

Para cargar la API de Maps JavaScript 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 la API de Maps JavaScript de forma dinámica 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 la secuencia de comandos 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á disponible para una experiencia de carga dinámica más fluida. 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:

import { Loader } from "@googlemaps/js-api-loader"

El cargador expone una interfaz de devolución de llamada y promesa. A continuación, se muestra el uso del método predeterminado de promesa 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

Observa en los ejemplos anteriores que se establecen varios atributos en la etiqueta script, que se recomiendan. La siguiente es 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, y callback, en el que especificas el nombre de una función global que se llamará una vez que la API de Maps JavaScript se cargue por completo. Obtenga 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ámetro callback.

Bibliotecas

Cuando cargues la API de Maps JavaScript mediante la URL, también puedes 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 Bibliotecas en la API de Maps JavaScript.

Carga 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 la carga de la API se bloquee hasta que esta se descargue.

Probablemente se demore la carga de tu página. Sin embargo, significa que puedes escribir etiquetas de secuencia de comandos posteriores suponiendo que la API ya está cargada.

Elementos de DOM de mapas

<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, esto se hace creando un elemento div con nombre y obteniendo una referencia a este en el modelo de objeto de documento (DOM) del navegador.

En el ejemplo anterior, usamos CSS para establecer la altura del div del mapa en "100%". Con esto se producirá una expansión para adecuar el tamaño en dispositivos móviles. Es posible que debas ajustar los valores de ancho y alto según el tamaño de pantalla y el relleno del navegador. Ten en cuenta que los divs generalmente toman su ancho del elemento que los contiene y que, por lo general, tienen un valor de altura de 0. Por este motivo, siempre debes configurar una altura en <div> de forma explícita.

Opciones de mapas

Hay dos opciones obligatorias para cada mapa: 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 en la que se muestra el mapa se establece con la propiedad zoom, en la que 0 de zoom corresponde a un mapa de la Tierra completamente alejado y los niveles de zoom más grandes se amplían a mayor resolución.

zoom: 8

Ofrecer un mapa de toda la Tierra como una sola imagen requeriría un mapa inmenso o un mapa pequeño con una resolución muy baja. Como resultado, las imágenes de mapas de Google Maps y la API de Maps JavaScript se dividen en niveles de zoom y mosaicos de mapas. Con bajos niveles de zoom, un conjunto pequeño de mosaicos de mapa cubren un área amplia; a mayores niveles de zoom, los mosaicos son de mayor resolución y cubren un área más pequeña. 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 siguientes tres imágenes reflejan la misma ubicación de Tokio en los niveles de zoom 0, 7 y 18.

Para obtener información sobre cómo la API de Maps JavaScript carga mosaicos según el nivel de zoom actual, consulta la guía sobre coordenadas de mapas y 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 separado en la página). Creamos 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 y 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 determinado, que suele ser un elemento DIV, mediante cualquier parámetro (opcional) que se pasa.

Solución de problemas

Errores en 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, con una marca de agua con el texto "solo para fines de desarrollo". Este comportamiento generalmente indica problemas con una clave de API o la facturación. Para usar los productos de Google Maps Platform, la facturación debe estar 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 este problema:

Si el código no funciona:

Para ayudarte a poner en marcha tus códigos de mapa, 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 distingue entre mayúsculas y minúsculas.
  • Consulta los aspectos básicos: algunos de los problemas más comunes se producen en la creación inicial del mapa. Por ejemplo:
    • Confirma que especificaste las propiedades zoom y center en las opciones de mapa.
    • Asegúrate de haber declarado un elemento div en el que el mapa aparecerá en la pantalla.
    • Asegúrate de que se haya especificado una altura para el elemento “div” del mapa. De forma predeterminada, los elementos div se crean con una altura de 0 y, por lo tanto, son invisibles.
    Consulta nuestros ejemplos para obtener una implementación de referencia.
  • Usa un depurador de JavaScript para identificar problemas, como el que está disponible en las Herramientas para desarrolladores de Chrome. Comienza la búsqueda de errores en la consola JavaScript.
  • Publica tus preguntas en Stack Overflow. Los lineamientos para publicar preguntas de calidad están disponibles en la página de Asistencia.