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

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, comme indiqué 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

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

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

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

Utiliser le package js-api-loader NPM

Le package @googlemaps/js-api-loader est disponible pour le chargement via le gestionnaire de packages 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

Utiliser l'ancien tag de chargement du script

L'ancien tag de chargement de script est toujours accepté. Cette section a été fournie pour réaliser l'intégration à l'aide de l'ancien tag de chargement de script. Google vous recommande de migrer vers l'API Dynamic Library Loading.

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

Anciens paramètres d'URL de chargement de script

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

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

Paramètres obligatoires (anciens)

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.

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

Paramètres facultatifs (anciens)

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.

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

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

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

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 l'ancien tag de chargement de script par le tag d'amorçage de chargement intégré.

Avant

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