Once you’ve enabled billing, installed your preferred dependency manager and other software, and created an API key, you’re ready to download the Maps SDK for iOS and add a simple map.
Release notes are available for each release of Maps SDK for iOS.
Step 1: Installing the SDK
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:
- 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. Note: on 11.7, create a Single View Application.)
- Create a file named
Podfile
in your project directory. This file defines your project's dependencies. - Edit the
Podfile
and add your dependencies along with their versions. Here is an example which includes the dependencies you need for the Maps SDK for iOS and Places SDK for iOS (optional):source 'https://github.com/CocoaPods/Specs.git' target 'YOUR_APPLICATION_TARGET_NAME_HERE' do pod 'GoogleMaps', '4.2.0' pod 'GooglePlaces', '4.2.0' end
Make sure to regularly runpod outdated
to detect when there is a newer version to ensure you're always on the latest. If necessary, [upgrade to the latest version](get-cocoapods). - Save the
Podfile
. Open a terminal and go to the directory containing the
Podfile
:cd <path-to-project>
Run the
pod install
command. This will install the APIs specified in thePodfile
, along with any dependencies they may have.pod install
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:
- Open a terminal and go to the project directory containing the
Podfile
. - Run the
pod update
command. This will update all of the APIs specified in thePodfile
to the latest version.
Use Carthage
The Maps SDK for iOS is available to use with Carthage, a simple, decentralized dependency manager for Swift and Objective-C Cocoa projects.
- Install Carthage. There are several methods, so see the Carthage README file for exact steps.
- 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. Note: on 11.7, create a Single View Application.)
- Create a file named
Cartfile
in your project directory. This file defines your project's dependencies. - Edit the
Cartfile
and add your dependencies along with their versions:
binary "https://dl.google.com/geosdk/GoogleMaps.json" == 4.2.0
Make sure to regularly runcarthage outdated
to detect when there is a newer version to ensure you're always on the latest. If necessary, [upgrade to the latest version](get-cocoapods). - Save the
Cartfile
. - In a terminal window, go to the directory containing the
Cartfile
:
cd <path-to-project>
- Run the
carthage update
command. This will install the APIs specified in theCartfile
, along with any dependencies they may have. - In the Finder, in your project directory, go to the downloaded framework files
under
Carthage/Build/iOS
. - 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.framework
GoogleMaps-x.x.x/Maps/Frameworks/GoogleMaps.framework
GoogleMaps-x.x.x/Maps/Frameworks/GoogleMapsCore.framework
Premium Plan customers must also include
GoogleMaps-x.x.x/M4B/Frameworks/GoogleMapsM4B.framework
. - Right-click
GoogleMaps.framework
in your project, and select Show In Finder. - Drag the
GoogleMaps.bundle
from theResources
folder into the top level directory of your Xcode project. When prompted, ensure Copy items into destination group's folder is not selected. - Select your project from the Project Navigator, and choose your application's target.
- 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
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.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:
- Open a terminal and go to the project directory containing the
Cartfile
. - Run the
carthage update
command. This will update all of the APIs specified in theCartfile
to the latest version.
Install manually
This guide shows how to manually add the GoogleMaps framework to your project and configure your build settings in Xcode.
- Download the SDK source files: GoogleMaps-4.2.0.
- Unpack the source files.
- Launch Xcode and either open an existing project, or create a new project. If you're new to iOS, create a new project and select the iOS App template. Note: on 11.7, create a Single View Application.
- 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.framework
GoogleMaps-x.x.x/Maps/Frameworks/GoogleMaps.framework
GoogleMaps-x.x.x/Maps/Frameworks/GoogleMapsCore.framework
Premium Plan customers must also include
GoogleMaps-x.x.x/M4B/Frameworks/GoogleMapsM4B.framework
. - Right-click
GoogleMaps.framework
in your project, and select Show In Finder. - Drag the
GoogleMaps.bundle
from theResources
folder into the top level directory of your Xcode project. When prompted, ensure Copy items into destination group's folder is not selected. - Select your project from the Project Navigator, and choose your application's target.
- 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
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.To install the Places SDK for iOS, see Get Started with the Places SDK for iOS.
Step 2: Adding your API key
Follow the Get an API key guide to add your API key to your app.
Step 3: Adding a map
The code below demonstrates how to add a simple map to an existing
ViewController
. If you're creating a new app, first follow the
SDK installation instructions above, and create a new project and select the
iOS App template. Note: on 11.7,
create a Single View Application.
Now, add or update a few methods inside your app's default
ViewController
to create and initialize an instance of
GMSMapView
.
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
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 4: Declaring the URL schemes used by the API
Beginning with iOS 9 and Xcode 7, apps must 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 therefore needs to 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 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.
For more details, see the guide to code samples.