Descripción general

Seleccionar plataforma: Android iOS JavaScript

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 familiarizadas con la programación en JavaScript y los conceptos de la programación orientada a objetos. También debes estar familiarizado con 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;
async function initMap(): Promise<void> {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();

JavaScript

let map;

async function initMap() {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

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>

    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
Ver ejemplo

Prueba la muestra

Incluso en este ejemplo simple, debes tener en cuenta algunos aspectos:

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

Estos pasos se explican a continuación.

Carga la API de Maps JavaScript

Se recomienda usar el cargador de arranque para cargar la API de Maps JavaScript. Como alternativa, también se proporciona el cargador de la API de JS. 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.

Si deseas obtener más información, consulta Carga la API de Maps JavaScript.

Cargador de arranque

Para cargar la API de Maps JavaScript, agrega el cargador de arranque intercalado al código de tu aplicación, como se muestra en el siguiente fragmento:

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY_HERE",
    // Add other bootstrap parameters as needed, using camel case.
    // Use the 'v' parameter to indicate the version to load (alpha, beta, weekly, etc.)
  });
</script>

Si deseas cargar bibliotecas en el entorno de ejecución, usa el operador await para llamar a importLibrary() desde una función asíncrona, como se muestra a continuación:

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();

JavaScript

let map;

async function initMap() {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();

Paquete js-api-loader de NPM

Usa @googlemaps/js-api-loader para cargar la API de Maps JavaScript mediante NPM. Emplea el siguiente comando para instalar este paquete con NPM:

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(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new 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(async () => {
  const { Map } = await google.maps.importLibrary("maps");

  map = new Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

Declara 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 etiqueta script, 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(async () => {
  const { Map } = await google.maps.importLibrary("maps") as google.maps.MapsLibrary;
  map = new 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(async () => {
  const { Map } = await google.maps.importLibrary("maps");

  map = new 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, y callback, 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ámetro callback.

Bibliotecas

Cuando cargues la API de Maps JavaScript mediante la URL, tienes la opción de cargar bibliotecas adicionales con el operador await para llamar a importLibrary() desde una función asíncrona. 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.

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 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 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 zoom y center en 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.
    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. 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.