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.

Step 1: Install the required software

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

• Xcode version 14.0 or later

• Cocoapods or Carthage

  Note: While you can install the Maps SDK for iOS manually without using Cocoapods or Carthage, most developers prefer to use a package manager.

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

Use 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, '14.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GoogleMaps', '8.0.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.

Use Carthage

Note: Carthage does not currently support libraries built targeting a minimum version of iOS 13 and later. That means the latest supported version of the Maps SDK for iOS is 6.2.1.

The Maps SDK for iOS is available to use with Carthage, a simple, decentralized dependency manager for Swift and Objective-C Cocoa projects.

1. Install Carthage. There are several methods, so see the Carthage README file for exact steps.
2. 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.
3. Create a file named Cartfile in your project directory. This file defines your project's dependencies.
4. Edit the Cartfile and add your dependencies along with their versions:
   

   binary "https://dl.google.com/geosdk/GoogleMaps.json" == 6.2.1

   Make sure to regularly run carthage outdated to detect when there is a newer version to ensure you're always on the latest. If necessary, upgrade to the latest version.
5. Save the Cartfile.
6. In a terminal window, go to the directory containing the Cartfile:
   

   cd <path-to-project>

7. Run the carthage update command. This will install the APIs specified in the Cartfile, along with any dependencies they may have.
8. In the Finder, in your project directory, go to the downloaded framework files under Carthage/Build/iOS.
9. Drag the following bundles into your project: (When prompted, select Copy items if needed, please use the same version as above.)
   • GoogleMaps-x.x.x/Base/Frameworks/GoogleMapsBase.xcframework
   • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMaps.xcframework
   • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMapsCore.xcframework
   • (Premium Plan customers only) GoogleMaps-x.x.x/M4B/Frameworks/GoogleMapsM4B.xcframework
10. Right-click GoogleMaps.xcframework in your project, and select Show In Finder.
11. Drag the GoogleMaps.bundle from the Resources folder into the top level directory of your Xcode project. When prompted, ensure Copy items into destination group's folder is not selected.
12. Select your project from the Project Navigator, and choose your application's target.
13. Open the Build Phases tab for your application’s target, and within Link Binary with Libraries, add the following frameworks and libraries:
    • Accelerate.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
    • QuartzCore.framework
    • SystemConfiguration.framework
    • UIKit.framework

14. Choose your project, rather than a specific target, and open the Build Settings tab. In the Other Linker Flags section, add -ObjC. If these settings are not visible, change the filter in the Build Settings bar from Basic to All.

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

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

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

Install manually

This guide shows how to manually add the Maps SDK for iOS to your project and configure your build settings in Xcode.

1. Download the SDK source files: GoogleMaps-8.0.0.
2. Unpack the source files.
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. Drag the following bundles into your project: (When prompted, select Copy items if needed, please use the same version as above.)
   • GoogleMaps-x.x.x/Base/Frameworks/GoogleMapsBase.xcframework
   • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMaps.xcframework
   • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMapsCore.xcframework
   • (Premium Plan customers only) GoogleMaps-x.x.x/M4B/Frameworks/GoogleMapsM4B.xcframework
5. Right-click GoogleMaps.xcframework in your project, and select Show In Finder.
6. Drag the GoogleMaps.bundle from the Resources folder into the top level directory of your Xcode project. When prompted, ensure Copy items into destination group's folder is not selected.
7. Select your project from the Project Navigator, and choose your application's target.
8. Open the Build Phases tab for your application’s target, and within Link Binary with Libraries, add the following frameworks and libraries:
   • Accelerate.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
   • QuartzCore.framework
   • SystemConfiguration.framework
   • UIKit.framework

9. Choose your project, rather than a specific target, and open the Build Settings tab. In the Other Linker Flags section, add -ObjC. If these settings are not visible, change the filter in the Build Settings bar from Basic to All.

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

Install the XCFramework

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

With Carthage

The Maps SDK for iOS is available to use with Carthage, a simple, decentralized dependency manager for Swift and Objective-C Cocoa projects.

1. Install Carthage. There are several methods, so see the Carthage README file for exact steps.
2. 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.
3. Create a file named Cartfile in your project directory. This file defines your project's dependencies.

4. Edit the Cartfile and add your dependencies along with their versions:

   binary "https://dl.google.com/geosdk/GoogleMaps.json" == 6.2.1-beta

5. Save the Cartfile.
6. In a terminal window, go to the directory containing the Cartfile:
   

   cd <path-to-project>

7. Run the carthage update command. This will install the APIs specified in the Cartfile, along with any dependencies they may have.
8. In the Finder, in your project directory, go to the downloaded framework files under Carthage/Build.
9. Drag the following XCFrameworks into your project under Frameworks, Libraries, and Embedded Content. Make sure to select Do Not Embed for each XCFramework:
   • GoogleMaps-x.x.x/GoogleMapsBase.xcframework
   • GoogleMaps-x.x.x/GoogleMaps.xcframework
   • GoogleMaps-x.x.x/GoogleMapsCore.xcframework
   • (Premium Plan customers only) GoogleMaps-x.x.x/GoogleMapsM4B.xcframework
10. Right-click GoogleMaps.xcframework in your project, and select Show In Finder.
11. Drag the GoogleMaps.bundle from the ios-arm64_x86_64-simulator/GoogleMaps.framework/Resources folder into the top level directory of your Xcode project. When prompted, ensure Copy items if needed is not selected.
12. Select your project from the Project Navigator, and choose your application's target.
13. Open the Build Phases tab for your application’s target, and within Link Binary with Libraries, and add the following frameworks and libraries:
    • Accelerate.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
    • QuartzCore.framework
    • SystemConfiguration.framework
    • UIKit.framework

14. Choose your project, rather than a specific target, and open the Build Settings tab. In the Other Linker Flags section, add -ObjC. If these settings are not visible, change the filter in the Build Settings bar from Basic to All.

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

Manually

This guide shows how to manually add the Maps SDK for iOS to your project and configure your build settings in Xcode.

1. Download the SDK source files: GoogleMaps-8.0.0.
2. Unpack the source files. Navigate to the Frameworks folder to access the XCFramework.
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. Drag the following XCFrameworks into your project under Frameworks, Libraries, and Embedded Content. Make sure to select Do Not Embed for each XCFramework:
   • GoogleMaps-x.x.x/GoogleMapsBase.xcframework
   • GoogleMaps-x.x.x/GoogleMaps.xcframework
   • GoogleMaps-x.x.x/GoogleMapsCore.xcframework
   • (Premium Plan customers only) GoogleMaps-x.x.x/GoogleMapsM4B.xcframework
5. Right-click GoogleMaps.xcframework in your project, and select Show In Finder.
6. Drag the GoogleMaps.bundle from the ios-arm64_x86_64-simulator/GoogleMaps.framework/Resources folder into the top level directory of your Xcode project. When prompted, ensure Copy items if needed is not selected.
7. Select your project from the Project Navigator, and choose your application's target.
8. Open the Build Phases tab for your application’s target, and within Link Binary with Libraries, and add the following frameworks and libraries:
   • Accelerate.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
   • QuartzCore.framework
   • SystemConfiguration.framework
   • UIKit.framework

9. Choose your project, rather than a specific target, and open the Build Settings tab. In the Other Linker Flags section, add -ObjC. If these settings are not visible, change the filter in the Build Settings bar from Basic to All.

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

Step 3: 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 4 (Optional): Opt-in to use the Metal rendering framework

The Maps SDK for iOS lets you opt-in to use the Metal rendering framework from Apple. To try the Metal renderer in your app, call [GMSServices setMetalRendererEnabled:YES] in Objective-C, or GMSServices.setMetalRendererEnabled(true) in Swift before creating any map views.

If you are Installing the SDK manually, you must also ensure to add the Metal.framework in Xcode.

Step 5: Add a map

The code below demonstrates how to add a simple map to an existing ViewController:

1. Add or update methods in your app's default ViewController to create and initialize an instance of GMSMapView.

   Replace all instances of ViewController in the example code with the name of your View Controller.

   Swift

   /*
    * Copyright 2020 Google Inc. All rights reserved.
    *
    *
    * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this
    * file except in compliance with the License. You may obtain a copy of the License at
    *
    *     http://www.apache.org/licenses/LICENSE-2.0
    *
    * Unless required by applicable law or agreed to in writing, software distributed under
    * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
    * ANY KIND, either express or implied. See the License for the specific language governing
    * permissions and limitations under the License.
    */
   
   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 camera = GMSCameraPosition.camera(withLatitude: -33.86, longitude: 151.20, zoom: 6.0)
           let mapView = GMSMapView.map(withFrame: self.view.frame, camera: camera)
           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

   /*
   * Copyright 2020 Google Inc. All rights reserved.
   *
   *
   * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this
   * file except in compliance with the License. You may obtain a copy of the License at
   *
   *     http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software distributed under
   * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
   * ANY KIND, either express or implied. See the License for the specific language governing
   * permissions and limitations under the License.
   */
   
   #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.
     GMSCameraPosition *camera = [GMSCameraPosition cameraWithLatitude:-33.86
                                                             longitude:151.20
                                                                  zoom:6];
     GMSMapView *mapView = [GMSMapView mapWithFrame:self.view.frame camera:camera];
     mapView.myLocationEnabled = YES;
     [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
   ViewController.m
         

2. Run your application. You should see a map with a single marker centered over Sydney, Australia. If you see the marker, but the map is not visible, confirm that you have provided your API key.

Step 6 (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:

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>googlechromes</string>
    <string>comgooglemaps</string>
</array>

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 as described above.

What's next

Now that you have an API key and an Xcode project, you can create and run apps. The Maps 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