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:

• Usa Dynamic Library Import
• Usa la etiqueta de carga de secuencia de comandos directa
• Usar el paquete js-api-loader de NPM

Cómo utilizar Dynamic Library Import

La importación de bibliotecas dinámicas proporciona la capacidad de cargar bibliotecas en el tiempo de ejecución. Esto te permite solicitar las bibliotecas necesarias en el momento en que las necesitas, en lugar de todas a la vez en el momento de la carga. También protege tu página de cargar la API de Maps JavaScript varias veces.

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. Declarar variables para las clases necesarias te permite omitir el uso de una ruta calificada (p.ej., google.maps.Map), como se muestra en el siguiente ejemplo de código:

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

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

Tu función también puede cargar bibliotecas sin declarar una variable para las clases necesarias, lo que es especialmente útil si agregaste un mapa con el elemento gmp-map:

async function initMap() {
  google.maps.importLibrary("maps");
  google.maps.importLibrary("marker");
}

initMap();

Como alternativa, puedes cargar las bibliotecas directamente en HTML, como se muestra a continuación:

<script>
google.maps.importLibrary("maps");
google.maps.importLibrary("marker");
</script>

Obtén más información para migrar a la API de Dynamic Library Loading.

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.

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

• mapIds: Es un array de IDs de mapas. Hace que se cargue previamente la configuración de los IDs de mapa especificados.

• channel: Consulta Seguimiento del uso por canal.

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

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

En esta sección, se muestra cómo usar la etiqueta de carga de secuencia de comandos directa. Dado que la secuencia de comandos directa carga bibliotecas cuando se carga el mapa, puede simplificar los mapas creados con un elemento gmp-map, ya que quita la necesidad de solicitar bibliotecas de forma explícita durante el tiempo de ejecución. Dado que la etiqueta de carga de secuencia de comandos directa carga todas las bibliotecas solicitadas a la vez cuando se carga la secuencia de comandos, el rendimiento puede verse afectado en algunas aplicaciones. Incluye la etiqueta de carga de secuencia de comandos directa solo una vez por carga de página.

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&loading=async&callback=initMap">
</script>

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

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
&loading=async
&callback=FUNCTION_NAME
&v=VERSION
&libraries="LIBRARIES"
&language="LANGUAGE"
&region="REGION"
&auth_referrer_policy="AUTH_REFERRER_POLICY"
&map_ids="MAP_IDS"
&channel="CHANNEL"
&solution_channel="SOLUTION_IDENTIFIER"

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&loading=async&callback=initMap">
</script>

Parámetros obligatorios (directos)

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.

Parámetros opcionales (directos)

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.

• loading: Es la estrategia de carga de código que puede usar la API de Maps JavaScript. Se establece en async para indicar que la API de Maps JavaScript no se cargó de forma síncrona y que el evento load de la secuencia de comandos no activa ningún código JavaScript. Para mejorar el rendimiento, se recomienda establecer este valor en async siempre que sea posible. (En su lugar, usa el parámetro callback para realizar acciones cuando la API de Maps JavaScript esté disponible). Disponible a partir de la versión 3.55.

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

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

• auth_referrer_policy: Los clientes 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.

• mapIds: Es una lista de IDs de mapas separados por comas. Hace que se cargue previamente la configuración de los IDs de mapa especificados.

• channel: Consulta Seguimiento del uso por canal.

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

Usa 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().

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

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.

En el siguiente ejemplo, se muestra cómo usar loader.importLibrary() para cargar bibliotecas:

const loader = new Loader({
  apiKey: "YOUR_API_KEY",
  version: "weekly",
  ...additionalOptions,
});

loader
  .importLibrary('maps')
  .then(({Map}) => {
    new Map(document.getElementById("map"), mapOptions);
  })
  .catch((e) => {
    // do something
});

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 directa por la etiqueta del cargador de arranque intercalado.

Antes

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=maps&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();