Skip to content
Products
Solutions
By industry
By use case
Resources
Products
Solutions
By industry
By use case
Resources
Products
Solutions
By industry
By use case
Resources
Immerse yourself: How to get started using 3D Maps in the Maps JavaScript API
Matt Toon
Google Maps Platform Solutions Engineer
Jul 25, 2024
Try Google Maps Platform
Get $200 usage monthly for no charge. Starting March 1, 2025, build more for free.*
Learn more

The Maps JavaScript API has always been about pushing the boundaries of what's possible with location-based data visualisation. This year at Google I/O, we announced the ability to integrate photorealistic 3D maps directly into your application using 3D Maps in the Maps JavaScript API.

In this post, we’ll walk through how to get started with this new release to create truly immersive visualisation experiences. For additional resources, make sure to also check out our newly released codelab on how to create your first 3D map using Photorealistic 3D Maps in Maps JavaScript.

From flat to fantastic: embracing a new dimension

Remember when Google Earth first launched and you could swoop through canyons and circle skyscrapers? Now, you can bring that same breathtaking realism directly into your web applications using cutting-edge Photorealistic 3D Maps. With this new release, you can render detailed cityscapes, terrain, and landmarks with incredible accuracy using just a few lines of code.

By integrating 3D Maps into your application, you can unlock a whole new world of possibilities:

  • Enhanced User Engagement: Immerse users in a familiar yet captivating representation of their surroundings, and promote deeper engagement with your application.

  • Intuitive Exploration: Simplify navigation and exploration in your app, and make complex spatial relationships crystal clear.

  • Deeper Data Insights: Display data overlays on top of 3D landscapes to provide your users with a more impactful and intuitive understanding of geographic information.

Getting started: It's easier than you think

Integrating 3D Maps into your existing applications is surprisingly straightforward. Here's a quick breakdown.

  1. Add the 3D Maps web component:

The current Experimental release is available in the alpha channel of the Maps JavaScript API, which means you first need to load the correct maps library. 

You have two options for loading the library. First, you can directly link to the whole library, which is syntactically a lot simpler. Your second option is to use the newer dynamic library function to reference the library, but only load a class when you need it at runtime. This may be more efficient. In both cases, you’ll need to include your particular API key for the cloud project that has maps enabled on it and ensure it’s using the alpha channel (highlighted in bold in each).

Direct Script Loading

<script async src="https://maps.googleapis.com/maps/api/js?key=<Enter API Key>>&v=alpha&libraries=maps3d&callback=init"></script>
Copied to clipboard!

Dynamic Library Loading

<script async defer>
   (g => { var h, a, k, p = "The Google Maps JavaScript API", ... )({
       key: "<Enter API Key>",
       v: "alpha",
   });
</script>
Copied to clipboard!

You can find out more about the different ways of loading the Maps JavaScript API in the documentation

2. Fine-tune the camera view:

The basis of engagement with the camera view is through the 3D map object, as if you were manipulating a camera object looking down on the earth. There are a number of parameters you can control to specify what the object is looking at, as shown in the image below:

Camera view image 1
3D Maps camera view image 2

You can set a number of values to control the point you are looking at on the earth:

  1. The Map3DElement center property controls the point you are looking at on the earth.

  2. The Map3DElement range property controls the distance from the object you want to be viewing.

  3. The Map3DElement heading property controls the direction you want to be viewing the point from.

  4. The Maps3DElement tilt property shows the angle you want to be looking down at the point from.

The code snippet below illustrates how a 3D Map is created, by specifying the location that is being visualised, the range the view is at and the angle of view. As discussed above, adding the 3D Map object can be accomplished either by direct script loading or dynamic library loading.

Direct Script Loading

<gmp-map-3d center="43.6425,-79.3871,400" range="1000" tilt="60"></gmp-map-3d>
Copied to clipboard!

Dynamic Library Loading

async function init() {
   const { Map3DElement } = await google.maps.importLibrary("maps3d");

   const map3DElement = new Map3DElement({
       center: { lat: 43.6425, lng: -79.3871, altitude: 400 },
       range: 1000,
       tilt: 60,
   });

   document.body.append(map3DElement);
}
init();
Copied to clipboard!

In both examples, you get the following view of the map, looking at the CN Tower in Toronto, Canada.

3D Maps CN Tower

Combine all of these as necessary. Modify them to manipulate the camera in “virtual” space to move around locations, look at different points based on responses to user interaction and objects, and perform animations such as fly throughs.

3. Add features on the map:

Now that you understand how to control the view, your next step might be to add data into the 3D Map to highlight a feature or building. Currently the API allows you to add lines and polygons to the view, set various levels of colour (named and CSS specified), and opacity (0 - 1 indicating percentage) on the boundaries of lines and fill colour of areas.

Since you are working in 3D, lines and polygons can also be extruded to add a third dimension by setting the altitude property on each point of the object. Each point is made up of either a Latitude and Longitude pair, or a Latitude, Longitude, Altitude trio. You can find more details about coordinates in the documentation.

Going back to our CN Tower example, you can load a polygon onto the map, which encompasses the base of the tower you were viewing earlier. For each point, you can specify a height so that when extruded, it draws the box from the ground to the height. (Again, the code examples below show both direct and dynamic forms to highlight the benefits of each option.) 

Direct

<gmp-map-3d center="43.6425,-79.3871,400" range="1000" tilt="60">
   <gmp-polygon-3d
       fill-color="rgba(0, 255, 255, 0.2)"
       stroke-color="rgba(255, 0, 255, 0.8)"
       stroke-width="4"
       extruded
       draws-occluded-segments
       altitude-mode="absolute">
   </gmp-polygon-3d>
</gmp-map-3d>

<script>
   function init() {
     const polygon = document.querySelector('gmp-polygon-3d');

     polygon.outerCoordinates = [
       { lat: 43.6427196, lng: -79.3876802, altitude: 600 },
       { lat: 43.6421742, lng: -79.3869184, altitude: 600 },
       { lat: 43.643001, lng: -79.3866475, altitude: 600 },
       { lat: 43.6427196, lng: -79.3876802, altitude: 600 }
     ];
   }
</script>
Copied to clipboard!

Dynamic

const { Polygon3DElement, AltitudeMode } = await google.maps.importLibrary("maps3d");

const polygonOptions = {
   strokeColor: "rgba(255, 0, 255, 0.8)",
   strokeWidth: 4,
   fillColor: "rgba(0, 255, 255, 0.2)",
   altitudeMode: AltitudeMode.ABSOLUTE,
   extruded: true,
   drawsOccludedSegments: true,
}

const towerPolygon = new google.maps.maps3d.Polygon3DElement(polygonOptions);

towerPolygon.outerCoordinates = [
   { lat: 43.6427196, lng: -79.3876802, altitude: 600 },
   { lat: 43.6421742, lng: -79.3869184, altitude: 600 },
   { lat: 43.643001, lng: -79.3866475, altitude: 600 },
   { lat: 43.6427196, lng: -79.3876802, altitude: 600 }
];

map3DElement.append(towerPolygon);
Copied to clipboard!

In the code, set the polygon’s altitude mode property to ABSOLUTE to make sure you are using real world heights (from sea level). Again, there are a number of options for handling the altitude of an object, which you can find in the documentation.

Since this is a polygon, the first and last points should be the same to ensure that it is enclosed and the enclosed space filled with the colour specified.  Lines would not require this.

The final interactive map would look like this:

Hopefully this post demonstrates how simple it is to create a 3D Map using the Maps JavaScript API and the different options you have to suit your programming style and the needs of your application.  

A new chapter in location-based experiences

The arrival of 3D Maps in the Maps JavaScript API marks a significant milestone in the evolution of immersive web mapping. We’re excited to see the innovative and engaging applications that you will create with this powerful new toolset.

Ready to get started? 

For additional training, remember to take a look at our newly released codelab. You will learn the basics about loading the right components of the Maps JavaScript API, displaying your first 3D Map and drawing features on it. 

Make sure to check out the samples and documentation as we dive deeper into the world of 3D mapping and continue to add more features to the platform. Let's build the future of location-based experiences together!

If you find something missing, don’t forget to leave us a message in the issue tracker.

Clay cityscape
Clay cityscape
Get going with Google Maps Platform