Add a 3D map to your app

This page walks through an example of how to add a basic 3D map to an iOS app using the Maps 3D SDK for iOS. The instructions on this page assume that you have already completed the steps in the Setup page and have the following:

• A Google Cloud project with the Maps 3D SDK for iOS enabled
• An API key Maps 3D SDK for iOS
• Xcode version 16.0 or later with the Maps 3D SDK for iOS package added.

For more information about these prerequisites, see Setup.

Follow a more advanced codelab.

See more code samples on GitHub.

Part 1: Create a basic SwiftUI app

1. Create a new app in Xcode.
2. Set your Product Name to Hello3DWorld, with the organization identifier set to com.example. The package name should be com.example.Hello3DWorld.
3. Choose the SwiftUI interface.
4. Add the Maps 3D library to your app. See instructions in the setup section.

Part 2: Add a map

1. Open the file called ContentView.swift. This is the entry point and main navigation for your app.

2. Import SwiftUI and the GoogleMaps3D package.

3. Replace all the code inside the body declaration with Map(mode: .hybrid).

   The minimum initial configuration you need to supply to initialize a Map is the MapMode:

   • .hybrid, or
   • .satellite

   Your ContentView.swift file should look like this:

   import SwiftUI
   import GoogleMaps3D
   
   struct ContentView: View {
     var body: some View {
       Map(mode: .hybrid)
     }
   }
   
   #Preview {
     ContentView()
   }
   

Part 3: Set your API key.

1. The API key must be set before the Map initializes. Do this by setting Map.apiKey in the init() event handler of the View that contains the Map.

   import SwiftUI
   import GoogleMaps3D
   
   struct ContentView: View {
     init () {
       Map.apiKey = "YOUR_API_KEY"
     }
   
     var body: some View {
       Map(mode: .hybrid)
     }
   }
   

Part 4: Use a camera to control the map view

3D Map views are controlled by the Camera class. In this step you will learn how to specify the location, altitude, heading, tilt, roll and range to customize the map view.

1. Change the Map() function call to include an initialCamera property. Initialize initialCamera to show a view of downtown Manhattan.

   import SwiftUI
   import GoogleMaps3D
   
   struct ContentView: View {
     init () {
       Map.apiKey = "YOUR_API_KEY"
     }
     var body: some View {
       Map(initialCamera: .init(
         latitude: 40.748339,
         longitude: -73.985912,
         altitude: 211.1,
         heading: 52,
         tilt: 68,
         range: 1039
       ), mode: .hybrid)
     }
   }
   

The code above sets values for these parameters:

• heading: The bearing in degrees from north to point the camera towards.
• tilt: The angle of tilt in degrees, where 0 is directly overhead and 90 is looking horizontally.
• roll: The angle of roll around the vertical plane of the camera, in degrees.
• range: The distance in metres of the camera from the latitude, longitude location
• altitude: The height of the camera above sea level.

If you don't supply any of these additional parameters, a default value will be used.

To make the camera view show more 3D data, set the initial parameters to show a closer, tilted view.

Part 6: Preview and run your App

1. Add an Xcode Preview

   Previews are a powerful XCode feature that let you see and interact with your App without having to use the Simulator or an external device.

   To add a preview, add a #Preview {} code block outside your struct.

   #Preview {
     CameraDemo()
   }
   

2. Run the app

Build and run the app.

Congratulations!

You've successfully added a 3D map to an app!

Next, you can explore more advanced features of the Maps 3D SDK for iOS, such as camera path animations, 3D markers, or polygons.