Set up an Xcode project

After you enable billing and create an API key, you're ready to set up the Xcode project that you use to develop your app.

Release notes are available for each release.

Step 1: Install the required software

To build a project using the Maps SDK for iOS, you must download and install:

• Xcode version 15.0 or later

Step 2: Create the Xcode project and install the Maps SDK for iOS

Note: The Maps SDK for iOS adds an average IPA size of 5.7 MB for apps made for specific devices. The download size for universal apps may be larger.

The SDK install size can vary. For example, the install size for Maps SDK for iOS version 9.0 is about 18 MB.

Swift Package Manager

The Maps SDK for iOS can be installed via Swift Package Manager. To add the SDK, ensure you have removed any existing Maps SDK for iOS dependencies.

Important: These instructions assume the use of Xcode 15 or later, but should be similar for previous versions of Xcode.

To add the SDK to a new or existing project, follow these steps:

1. Open your Xcode project or workspace, then go to File > Add Package Dependencies.
2. Enter https://github.com/googlemaps/ios-maps-sdk as the URL, press Enter to pull in the package, and click "Add Package".
3. To install a specific version, set the Dependency Rule field to one of the version-based options. For new projects, we recommend specifying the latest version and using the "Exact Version" option. Once complete, click "Add Package".
4. From the Choose Package Products window, verify GoogleMaps (for versions earlier than 9.0.0, verify GoogleMaps, GoogleMapsBase, and GoogleMapsCore) will be added to your designated main target. Once complete, click "Add Package".
5. To verify your installation, navigate to your target's General pane. In the Frameworks, Libraries, and Embedded Content you should see the installed packages. You can also view the "Package Dependencies" section of "Project Navigator" to verify the package and its version.

To update the package for an existing project, follow these steps:

1. If you are upgrading from a version earlier than 9.0.0, you must remove the following dependencies: GoogleMapsBase, GoogleMapsCore, and GoogleMapsM4B after upgrading. Do not remove the dependency for GoogleMaps. For more information, see the Version 9.0.0 Release Notes.

   From your Xcode project configuration settings, find Frameworks, Libraries, and Embedded Content. Use the minus sign(-) to remove the following framework:

   • GoogleMapsBase (Only for upgrades from versions earlier than 9.0.0)
   • GoogleMapsCore (Only for upgrades from versions earlier than 9.0.0)
   • GoogleMapsM4B (Only for upgrades from versions earlier than 9.0.0)
2. From Xcode, go to "File > Packages > Update To Latest Package Versions".
3. To verify your installation, go to the Package Dependencies section of Project Navigator to verify the package and its version.

Important: Sometimes, artifacts cannot be resolved or errors can occur, in this case select "File > Packages > Reset Package Cache".

To remove existing Maps SDK for iOS dependencies added using CocoaPods, follow these steps:

1. Close your Xcode workspace. Open terminal and execute the following command:

   sudo gem install cocoapods-deintegrate cocoapods-clean 
   pod deintegrate 
   pod cache clean --all

2. Remove the Podfile, Podfile.resolved and the Xcode workspace if you are not using them for anything other than CocoaPods.

To remove existing Maps SDK for iOS installed manually, follow these steps:

1. From your Xcode project configuration settings, find Frameworks, Libraries, and Embedded Content. Use the minus sign(-) to remove the following framework:
   • GoogleMaps
   • GoogleMapsBase (Only for installations earlier than version 9.0.0)
   • GoogleMapsCore (Only for installations earlier than version 9.0.0)
   • GoogleMapsM4B (Only for installations earlier than version 9.0.0)
2. From the top level directory of your Xcode project, remove the GoogleMaps bundle.

CocoaPods

The Maps SDK for iOS is available as a CocoaPods pod. CocoaPods is an open source dependency manager for Swift and Objective-C Cocoa projects.

If you don't already have the CocoaPods tool, install it on macOS by running the following command from the terminal. For details, see the CocoaPods Getting Started guide.

sudo gem install cocoapods

Create a Podfile for the Maps SDK for iOS and use it to install the API and its dependencies:

1. If you don't have an Xcode project yet, create one now and save it to your local machine. If you're new to iOS development:
   1. Create a new project.
   2. Select the iOS > App template.
   3. On the project options screen:
      1. Enter the Project Name.
      2. Record the value of the Bundle identifier field. You can use that value to restrict your API key below.
      3. Set the project Interface to Storyboard.
      4. Set the Language to Swift or Objective-C.
2. Create a file named Podfile in your project directory. This file defines your project's dependencies.
3. Edit the Podfile and add your dependencies along with their versions. Here is an example which includes the dependency you need for the Maps SDK for iOS:

   source 'https://github.com/CocoaPods/Specs.git'
   
   platform :ios, '15.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleMaps', '8.4.0'
   end

   Make sure to regularly run pod outdated to detect when there is a newer version to ensure you're always on the latest. If necessary, upgrade to the latest version.
4. Save the Podfile.

5. Open a terminal and go to the directory containing the Podfile:

   cd <path-to-project>

6. Run the pod install command. This will install the APIs specified in the Podfile, along with any dependencies they may have.

   pod install

7. Close Xcode, and then open (double-click) your project's .xcworkspace file to launch Xcode. From this time onwards, you must use the .xcworkspace file to open the project.

To update the API for an existing project, follow these steps:

1. Open a terminal and go to the project directory containing the Podfile.
2. Run the pod update command. This will update all of the APIs specified in the Podfile to the latest version.

Manual Installation

This guide shows how to manually add the XCFrameworks containing the Maps SDK for iOS to your project and configure your build settings in Xcode. An XCFramework is a binary package that you can use on multiple platforms, including machines using Apple silicon.

1. Download the following SDK binaries and resource files:
   • GoogleMaps
   • GoogleMapsBase
   • GoogleMapsCore
   • GoogleMapsM4B
   • GoogleMapsResources
2. Extract the files to access the XCFrameworks and resources.
3. If you don't have an Xcode project yet, create one now and save it to your local machine. If you're new to iOS development:
   1. Create a new project.
   2. Select the iOS > App template.
   3. On the project options screen:
      1. Enter the Project Name.
      2. Record the value of the Bundle identifier field. You can use that value to restrict your API key below.
      3. Set the project Interface to Storyboard.
      4. Set the Language to Swift or Objective-C.
4. Open the General tab. Drag the following XCFrameworks into your project under Frameworks, Libraries, and Embedded Content. Make sure to select Do Not Embed for each XCFramework:
   • GoogleMaps.xcframework
   • GoogleMapsBase.xcframework
   • GoogleMapsCore.xcframework
5. Copy the GoogleMaps.bundle from the GoogleMapsResources you downloaded into your Xcode project's top level directory. Make sure to select Copy items into destination group's folder when prompted.
6. Select your project from the Project Navigator, and choose your application's target.
7. Open the Build Phases tab for your application's target. Within Link Binary with Libraries, add the following frameworks and libraries:
   • Accelerate.framework
   • Contacts.framework
   • CoreData.framework
   • CoreGraphics.framework
   • CoreImage.framework
   • CoreLocation.framework
   • CoreTelephony.framework
   • CoreText.framework
   • GLKit.framework
   • ImageIO.framework
   • libc++.tbd
   • libz.tbd
   • Metal.framework
   • OpenGLES.framework (Only if you are using OpenGL)
   • QuartzCore.framework
   • SystemConfiguration.framework
   • UIKit.framework

8. Choose your project, rather than a specific target, and open the Build Settings tab. In the Linking - General -> Other Linker Flags section, add -ObjC to "Debug" and "Release". If these settings aren't visible, change the filter in the Build Settings bar from Basic to All.

9. To install the Places SDK for iOS XCFramework, see Get Started with the Places SDK for iOS.

Step 3: Inspect Apple Privacy Manifest file

Apple requires app privacy details for apps on the App Store. Visit the Apple App Store Privacy Details page for updates and more information.

The Apple Privacy Manifest file is included in the resources bundle for the SDK. To verify that the Privacy Manifest File has been included, and to inspect its contents, create an archive of your app and generate a privacy report from the archive.

Step 4: Add your API key to the project

In Get an API key, you generated an API key for your app. Now add that key to your Xcode project.

In the following examples, replace YOUR_API_KEY with your API key.

Note: If you recorded the Bundle identifier of your project, or obtained it from the project properties, you can use it to restrict your API key for use only with iOS applications with that specific bundle identifier. See Restricting API keys for more information.

Swift

Add your API key to your AppDelegate.swift as follows:

1. Add the following import statement:

   import GoogleMaps

2. Add the following to your application(_:didFinishLaunchingWithOptions:) method, using your API key:

   GMSServices.provideAPIKey("YOUR_API_KEY")

3. If you are also using the Places API, add your key again as shown here:

   GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

Add your API key to your AppDelegate.m as follows:

1. Add the following import statement:

   @import GoogleMaps;

2. Add the following to your application:didFinishLaunchingWithOptions: method, using your API key:

   [GMSServices provideAPIKey:@"YOUR_API_KEY"];

3. If you are also using the Places API, add your key again as shown here:

   [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

Step 5: Add a map

Swift

import UIKit
import GoogleMaps

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view.
        // Create a GMSCameraPosition that tells the map to display the
        // coordinate -33.86,151.20 at zoom level 6.

        let options = GMSMapViewOptions()
        options.camera = GMSCameraPosition.camera(withLatitude: -33.86, longitude: 151.20, zoom: 6.0)
        options.frame = self.view.bounds

        let mapView = GMSMapView(options: options)
        self.view.addSubview(mapView)

        // Creates a marker in the center of the map.
        let marker = GMSMarker()
        marker.position = CLLocationCoordinate2D(latitude: -33.86, longitude: 151.20)
        marker.title = "Sydney"
        marker.snippet = "Australia"
        marker.map = mapView
  }
}

Objective-C

#import "ViewController.h"
#import <GoogleMaps/GoogleMaps.h>

@interface ViewController()

@end

@implementation ViewController

-   (void)viewDidLoad {
  [super viewDidLoad];
  // Do any additional setup after loading the view.
  // Create a GMSCameraPosition that tells the map to display the
  // coordinate -33.86,151.20 at zoom level 6.
  GMSMapViewOptions *options = [[GMSMapViewOptions alloc] init];
  options.camera = [GMSCameraPosition cameraWithLatitude:-33.8683
                                                        longitude:151.2086
                                                             zoom:6];
  options.frame = self.view.bounds;
  GMSMapView *mapView = [[GMSMapView alloc] initWithOptions:options];

  [self.view addSubview:mapView];

  // Creates a marker in the center of the map.
  GMSMarker *marker = [[GMSMarker alloc] init];
  marker.position = CLLocationCoordinate2DMake(-33.86, 151.20);
  marker.title = @"Sydney";
  marker.snippet = @"Australia";
  marker.map = mapView;
}

@end

Step 5 (Optional): Declare the URL schemes used by the API

Beginning with iOS 9 and Xcode 7, apps can declare the URL schemes that they intend to open, by specifying the schemes in the app's Info.plist file. The Maps SDK for iOS opens the Google Maps mobile app when the user clicks the Google logo on the map, and your app can therefore declare the relevant URL schemes.

To declare the URL schemes used by the Maps SDK for iOS, add the following lines to your Info.plist:

LSApplicationQueriesSchemes googlechromes comgooglemaps

The following screenshot shows the configuration in the Xcode user interface:

Without the above declaration, the following errors can occur when the user taps the Google logo on the map:

• -canOpenURL: failed for URL: "comgooglemaps://" - error: "This app is not allowed to query for scheme comgooglemaps"
• -canOpenURL: failed for URL: "googlechromes://" - error: "This app is not allowed to query for scheme googlechromes"

To eliminate these errors, add the declaration to your Info.plist.

What's next

Now that you have an API key and an Xcode project, you can create and run apps. The Navigation SDK for iOS provides many tutorials and sample apps that can help you get started. For more details, see:

• Code samples
• Tutorials
  • Adding a Map with a Marker
  • Select Current Place and Show Details on a Map
  • Reverse Geocoding
• Codelabs
• Maps Solutions