Vous êtes prêt !

Pour passer à l'étape de développement, accédez à notre documentation pour les développeurs.

Activer Google Maps JavaScript API

Pour commencer, nous allons vous guider à travers la console Google Developers et effectuer deux ou trois petites choses :

  1. Créer ou sélectionner un projet
  2. Activer Google Maps JavaScript API et les services connexes
  3. Créer les clés appropriées
Continuer

Premiers pas

Public ciblé

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 les cartes Google Maps du point de vue de l'utilisateur. De nombreux tutoriaux sur 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 Google Maps JavaScript API. Nous publions également la Référence Google Maps JavaScript API.

Hello, World

La façon la plus facile d'apprendre à utiliser Google Maps JavaScript API est de commencer par un exemple simple. La page Web suivante montre une carte centrée sur Sydney, dans l'État de Nouvelle-Galles du Sud, en Australie :

var map;
function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -34.397, lng: 150.644},
    zoom: 8
  });
}
<div id="map"></div>
/* 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;
}
<!-- Replace the value of the key parameter with your own API key. -->
<script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyCkUOdZ5y7hMm0yrcCQoCvLwzdM6M8s5qk&callback=initMap" async defer></script>
<!DOCTYPE html>
<html>
  <head>
    <title>Simple Map</title>
    <meta name="viewport" content="initial-scale=1.0">
    <meta charset="utf-8">
    <style>
      /* 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>
  </head>
  <body>
    <div id="map"></div>
    <script>
      var map;
      function initMap() {
        map = new google.maps.Map(document.getElementById('map'), {
          center: {lat: -34.397, lng: 150.644},
          zoom: 8
        });
      }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
    async defer></script>
  </body>
</html>

Voir l'exemple (map-simple.html)

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

  1. Nous déclarons l'application au format HTML5 en utilisant la déclaration <!DOCTYPE html>.
  2. Nous créons un élément div appelé « map » pour contenir la carte.
  3. Nous définissons une fonction JavasScript qui crée une carte dans l'élément div.
  4. Nous chargeons Maps JavaScript API au moyen de la balise script.

Ces étapes sont expliquées ci-dessous.

Déclarer votre application au format HTML5

Nous vous recommandons de déclarer un véritable DOCTYPE dans votre application Web. Dans les exemples qui vous sont proposés ici, nous avons déclaré nos applications au format HTML5 au moyen d'un simple DOCTYPE HTML5, tel qu'illustré ci-dessous :

<!DOCTYPE html>

La plupart des navigateurs actuels effectuent le rendu du contenu déclaré avec ce DOCTYPE en mode « standards », ce qui signifie que votre application devrait être davantage compatible avec différents navigateurs. Le DOCTYPE est également conçu pour une dégradation progressive ; les navigateurs qui ne le comprennent pas se contentent de l'ignorer et utilisent le mode « quirks » pour afficher le contenu.

Notez que certains styles CSS qui fonctionnent dans le 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 de ces parents ne spécifie aucune taille, celle-ci 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 la carte <div> (avec l'identifiant map) doit occuper 100 % de la hauteur du corps du document HTML. Notez que nous devons spécifiquement déclarer ces pourcentages pour les balises <body> et <html> également.

Charger Google Maps JavaScript API

Pour charger Google Maps JavaScript API, utilisez une balise script comme celle illustrée dans l'exemple suivant :
    <script async defer
      src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
    </script>

L'URL contenue dans la balise script désigne l'emplacement d'un fichier JavaScript qui charge tous les symboles et toutes les définitions dont vous avez besoin pour utiliser Maps JavaScript API. Cette balise script est obligatoire.

L'attribut async permet au navigateur d'effectuer le rendu du reste de votre site Web pendant le chargement de Maps JavaScript API. Une fois l'API prête, elle appelle la fonction spécifiée en utilisant le paramètre callback.

Le paramètre key contient la clé d'API de votre application. Pour plus d'informations, voir Obtenir une clé.

Remarque : les clients Google Maps APIs Premium Plan peuvent utiliser soit une clé d'API, soit un ID client valide lorsqu'ils chargent l'API. En savoir plus sur les paramètres d'authentification des clients Premium Plan.

HTTPS ou HTTP

Nous pensons que la sécurité sur le Web est très importante et recommandons d'utiliser si possible le protocole HTTPS. Dans le cadre de nos efforts pour rendre le Web plus sûr, tous les produits Maps JavaScript API sont disponibles via HTTPS. L'utilisation du chiffrement HTTPS rend votre site plus sûr et plus résistant au furetage ou à la falsification.

Nous recommandons de charger Maps JavaScript API via HTTPS au moyen de la balise <script> fournie plus haut.

Si nécessaire, vous pouvez charger Maps JavaScript API via HTTP en utilisant l'adresse http://maps.googleapis.com/ ou http://maps.google.cn pour les utilisateurs situés en Chine.

Bibliothèques

Lorsque vous chargez Maps JavaScript API via l'URL, vous pouvez également charger des bibliothèques supplémentaires en utilisant le paramètre d'URL libraries. Les bibliothèques sont des modules de code qui apportent des fonctionnalités supplémentaires à l'interface principale Maps JavaScript API, mais qui ne sont pas chargées tant que vous n'en faites pas explicitement la demande. Pour plus d'informations, voir Bibliothèques dans Maps JavaScript API.

Chargement synchrone de l'API

Dans la balise script qui charge Maps JavaScript API, il est possible d'omettre l'attribut async et le paramètre callback. Cela entraîne le blocage du chargement de l'API jusqu'à ce qu'elle ait été téléchargée.

Si cela risque de ralentir le chargement de votre page, cela signifie aussi que vous pouvez définir d'autres balises de script, considérant 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 procédons en créant un élément div nommé et en obtenant une référence pour cet élément dans le modèle objet de document (DOM) du navigateur.

Dans l'exemple ci-dessus, nous avons utilisé une classe 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. 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 exté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 une hauteur dans l'élément <div>.

Options de carte

Deux options doivent obligatoirement être renseignées 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ù la valeur 0 correspond à une vue de la Terre en entier et les niveaux de zoom supérieurs offrent une vue rapprochée à une résolution plus élevée. Spécifiez le niveau de zoom en tant que nombre entier.

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 faible résolution. En conséquence, les images de carte dans Google Maps et Maps JavaScript API sont divisées en « tuiles » de carte et « 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 que vous pouvez vous attendre à voir à chaque niveau de zoom :

  • 1 : Le monde
  • 5 : La masse continentale/le continent
  • 10 : Ville
  • 15 : Rues
  • 20 : Immeubles

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

Pour plus d'informations sur la manière dont Maps JavaScript API charge les tuiles en fonction du niveau de zoom sélectionné, voir la section Coordonnées de tuile dans la documentation sur les types de carte.

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 même classe et chaque objet définira une carte séparée sur la page.) Pour créer une nouvelle instance de cette classe, nous utilisons l'opérateur JavaScript new.

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

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

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

Résolution des erreurs

Pour vous aider à créer un code opérationnel pour vos cartes, Brendan Kenny et Mano Marks passent en revue quelques erreurs communes et vous expliquent comment les résoudre dans cette vidéo.

Si votre code ne fonctionne pas :

  • 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 :
    • Assurez-vous d'avoir 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 pour une implémentation de référence.
  • Utilisez un débogueur JavaScript pour vous aider à identifier les problèmes, comme celui proposé dans les outils de développeur Chrome. Commencez par rechercher d'éventuelles erreurs dans la console JavaScript.
  • Publiez vos questions dans Stack Overflow. Des instructions sur la manière de publier d'excellentes questions sont disponibles sur la page Support.

Envoyer des commentaires concernant…

Google Maps JavaScript API
Google Maps JavaScript API
Besoin d'aide ? Consultez notre page d'assistance.