Aperçu

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.
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 sur 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. Vous devez également 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 d'explorer 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;

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;

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>

    <!-- 
     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>
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 y stocker 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 du format DOCTYPE simple HTML5, comme indiqué ci-dessous:

<!DOCTYPE html>

La plupart des navigateurs actuels affichent le contenu qui est déclaré avec ce DOCTYPE en mode "standards". Cela signifie que votre application doit être plus compatible avec plusieurs navigateurs. Le DOCTYPE est également conçu pour se dégrader avec fluidité ; les navigateurs qui ne comprennent pas qu'il l'ignorera et l'utiliseront pour afficher son contenu.

Notez que certains CSS qui fonctionnent en mode "quirks" ne sont pas valides en mode standard. Plus précisément, toutes les tailles basées sur un pourcentage doivent hériter des éléments de bloc parents. Si l'un de ces ancêtres ne spécifie pas de taille, elle est considérée comme étant de 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 également déclarer ces pourcentages pour <body> et <html>.

Charger l'API Maps JavaScript

L'API Maps JavaScript est chargée à l'aide d'un tag script, qui peut être ajouté directement à votre fichier HTML ou 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 une balise 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 à ajouter la balise de script intégrée.

// 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 simplifier le chargement dynamique. Il peut être installé via NPM avec les éléments suivants:

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 interface de promesse et de rappel. Vous trouverez ci-dessous un exemple d'utilisation de la méthode de promesse load() 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,
  });
});

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

Attributs de balise de script

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

  • src: URL à partir de laquelle l'API Maps JavaScript est chargée, y compris tous les 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 une fois que l'API Maps JavaScript a été entièrement chargée. 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 manière synchrone

Dans la balise script qui charge l'API Maps JavaScript, il est possible d'omettre l'attribut defer et le paramètre callback. Le chargement de l'API sera bloqué jusqu'à ce que l'API soit téléchargée.

Si cela risque de ralentir le chargement de votre page, Toutefois, cela signifie que vous pouvez écrire d'autres balises de script en supposant 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. Pour ce faire, nous créons généralement un élément div nommé et obtenons une référence à cet élément dans le modèle d'objet de document (DOM) du navigateur.

Dans l'exemple ci-dessus, nous avons utilisé le CSS pour définir la hauteur de l'élément div de la carte sur "100%". Cela permet d'adapter la carte à la taille des écrans des appareils mobiles. Vous devrez peut-être ajuster les valeurs de largeur et de hauteur en fonction de la taille de l'écran et de la marge intérieure du navigateur. Notez que la largeur des éléments div dépend généralement de leur conteneur, et que la hauteur des éléments div vides est de 0. Pour cette raison, vous devez toujours définir explicitement la hauteur sur la propriété <div>.

Options de carte

Deux options sont requises 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 avec un zoom arrière complet et un niveau de zoom plus important effectue un zoom avant à une résolution plus élevée.

zoom: 8

Pour afficher une carte de la Terre entière sous la forme d'une seule image, vous aurez besoin d'une carte immense ou d'une petite carte avec une résolution très faible. Par conséquent, les images de cartes dans Google Maps et l'API Maps JavaScript sont divisées en niveaux de "carte" et de niveau de zoom. À faible niveau de zoom, un petit ensemble de tuiles de carte couvre une vaste zone. Aux niveaux de zoom supérieurs, les tuiles sont de plus haute résolution et couvrent une zone plus petite. La liste suivante indique le niveau de détail approximatif que 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 immeubles

Les trois images suivantes reflètent le même établissement 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 des cartes et des tuiles.

L'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 classe. Chaque objet définit une carte distincte 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 carte dans le conteneur HTML donné, qui est généralement un élément DIV, en utilisant les paramètres (facultatifs) transmis.

Dépannage

Clé API et erreurs de facturation

Dans certains cas, une carte plus sombre ou une image Street View négative avec le texte en "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 de carte, 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. JavaScript est un langage sensible à la casse.
  • Vérifiez les principes de base. Certains des problèmes les plus courants surviennent lors de la création initiale de la carte. Exemples :
    • Vérifiez que vous avez spécifié les propriétés zoom et center dans vos options de carte.
    • Assurez-vous d'avoir déclaré un élément div dans lequel la carte apparaîtra à 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.
    Consultez nos exemples de mise en œuvre 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. Les consignes pour publier des questions pertinentes sont disponibles sur la page Assistance.