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

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

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

let map;

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

window.initMap = initMap;
index.js

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

style.css

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>

    <!--
      The `defer` attribute causes the callback to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises
      with https://www.npmjs.com/package/@googlemaps/js-api-loader.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initMap&v=weekly"
      defer
    ></script>
  </body>
</html>
index.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 d'un tag script.

Ces étapes sont expliquées ci-dessous.

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(() => {
  map = new google.maps.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(() => {
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: -34.397, lng: 150.644 },
    zoom: 8,
  });
});

index.js

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 éventuellement charger des bibliothèques supplémentaires à l'aide du paramètre d'URL libraries. 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.

Charger l'API de façon synchrone

Dans le tag script qui charge l'API Maps JavaScript, il est possible d'omettre l'attribut defer et le paramètre callback. Cela bloque le chargement de l'API jusqu'à ce qu'elle soit téléchargée.

Si cela risque de ralentir le chargement de votre page, cela signifie aussi que vous pouvez définir d'autres tags de script qui supposent que l'API est déjà chargée.

É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 google.maps.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 google.maps.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.