Get Started

Follow the steps in this guide to download the Places SDK for iOS, to add the library and its dependencies to your app, and to get a free API key.

Release notes are available for each release.

Step 1: Get the latest version of Xcode

To build a project using the Places SDK for iOS, you need:

1. Xcode version 11.7 or later.
2. Cocoapods or Carthage.

Step 2: Install the SDK

To install the API in a new project, follow these steps:

Use Cocoapods

The Places SDK for iOS is available as a CocoaPod pod, GooglePlaces, which contains all places functionality.

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 Places SDK for iOS and use it to install the SDK 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 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.)
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 specifies your application target name, and the name of the GooglePlaces pod:

   source 'https://github.com/CocoaPods/Specs.git'
   target 'YOUR_APPLICATION_TARGET_NAME_HERE' do
     pod 'GooglePlaces', '4.1.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.
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

The Places 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, 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 your dependencies along with their versions:
   

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

   Make sure to regularly run carthage outdated to detect when there is a newer version to ensure you're always on the latest.
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):
   • GooglePlaces-3.x.x/Frameworks/GooglePlaces.framework
   • GoogleMaps-3.x.x/Base/Frameworks/GoogleMapsBase.framework
10. Right-click GooglePlaces.framework in your project, and select Show In Finder.
11. Drag the GooglePlaces.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, and within Link Binary with Libraries, add the following frameworks:
    • GooglePlaces.framework
    • GoogleMapsBase.framework
    • 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.

15. 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.

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 GooglePlaces framework to your project and configure your build settings in Xcode.

1. Download the SDK source files:
   • GooglePlaces-4.1.0
   • GoogleMaps-4.1.0
2. Unpack the source files.
3. Launch Xcode and either open an existing project, or create a new project. If you're new to iOS, create a Single View Application, and disable Use Storyboards and enable Use Automatic Reference Counting.
4. Remove any Maps bundles from previous releases from your project.
5. Drag the following bundles into your project (when prompted, select Copy items if needed):
   • GooglePlaces-3.x.x/Frameworks/GooglePlaces.framework
   • GoogleMaps-3.x.x/Base/Frameworks/GoogleMapsBase.framework
6. Right-click GooglePlaces.framework in your project, and select Show In Finder.
7. Drag the GooglePlaces.bundle from the Resources folder into your project. When prompted, ensure Copy items into destination group's folder is not selected.
8. Select your project from the Project Navigator, and choose your application's target.
9. Open the Build Phases tab, and within Link Binary with Libraries, add the following frameworks:
   • GooglePlaces.framework
   • GoogleMapsBase.framework
   • 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

10. Choose your project, rather than a specific target, and open the Build Settings tab.

11. 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.

There is a known issue where apps do not compile properly for the simulator under Xcode 12. If you experience this issue, see the Google Maps Platform FAQ for steps to resolve the problem.

Step 3: Get an API key

1. Enable billing on your project.
2. Enable the Places API for your project.
3. Follow the Get an API key guide to get, add, and restrict an API key.

Step 4: Start writing code

The following code samples demonstrate how to get the current place.

Get current place

Please note, as this sample requires access to the location of the device to get the current location, you will need to set the NSLocationWhenInUseUsageDescription key with appropriate explanatory text in your project's Info.plist file. For more details, see the guide to getting current place.

Swift

import GooglePlaces
import UIKit

class GetStartedViewController : UIViewController {

  // Add a pair of UILabels in Interface Builder, and connect the outlets to these variables.
  @IBOutlet private var nameLabel: UILabel!
  @IBOutlet private var addressLabel: UILabel!

  private var placesClient: GMSPlacesClient!

  override func viewDidLoad() {
    super.viewDidLoad()
    placesClient = GMSPlacesClient.shared()
  }

  // Add a UIButton in Interface Builder, and connect the action to this function.
  @IBAction func getCurrentPlace(_ sender: UIButton) {
    let placeFields: GMSPlaceField = [.name, .formattedAddress]
    placesClient.findPlaceLikelihoodsFromCurrentLocation(withPlaceFields: placeFields) { [weak self] (placeLikelihoods, error) in
      guard let strongSelf = self else {
        return
      }

      guard error == nil else {
        print("Current place error: \(error?.localizedDescription ?? "")")
        return
      }

      guard let place = placeLikelihoods?.first?.place else {
        strongSelf.nameLabel.text = "No current place"
        strongSelf.addressLabel.text = ""
        return
      }

      strongSelf.nameLabel.text = place.name
      strongSelf.addressLabel.text = place.formattedAddress
    }
  }
}
      

Objective-C

#import "GetStartedViewController.h"
@import GooglePlaces;

@interface GetStartedViewController ()
// Add a pair of UILabels in Interface Builder and connect the outlets to these variables
@property (weak, nonatomic) IBOutlet UILabel *nameLabel;
@property (weak, nonatomic) IBOutlet UILabel *addressLabel;
@end

@implementation GetStartedViewController {
  GMSPlacesClient *_placesClient;
}

- (void)viewDidLoad {
  [super viewDidLoad];
  _placesClient = [GMSPlacesClient sharedClient];
}

// Add a pair of UILabels in Interface Builder and connect the outlets to these variables.
- (IBAction)getCurrentPlace:(UIButton *)sender {
  GMSPlaceField placeFields = (GMSPlaceFieldName | GMSPlaceFieldFormattedAddress);

  __weak typeof(self) weakSelf = self;
  [_placesClient findPlaceLikelihoodsFromCurrentLocationWithPlaceFields:placeFields callback:^(NSArray<GMSPlaceLikelihood *> * _Nullable likelihoods, NSError * _Nullable error) {
    __typeof__(self) strongSelf = weakSelf;
    if (strongSelf == nil) {
      return;
    }

    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    }

    GMSPlace *place = likelihoods.firstObject.place;
    if (place == nil) {
      strongSelf.nameLabel.text = @"No current place";
      strongSelf.addressLabel.text = @"";
      return;
    }

    strongSelf.nameLabel.text = place.name;
    strongSelf.addressLabel.text = place.formattedAddress;
  }];
}

@end
      

Experiment with the Places SDK for iOS demo

Try the SDK demo. You'll need Cocoapods v1.6.1 installed.