Cómo agregar un mapa de Google Maps con un marcador usando JavaScript

Introducción

En este instructivo, se muestra cómo agregar un mapa de Google Maps con un marcador a una página web con HTML, CSS y JavaScript. También se muestra cómo configurar las opciones del mapa y cómo usar la asignación de ranuras de control para agregar una etiqueta al mapa.

A continuación, se muestra el mapa que crearás con este instructivo. El marcador se ubica en Uluru (también conocido como Ayers Rock) en el Parque Nacional Uluru-Kata Tjuta.

Cómo comenzar

Para crear un mapa de Google Maps con un marcador en tu página web, sigue estos tres pasos:

1. Obtén una clave de API.
2. Crea una página HTML.
3. Agrega un mapa con un marcador.

Necesitas un navegador web. De la lista de navegadores compatibles, elige uno conocido, como Google Chrome (recomendado), Firefox, Safari o Edge, según la plataforma que utilices.

Paso 1: Obtén una clave de API

En esta sección se explica cómo autenticar tu app en la API de Maps JavaScript con tu propia clave de API.

Sigue estos pasos para obtener una clave de API:

1. Ve a la consola de Google Cloud.

2. Crea o selecciona un proyecto.

3. Haz clic en Continuar para habilitar la API y los servicios relacionados.

4. En la página Credenciales, obtén una clave de API (y configura sus restricciones). Si ya tienes una clave de API sin restricciones o una clave con restricciones de navegador, puedes usarla.

5. Para evitar el robo de cuota y proteger tu clave de API, consulta Cómo usar las claves de API.

6. Habilita la facturación. Consulta Uso y facturación para obtener más información.

7. Una vez que hayas obtenido una clave de API, agrégala al siguiente fragmento haciendo clic en "YOUR_API_KEY". Copia y pega la etiqueta de secuencia de comandos del bootloader para usarla en tu propia página web.

   <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",
       v: "weekly",
       // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
       // Add other bootstrap parameters as needed, using camel case.
     });
   </script>

Paso 2: Crea una página HTML

Este es el código para una página web HTML básica:

<!DOCTYPE html>
<!--
 @license
 Copyright 2025 Google LLC. All Rights Reserved.
 SPDX-License-Identifier: Apache-2.0
-->

<html>
  <head>
    <title>Add a Map</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
    <!-- 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: "YOUR_API_KEY", v: "weekly"});</script>
  </head>
  <body>

    <!-- The map, centered at Uluru, Australia. -->
    <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
    </gmp-map>

  </body>
</html>

Esta es una página HTML básica que usa un elemento gmp-map para mostrar un mapa en la página. El mapa estará en blanco, ya que aún no agregamos ningún código JavaScript.

Comprende el código

En esta etapa del ejemplo, tenemos lo siguiente:

• Se declara la aplicación como HTML5 con la declaración !DOCTYPE html.
• Cargar la API de Maps JavaScript con el cargador de arranque
• Se creó un elemento gmp-map para que contenga el mapa.

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, 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>
  gmp-map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

Carga la API de Maps JavaScript

El cargador de arranque prepara la API de Maps JavaScript para la carga (no se cargarán bibliotecas hasta que se llame a importLibrary()).

<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",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>

Consulta el Paso 3: Obtén una clave de API para ver instrucciones sobre cómo obtener tu propia clave.

En esta etapa del instructivo, aparece una ventana en blanco que solo muestra el texto de la etiqueta sin formato. Esto se debe a que aún no agregamos ningún código de JavaScript.

Crea un elemento gmp-map

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 gmp-map y se obtiene una referencia a este elemento en el modelo de objetos del documento (DOM) del navegador. También puedes usar un elemento div para hacerlo (obtén más información), pero se recomienda usar el elemento gmp-map.

En el siguiente código, se define el elemento gmp-map y se establecen los parámetros center, zoom y map-id.

<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
</gmp-map>

Las opciones center y zoom siempre son obligatorias. En el código anterior, la propiedad center le indica a la API dónde debe centrar el mapa, y la propiedad zoom especifica el nivel de zoom del mapa. 0 es el valor de zoom más bajo y muestra todo el planeta. Define un valor de zoom más alto para acercarte a la Tierra con resoluciones más altas.

Niveles de zoom

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 o 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.

En el siguiente código, se describe el CSS que establece el tamaño del elemento gmp-map.

/* Set the size of the gmp-map element that contains the map */
gmp-map {
    height: 400px; /* The height is 400 pixels */
    width: 100%; /* The width is the width of the web page */
}

En el código anterior, el elemento style establece el tamaño del gmp-map. Configura el ancho y la altura en más de 0 px para que el mapa sea visible. En este caso, se configura el gmp-map con una altura de 400 píxeles y un ancho del 100% para que se muestre a lo ancho de la página web. Se recomienda establecer siempre de forma explícita los estilos de altura y ancho.

Nota: Para los mapas de tramas, el límite de la dimensión máxima es de 6,144 x 6,144 píxeles.

Ubicación de controles

Puedes usar la asignación de ranuras de controles para agregar controles de formulario HTML a tu mapa. Un espacio es una posición predefinida en el mapa. Usa el atributo slot para establecer la posición necesaria de un elemento y anida elementos dentro del elemento gmp-map. En el siguiente fragmento, se muestra cómo agregar una etiqueta HTML a la esquina superior izquierda del mapa.

<!-- The map, centered at Uluru, Australia. -->
<gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
  <div id="controls" slot="control-inline-start-block-start">
    <h3>My Google Maps Demo</h3>
  </div>
</gmp-map>

Paso 3: Agrega el código JavaScript

En esta sección, se muestra cómo cargar la API de Maps JavaScript en una página web y cómo escribir tu propio código JavaScript que use la API para agregar un mapa con un marcador.

TypeScript

async function init(): Promise<void> {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map')!;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.ts

Nota: Consulta la guía sobre cómo utilizar TypeScript y Google Maps.

JavaScript

async function init() {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.js

El código anterior hace lo siguiente cuando se llama a initMap():

• Carga las bibliotecas maps y marker.
• Obtiene el elemento del mapa del DOM.
• Establece opciones de mapa adicionales en el mapa interno.
• Agrega un marcador al mapa.

Obtén el objeto de mapa y establece las opciones

innerMap representa una instancia de la clase Map. Para configurar las opciones del mapa, obtén la instancia de innerMap del elemento del mapa y llama a setOptions. En el siguiente fragmento, se muestra cómo obtener la instancia de innerMap del DOM y, luego, llamar a setOptions:

// Get the gmp-map element.
const mapElement = document.querySelector(
  "gmp-map"
) as google.maps.MapElement;

// Get the inner map.
const innerMap = mapElement.innerMap;

// Set map options.
innerMap.setOptions({
  mapTypeControl: false,
});

Espera a que se cargue el mapa.

Cuando usas el elemento gmp-map, el mapa se carga de forma asíncrona. Esto puede generar una condición de carrera si se realizan otras solicitudes en el momento de la inicialización (por ejemplo, una solicitud de geolocalización o de Place Details). Para asegurarte de que tu código solo se ejecute después de que el mapa se haya cargado por completo, usa un controlador de eventos inactivos addListenerOnce en tu función de inicialización, como se muestra a continuación:

// Do things once the map has loaded.
google.maps.event.addListenerOnce(innerMap, 'idle', () => {
    // Run this code only after the map has loaded.
    console.log("The map is now ready!");
});

De esta manera, se garantiza que tu código solo se ejecute después de que se haya cargado el mapa. El controlador solo se activa una vez durante el ciclo de vida de la app.

Nota sobre la optimización del rendimiento interno:

Para mejorar las velocidades de carga de página, la API de Maps JavaScript puede aplazar de forma interna la carga de contenido interactivo hasta que el elemento o contenedor se acerque al viewport. Estas optimizaciones internas están sujetas a cambios en cualquier momento y sin previo aviso. Están diseñadas para mejorar el rendimiento y no deben usarse como un mecanismo para administrar la facturación. Para asegurarte de que no se generen cargos de facturación hasta que un elemento sea visible, aplaza su creación en el código de la aplicación.

Ejemplo de código completo

Consulta el ejemplo completado de código aquí:

TypeScript

async function init(): Promise<void> {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map')!;

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.ts

Nota: Consulta la guía sobre cómo utilizar TypeScript y Google Maps.

JavaScript

async function init() {
    // Request the needed libraries.
    const [{ AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
    ]);
    // Get the gmp-map element.
    const mapElement = document.querySelector('gmp-map');

    // Get the inner map.
    const innerMap = mapElement.innerMap;

    // Set map options.
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Add a marker positioned at the map center (Uluru).
    new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: 'Uluru/Ayers Rock',
    });
}
void init();
index.js

CSS

/*
 * Always set the map height explicitly to define the size of the div element
 * that contains the map.
 */
gmp-map {
    height: 100%;
}

/*
   * Optional: Makes the sample page fill the window.
   */
html,
body {
    height: 100%;
    margin: 0;
    padding: 0;
}
style.css

HTML

<html>
    <head>
        <title>Add a Map</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <!-- The map, centered at Uluru, Australia. -->
        <gmp-map center="-25.344,131.031" zoom="4" map-id="DEMO_MAP_ID">
            <div id="controls" slot="control-inline-start-block-start">
                <h3>My Google Maps Demo</h3>
            </div>
        </gmp-map>
    </body>
</html>
index.html

Obtén más información sobre los marcadores:

• Cómo configurar un marcador para que sea accesible
• Marcadores con íconos gráficos
• Animaciones de marcadores

Sugerencias y solución de problemas

• Obtén más información para obtener coordenadas de latitud y longitud o convertir una dirección en coordenadas geográficas.
• Puedes modificar determinadas opciones, como los diseños y las propiedades, para personalizar el mapa. Si deseas obtener más información sobre cómo personalizar mapas, consulta las guías de diseño y dibujos en el mapa.
• Usa la consola de Herramientas para desarrolladores en tu navegador web para probar y ejecutar tu código, leer los informes de errores y resolver los problemas.
• Usa las siguientes combinaciones de teclas para abrir la consola en Chrome:
  Comando + Opción + J (en Mac) o Control + Mayúsculas + J (en Windows).

• Sigue los pasos que se indican a continuación para obtener las coordenadas de latitud y longitud de una ubicación en Google Maps.

  1. Abre Google Maps en un navegador.
  2. Haz clic con el botón derecho en la ubicación exacta del mapa para la que necesitas las coordenadas.
  3. Selecciona las coordenadas de latitud y longitud en el menú.

• Puedes convertir una dirección en coordenadas de latitud y longitud mediante el servicio Geocoding. Las guías para desarrolladores brindan información detallada sobre cómo comenzar a usar el servicio Geocoding.