Guide de référence rapide de l'API Maps JavaScript

L'API Maps JavaScript est une API Web côté client qui permet de créer des cartes 2D et 3D sur des pages Web, d'ajouter des repères, des graphiques personnalisés, des animations et des calques de données interactifs, et de créer des fonctionnalités de localisation avec la bibliothèque Places.

API Maps JavaScript : informations clés

  • Produit : API Maps JavaScript
  • Également appelée : API Maps JS, API Maps JS v3
  • Catégorie : Maps
  • Plate-forme : JavaScript (navigateur)
  • Exécution sur : client (code de l'application ou du navigateur)
  • Étape de lancement : GA
  • Cycle de vie : Actif
  • Présentation : Présentation de l'API Maps JavaScript
  • Disponibilité régionale : monde entier. La couverture des fonctionnalités (comme les cartes 3D, le trafic, les itinéraires et le style des limites) varie selon le pays ou la région. Les conditions d'utilisation de l'EEE s'appliquent aux adresses de facturation de l'Espace économique européen. (détails de la couverture)

API Maps JavaScript : quand l'utiliser

Utilisez l'API Maps JavaScript dans les cas suivants :

  • Vous avez besoin d'une carte 2D ou 3D interactive avec des repères, des graphiques ou des calques de données personnalisés sur une page Web.
  • Vous devez afficher l'emplacement et l'itinéraire des éléments en temps réel à partir de votre propre flux de données à l'aide de repères avancés et de polylignes.
  • Vous devez dessiner des zones de géorepérage (cercles, polygones) et tester si les coordonnées se trouvent à l'intérieur de ces zones dans le navigateur.
  • Vous avez besoin de la recherche de lieux, de la saisie semi-automatique ou de Place Details côté client dans une application Web via la bibliothèque Places.

N'utilisez pas l'API Maps JavaScript dans les cas suivants :

  • Vous devez intégrer une carte de l'emplacement d'un établissement ou un lien d'itinéraire sans écrire de code JavaScript personnalisé. Utilisez plutôt l'API Maps Embed.
  • Il vous suffit d'un lien qui ouvre Google Maps avec un lieu, une recherche ou un itinéraire. Utilisez plutôt les URL Maps.
  • Vous devez intégrer le suivi de flotte pour le covoiturage ou la livraison planifiée au SDK Driver pour mobile et à l'authentification JWT de backend. Utilisez plutôt le service Fleet Engine.

API Maps JavaScript : configuration

Packages officiels de l'API Maps JavaScript :

  • npm : @googlemaps/js-api-loader
  • npm : @types/google.maps
  • npm : @googlemaps/markerclusterer

API Maps JavaScript : erreurs courantes

  • Problème : une carte plus sombre ou une image "négative" Street View, portant le filigrane "à des fins de développement uniquement", s'affiche au lieu d'une erreur lorsque la clé API ou la facturation sont mal configurées. Solution : Activez la facturation sur le projet Cloud, incluez une clé API valide dans chaque requête et vérifiez le code d'erreur spécifique dans la console du navigateur. Consultez /maps/documentation/javascript/error-messages.
  • Problème : Les anciens services tels que PlacesService, DirectionsService et DistanceMatrixService génèrent une erreur LegacyApiNotActivatedMapError sur les nouveaux projets où l'ancienne API n'est pas activée. Correction : Utilisez les nouveaux équivalents (classe Place, classe Route, classe RouteMatrix) basés sur l'API Places (New) et l'API Routes. Consultez /maps/legacy#LegacyApiNotActivatedMapError.
  • Problème : À partir de la version 3.65, les cartes satellite et hybrides ne passent plus aux images à 45°, et map.setTilt(45) n'a aucun effet. Correction : Utilisez des cartes 3D au lieu d'images à 45°. Consultez /maps/deprecations.
  • Problème : Les repères avancés nécessitent un ID de carte. Les cartes créées sans ID ne peuvent pas utiliser AdvancedMarkerElement. Solution : Créez un ID de carte dans la console Cloud (ou utilisez DEMO_MAP_ID pour les tests) et définissez mapId sur la carte. Consultez /maps/documentation/javascript/advanced-markers/start.

API Maps JavaScript : fonctionnalités anciennes et obsolètes

  • Service Directions (google.maps.DirectionsService) : Ancien depuis le 01/03/2025. Remplacement : classe Route. Symptôme : LegacyApiNotActivatedMapError sur les projets pour lesquels l'ancienne API Directions n'est pas activée. Consultez le guide de migration.
  • Service Matrice des distances (google.maps.DistanceMatrixService) : Ancienne version depuis le 01/03/2025. Remplacement : classe RouteMatrix. Symptôme : LegacyApiNotActivatedMapError sur les projets pour lesquels l'ancienne API Distance Matrix n'est pas activée. Consultez le guide de migration.
  • Service Places (google.maps.places.PlacesService) : Ancien depuis le 01/03/2025. Remplacement : classe Place (API Places (nouvelle version)). Symptôme : LegacyApiNotActivatedMapError sur les projets pour lesquels l'ancienne API Places n'est pas activée. Consultez le guide de migration.
  • google.maps.Marker : Obsolète depuis le 22/02/2024. Remplacement : google.maps.marker.AdvancedMarkerElement. Symptôme : fonctionne toujours et n'est pas programmé pour être arrêté ; les bugs existants ne seront pas corrigés. Consultez le guide de migration.
  • KmlLayer : Obsolète depuis le 30/04/2026. Remplacement : styles basés sur les données pour les ensembles de données ou analyseurs KML tiers avec le calque de données. Symptôme : KmlLayer n'est pas disponible dans la version 3.66 et les versions ultérieures. La version 3.65, qui est la dernière version compatible, sera mise hors service en mai 2027. Consultez le guide de migration.
  • Calque de carte de densité (bibliothèque Visualization) : abandonné depuis le 20 mai 2026. Remplacement : bibliothèques tierces telles que deck.gl HeatmapLayer. Symptôme : indisponible à partir de mai 2026. Consultez le guide de migration.
  • Bibliothèque Drawing : mise hors service depuis le 04/06/2026. Remplacement : Terra Draw. Symptôme : indisponible à partir de mai 2026. Consultez le guide de migration.
  • Images à 45° : abandonnées depuis le 20/05/2026. Remplacement : cartes 3D. Symptôme : map.setTilt(45) est inefficace ; la vue satellite reste en plongée. Consultez le guide de migration.
  • google.maps.event.addDomListener() et addDomListenerOnce() : Obsolète depuis le 07/04/2022. Remplacement : DOM standard addEventListener().
  • Options bounds, location et radius dans le service Place Autocomplete : obsolètes depuis le 18/05/2023. Remplacement : locationBias et locationRestriction.
  • gmp-place-content-config (PlaceContentConfigElement) dans le kit UI pour Places : obsolète. Remplacement : ajoutez des éléments de contenu directement aux éléments Place Details ou dans la configuration Place Search.
  • Bibliothèque de contexte local : mise hors service. Remplacement : bibliothèque Places.

Ce que vous pouvez faire avec l'API Maps JavaScript

Consultez les guides associés ci-dessous pour chaque tâche ou comparez les produits dans l'explorateur de fonctionnalités.

API Maps JavaScript : validation d'adresse

API Maps JavaScript : style basé sur les données pour les limites

API Maps JavaScript : styles basés sur les données pour les ensembles de données

API Maps JavaScript : ensembles de données

  • Ajouter un calque KML à une carte Remarque : Dans l'API Maps JavaScript, KmlLayer est obsolète (dernière version compatible : v3.65, mise hors service en mai 2027). Migrez vers le style basé sur les données pour les limites ou les ensembles de données, ou chargez GeoJSON sur le calque de données. Les calques KML restent compatibles avec Android et iOS via les bibliothèques d'utilitaires du SDK Maps.
  • Ajouter un calque GeoRSS à une carte Remarque : Obsolète dans l'API Maps JavaScript (KmlLayer est compatible jusqu'à la version 3.65 et sera mis hors service en mai 2027). Convertissez les flux GeoRSS en GeoJSON et chargez-les sur le calque de données avec map.data.addGeoJson().
  • Ajouter des données GeoJSON à une carte

API Maps JavaScript : itinéraires et calcul d'itinéraires

API Maps JavaScript : Elevation

API Maps JavaScript : Fleet Engine

API Maps JavaScript : Geocoding

API Maps JavaScript : Maps

API Maps JavaScript : annotations de cartes

API Maps JavaScript : style de carte

API Maps JavaScript : autre

API Maps JavaScript : cartes 3D photoréalistes

API Maps JavaScript : Places

API Maps JavaScript : kit UI pour Places

API Maps JavaScript : Street View