Carga la API de Maps JavaScript

En esta guía, se muestra cómo cargar la API de Maps JavaScript. Existen tres maneras de hacerlo:

• Usar Dynamic Library Import (recomendado)
• Usar el paquete js-api-loader de NPM
• Usar la etiqueta de carga de la secuencia de comandos heredada

Cómo utilizar Dynamic Library Import

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",
    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>

También puedes agregar el código del cargador de arranque directamente a tu código JavaScript.

Si deseas cargar bibliotecas en el entorno de ejecución, usa el operador await para llamar a importLibrary() desde una función async, como se muestra en el siguiente código de ejemplo:

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  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,
  });
}

initMap();
index.ts

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

JavaScript

let map;

async function initMap() {
  const { Map } = await google.maps.importLibrary("maps");

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

initMap();
index.js

Parámetros obligatorios

• key: Es tu clave de API. La API de Maps JavaScript no se cargará si no se especifica una clave de API válida.

Parámetros opcionales

• v: Indica la versión de la API de Maps JavaScript que se cargará.

• libraries: Incluye una lista separada por comas de bibliotecas adicionales de la API de Maps JavaScript que se cargarán. Por lo general, no se recomienda especificar un conjunto fijo de bibliotecas, pero esta opción está disponible para los desarrolladores que deseen definir con precisión cómo se comporta el almacenamiento en caché en su sitio web.

• language: Es el idioma que se usará. Este parámetro afecta los nombres de los controles, los avisos sobre derechos de autor, las rutas en auto y las etiquetas de control, así como las respuestas a las solicitudes de servicio. Consulta la lista de idiomas disponibles.

• region: Es el código de la región que se usará. Esto modifica el comportamiento del mapa según el país o el territorio determinados.

• solutionChannel: Google Maps Platform proporciona muchos tipos de códigos de muestra para ayudarte a comenzar rápidamente. Para realizar un seguimiento de la adopción de nuestras muestras de código más complejas y mejorar la calidad de las soluciones, Google incluye el parámetro de consulta solutionChannel en las llamadas a la API en nuestro código de muestra.

• authReferrerPolicy: Los clientes de Maps JS pueden configurar restricciones de URLs de referencia HTTP en la consola de Cloud para limitar las URLs que pueden usar una clave de API en particular. De forma predeterminada, estas restricciones se pueden configurar para permitir que solo ciertas rutas de acceso usen una clave de API. Si una URL con el mismo origen o dominio puede usar la clave de API, puedes configurar authReferrerPolicy: "origin" para limitar la cantidad de datos que se envían cuando se autorizan solicitudes de la API de Maps JavaScript. Cuando se especifica este parámetro y se habilitan las restricciones de URLs de referencia HTTP en la consola de Cloud, la API de Maps JavaScript solo podrá cargarse si hay una restricción de URLs de referencia HTTP que coincida con el dominio del sitio web actual sin una ruta especificada.

Cómo usar el paquete js-api-loader de NPM

El paquete @googlemaps/js-api-loader está disponible para cargar a través del administrador de paquetes de NPM. Instálalo con el siguiente comando:

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,
  });
});
index.ts

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

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,
  });
});
index.js

Mira un ejemplo en el que se usa js-api-loader.

Cómo usar la etiqueta de carga de la secuencia de comandos heredada

Aún se admite la etiqueta de carga de la secuencia de comandos heredada. Esta sección se proporcionó para admitir integraciones con la etiqueta de carga de la secuencia de comandos heredada. Google recomienda migrar a la API de Dynamic Library Loading.

Agrega una etiqueta de secuencia de comandos

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>

Parámetros de la URL de carga de la secuencia de comandos heredada

En esta sección, se analizan todos los parámetros que puedes especificar en la cadena de consulta de la URL de carga de la secuencia de comandos cuando cargas la API de Maps JavaScript. Algunos parámetros son obligatorios y otros son opcionales. Tal como es práctica estándar para las URLs, todos los parámetros se separan usando el signo et (&).

La siguiente URL de ejemplo tiene marcadores de posición para todos los parámetros posibles:

https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&solution_channel="SOLUTION_IDENTIFIER"
&auth_referrer_policy="AUTH_REFERRER_POLICY"

La URL de la siguiente etiqueta script de ejemplo carga la API de Maps JavaScript:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>

Parámetros obligatorios (heredados)

Los siguientes parámetros son obligatorios cuando se carga la API de Maps JavaScript.

• key: Es tu clave de API. La API de Maps JavaScript no se cargará si no se especifica una clave de API válida.

• callback: Es el nombre de una función global que se llamará una vez que la API de Maps JavaScript se cargue por completo.

Parámetros opcionales (heredados)

Usa estos parámetros para solicitar una versión específica de la API de Maps JavaScript, cargar bibliotecas adicionales, localizar tu mapa o especificar la política de verificación de las URLs de referencia HTTP.

• v: Indica la versión de la API de Maps JavaScript que se usará.

• libraries: Incluye una lista separada por comas de bibliotecas adicionales de la API de Maps JavaScript que se cargarán.

• language: Es el idioma que se usará. Esto afecta los nombres de los controles, los avisos sobre derechos de autor, las rutas en auto y las etiquetas de control, así como las respuestas a las solicitudes de servicio. Consulta la lista de idiomas disponibles.

• region: Es el código de la región que se usará. Esto modifica el comportamiento del mapa según el país o el territorio determinados.

• solution_channel: Google Maps Platform proporciona muchos tipos de códigos de muestra para ayudarte a comenzar rápidamente. Para realizar un seguimiento de la adopción de nuestras muestras de código más complejas y mejorar la calidad de las soluciones, Google incluye el parámetro de consulta solution_channel en las llamadas a la API en nuestro código de muestra.

  Nota: Este parámetro de consulta es para uso exclusivo de Google. Consulta Parámetro de soluciones de Google Maps Platform para obtener más información.

• auth_referrer_policy: Los clientes de Maps JS pueden configurar restricciones de URLs de referencia HTTP en la consola de Cloud para limitar las URLs que pueden usar una clave de API en particular. De forma predeterminada, estas restricciones se pueden configurar para permitir que solo ciertas rutas de acceso usen una clave de API. Si una URL con el mismo origen o dominio puede usar la clave de API, puedes configurar auth_referrer_policy=origin para limitar la cantidad de datos que se envían cuando se autorizan solicitudes de la API de Maps JavaScript. Esta función está disponible a partir de la versión 3.46. Cuando se especifica este parámetro y se habilitan las restricciones de URLs de referencia HTTP en la consola de Cloud, la API de Maps JavaScript solo podrá cargarse si hay una restricción de URLs de referencia HTTP que coincida con el dominio del sitio web actual sin una ruta especificada.

Cómo migrar a la API de Dynamic Library Import

En esta sección, se describen los pasos necesarios para migrar tu integración y usar la API de Dynamic Library Import.

Pasos de la migración

Primero, reemplaza la etiqueta de carga de la secuencia de comandos heredada por la etiqueta del cargador de arranque intercalado.

Antes

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
</script>

Después

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

A continuación, actualiza el código de tu aplicación:

• Cambia la función initMap() para que sea asíncrona.
• Llama a importLibrary() para cargar las bibliotecas que necesitas y acceder a ellas.

Antes

let map;

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

window.initMap = initMap;

Después

let map;
// initMap is now async
async function initMap() {
    // Request libraries when needed, not in the script tag.
    const { Map } = await google.maps.importLibrary("maps");
    // Short namespaces can be used.
    map = new Map(document.getElementById("map"), {
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
    });
}

initMap();