Thanks for tuning in to Google I/O. Check out the sessions.

Geospatial quickstart for Android

This quickstart for the ARCore Geospatial API shows you how to run a sample app in Android Studio that demonstrates the Geospatial API.

For a guide to developing your own app with the Geospatial API, see the Geospatial developer guide for Android (Kotlin/Java) or the Geospatial developer guide for Android NDK (C).

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

If you're new to developing with ARCore, see Getting started.

Requirements

Device support

See Supported devices for a complete list of devices that have been certified to work with ARCore. For the Geospatial API, one of the key pieces of hardware required is a magnetometer that meets the Geospatial API specifications. Some magnetometers do not meet the spec; devices with these off-spec magnetometers are not supported.

Software

  • The latest version of Google Play Services for AR installed on the supported device.

  • Android Studio version 3.0 or later with Android SDK Platform version 7.0 (API level 24) or higher

  • The ARCore SDK for Android, which you can get in one of two ways:

    • Download it from GitHub and extract it on your machine.

    • Clone the repository with the following command: 

      git clone https://github.com/google-ar/arcore-android-sdk.git

Open and set up the sample app

The geospatial_java project included with the ARCore SDK for Android describes code that calls the Geospatial API.

  1. In Android Studio, from the File menu, click Open.

  2. Navigate to the project folder for the arcore-android-sdk.

  3. Open the samples folder, select the geospatial_java folder, and click Open.

Set up a Google Cloud Project

To use the Visual Positioning System (VPS), your app needs to be associated with a Google Cloud Project that is enabled for the ARCore API.

You must enable the ARCore API in your Google Cloud Project. If you need to create the project, do the following:

  1. Visit Create a project in Google Cloud Platform.

  2. Enter an appropriate Project name, and choose a location for it.

  3. Click Create.

  4. In the sidebar, select APIs & Services, then Library.

  5. Search for the ARCore API, select it, and click Enable.

Set up authorization

To make Geospatial API calls to VPS, your sample app instance may use keyless authorization.

  1. In your Android Studio project, open the Gradle toolpane.

  2. Navigate to <project-name> > work > Tasks > android.

  3. Run the signingReport task.

  4. Copy the SHA-1 fingerprint; you will paste it in a later step.

    For sample apps, use the debug fingerprint.

  5. In your Google Cloud Project, Create an OAuth client ID.

  6. In the SHA-1 fingerprint field, paste the SHA-1 fingerprint from the previous step.

  7. Click CREATE to create the OAuth client ID.

Include required libraries

In the sample app's build.gradle file, setup Google Play services to include the Google Sign-In for Android library.

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

Run the sample app

In Android Studio, run the sample app.

You should be able to see a camera view, along with debug information describing the current Geospatial pose of your device. As you scan the environment around you, notice the positioning accuracy confidence values may change as you move around, if you're in an area supported by VPS localisation.

When ARCore is confident in your device's location and heading, you can place an Anchor at your current location using the Geospatial pose.

The positioning accuracy may be too low if VPS information is unavailable. The app must be connected to the internet, and the location must be known to the VPS. For best results, run the sample app outside (not indoors) during daylight hours.

Also, if you are in an area that does not support VPS, or if GPS signals aren't sufficient, you may need to adjust the confidence thresholds in the app in order to place an anchor.

To adjust the thresholds:

  1. In Android Studio, open the GeospatialActivity and browse to the following section:

    // The thresholds that are required for horizontal and heading accuracies before entering into the
// LOCALIZED state. Once the accuracies are equal or less than these values, the app will
// allow the user to place anchors.
private static final double LOCALIZING_HORIZONTAL_ACCURACY_THRESHOLD_METERS = 10;
private static final double LOCALIZING_HEADING_ACCURACY_THRESHOLD_DEGREES = 15;

  2. Adjust these values as needed. The higher the value, the lower the accuracy.

    Lowering the accuracy allows the app greater latitude in placing an anchor. See Adjust for pose accuracy for more information.

Next steps