Maps JavaScript API quick reference

The Maps JavaScript API is a client-side web API for creating 2D and 3D maps on web pages, adding markers, custom graphics, animations, and interactive data layers, and building location features with the Places library.

Maps JavaScript API: key facts

  • Product: Maps JavaScript API
  • Also known as: Maps JS API, Maps JS API v3
  • Category: Maps
  • Platform: JavaScript (browser)
  • Runs on: Client (app or browser code)
  • Launch stage: GA
  • Lifecycle: Active
  • Overview: Maps JavaScript API overview
  • Regional availability: Global. Feature coverage (such as 3D maps, traffic, directions, and boundary styling) varies by country or region; EEA Terms of Service apply to European Economic Area billing addresses. (coverage details)

Maps JavaScript API: when to use it

Use Maps JavaScript API when:

  • You need an interactive 2D or 3D map with custom markers, graphics, or data layers on a web page.
  • You need to show live asset locations and travel paths from your own data stream using Advanced Markers and polylines.
  • You need to draw geofences (circles, polygons) and test whether coordinates fall inside them in the browser.
  • You need client-side place search, autocomplete, or place details in a web app through the Places library.

Don't use Maps JavaScript API when:

  • You need to embed a business location map or directions link without writing custom JavaScript. Use Maps Embed API instead.
  • You only need a link that opens Google Maps with a location, search, or directions. Use Maps URLs instead.
  • You need ridesharing or scheduled delivery fleet tracking integrated with the mobile Driver SDK and backend JWT auth. Use Fleet Engine Service instead.

Maps JavaScript API: setup

Official Maps JavaScript API packages:

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

Maps JavaScript API: common mistakes

  • Problem: A darkened map or negative Street View image watermarked "for development purposes only" appears instead of an error when the API key or billing is misconfigured. Fix: Enable billing on the Cloud project, include a valid API key in every request, and check the browser console for the specific error code. See /maps/documentation/javascript/error-messages.
  • Problem: Legacy services such as PlacesService, DirectionsService, and DistanceMatrixService throw LegacyApiNotActivatedMapError on new projects where the legacy API isn't enabled. Fix: Use the new equivalents (Place class, Route class, RouteMatrix class) backed by Places API (New) and Routes API. See /maps/legacy#LegacyApiNotActivatedMapError.
  • Problem: As of v3.65, satellite and hybrid maps no longer switch to 45° imagery and map.setTilt(45) has no effect. Fix: Use 3D maps instead of 45° imagery. See /maps/deprecations.
  • Problem: Advanced Markers require a map ID; maps created without one can't use AdvancedMarkerElement. Fix: Create a map ID in the Cloud console (or use DEMO_MAP_ID for testing) and set mapId on the map. See /maps/documentation/javascript/advanced-markers/start.

Maps JavaScript API: legacy and deprecated features

  • Directions Service (google.maps.DirectionsService): Legacy since 2025-03-01. Replacement: Route class. Symptom: LegacyApiNotActivatedMapError on projects without the legacy Directions API enabled. See the migration guide.
  • Distance Matrix Service (google.maps.DistanceMatrixService): Legacy since 2025-03-01. Replacement: RouteMatrix class. Symptom: LegacyApiNotActivatedMapError on projects without the legacy Distance Matrix API enabled. See the migration guide.
  • Places Service (google.maps.places.PlacesService): Legacy since 2025-03-01. Replacement: Place class (Places API (New)). Symptom: LegacyApiNotActivatedMapError on projects without the legacy Places API enabled. See the migration guide.
  • google.maps.Marker: Deprecated since 2024-02-22. Replacement: google.maps.marker.AdvancedMarkerElement. Symptom: Still works and isn't scheduled for discontinuation; existing bugs won't be fixed. See the migration guide.
  • KmlLayer: Deprecated since 2026-04-30. Replacement: Data-driven styling for datasets, or third-party KML parsers with the Data layer. Symptom: KmlLayer is unavailable in version 3.66 and later; version 3.65, the last version that supports it, is decommissioned in May 2027. See the migration guide.
  • Heatmap Layer (visualization library): Decommissioned since 2026-05-20. Replacement: Third-party libraries such as deck.gl HeatmapLayer. Symptom: Unavailable as of May 2026. See the migration guide.
  • Drawing Library: Decommissioned since 2026-06-04. Replacement: Terra Draw. Symptom: Unavailable as of May 2026. See the migration guide.
  • 45° Imagery: Decommissioned since 2026-05-20. Replacement: 3D maps. Symptom: map.setTilt(45) is ineffective; satellite view stays top-down. See the migration guide.
  • google.maps.event.addDomListener() and addDomListenerOnce(): Deprecated since 2022-04-07. Replacement: Standard DOM addEventListener().
  • bounds, location, and radius options in Place Autocomplete Service: Deprecated since 2023-05-18. Replacement: locationBias and locationRestriction.
  • gmp-place-content-config (PlaceContentConfigElement) in Places UI Kit: Deprecated. Replacement: Add content elements directly to Place Details elements or in Place Search configuration.
  • Local Context Library: Decommissioned. Replacement: Places Library.

What you can do with Maps JavaScript API

See the guides linked below for each task, or compare across products in the Capabilities Explorer.

Maps JavaScript API: Address validation

Maps JavaScript API: Data-driven styling for boundaries

Maps JavaScript API: Data-driven styling for datasets

Maps JavaScript API: Datasets

  • Add a KML layer to a map. Note: In Maps JavaScript API, KmlLayer is deprecated (last supported in v3.65, decommissioned May 2027); migrate to Data-driven styling for boundaries or datasets, or load GeoJSON on the Data layer. KML layers remain supported on Android and iOS via the Maps SDK Utility Libraries.
  • Add a GeoRSS layer to a map. Note: Deprecated in Maps JavaScript API (KmlLayer is last supported in v3.65, decommissioned May 2027); convert GeoRSS feeds to GeoJSON and load them on the Data layer with map.data.addGeoJson().
  • Add GeoJSON data to a map.

Maps JavaScript API: Directions and Routing

Maps JavaScript API: Elevation

Maps JavaScript API: Fleet Engine

Maps JavaScript API: Geocoding

Maps JavaScript API: Maps

Maps JavaScript API: Maps annotations

Maps JavaScript API: Maps styling

Maps JavaScript API: Other

Maps JavaScript API: Photorealistic 3D maps

Maps JavaScript API: Places

Maps JavaScript API: Places UI Kit

  • Add a UI element that displays AI-powered summaries and reviews about specific places to a web page or mobile app. Note: Supported on web only (Maps JavaScript API Places UI Kit); mobile Places UI Kits do not include an AI summary element. EEA COMPLIANCE REQUIREMENT: For showing place data on a map in the European Economic Area (EEA), use client-side Places UI Kit components within the Maps JavaScript API rather than calling Places API web services from a backend server. Full requirements and FAQ: https://developers.google.com/maps/comms/eea/faq
  • Apply CSS styling to a place data UI element. Note: CSS custom properties apply to Maps JavaScript API Places UI Kit elements; Places SDK for Android and Places SDK for iOS style Place UI Kit views programmatically using theme and style attributes. EEA COMPLIANCE REQUIREMENT: For showing place data on a map in the European Economic Area (EEA), do not call Places API web services from a backend server. Use client-side Places UI Kit components on the target platform (Maps JavaScript API on web, Places SDK for Android on Android, or Places SDK for iOS on iOS). Full requirements and FAQ: https://developers.google.com/maps/comms/eea/faq
  • Customize place data UI element styling and configurations with a UI element customization tool. Note: EEA COMPLIANCE REQUIREMENT: For showing place data on a map in the European Economic Area (EEA), do not call Places API web services from a backend server. Use client-side Places UI Kit components on the target platform (Maps JavaScript API on web, Places SDK for Android on Android, or Places SDK for iOS on iOS). Full requirements and FAQ: https://developers.google.com/maps/comms/eea/faq
  • Add a UI element that displays information about a specific place to a web page or mobile app. Note: EEA COMPLIANCE REQUIREMENT: For showing place data on a map in the European Economic Area (EEA), do not call Places API web services from a backend server. Use client-side Places UI Kit components on the target platform (Maps JavaScript API on web, Places SDK for Android on Android, or Places SDK for iOS on iOS). Full requirements and FAQ: https://developers.google.com/maps/comms/eea/faq
  • Add a UI element that displays a list of places based on a query string to a web page. Note: Supported on both web pages (Maps JavaScript API) and mobile apps (Places SDK for Android and Places SDK for iOS). EEA COMPLIANCE REQUIREMENT: For showing place data on a map in the European Economic Area (EEA), do not call Places API web services from a backend server. Use client-side Places UI Kit components on the target platform (Maps JavaScript API on web, Places SDK for Android on Android, or Places SDK for iOS on iOS). Full requirements and FAQ: https://developers.google.com/maps/comms/eea/faq
  • Add a UI element that displays a list of places near a specific location to a web page. Note: Supported on both web pages (Maps JavaScript API) and mobile apps (Places SDK for Android and Places SDK for iOS). EEA COMPLIANCE REQUIREMENT: For showing place data on a map in the European Economic Area (EEA), do not call Places API web services from a backend server. Use client-side Places UI Kit components on the target platform (Maps JavaScript API on web, Places SDK for Android on Android, or Places SDK for iOS on iOS). Full requirements and FAQ: https://developers.google.com/maps/comms/eea/faq
  • Add a basic autocomplete UI element to a web page or app that returns Google Place identifiers based on a query string. Note: EEA COMPLIANCE REQUIREMENT: For showing place data on a map in the European Economic Area (EEA), do not call Places API web services from a backend server. Use client-side Places UI Kit components on the target platform (Maps JavaScript API on web, Places SDK for Android on Android, or Places SDK for iOS on iOS). Full requirements and FAQ: https://developers.google.com/maps/comms/eea/faq

Maps JavaScript API: Street View