Setup and Demo

This page describes how to set up the utility library for the Maps SDK for iOS. We recommend you pull our demos from GitHub. Alternately, you can install the utility library's demo app into a temporary Xcode project, and run it to see examples of the library's functionality.

Get CocoaPods

The utility library is available as a CocoaPods pod named Google-Maps-iOS-Utils. 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:

sudo gem install cocoapods

For details, see the CocoaPods Getting Started guide.

(Optional) Install and run the demo app

The utility library includes a demo app that you can install.

There is a known issue with 'pod try' in CocoaPods version 1.8.1 and higher. If you want to fetch the files using Cocoapods, we recommend using version 1.6.1 of CocoaPods. Alternatively, you can download the sample files from GitHub.

1. Run the demo app by using one of these two methods:

   Use files from GitHub

   1. Download the code sample archive from GitHub and unpack the archive.
   2. Open a terminal window, navigate to the directory where you expanded the sample files, and drill down into the appropriate samples directory for the language you want to use:
      • For Swift, run cd google-maps-ios-utils-master/samples/SwiftDemoApp
      • For Objective-C, run cd google-maps-ios-utils-master/samples/ObjCDemoApp
   3. Run the following command:
      

      pod install

   4. CocoaPods updates your spec repositories, then opens the demo in a temporary Xcode project named SwiftDemoApp.xcodeproj or ObjCDemoApp.xcodeproj.

   Use CocoaPods v1.6.1

   1. Open a terminal window and install version 1.6.1:

      sudo gem install cocoapods -v1.6.1

   2. Fetch the Google Maps files using Cocoapods:

      pod try Google-Maps-iOS-Utils

      Choose either Swift or Objective-C when prompted. CocoaPods updates your spec repositories, then opens the demo in a temporary Xcode project named SwiftDemoApp.xcodeproj or ObjCDemoApp.xcodeproj.

2. If you don't yet have a Google Maps API key, get one now:
   1. Go to the Google Cloud Console.
   2. Create or select a project.
   3. Click Continue to enable the Maps SDK for iOS.
   4. On the Credentials page, get an API key.
      Note: If you have a key with iOS restrictions, you may use that key. You can use the same key with any of your iOS applications within the same project.
   5. From the dialog displaying the API key, select Restrict key to set an iOS restriction on the API key.
   6. In the Restrictions section, select iOS apps, then enter your app's bundle identifier. For example: com.example.hellomap.

   7. Click Save.

      Your new iOS-restricted API key appears in the list of API keys for your project. An API key is a string of characters, something like this:

      AIzaSyBdVl-cTICSwYKrZ95SuvNw7dbMuDt1KG0

   You can also look up an existing key in the Google Cloud Console.

3. Edit the AppDelegate.swift or AppDelegate.m file in your Xcode project, and paste your API key into the definition of the kMapsAPIKey constant.
4. Build and run the project.

Install the utility library as an Xcode project

Follow these steps to add the utility library to your Xcode workspace:

Use CocoaPods

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, create a Single View Application.)
2. If you don't already have a pod file for your project, create a file named Podfile in your project directory. This file defines your project's dependencies.
3. Edit your project's pod file and add a dependency on the Google-Maps-iOS-Utils pod. Here is an example which includes the dependencies you need for the Maps SDK for iOS and the utility library:

   source 'https://github.com/CocoaPods/Specs.git'
   platform :ios, '10.0'
   
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     use_frameworks!
     pod 'GoogleMaps', '4.0.0'
     pod 'Google-Maps-iOS-Utils', '3.4.0'
   end

4. Run pod install.
5. 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.

Note: The marker clustering utility is dependent on the quadtree, but you can use the quadtree without marker clustering. If you want only the quadtree utility, you can change pod 'Google-Maps-iOS-Utils' to 'Google-Maps-iOS-Utils/QuadTree' in your pod file.

Use Carthage

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 newer to iOS development, create a new project and select the iOS App template. In Xcode 11.7 or earlier, create a Single View Application.)
3. Create a file named Cartfile in your project directory. This file defines your project's dependencies.
4. Edit the Cartfile and add the Maps SDK for iOS Utility Library dependency:
   

   github "googlemaps/google-maps-ios-utils"

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

   cd <path-to-project>

7. Run the update command:
   

   carthage update --platform iOS

   
   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. Add the Maps SDK for iOS frameworks into your project by dragging 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.framework
   • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMaps.framework
   • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMapsCore.framework
   • GoogleMaps-x.x.x/Maps/Frameworks/GoogleMapsUtils.framework
   Premium Plan customers must also include GoogleMaps-x.x.x/M4B/Frameworks/GoogleMapsM4B.framework.
10. Right-click GoogleMaps.framework in your project, and select Show In Finder.
11. Drag the Carthage/Build/iOS/GoogleMaps.framework/Resources/GoogleMaps.bundle from the Resources folder into your 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:
    • Accelerate.framework
    • CoreData.framework
    • CoreGraphics.framework
    • CoreImage.framework
    • CoreLocation.framework
    • CoreTelephony.framework
    • CoreText.framework
    • GLKit.framework
    • ImageIO.framework
    • libc++.tbd
    • libz.tbd
    • 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.

Use Swift Package Manager

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, create a new project and select the iOS App template. On Xcode 11.7 or older, create a Single View Application.)
2. Add the Maps SDK for iOS as a dependency. See Installing the SDK for options.
3. In your Xcode project, navigate to File -> Swift Packages -> Add Package Dependency.
4. In the presented window, enter the Maps SDK for iOS Utility Library repository URL https://github.com/googlemaps/google-maps-ios-utils and select Next.
• At this point, you may be prompted to authenticate with your GitHub account. Follow the instructions to create a GitHub personal access token to continue the process.
5. In the next window, select the Version radio option, select Exact from the dropdown list, enter the latest version of the Maps SDK for iOS Utility Library (e.g. "3.4.0") and select Next.

Get an API key

Click the button below, which guides you through the process of enabling the Maps SDK for iOS and getting an API key. (If your project already has an iOS-restricted API key, you may use that key.)

Get a Key

Alternatively, see Get the API key and Restrict the API key.

Add the API key to your app

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, replacing YOUR_API_KEY with 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, replacing YOUR_API_KEY with 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"];

Add a utility to your app

See the guides to:

• Marker clustering
• Quadtree
• KML and GeoJSON rendering
• Heatmap