Configure your app's settings so that it can use the [Geospatial API](https://developers.google.com/ar/develop/geospatial).

## Prerequisites

Make sure that you understand [fundamental AR concepts](https://developers.google.com/ar/develop/fundamentals)
and how to [configure an ARCore session](https://developers.google.com/ar/develop/c/session-config) before proceeding.

If you want to run a sample app that demonstrates the functionality described
here, see the
[ARCore Geospatial Quickstart for Android](https://developers.google.com/ar/develop/java/geospatial/quickstart)
for Java. The sample app in the Quickstart is written in Java. The code samples
in this document are for the same functionality written in C.

See the
[Introduction to the Geospatial API](https://developers.google.com/ar/develop/geospatial) for more
information about the Geospatial API.

If you're new to developing with ARCore, see [Getting started](https://developers.google.com/ar/develop/getting-started)
for information about software and hardware requirements, prerequisities and
other information specific to the platforms you are using.

Be sure your development environment satisfies the ARCore SDK requirements, as
described in the [Quickstart](https://developers.google.com/ar/develop/java/geospatial/quickstart) for Java.

## Enable the ARCore API

Before using the Visual Positioning System (VPS) in your app, you must first
enable the [**ARCore API**](https://developers.google.com/ar/develop/authorization?platform=c)
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.

In your app's `build.gradle` file, [setup Google Play services](https://developers.google.com/android/guides/setup) to include the Play
Services Location library.

    dependencies {
      // Apps must declare play-services-location version >= 16.
      // In the following line, substitute `16 (or later)` with the latest version.
      implementation 'com.google.android.gms:play-services-location:16 (or later)'
    }

## Enable Geospatial capabilities in the session configuration

Before creating the session, change the `GeospatialMode` in your session
configuration to [`ENABLED`](https://developers.google.com/ar/reference/java/com/google/ar/core/Config.GeospatialMode#enabled):

```c
// Create a session config.
ArConfig* ar_config = NULL;
ArConfig_create(ar_session, &ar_config);

// Enable the Geospatial API.
ArConfig_setGeospatialMode(ar_session, ar_config, AR_GEOSPATIAL_MODE_ENABLED);
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);

// Release config resources.
ArConfig_destroy(ar_config);
```

While the Geospatial mode is set to `ENABLED`, the application is allowed to obtain
geographical information from the Visual Positioning System (VPS).

## Prompt user to allow usage of device data

Apps that use the ARCore Geospatial API must present the user with a prompt to
acknowledge and allow the use of data from their device. See
[User privacy requirements](https://developers.google.com/ar/develop/privacy-requirements) for more
information.

## Check device compatibility

Not all devices that support ARCore also support the Geospatial API, as
described in the [quickstart](https://developers.google.com/ar/develop/java/geospatial/quickstart#device-support)
for Java.

To check the user's device for compatibility, call
[`ArSession_isGeospatialModeSupported()`](https://developers.google.com/ar/reference/c/group/ar-session#arsession_isgeospatialmodesupported).
If this returns false do not attempt to configure the session (below), as doing
so will cause the `ArStatus` to report an
[`AR_ERROR_UNSUPPORTED_CONFIGURATION`](https://developers.google.com/ar/reference/c/group/shared-types#ar_error_unsupported_configuration).

## Ask user for location permissions at runtime

Your app must [request location permissions at runtime](https://developer.android.com/training/location/permissions#request-location-access-runtime).

To use the ARCore Geospatial API, your app needs to register the following
extra permissions:

- [`ACCESS_FINE_LOCATION`](https://developer.android.com/training/location/permissions)
  to accurately determine the user's location.

- [`ACCESS_COARSE_LOCATION`](https://developer.android.com/training/location/permissions)
  for non-accurate determination of the user's location and to comply with
  user privacy requirements. However, the Geospatial API cannot be configured
  to work with coarse location, and API requests will fail when the user has
  set this permission. See below for more information.

- [`ACCESS_INTERNET`](https://developer.android.com/training/basics/network-ops/connecting)
  to contact the ARCore Geospatial API service.

    <manifest ... >
      <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
      <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
      <uses-permission android:name="android.permission.INTERNET" />
    </manifest>

On devices that run Android version 12 or higher,
[users can request](https://developer.android.com/training/location/permissions#approximate-request)
that your app have access to only
[approximate location](https://developer.android.com/training/location/permissions#accuracy)
information. To accommodate this request, your app must have the
[`ACCESS_COARSE_LOCATION`](https://developer.android.com/training/location/permissions)
permission configured, along with
[`ACCESS_FINE_LOCATION`](https://developer.android.com/training/location/permissions),
as shown above. You must
[configure both location permissions](https://developer.android.com/training/location/permissions#approximate-request).

However, when users specify coarse location, doing so prevents the Geospatial
API from obtaining the precise location it requires. The Geospatial service will
not allow itself to be configured if your app gives it only coarse location.
Your app cannot use the Geospatial API with coarse location.

## Check Geospatial availability at the device's current location

Because the Geospatial API uses a combination of [VPS](https://developers.google.com/ar/develop/geospatial#global_localization_with_vps) and GPS to determine a Geospatial pose, 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 poses. Under typical conditions, VPS can be expected to provide positional accuracy of approximately 5 meters, and rotational accuracy of 5 degrees. Use [`ArSession_checkVpsAvailabilityAsync()`](https://developers.google.com/ar/reference/c/group/ar-session#arsession_checkvpsavailabilityasync) 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 pose with high accuracy.

## What's next

- [Obtain the device camera's Geospatial pose](https://developers.google.com/ar/develop/c/geospatial/obtain-device-pose) to determine the exact location of the user's device in the real world.
- [Check VPS availability](https://developers.google.com/ar/develop/c/geospatial/check-vps-availability) at a device's given location.