Select platform: [Android](https://developers.google.com/maps/documentation/maps-3d/android-sdk/add-a-3d-map.md.txt "View this page for the Android platform docs.") [iOS](https://developers.google.com/maps/documentation/maps-3d/ios-sdk/add-a-3d-map.md.txt "View this page for the iOS platform docs.") [JavaScript](https://developers.google.com/maps/documentation/javascript/3d/get-started.md.txt "View this page for the JavaScript platform docs.")

<br />

![Basic maps of Seattle, San Francisco, and Paris](https://developers.google.com/static/maps/documentation/maps-3d/ios-sdk/images/three-basic.png "Basic maps of Seattle, San Francisco, and Paris")

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](https://developers.google.com/maps/documentation/maps-3d/ios-sdk/setup.md.txt) page and have the following:

- A Google Cloud project with the Maps 3D SDK for iOS enabled
- An API key for Maps 3D SDK for iOS
- [Xcode](https://developer.apple.com/xcode/) **version
  16.0** or later with the Maps 3D SDK for iOS package added.

For more information about these prerequisites, see
[Setup](https://developers.google.com/maps/documentation/maps-3d/ios-sdk/setup.md.txt).

[Follow a more advanced
codelab](https://developers.google.com/codelabs/maps-platform/maps-platform-101-3d-maps-ios).

[See more code samples on
GitHub](https://github.com/googlemaps-samples/ios-maps-3d-sdk-samples).

## 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](https://developers.google.com/maps/documentation/maps-3d/ios-sdk/setup#step_2_create_the_xcode_project_and_install_the).

## Part 2: Add a map

![Minimal 3D map of a globe](https://developers.google.com/static/maps/documentation/maps-3d/ios-sdk/images/minimal-map.png "Minimal 3D map of a globe")

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`,
   - `.roadmap`, or
   - `.satellite`

   Your `ContentView.swift` file should look like this:

   ```swift
   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.

   > [!WARNING]
   > **Warning:** Don't check the API key into external or public source control

   ```swift
   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.

   > [!NOTE]
   > **Note:** Parameter order matters. The Camera is initialized by providing latitude first, then longitude. Make sure you specify the correct values for each, especially when pasting in from another source, or the camera may show an unexpected location.

   ```swift
   import SwiftUI
   import GoogleMaps3D

   struct ContentView: View {
     init () {
       Map.apiKey = "YOUR_API_KEY"
     }
     var body: some View {
       Map(initialCamera: .init(
         center: .init(latitude: 40.748339, longitude: -73.985912, altitude: 211.1),
         heading: 52,
         tilt: 68,
         roll: 0.0,
         range: 1039,
         fieldOfView: .degrees(50)
       ), mode: .hybrid)
     }
   }
   ```

The code above sets values for these parameters:

- `center`: The `LatLngAltitude` representing the camera location
- `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
- `fieldOfView`: The angle representing the camera field of view

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

> [!NOTE]
> **Note:** You can also adjust the relative altitude of the camera using tilt and range.

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

## Part 5: Preview and run your app

![Basic 3D map of New York City](https://developers.google.com/static/maps/documentation/maps-3d/ios-sdk/images/new-york.png "Basic 3D map of New York City")

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.

   ```swift
   #Preview {
     ContentView()
   }
   ```
2. Run the app

Build and run the app.

## Map loading and error states

The Maps 3D SDK for iOS automatically displays built-in visual feedback while
managing the state of the [`Map`](https://developers.google.com/maps/documentation/maps-3d/ios-sdk/reference/Structs/Map.md.txt):

- **Loading overlay:** A centered progress indicator is displayed when the map view is first initialized or loading.
- **Error overlay:** An error overlay is displayed if the map fails to load.

If you apply a cloud-based map style using
[`style(mapID:error:)`](https://developers.google.com/maps/documentation/maps-3d/ios-sdk/reference/Structs/Map.md.txt#/s:12GoogleMaps3D3MapV5style5mapID5errorACSS_yycSgtF)
on [`Map`](https://developers.google.com/maps/documentation/maps-3d/ios-sdk/reference/Structs/Map.md.txt), you
can pass an `error` closure to handle style loading errors.

## Listen for map tap events

To listen for tap events on the map, apply the
[`onTap(_:)`](https://developers.google.com/maps/documentation/maps-3d/ios-sdk/reference/Extensions/View.md.txt#/s:7SwiftUI4ViewP12GoogleMaps3DAD13MapAnimatableRzrlE5onTapyQryAD0fI4InfoVcF)
modifier to [`Map`](https://developers.google.com/maps/documentation/maps-3d/ios-sdk/reference/Structs/Map.md.txt).
When a user taps the map, the closure receives a
[`MapTapInfo`](https://developers.google.com/maps/documentation/maps-3d/ios-sdk/reference/Structs/MapTapInfo.md.txt)
value that provides the
[`location`](https://developers.google.com/maps/documentation/maps-3d/ios-sdk/reference/Structs/MapTapInfo.md.txt#/s:12GoogleMaps3D10MapTapInfoV8locationAA14LatLngAltitudeVvp)
([`LatLngAltitude`](https://developers.google.com/maps/documentation/maps-3d/ios-sdk/reference/Structs/LatLngAltitude.md.txt))
and tapped
[`content`](https://developers.google.com/maps/documentation/maps-3d/ios-sdk/reference/Structs/MapTapInfo.md.txt#/s:12GoogleMaps3D10MapTapInfoV7contentAC7ContentOvp)
([`MapTapInfo.Content.map`](https://developers.google.com/maps/documentation/maps-3d/ios-sdk/reference/Structs/MapTapInfo/Content.md.txt#/s:12GoogleMaps3D10MapTapInfoV7ContentO3mapyA2EmF)
or
[`MapTapInfo.Content.place(id:)`](https://developers.google.com/maps/documentation/maps-3d/ios-sdk/reference/Structs/MapTapInfo/Content.md.txt#/s:12GoogleMaps3D10MapTapInfoV7ContentO5placeyAESS_tcAEmF)).
For more information on point of interest interactions, see
[Interact with points of interest](https://developers.google.com/maps/documentation/maps-3d/ios-sdk/points-of-interest.md.txt).

```swift
Map(mode: .hybrid)
  .onTap { tapInfo in
    print("Tapped at \(tapInfo.location), content: \(tapInfo.content)")
  }
```

## 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](https://developers.google.com/maps/documentation/maps-3d/ios-sdk/custom-camera-paths), [3D
markers](https://developers.google.com/maps/documentation/maps-3d/ios-sdk/add-a-marker), or
[polygons](https://developers.google.com/maps/documentation/maps-3d/ios-sdk/add-polygons.md.txt).