Présentation

Sélectionnez une plate-forme : Android iOS JavaScript

L'API Maps JavaScript vous permet de personnaliser des cartes avec votre contenu et vos images afin de les afficher sur des pages Web et des appareils mobiles. L'API Maps JavaScript propose quatre types de carte de base (carte routière, satellite, hybride et relief) que vous pouvez modifier à l'aide de calques et de styles, de commandes et d'événements, ainsi que de différents services et bibliothèques.

Audience

Cette documentation s'adresse aux personnes familiarisées avec la programmation JavaScript et les concepts de programmation orientée objet. Il est également recommandé de connaître Maps du point de vue de l'utilisateur. De nombreux tutoriels JavaScript sont disponibles sur le Web.

Cette documentation conceptuelle est conçue pour vous permettre de découvrir et de développer rapidement des applications avec l'API Maps JavaScript. Nous publions également la documentation de référence de l'API Maps JavaScript.

Hello World

Le moyen le plus simple de vous familiariser avec l'API Maps JavaScript est de consulter un exemple simple. L'exemple suivant affiche une carte centrée sur Sydney, en Nouvelle-Galles du Sud en Australie.

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();

JavaScript

let map;

async function initMap() {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");

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

initMap();

CSS

/*
 * Always set the map height explicitly to define the size of the div element
 * that contains the map.
 */
#map {
  height: 100%;
}

/*
 * Optional: Makes the sample page fill the window.
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

HTML

<html>
  <head>
    <title>Simple Map</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="map"></div>

    <!-- 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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
Voir un exemple

Essayer l'exemple

Même dans ce simple exemple, plusieurs choses sont à noter :

  1. Nous déclarons l'application au format HTML5 à l'aide de la déclaration <!DOCTYPE html>.
  2. Nous créons un élément div nommé "map" pour contenir la carte.
  3. Nous définissons une fonction JavaScript qui crée une carte dans div.
  4. Nous chargeons l'API Maps JavaScript à l'aide du chargeur d'amorçage.

Ces étapes sont expliquées ci-dessous.

Charger l'API Maps JavaScript

Il est recommandé de charger l'API Maps JavaScript avec le chargeur d'amorçage. Vous pouvez également utiliser le chargeur d'API JS. Nous vous recommandons d'examiner les deux approches et de choisir celle qui convient le mieux à la structure du code de votre projet.

Pour en savoir plus, consultez Charger l'API Maps JavaScript.

Chargeur d'amorçage

Chargez l'API Maps JavaScript en ajoutant le chargeur d'amorçage intégré au code de votre application, comme indiqué dans l'extrait de code 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_HERE",
    // Add other bootstrap parameters as needed, using camel case.
    // Use the 'v' parameter to indicate the version to load (alpha, beta, weekly, etc.)
  });
</script>

Pour charger des bibliothèques lors de l'exécution, utilisez l'opérateur await pour appeler importLibrary() à partir d'une fonction asynchrone, comme indiqué ci-dessous :

TypeScript

let map: google.maps.Map;
async function initMap(): Promise<void> {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");
  map = new Map(document.getElementById("map") as HTMLElement, {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
}

initMap();

JavaScript

let map;

async function initMap() {
  //@ts-ignore
  const { Map } = await google.maps.importLibrary("maps");

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

initMap();

Package NPM js-api-loader

Utilisez @googlemaps/js-api-loader pour charger l'API Maps JavaScript à l'aide de NPM. Installez-la via NPM à 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,
  });
});

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

Déclarer votre application au format HTML5

Nous vous recommandons de déclarer un vrai DOCTYPE dans votre application Web. Dans les exemples de cette page, nous avons déclaré nos applications au format HTML5 à l'aide de l'élément HTML5 DOCTYPE simple, comme illustré ci-dessous :

<!DOCTYPE html>

La plupart des navigateurs actuels affichent le contenu déclaré avec ce DOCTYPE en mode "standards", ce qui signifie que votre application devrait être conforme pour un plus grand nombre de navigateurs. Le DOCTYPE est également conçu pour être à l'épreuve du temps. Les navigateurs qui ne le comprennent pas l'ignoreront et utiliseront le mode quirks pour afficher leur contenu.

Notez que certains CSS qui fonctionnent en mode quirks ne sont pas valides en mode standards. Plus précisément, toutes les tailles basées sur des pourcentages doivent hériter des éléments de bloc parents, et si l'un des ancêtres ne spécifie aucune taille, elle est définie sur 0 x 0 pixel. Pour cette raison, nous incluons la déclaration <style> suivante :

<style>
  #map {
    height: 100%;
  }
  html, body {
    height: 100%;
    margin: 0;
    padding: 0;
  }
</style>

Cette déclaration CSS indique que le conteneur de carte <div> (avec l'ID map) doit occuper 100 % de la hauteur du corps HTML. Notez que nous devons spécifiquement déclarer ces pourcentages pour <body> et <html> également.

Charger l'API Maps JavaScript

L'API Maps JavaScript est chargée à l'aide d'un tag script, qui peut être intégré à votre fichier HTML ou ajouté dynamiquement à l'aide d'un fichier JavaScript distinct. Nous vous recommandons d'examiner les deux approches et de choisir celle qui convient le mieux à la structure du code de votre projet.

Chargement intégré

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>

Chargement dynamique

Pour charger dynamiquement l'API Maps JavaScript intégrée à l'aide d'un fichier JavaScript distinct, consultez l'exemple ci-dessous. Cette approche vous permet de gérer tout votre code à utiliser avec l'API à partir d'un fichier .js distinct. Cela équivaut à intégrer le tag du script.

// Create the script tag, set the appropriate attributes
var script = document.createElement('script');
script.src = 'https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap';
script.async = true;

// Attach your callback function to the `window` object
window.initMap = function() {
  // JS API is loaded and available
};

// Append the 'script' element to 'head'
document.head.appendChild(script);
      

Chargement dynamique

Le package @googlemaps/js-api-loader est disponible pour fluidifier le chargement dynamique. Il peut être installé via NPM avec 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,
  });
});

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

Attributs du tag de script

Notez dans les exemples ci-dessus que plusieurs attributs sont définis sur le tag script, ce qui est recommandé. Vous trouverez ci-dessous une explication pour chaque attribut.

  • src : l'URL à partir de laquelle l'API Maps JavaScript est chargée, y compris l'ensemble des symboles et définitions dont vous avez besoin pour utiliser l'API Maps JavaScript. Dans cet exemple, l'URL comporte deux paramètres : key, où vous fournissez votre clé API, et callback, où vous spécifiez le nom d'une fonction globale à appeler lorsque que l'API Maps JavaScript se charge complètement. En savoir plus sur les paramètres d'URL
  • async : demande au navigateur de télécharger et d'exécuter le script de manière asynchrone. Lorsque le script est exécuté, il appelle la fonction spécifiée à l'aide du paramètre callback.

Bibliothèques

Lorsque vous chargez l'API Maps JavaScript via l'URL, vous pouvez, si vous le souhaitez, charger des bibliothèques supplémentaires à l'aide de l'opérateur await pour appeler importLibrary() dans une fonction asynchrone. Les bibliothèques sont des modules de code qui fournissent des fonctionnalités supplémentaires à l'API Maps JavaScript principale, mais qui ne sont pas chargés, sauf si vous les demandez spécifiquement. Pour en savoir plus, consultez la section Bibliothèques de l'API Maps JavaScript.

Éléments DOM de carte

<div id="map"></div>

Pour que la carte s'affiche sur une page Web, vous devez lui réserver un espace. En règle générale, nous créons pour cela un élément div nommé et en obtenant une référence à cet élément dans le Document Object Model (DOM) du navigateur.

Dans l'exemple ci-dessus, nous avons utilisé un CSS pour définir la hauteur du div de la carte sur "100%". La carte sera ainsi adaptée à la taille des écrans des appareils mobiles. Il se peut que vous deviez adapter les valeurs de largeur et de hauteur en fonction de la taille d'écran et de la marge intérieure du navigateur. Notez que la largeur des div dépend généralement de leur élément conteneur et que la hauteur des div vides est de 0. Pour cette raison, vous devez toujours définir explicitement la hauteur du <div>.

Options de carte

Deux options sont obligatoires pour chaque carte : center et zoom.

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

Niveaux de zoom

La résolution initiale à laquelle afficher la carte est définie par la propriété zoom, où le zoom 0 correspond à une carte de la Terre complètement dézoomée tandis que les niveaux de zoom plus importants correspondent à une résolution plus élevée.

zoom: 8

Fournir une carte de la Terre entière sous la forme d'une seule image nécessiterait soit une carte immense, soit une petite carte à très basse résolution. Par conséquent, les images de carte dans Google Maps et l'API Maps JavaScript sont divisées en "tuiles" et en "niveaux de zoom". Aux niveaux de zoom peu élevés, un petit ensemble de tuiles de carte couvre une grande superficie. Aux niveaux de zoom supérieurs, les tuiles offrent une plus grande résolution et couvrent une surface plus réduite. La liste suivante indique le niveau de détail approximatif auquel vous pouvez vous attendre à chaque niveau de zoom :

  • 1 : Le monde
  • 5 : La masse continentale/le continent
  • 10 : La ville
  • 15 : Les rues
  • 20 : Les bâtiments

Les trois images suivantes montrent la même vue de Tokyo aux niveaux de zoom 0, 7 et 18.

Pour savoir comment l'API Maps JavaScript charge les tuiles en fonction du niveau de zoom actuel, consultez le guide sur les coordonnées de carte et de tuile.

Objet Map

map = new Map(document.getElementById("map"), {...});

La classe JavaScript qui représente une carte est la classe Map. Les objets de cette classe définissent une seule carte sur une page. Vous pouvez créer plusieurs instances de cette même classe. Chaque objet définira alors une carte séparée sur la page. Nous créons une instance de cette classe à l'aide de l'opérateur JavaScript new.

Lorsque vous créez une instance de carte, vous spécifiez un élément HTML <div> sur la page en tant que conteneur pour la carte. Les nœuds HTML sont des enfants de l'objet JavaScript document. Nous obtenons une référence à cet élément via la méthode document.getElementById().

Ce code définit une variable (nommée map) et l'attribue à un nouvel objet Map. La fonction Map() est appelée constructeur et sa définition est illustrée ci-dessous :

Constructeur Description
Map(mapDiv:Node, opts?:MapOptions ) Crée une nouvelle carte à l'intérieur du conteneur HTML (en général un élément DIV) en utilisant tout paramètre (facultatif) transmis.

Résoudre les problèmes

Clé API et erreurs de facturation

Dans certains cas, une carte plus sombre ou une image "négative" Street View, portant le filigrane "à des fins de développement uniquement", peut s'afficher. Cela indique généralement des problèmes liés à une clé API ou à la facturation. Pour utiliser les produits Google Maps Platform, vous devez activer la facturation dans votre compte, et toutes les requêtes doivent inclure une clé API valide. La procédure suivante permet de résoudre ce problème :

Si votre code ne fonctionne pas :

Pour vous aider à configurer votre code Maps, Brendan Kenny et Mano Marks vous présentent dans cette vidéo quelques-unes des erreurs les plus courantes et la façon de les corriger.

  • Vérifiez qu'il ne contient pas de fautes de frappe. Rappelez-vous que le langage JavaScript est sensible à la casse.
  • Vérifiez les bases. Certains des problèmes les plus courants surviennent en effet lors de la création initiale de la carte. Par exemple :
    • Vérifiez que vous avez spécifié les propriétés zoom et center dans les options de votre carte.
    • Assurez-vous d'avoir déclaré un élément div dans lequel la carte s'affichera à l'écran.
    • Assurez-vous d'avoir défini une hauteur dans l'élément div pour la carte. Par défaut, les éléments div sont créés avec une hauteur de 0 et sont donc invisibles.
    Reportez-vous à nos exemples, qui vous proposent une implémentation de référence.
  • Utilisez un débogueur JavaScript pour identifier les problèmes, par exemple celui disponible dans les outils pour les développeurs Chrome. Commencez par rechercher d'éventuelles erreurs dans la console JavaScript.
  • Posez vos questions sur Stack Overflow. Pour savoir comment poser des questions de qualité, consultez la page d'assistance.