Charger l'API Maps JavaScript

Ce guide vous explique comment charger l'API Maps JavaScript. Vous pouvez le faire de trois manières :

Utiliser l'importation dynamique de bibliothèques

L'importation de bibliothèques dynamiques permet de charger des bibliothèques au moment de l'exécution. Vous pouvez ainsi demander les bibliothèques nécessaires au moment où vous en avez besoin, plutôt que toutes en même temps au moment du chargement. Il empêche également votre page de charger l'API Maps JavaScript plusieurs fois.

Chargez l'API Maps JavaScript en ajoutant le chargeur d'amorçage intégré au code de votre application, comme indiqué dans l'extrait suivant :

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

Vous pouvez également ajouter le code du chargeur d'amorçage directement à votre code JavaScript.

Pour charger des bibliothèques lors de l'exécution, utilisez l'opérateur await pour appeler importLibrary() à partir d'une fonction async. Déclarer des variables pour les classes nécessaires vous permet d'ignorer l'utilisation d'un chemin qualifié (par exemple, google.maps.Map), comme illustré dans l'exemple de code suivant:

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

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

Votre fonction peut également charger des bibliothèques sans déclarer de variable pour les classes requises, ce qui est particulièrement utile si vous avez ajouté une carte à l'aide de l'élément gmp-map:

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

initMap();

Vous pouvez également charger les bibliothèques directement en HTML, comme indiqué ci-dessous:

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

Découvrez comment migrer vers l'API Dynamic Library Loading.

Paramètres obligatoires

  • key : votre clé API. L'API Maps JavaScript ne se charge pas tant qu'aucune clé API valide n'est spécifiée.

Paramètres facultatifs

  • v : version de l'API Maps JavaScript à charger.

  • libraries : liste des bibliothèques supplémentaires de l'API Maps JavaScript à charger, séparées par une virgule. Généralement, il n'est pas recommandé de spécifier un ensemble défini de bibliothèques, mais cette option est disponible pour les développeurs qui souhaitent affiner le comportement de mise en cache sur leur site Web.

  • language : langue à utiliser. Ce paramètre affecte le nom des commandes, les avis de droits d'auteur, les itinéraires, les libellés de commandes et les réponses aux demandes de service. Consultez la liste des langues acceptées.

  • region : code régional à utiliser. Ce paramètre modifie le comportement de la carte en fonction d'un pays ou d'un territoire donné.

  • authReferrerPolicy : les clients Maps JS peuvent configurer des restrictions d'URL de provenance HTTP dans la console Cloud afin de limiter les URL autorisées à utiliser une clé API donnée. Par défaut, ces restrictions peuvent être configurées pour n'autoriser que certains chemins à utiliser une clé API. Si une URL du même domaine ou de la même origine peut utiliser la clé API, vous pouvez définir authReferrerPolicy: "origin" pour limiter la quantité de données envoyées lors de l'autorisation des requêtes à partir de l'API Maps JavaScript. Lorsque ce paramètre est spécifié et que des restrictions d'URL de provenance HTTP sont activées dans la console Cloud, l'API Maps JavaScript ne peut être chargée que si une restriction d'URL de provenance HTTP correspond au domaine du site Web actuel sans chemin spécifié.

  • mapIds: tableau d'ID de carte. Permet de précharger la configuration des ID de carte spécifiés.

  • channel: consultez Suivi de l'utilisation par canal.

  • solutionChannel : pour vous aider à démarrer rapidement, Google Maps Platform propose de nombreux types d'exemples de code. Pour suivre l'adoption de nos exemples de code plus complexes et améliorer la qualité de la solution, Google inclut le paramètre de requête solutionChannel des appels d'API dans les exemples.

Utiliser la balise de chargement de script direct

Cette section explique comment utiliser la balise de chargement de script direct. Étant donné que le script direct charge des bibliothèques lorsque la carte est chargée, il peut simplifier les cartes créées à l'aide d'un élément gmp-map en supprimant la nécessité de demander explicitement des bibliothèques au moment de l'exécution. Étant donné que la balise de chargement de script direct charge toutes les bibliothèques demandées en même temps lorsque le script est chargé, les performances peuvent être affectées pour certaines applications. N'incluez la balise de chargement de script direct qu'une seule fois par chargement de page.

Ajouter un tag de script

Pour charger l'API Maps JavaScript intégrée dans un fichier HTML, ajoutez un tag script comme indiqué ci-dessous.

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

Paramètres d'URL de chargement de script direct

Cette section présente tous les paramètres que vous pouvez spécifier dans la chaîne de requête de l'URL de chargement de script lorsque l'API Maps JavaScript est chargée. Certains paramètres sont obligatoires, d'autres sont facultatifs. Comme c'est la norme pour les URL, les différents paramètres sont séparés par une esperluette (&).

L'exemple d'URL suivant comporte des espaces réservés pour tous les paramètres possibles :

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"

Dans l'exemple de tag de script suivant, l'URL charge l'API Maps JavaScript :

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

Paramètres obligatoires (direct)

Les paramètres suivants sont requis pour charger l'API Maps JavaScript.

  • key : votre clé API. L'API Maps JavaScript ne se charge pas tant qu'aucune clé API valide n'est spécifiée.

Paramètres facultatifs (directs)

Utilisez ces paramètres pour demander une version spécifique de l'API Maps JavaScript, charger des bibliothèques supplémentaires, localiser votre carte ou spécifier la règle de vérification de l'URL de provenance HTTP.

  • loading: stratégie de chargement de code que l'API Maps JavaScript peut utiliser. Définissez cette valeur sur async pour indiquer que l'API Maps JavaScript n'a pas été chargée de manière synchrone et qu'aucun code JavaScript n'est déclenché par l'événement load du script. Nous vous recommandons vivement de définir ce paramètre sur async dans la mesure du possible pour améliorer les performances. (Utilisez plutôt le paramètre callback pour effectuer des actions lorsque l'API Maps JavaScript est disponible.) Disponible à partir de la version 3.55.

  • callback : nom d'une fonction globale à appeler une fois que l'API Maps JavaScript a été entièrement chargée.

  • v : version de l'API Maps JavaScript à utiliser.

  • libraries : liste des bibliothèques supplémentaires de l'API Maps JavaScript à charger, séparées par une virgule.

  • language : langue à utiliser. Ce paramètre affecte le nom des commandes, les avis de droits d'auteur, les itinéraires et les libellés de commandes, ainsi que les réponses aux demandes de service. Consultez la liste des langues acceptées.

  • region : code régional à utiliser. Ce paramètre modifie le comportement de la carte en fonction d'un pays ou d'un territoire donné.

  • auth_referrer_policy: les clients peuvent configurer des restrictions d'URL de provenance HTTP dans la console Cloud afin de limiter les URL autorisées à utiliser une clé API donnée. Par défaut, ces restrictions peuvent être configurées pour n'autoriser que certains chemins à utiliser une clé API. Si une URL du même domaine ou de la même origine peut utiliser la clé API, vous pouvez définir auth_referrer_policy=origin pour limiter la quantité de données envoyées lors de l'autorisation des requêtes à partir de l'API Maps JavaScript. Cette fonctionnalité est disponible à partir de la version 3.46. Lorsque ce paramètre est spécifié et que des restrictions d'URL de provenance HTTP sont activées dans la console Cloud, l'API Maps JavaScript ne peut être chargée que si une restriction d'URL de provenance HTTP correspond au domaine du site Web actuel sans chemin spécifié.

  • mapIds: liste d'ID de carte séparés par une virgule. Permet de précharger la configuration des ID de carte spécifiés.

  • channel: consultez Suivi de l'utilisation par canal.

  • solution_channel : pour vous aider à démarrer rapidement, Google Maps Platform propose de nombreux types d'exemples de code. Pour suivre l'adoption de nos exemples de code plus complexes et améliorer la qualité de la solution, Google inclut le paramètre de requête solution_channel des appels d'API dans les exemples.

Utiliser le package js-api-loader NPM

Le package @googlemaps/js-api-loader est disponible pour le chargement via le gestionnaire de paquets NPM. Installez-le à l'aide de la commande suivante :

npm install @googlemaps/js-api-loader

Ce package peut être importé dans l'application avec :

import { Loader } from "@googlemaps/js-api-loader"

Le chargeur expose une promesse et une interface de rappel. Voici un exemple d'utilisation de la méthode load() de promesse par défaut.

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

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

Voir un exemple avec js-api-loader

L'exemple suivant montre comment utiliser loader.importLibrary() pour charger des bibliothèques:

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
});

Migrer vers l'API Dynamic Library Import

Cette section décrit la procédure à suivre pour migrer votre intégration afin d'utiliser l'API Dynamic Library Import.

Étapes de migration

Tout d'abord, remplacez la balise de chargement de script direct par la balise de chargeur d'amorçage intégré.

Avant

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

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

Ensuite, modifiez le code de votre application :

  • Modifiez la fonction initMap() pour qu'elle soit asynchrone.
  • Appelez importLibrary() pour charger les bibliothèques dont vous avez besoin et y accéder.

Avant

let map;

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

window.initMap = initMap;

Aprè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();