Enable the Geospatial API for your iOS app

Configure your app's settings so that it can use the Geospatial API.

Prerequisites

Make sure that you understand fundamental AR concepts and how to configure an ARCore session before proceeding.

If you want to run a sample app that demonstrates the functionality described here, see the ARCore Geospatial quickstart for iOS.

See the Introduction to the Geospatial API for more information about the Geospatial API.

If you're new to developing with ARCore, see Getting started for information about software and hardware requirements, prerequisities and other information specific to the platforms you are using.

Enable the ARCore API

Before using the Visual Positioning System (VPS) in your app, you must first enable the ARCore API in a new or existing Google Cloud project. This service is responsible for hosting, storing, and resolving Geospatial anchors.

Keyless authorization is preferred, but API Key authorization is also supported.

Add required libraries to your app

After authorizing your app to call the ARCore API, you must add libraries to enable Geospatial features in your app.

Update the Podfile for your app to include the ARCore SDK and supported iOS versioning. To do this:

  1. Add the following platform and pod to your project's Podfile:

    platform :ios, '11.0'
pod 'ARCore/Geospatial', '~> 1.42.0'

    You may also specify platform :ios, '10.0', if you want to support iOS 10, but note that the Geospatial API will only function at runtime on iOS >= 11.

  2. Open a Terminal window and run pod install from the folder where your Xcode project exists.

    This generates an .xcworkspace file that you use to build and run the app.

Be sure your development environment satisfies the ARCore SDK requirements, as described in the Quickstart.

Enable Geospatial capabilities in the session configuration

Check device compatibility

Not all devices that support ARCore also support the Geospatial API, as described in the quickstart.

Use GARSession.isGeospatialModeSupported: to check the device, as in the following:

if (![self.garSession isGeospatialModeSupported:GARGeospatialModeEnabled]) {
  [self setErrorStatus:@"GARGeospatialModeEnabled is not supported on this device."];
  return;
}

GARSessionConfiguration *configuration = [[GARSessionConfiguration alloc] init];
configuration.geospatialMode = GARGeospatialModeEnabled;
[self.garSession setConfiguration:configuration error:&error];
if (error) {
  [self setErrorStatus:[NSString stringWithFormat:@"Failed to configure GARSession: %d",
                                                  (int)error.code]];
  return;
}

Ask user for location permissions at runtime

Your app must request the following location permissions at runtime, before configuring the session:

Check Geospatial availability at the device's current location

Because the Geospatial API uses a combination of VPS and GPS to determine a Geospatial transform, the API can be used as long as the device is able to determine its location. In areas with low GPS accuracy, such as indoor spaces and dense urban environments, the API will rely on VPS coverage to generate high accuracy transforms. Under typical conditions, VPS can be expected to provide positional accuracy of approximately 5 meters, and rotational accuracy of 5 degrees. Use GARSession.checkVPSAvailabilityAtCoordinate:completionHandler: to determine if a given location has VPS coverage.

The Geospatial API can also be used in areas that do not have VPS coverage. In outdoor environments with few or no overhead obstructions, GPS may be sufficient to generate a transform with high accuracy.

What's next