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 développer rapidement des applications avec Google Maps API. Nous publions également la Google Maps API Reference.

Hello, World

La façon la plus facile d'apprendre à utiliser Google Maps 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 :

<!DOCTYPE html>
<html>
  <head>
    <style type="text/css">
      html, body { height: 100%; margin: 0; padding: 0; }
      #map { height: 100%; }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <script type="text/javascript">

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

    </script>
    <script async defer
      src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap">
    </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 API JavaScript au moyen d'une 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 type="text/css">
  html, body { height: 100%; margin: 0; padding: 0; }
  #map { height: 100%; }
</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 API

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

Pour des informations importantes sur comment charger Maps API dans leurs applications, les utilisateurs de Google Maps API for Work doivent se reporter à la section Charger Google Maps JavaScript API de la documentation Maps API for Work.

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, toutes les Google Maps 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 Google Maps JavaScript API via HTTPS au moyen de la balise <script> fournie plus haut.

Si nécessaire, vous pouvez charger Google 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 JavaScript Maps 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 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 API V3.

Chargement synchrone de l'API

Dans la balise script qui charge Maps 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.

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

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 API charge les tuiles en fonction du niveau de zoom sélectionné, voir 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…

Cette page
Commentaires sur la documentation
Google Maps JavaScript API
Google Maps JavaScript API
Commentaires sur le produit
Besoin d'aide ? Consultez notre page d'assistance.