Setup and Demo

This page describes how to set up the utility library for the Maps SDK for iOS. If you like, you can also 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 and run as follows:

  1. Run the following command: 
    pod try Google-Maps-iOS-Utils
  2. 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.

  3. If you don't yet have a Google Maps API key, get one now:
    1. Go to the Google Cloud Platform 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 Platform Console.

  4. Edit the AppDelegate.swift or AppDelegate.m file in your Xcode project, and paste your API key into the definition of the kMapsAPIKey constant.
  5. 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:

  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'

target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
  pod 'GoogleMaps'
  pod 'Google-Maps-iOS-Utils'
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.

Create a bridging header (Swift only)

If you created your project using Swift, you must add a bridging header to your project so that Swift can use the utility library's Objective-C classes. Follow these steps to add a bridging header:

  1. Add a new header file in your project's root folder. Name the file whatever you like, with a file name extension of .h.
  2. Paste the following code into the file: 
    #import <Google-Maps-iOS-Utils/GMUMarkerClustering.h>

    Or paste the following code, if you want only the quadtree utility:

    #import <Google-Maps-iOS-Utils/GQTPointQuadTree.h>
  3. Save the file.
  4. In the Xcode project editor, select the main project.
  5. Go to Build Settings in the Xcode build editor.
  6. In the build settings, find Swift Compiler - Code Generation.
  7. In the Objective-C Bridging Header section, add the path to the header file you created.
  8. Build the project.

For more details, see Apple's guide to using Swift and Objective-C in the same project.

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: