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

Mettre à jour votre application Google Maps JavaScript API de la version 2 à la version 3

La version 2 de Google Maps JavaScript API n'est plus disponible. Ce guide a été conçu pour aider les développeurs qui utilisent déjà la version 2 de Google Maps JavaScript API à migrer leur code vers la version 3.

Beaucoup de choses ont changé entre les versions 2 et 3 de Google Maps JavaScript API. À mesure que vous allez commencer à travailler avec la nouvelle API, vous allez rapidement vous rendre compte qu'il ne s'agit pas d'une simple mise à niveau incrémentielle. La bonne nouvelle, c'est que nous avons ajouté un grand nombre de nouvelles fonctionnalités très pratiques et amélioré la facilité d'utilisation globale de l'API en nous mettant à la place des développeurs. Si vous prévoyez passer de mettre à niveau de Google Maps JavaScript API v2 vers Google Maps JavaScript API v3, ce guide vous aidera tout au long du processus, en décrivant notamment certains des principaux changements pour les utilisateurs de la version 2.

Présentation

Si le processus de migration varie légèrement pour chaque application, certaines étapes sont toutefois communes à tous les projets :

  1. Obtenez une nouvelle clé. Google Maps JavaScript API utilise désormais Google API Console pour gérer les clés. Avant de commencer votre migration, assurez-vous d'obtenir votre nouvelle clé d'API.
  2. Mettez à jour le Bootstrap de votre API. La plupart des applications chargeront Google Maps JavaScript API v3 avec le code suivant :
    <script type="text/javascript" src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=true_OR_false"></script>
    
  3. Mettez à jour votre code. La quantité de changements requis dépendra en grande partie de votre application. Voici certains changements courants :
    • Référencez toujours l'espace de noms google.maps. Dans la version 3, tout le code de Google Maps JavaScript API est stocké dans l'espace de noms google.maps.* plutôt que dans l'espace de noms global. Dans le cadre de ce processus, la plupart des objets ont également été renommés. Par exemple, au lieu de charger GMap2, vous chargerez désormais google.maps.Map.
    • Supprimez toute référence aux méthodes obsolètes. Un certain nombre de méthodes d'utilitaires générales on été supprimées, comme GDownloadURL ou GLog. Vous devez soit remplacer ces fonctionnalités par des bibliothèques d'utilitaires tierces, soit supprimer ces références de votre code.
    • (Facultatif) Ajoutez des bibliothèques à votre code. De nombreuses fonctionnalités ont été regroupées dans des bibliothèques d'utilitaires, de sorte que chaque application ne doit charger que les parties de l'API qu'elle utilisera.
    • (Facultatif) Configurez votre projet pour utiliser les externs de la version 3. Les externs de la version 3 peuvent être utilisés pour valider votre code avec le Closure Compiler ou pour déclencher la saisie semi-automatique dans votre environnement de développement. En savoir plus sur la compilation avancées et les externs.
  4. Testez et itérez. À ce stade, il vous restera encore un peu de travail à faire, mais vous aurez déjà bien avancé dans votre migration vers la nouvelle application Maps v3.

Changement apportés à la version 3 de Google Maps JavaScript API

Avant de planifier votre migration, prenez le temps de comprendre les différences entre Google Maps JavaScript API v2 et Google Maps JavaScript API v3. La version la plus récente de Google Maps JavaScript API a été entièrement réécrite, en mettant l'accent sur les techniques de programmation JavaScript modernes, l'usage accru des bibliothèques et la simplification de l'API. Un grand nombre de nouvelles fonctionnalités ont été ajoutées à l'API, et plusieurs fonctionnalités familières ont été modifiées, voire supprimées. Cette section présente certaines des principales différences entre les deux versions.

Changements apportés à la version 3 de l'API :

  • Une bibliothèque centrale simplifiée. La plupart des fonctionnalités supplémentaires ont été déplacées dans des bibliothèques, afin de réduire les temps de chargement et d'analyse pour l'API centrale et charger ainsi plus rapidement vos cartes sur n'importe quel appareil.
  • Des performances améliorées pour plusieurs fonctionnalités, dont le rendu des polygones et le placement des marqueurs.
  • Une nouvelle approche des limites d'utilisation côté client afin de mieux prendre en charge les adresses partagées utilisées par les proxies mobiles et les pare-feu d'entreprise.
  • La prise en charge de plusieurs navigateurs modernes et de navigateurs mobiles. Internet Explorer 6 n'est plus pris en charge.
  • La suppression de nombreuses classes d'aide générales (GLog ou GDownloadUrl). Il existe aujourd'hui un grand nombre d'excellentes bibliothèques JavaScript qui fournissent une fonctionnalité similaire, comme Closure ou jQuery.
  • Une implémentation HTML5 de Street View qui se chargera sur n'importe quel appareil mobile.
  • Des panoramas Street View personnalisés avec vos propres photos, pour que vous puissiez partager des panoramas de pistes de ski, de maisons en vente ou autres lieux d'intérêt.
  • Des personnalisations de cartes stylisées vous permettant d'adapter l'affichage des éléments de la carte de base en fonction de votre identité visuelle spécifique.
  • La prise en charge de plusieurs nouveaux services, comme les services ElevationService et Distance Matrix.
  • Un service Directions amélioré proposant des itinéraires alternatifs, l'optimisation des itinéraires (des solutions alternatives au problème du voyageur de commerce), des itinéraires à vélo (avec un calque bicycling), des itinéraires en transports en commun et des itinéraires déplaçables.
  • Un format de géocodage mis à jour fournissant des informations de type plus précises que la valeur accuracy de Google Maps Geocoding API v2.
  • La prise en charge de plusieurs fenêtres d'info sur une même carte.

Mettre à jour votre application

Votre nouvelle clé

Google Maps JavaScript API v3 utilise un nouveau système de clés. Cela signifie que votre clé pour la version 2 ne fonctionnera pas avec la version 3. En ajoutant une clé v3 avant de mettre votre application en service :

La clé est transmise lors du chargement de Google Maps JavaScript API v3. Pour générer une clé :

  1. Accédez à la Google API Console et connectez-vous à l'aide de votre compte Google.
  2. Cliquez sur le lien Services dans le menu de gauche et activez le service Google Maps JavaScript API v3.
  3. Une fois le service activé, votre clé d'API est disponible via la page API Access, dans la section Simple API Access. Les applications Maps API utilisent les clés pour applications de navigateur.

ID client pour les licences Maps APIs for Work

Si vous êtes titulaire d'une licence Google Maps APIs for Work, vous devez utiliser un ID client à la place de la clé. Notez qu'il n'est pas possible d'utiliser les deux ensemble. Les ID client sont similaires aux clés, avec toutefois les différences suivantes :

  • Les applications Google Maps APIs qui utilisent un ID client peuvent avoir accès à des fonctionnalités supplémentaires ou des limites supérieures, comme Maps Analytics.
  • Votre ID client est créé par Google Cloud Support et vous est fourni dans votre lettre de bienvenue de Maps APIs for Work. Vous n'utilisez pas Google API Console pour créer ou trouver votre ID client.
  • Lorsque vous chargerez Google Maps JavaScript API, vous utiliserez le paramètre client plutôt que le paramètre key. Par exemple :
    <script src="//maps.googleapis.com/maps/api/js?v=3&client=gme-yourclientid&sensor=true_or_false" type="text/javascript"></script>
  • Les ID client sont toujours précédés du préfixe gme-.

Charger l'API

La première modification que vous devrez apporter à votre code concerne le chargement de l'API. Dans la version 2, vous chargez Google Maps JavaScript API via une requête à http://maps.google.com/maps. Si vous chargez Google Maps JavaScript API v3, vous devez apporter les modifications suivantes :

  1. Chargez l'API depuis //maps.googleapis.com/maps/api/js
  2. Supprimez le paramètre file.
  3. Assurez-vous d'inclure le paramètre sensor obligatoire.
  4. Mettez à jour le paramètre key avec votre nouvelle clé v3. Les clients Google Maps APIs for Work doivent utiliser un paramètre client.
  5. (Google Maps APIs Premium Plan uniquement) Veillez à ce que le paramètre client soit fourni, tel qu'expliqué dans le Guide du développeur de Google Maps APIs Premium Plan.
  6. Supprimez le paramètre v pour demander la version la plus récente ou modifiez sa valeur conformément au schéma de versionnage v3.
  7. (Facultatif) Remplacez le paramètre hl par le paramètre language et conservez sa valeur.
  8. (Facultatif) Ajoutez un paramètre libraries pour charger des bibliothèques facultatives.

Dans le cas le plus simple, le bootstrap v3 spécifiera uniquement votre clé d'API et le paramètre sensor :

<script type="text/javascript" src="//maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&sensor=false"></script>

L'exemple ci-dessous demande la dernière version (Experimental) de Maps JavaScript API v2 en allemand :

<script type="text/javascript" src="//maps.google.com/maps?file=api&v=2.x&sensor=false&key=YOUR_API_KEY&hl=de"></script>

L'exemple ci-dessous est une requête équivalente pour la version 3.

<script type="text/javascript" src="//maps.googleapis.com/maps/api/js?v=3.exp&sensor=false&key=YOUR_API_KEY&language=de"></script>

Versionnage

Dans v3, il n'est pas nécessaire de charger une version spécifique. Si vous omettez le paramètre de version, vous obtiendrez la version Experimental la plus récente de l'API. Si vous préférez, vous pouvez spécifier un numéro de version spécifique, la dernière version (Experimental) ou la version la plus stable, Frozen.

Le tableau ci-dessous indique le schéma de versionnage de la version 2 à la version 3.

v2 v3 Cas d'utilisation
2.s 3.0 Version Frozen. Version la plus ancienne disponible.
2 3 Version Release. Version stable la plus récente.
2.x 3.exp Version Experimental.

Important : Le contrat de niveau de service pour Google Maps APIs Premium Plan ne s'applique pas à la version Experimental. Les applications Google Maps APIs Premium Plan doivent utiliser l'actuelle version Release ou Frozen pour être couvertes par le contrat de niveau de service.

Présentation de l'espace de noms google.maps

Le changement le plus notable apporté par Google Maps JavaScript API v3 est sans doute l'introduction de l'espace de noms google.maps. L'API v2 place tous les objets dans l'espace de noms Global par défaut, ce qui peut entraîner des conflits de noms. Dans la version 3, tous les objets sont situés dans l'espace de noms google.maps.

Lorsque vous migrez votre application vers la version 3, vous devez modifier votre code pour utiliser le nouvel espace de noms. Malheureusement, il ne suffit pas de rechercher les occurrences de « G » et de les remplacer par « google.maps ». C'est toutefois une bonne règle de départ pour modifier votre code. Voici quelques exemples des classes équivalentes dans les versions 2 et 3.

v2 v3
GMap2 google.maps.Map
GLatLng google.maps.LatLng
GInfoWindow google.maps.InfoWindow
GMapOptions google.map.MapOptions
G_API_VERSION google.maps.version
GPolyStyleOptions google.maps.PolygonOptions
ou google.maps.PolylineOptions

Supprimer le code Google obsolète

Si Google Maps JavaScript API v3 offre des équivalents pour presque toutes les fonctionnalités de v2, certaines classes ne sont toutefois plus prises en charge. Dans le cadre de votre migration, vous devez soit remplacer ces classes par des bibliothèques d'utilitaires tierces, soit supprimer ces références de votre code. Il existe un grand nombre d'excellentes bibliothèques JavaScript qui fournissent une fonctionnalité similaire, comme Closure ou jQuery.

Les classes suivantes n'ont pas d'équivalent dans Google Maps JavaScript API v3 :

GBoundsGLanguage
GBrowserIsCompatibleGLayer
GControlGLog
GControlAnchorGMercatorProjection
GControlImplGNavLabelControl
GControlPositionGObliqueMercator
GCopyrightGOverlay
GCopyrightCollectionGPhotoSpec
GDownloadUrlGPolyEditingOptions
GDraggableObjectGScreenOverlay
GDraggableObjectOptionsGStreetviewFeatures
GFactualGeocodeCacheGStreetviewLocation
GGeoAddressAccuracyGStreetviewOverlay
GGeocodeCacheGStreetviewUserPhotosOptions
GGoogleBarGTileLayerOptions
GGoogleBarAdsOptionsGTileLayerOverlayOptions
GGoogleBarLinkTargetGTrafficOverlayOptions
GGoogleBarListingTypesGUnload
GGoogleBarOptionsGXml
GGoogleBarResultListGXmlHttp
GInfoWindowTabGXslt
GKeyboardHandler

Comparer le code

Comparons deux applications plutôt simples qui ont été écrites avec les API v2 et v3.

<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.google.com/maps?file=api&v=2&key=YOUR_API_KEY&sensor=false"
        type="text/javascript"></script>
    <style type="text/css">
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script type="text/javascript">
    function initialize() {
      if (GBrowserIsCompatible()) {
        var map = new GMap2(
            document.getElementById('map'));
        map.setCenter(new GLatLng(37.4419, -122.1419), 13);
        map.setUIToDefault();

        map.addOverlay(new GMarker(new GLatLng(37.4419, -122.1419)));

      }
    }
    </script>
  </head>
  <body onload="initialize()" onunload="GUnload()">
    <div id="map"></div>
  </body>
</html>
    
<!DOCTYPE html>
<html>
  <head>
    <script src="//maps.googleapis.com/maps/api/js?sensor=false"
        type="text/javascript"></script>
    <style type="text/css">
      html, body, #map { height: 100%; margin: 0; }
    </style>
    <script type="text/javascript">
    function initialize() {
      var map = new google.maps.Map(
        document.getElementById('map'), {
          center: new google.maps.LatLng(37.4419, -122.1419),
          zoom: 13,
          mapTypeId: google.maps.MapTypeId.ROADMAP
      });

      var marker = new google.maps.Marker({
            position: new google.maps.LatLng(37.4419, -122.1419),
            map: map
      });

    }
    google.maps.event.addDomListener(window, 'load', initialize);
    </script>
  </head>
  <body>
    <div id="map"></div>
  </body>
</html>
    

Comme vous pouvez le voir, il y a plusieurs différences entre les deux applications. Les changements notables sont les suivants :

  • L'adresse à partir de laquelle l'API est chargée a été modifiée.
  • Les méthodes GBrowserIsCompatible() et GUnload() ne sont plus requises dans la version 3 et ont été supprimées de l'API.
  • L'objet GMap2 est remplacé par google.maps.Map en tant qu'objet central dans l'API.
  • Les propriétés sont désormais chargées via les classes Options. Dans l'exemple ci-dessus, nous avons défini les trois propriétés requises pour charger une carte (center, zoom et mapTypeId) via un objet en ligne MapOptions.
  • L'interface utilisateur par défaut est activée par défaut dans la version 3. Vous pouvez désactiver ce réglage en définissant la propriété disableDefaultUI sur true dans l'objet MapOptions.

Résumé

À ce stade, vous connaissez les principaux points nécessaires à votre migration de Google Maps JavaScript API v2 vers Google Maps JavaScript API v3. Il vous reste encore toutefois beaucoup de choses à savoir, mais cela dépend de votre application. Dans les sections suivantes, nous vous proposons des instructions de migration pour les cas spécifiques que vous pourriez rencontrer. Il existe également des ressources que vous pourriez trouver utiles durant le processus de mise à niveau.

  • La documentation sur Google Maps JavaScript API v3 pour les développeurs est le meilleur endroit pour en savoir plus sur l'API et son fonctionnement.
  • La référence sur l'API v3 vous permettra d'en apprendre davantage sur les nouvelles classes et méthodes utilisées dans l'API v3.
  • La communauté Stack Overflow est l'endroit idéal pour poser vos questions relatives au code. Sur le site, les questions et réponses liées à Google Maps JavaScript API utilisent les mots clés « google-maps » ou « google-maps-api-3 ».
  • Les clients Google Maps APIs Premium Plan voudront lire la documentation sur Google Maps APIs Premium Plan.
  • Notre Page Google Plus et le Blog Google Geo Developers sont d'excellentes ressources pour connaître les derniers changements apportés à l'API.

Si vous avez des problèmes ou des questions concernant cet article, veuillez utiliser le lien Send Feedback en haut de cette page.

Référence détaillée

Cette section offre un comparatif détaillé des fonctionnalités les plus populaires des versions 2 et 3 de Google Maps JavaScript API. Chaque section de la référence a été conçue pour être lue individuellement. Nous vous conseillons donc de ne pas lire cette référence d'une seule traite, mais de vous y reporter au cas par cas durant le processus de migration.

  • Événements - enregistrement et gestion des événements
  • Commandes - manipulation des commandes de navigation qui apparaissent sur la carte.
  • Superpositions - ajout et modification d'objets sur la carte.
  • Types de carte - identification des tuiles qui constituent la carte de base.
  • Calques - ajout et modification de contenu en tant que groupe, par exemple les calques KML ou Trafic.
  • Services - utilisation des services Geocoding, Directions ou Street View de Google.

Événements

Le modèle d'événement de Google Maps JavaScript API v3 est similaire à celui utilisé dans le version 2, mais certains éléments ont été profondément remaniés.

Commandes

Google Maps JavaScript API affiche des commandes d'interface utilisateur qui permettent aux utilisateurs d'interagir avec votre carte. Vous pouvez utiliser l'API pour personnaliser l'aspect de ces commandes.

Superpositions

Les superpositions reflètent les objets que vous « ajoutez » à la carte pour désigner des points, des lignes, des zones ou des groupes d'objets.

Types de carte

Les types de carte disponibles dans les versions 2 et 3 sont légèrement différents, mais tous les types de carte basiques sont disponibles dans les deux versions de l'API. Par défaut, la version 2 utilise des tuiles de carte routière « peintes » standard. La version 3 nécessite toutefois qu'un type de carte spécifique soit fourni lors de la création d'un objet google.maps.Map.

Calques

Sur une carte, les calques sont des objets qui consistent en une ou plusieurs superpositions. Ils peuvent être manipulés en tant qu'entité unique et reflètent en général des groupes d'objets.

Services

Envoyer des commentaires concernant…

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