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
- Service to enable:
maps-backend.googleapis.com - Authentication: API key
- Usage attribution: Set the
internalUsageAttributionIdsproperty (inMapOptions, onMapElementandMap3DElement, or on Places, Routes, and Address Validation elements and request options) to add usage attribution IDs that tell Google which libraries and samples you use. - Get started: Set up Maps JavaScript API
- Reference: Maps JavaScript API reference
- Pricing: Maps JavaScript API usage and billing
- Policies: Maps JavaScript API policies
- Release notes: Maps JavaScript API release notes
Official Maps JavaScript API packages:
- npm:
@googlemaps/js-api-loader - npm:
@types/google.maps - npm:
@googlemaps/markerclusterer
Maps JavaScript API: related products
- Often used with: Places API (New)
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, andDistanceMatrixServicethrowLegacyApiNotActivatedMapErroron new projects where the legacy API isn't enabled. Fix: Use the new equivalents (Placeclass,Routeclass,RouteMatrixclass) 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 useDEMO_MAP_IDfor testing) and setmapIdon 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:Routeclass. Symptom:LegacyApiNotActivatedMapErroron projects without the legacy Directions API enabled. See the migration guide. - Distance Matrix Service (
google.maps.DistanceMatrixService): Legacy since 2025-03-01. Replacement:RouteMatrixclass. Symptom:LegacyApiNotActivatedMapErroron projects without the legacy Distance Matrix API enabled. See the migration guide. - Places Service (
google.maps.places.PlacesService): Legacy since 2025-03-01. Replacement:Placeclass (Places API (New)). Symptom:LegacyApiNotActivatedMapErroron 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:KmlLayeris 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()andaddDomListenerOnce(): Deprecated since 2022-04-07. Replacement: Standard DOMaddEventListener().bounds,location, andradiusoptions in Place Autocomplete Service: Deprecated since 2023-05-18. Replacement:locationBiasandlocationRestriction.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
- Return a validated address for a specified address or partial address.
- Return the latitude/longitude coordinates for a validated address.
- Return the Google place identifier for a validated address.
- Use United States Postal Service (USPS) Coding Accuracy Support System (CASS) certification for address validation.
- Return information about whether a validated address is a business, residence, or PO box.
- Return United States Postal Service (USPS) delivery metadata for a validated address.
- Return the Plus Code for a validated address.
Maps JavaScript API: Data-driven styling for boundaries
- Change the style of boundaries on a map.
- Respond to user interactions with boundaries on a map.
- Add choropleth styling to a map.
Maps JavaScript API: Data-driven styling for datasets
- Create a reusable, cross-platform geospatial dataset.
- Add a custom geospatial dataset to a map.
- Change the style of custom dataset features on a map.
- Respond to user interactions with custom dataset features on a map.
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
- Return directions between two or more latitude/longitude coordinates as a series of coordinates for each step along a route.
- Return directions between two or more sets of latitude/longitude coordinates as a series of maneuver descriptions for the steps along a route.
- Return the distance between each step along a route between two or more sets of latitude/longitude coordinates.
- Return the travel time between each step along a route between two or more sets of latitude/longitude coordinates.
- Return an encoded polyline between each step along a route between two or more set of latitude/longitude coordinates.
- Return the distance for a route between two or more sets of latitude/longitude coordinates.
- Return the travel time for a route between two or more sets of latitude/longitude coordinates.
- Return an encoded polyline for a route between two or more sets of latitude/longitude coordinates.
- Specify the travel mode (drive, transit, walk, two-wheeled) for a route request. Note: In Routes API web service (computeRoutes), pass travelMode in the HTTP POST JSON body using RouteTravelMode (DRIVE, BICYCLE, TWO_WHEELER, WALK, TRANSIT, or TRUCK with routeModifiers.vehicleInfo) and include the required X-Goog-FieldMask header instead of a legacy GET mode query parameter. In Maps JavaScript API Routes library, pass travelMode and fields on ComputeRoutesRequest.
- Specify a stop or pass-through point for a route request.
- Specify how traffic data is used in a route request.
- Specify features to avoid, such as highways or tolls, for a route request.
- Specify shorter distance or alternative routing for a routes request. Note: In Routes API, requesting a shorter-distance reference route (SHORTER_DISTANCE) is Experimental, whereas requesting alternative routes (computeAlternativeRoutes) is GA.
- Return distances for a matrix of routes between multiple origins and destinations.
- Return travel times for a matrix of routes between multiple origins and destinations.
- Specify the travel mode (drive, transit, walk, two-wheeled) for a route matrix request. Note: In Routes API web service (computeRouteMatrix), pass travelMode in the HTTP POST JSON body using RouteTravelMode (DRIVE, TWO_WHEELER, WALK, TRANSIT, or TRUCK with origins[].routeModifiers.vehicleInfo; BICYCLE is not supported for route matrices) and include the required X-Goog-FieldMask header. In Maps JavaScript API Routes library, pass travelMode and fields on ComputeRouteMatrixRequest.
Maps JavaScript API: Elevation
- Return the elevation of a set of latitude/longitude coordinates.
- Return the difference in elevation along a path between two or more sets of latitude/longitude coordinates.
Maps JavaScript API: Fleet Engine
- Add the real-time location of Fleet Engine delivery vehicles and tasks to a map.
- Add the predicted routes of Fleet Engine delivery vehicles and tasks to a map.
- Add a Fleet Engine delivery vehicle's location, stops, tasks, and waypoint markers to a map.
- Respond to Fleet Engine delivery vehicle events, including completed trips, segments, deliveries, and tasks.
- Change the style of roads, polylines, and polygons on a Fleet Engine fleet tracking map.
- Display or hide map features on a Fleet Engine fleet tracking map.
- Change the style of icons and text labels on a Fleet Engine fleet tracking map.
- Apply different map styles to different zoom levels on a Fleet Engine fleet tracking map.
- Change the density of places on a Fleet Engine fleet tracking map. Experimental Note: Cloud-based Maps Styling support on Fleet Engine fleet tracking maps is GA, while POI density control is an Experimental Cloud-based Maps Styling feature (supported on light map styles only).
- Change the style of buildings on a Fleet Engine fleet tracking map. Experimental Note: Cloud-based Maps Styling support on Fleet Engine fleet tracking maps is GA, while 3D and footprint building style customization is an Experimental Cloud-based Maps Styling feature (supported on light map styles only).
- Change the style of landmarks on a Fleet Engine fleet tracking map. Experimental Note: Cloud-based Maps Styling support on Fleet Engine fleet tracking maps is GA, while landmark icon customization is an Experimental Cloud-based Maps Styling feature (supported on light map styles only).
- Customize a marker on a Fleet Engine fleet tracking map.
- Customize the route polyline on a Fleet Engine fleet tracking map.
Maps JavaScript API: Geocoding
- Return the latitude/longitude coordinates of an address (geocoding).
- Return the address for a set of latitude/longitude coordinates (reverse geocoding).
Maps JavaScript API: Maps
- Add a customizable, interactive map to a web page or mobile app. Note: For Android: Configure
inAndroidManifest.xmlbacked by the Secrets Gradle Plugin ormanifestPlaceholders["MAPS_API_KEY"]inapp/build.gradle.kts. Never hardcodeYOUR_GOOGLE_MAPS_API_KEYinAndroidManifest.xml, and never replaceGoogleMap(or maps-composeGoogleMap) with an offline mock canvas or Leaflet WebView ifE/Google Maps Android API: Authorization failureappears. Instruct the user to supplyMAPS_API_KEYvia Secrets and enable Maps SDK for Android (or Navigation SDK when using NavigationView / SupportNavigationFragment). - Create a reusable map identifier to store map configuration and styling settings.
- Respond to user interactions and events on a map.
- Customize the controls that appear on a map.
- Control zoom and pan on a map (camera).
- Change the map type.
- Change the map color scheme.
- Localize a map.
- Add a traffic layer to a map.
- Add a transit layer to a map.
- Add a bicycling layer to a map.
Maps JavaScript API: Maps annotations
- Add an info window to a map.
- Add a shape or line to a map.
- Add a vector-based icon to a map.
- Add deck.gl overlays to a map.
- Add an overlay image grounded to the surface of a map.
- Add a custom tile overlay to a map.
- Add a marker to a map. Note: Navigation SDK for Android does not support AdvancedMarkerOptions; when using Navigation SDK for Android, add markers with GoogleMap.addMarker(MarkerOptions).
- Customize a marker on a map. Note: Navigation SDK for Android does not support AdvancedMarkerOptions; when using Navigation SDK for Android, customize markers with MarkerOptions.
- Respond to user interactions with markers on a map.
- Determine whether a coordinate is inside a polygon or circular area on a map. Note: On Android, use PolyUtil.containsLocation in the Maps SDK for Android Utility Library for polygons. For circular areas, check whether the spherical distance from the circle center is within the radius (for example, computeDistanceBetween in Maps JavaScript API, SphericalUtil.computeDistanceBetween on Android, or GMSGeometryDistance on iOS).
- Calculate spherical distance, area, or heading between coordinates on a map.
Maps JavaScript API: Maps styling
- Create a reusable, cross-platform map style.
- Change the style of roads, polylines, and polygons on a map.
- Display or hide map features.
- Change the style of icons and text labels on a map.
- Apply different map styles to different zoom levels.
- Change the density of places on a map. Experimental
- Change the style of buildings on a map. Experimental
- Change the style of landmarks on a map. Experimental
Maps JavaScript API: Other
Maps JavaScript API: Photorealistic 3D maps
- Add an interactive, photorealistic 3D map to a web page.
- Add a marker to a photorealistic 3D map.
- Customize a marker on a photorealistic 3D map.
- Add a 3D model to a photorealistic 3D map.
- Add an overlay to a photorealistic 3D map.
- Add a 3D polyline to a photorealistic 3D map.
- Add a 3D polygon to a photorealistic 3D map.
- Respond to user interactions and events on a photorealistic 3D map.
- Customize the controls that appear on a photorealistic 3D map.
- Control camera path and animations on a photorealistic 3D map.
- Control camera restrictions on a photorealistic 3D map.
Maps JavaScript API: Places
- Return a list of places and place details based on a query string.
- Return a list of places and place details near a specific location.
- Return autocomplete results about places based on a query string.
- Return detailed information about a specific place.
- Return photos of a specific place. Note: Display each photo's author attributions (the author's name, linked to their profile URI) with the photo. The Places policies for each platform require this, for example /maps/documentation/javascript/policies#photo-attributions and /maps/documentation/places/web-service/policies#photos-and-review.
- Resize place photos.
- Return ratings and reviews for a specific place. Note: In Places API (New) web service, Place Details is an HTTP GET request to https://places.googleapis.com/v1/places/{placeId} with X-Goog-FieldMask (for example, rating,userRatingCount,reviews); Text Search, Nearby Search, and Autocomplete use POST. On Android, pass Place.Field.RATING, USER_RATING_COUNT, and REVIEWS to PlacesClient.fetchPlace(). On iOS, pass GMSPlacePropertyRating, GMSPlacePropertyUserRatingsTotal, and GMSPlacePropertyReviews in GMSFetchPlaceRequest.
- Add an autocomplete widget to a web page or app that returns results about places based on a query string.
- Specify the data fields included in place information responses.
- Specify the place types to include in place information responses.
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
- Add a configurable, interactive Google Street View to a web page or mobile app.
- Add a marker or overlay to a Google Street View.
- Respond to user interactions and events in a Google Street View.
- Customize the controls that appear on a Google Street View.
- Return a Google Street View panorama for a specific location.