Se usó la API de Cloud Translation para traducir esta página.

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 establecer opciones del mapa y cómo usar la inserción de controles 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:

Obtén una clave de API.
Crea una página HTML.
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:

Ve a la consola de Google Cloud.
Crea o selecciona un proyecto.
Haz clic en Continuar para habilitar la API y los servicios relacionados.
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.
Para evitar el robo de cuota y proteger tu clave de API, consulta Cómo usar las claves de API.
Habilita la facturación. Consulta Uso y facturación para obtener más información.

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 cargador de arranque 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 muy básica que usa un elemento gmp-map para mostrar un mapa en la página. El mapa estará en blanco porque aún no agregamos ningún código de JavaScript.

Comprende el código

En esta etapa del ejemplo, tenemos lo siguiente:

Se declaró la aplicación como HTML5 con la declaración !DOCTYPE html.
Se cargó la API de Maps JavaScript con el cargador de arranque.
Se creó un elemento gmp-map para contener 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 el DOCTYPE de 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. Específicamente, 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 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.

El siguiente código define el elemento gmp-map y establece 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. Zoom: 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. Como resultado, 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.

Control de la asignación de espacios

Puedes usar el control slotting para agregar controles de formulario HTML a tu mapa. Una ranura es una posición predefinida en el mapa. Usa el atributo slot para establecer la posición necesaria para 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 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 initMap(): Promise<void> {
  //  Request the needed libraries.
  const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
    google.maps.importLibrary("maps") as Promise<google.maps.MapsLibrary>,
    google.maps.importLibrary("marker") as Promise<google.maps.MarkerLibrary>,
  ]);
  // 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,
  });

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

JavaScript

async function initMap() {
    //  Request the needed libraries.
    const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary("maps"),
        google.maps.importLibrary("marker"),
    ]);
    // 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).
    const marker = new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: "Uluru/Ayers Rock",
    });
}
initMap();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 configura las opciones

El 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 se usa 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 durante el tiempo de inicialización (por ejemplo, una solicitud de geolocalización o de detalles de Place). Para asegurarte de que tu código solo se ejecute después de que el mapa se cargue por completo, usa un controlador de eventos inactivo addListenerOnce en tu función de inicialización, como se muestra aquí:

// 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!");
});

Esto garantiza que tu código solo se ejecute después de que se cargue el mapa. El controlador solo se activa una vez durante el ciclo de vida de la app.

Ejemplo de código completo

Consulta el ejemplo de código completo aquí:

TypeScript

async function initMap(): Promise<void> {
  //  Request the needed libraries.
  const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
    google.maps.importLibrary("maps") as Promise<google.maps.MapsLibrary>,
    google.maps.importLibrary("marker") as Promise<google.maps.MarkerLibrary>,
  ]);
  // 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,
  });

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

JavaScript

async function initMap() {
    //  Request the needed libraries.
    const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
        google.maps.importLibrary("maps"),
        google.maps.importLibrary("marker"),
    ]);
    // 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).
    const marker = new AdvancedMarkerElement({
        map: innerMap,
        position: mapElement.center,
        title: "Uluru/Ayers Rock",
    });
}
initMap();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>
    <!-- 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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", 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">
      <div id="controls" slot="control-inline-start-block-start">
        <h3>My Google Maps Demo</h3>
      </div>
    </gmp-map>
  </body>
</html>index.html

Prueba la muestra

JSFiddle.net

Obtén más información sobre los 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 ¿Qué hay aquí? en el menú contextual que aparece. El mapa mostrará una tarjeta en la parte inferior de la pantalla. Busca las coordenadas de latitud y longitud en la última fila de la tarjeta.
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.

Cómo agregar un mapa de Google Maps con un marcador usando JavaScript Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Introducción

Cómo comenzar

Paso 1: Obtén una clave de API

Paso 2: Crea una página HTML

Comprende el código

Declara tu aplicación como HTML5

Carga la API de Maps JavaScript

Crea un elemento gmp-map

Niveles de zoom

Control de la asignación de espacios

Paso 3: Agrega código JavaScript

TypeScript

JavaScript

Obtén el objeto de mapa y configura las opciones

Espera a que se cargue el mapa.

Ejemplo de código completo

TypeScript

JavaScript

CSS

HTML

Prueba la muestra

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

Sugerencias y solución de problemas

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

Crea un elemento `gmp-map`