ARCore Cloud Anchor Management API

Manage Cloud Anchors outside of your ARCore app using the ARCore Cloud Anchor Management API.

Getting started

Example operations

Authorization

Create a service account key in the Google Cloud Platform console and generate an OAuth2 token to authorize Cloud Anchor management API calls.

  1. In the navigation menu of the Google Cloud Platform console, go to APIs & Services > Credentials.

  2. Select the desired project, then click Create Credentials > Service account.

  3. Under Service account details, type a name for the new account, then click Create.

  4. On the Service account permissions page, go to the Select a role dropdown. Select Service Accounts > Service Account Token Creator, then click Continue.

  5. On the Grant users access to this service account page, click Done. This takes you back to APIs & Services > Credentials.

  6. On the Credentials page, scroll down to the Service Accounts section and click the name of the account you just created.

  7. On the Service account details page, scroll down to the Keys section and select Add Key > Create new key.

  8. Select JSON as the key type and click Create. This downloads a JSON file containing the private key to your machine. Store the downloaded JSON key file in a secure location.

Generate an OAuth2 token

arcore.management is the OAuth scope for the Cloud Anchors Management API. By default, oauth2l works on a token cache. The fetch command retrieves the same token. Use oauth2l to generate an OAuth2 token for authorization:

oauth2l fetch --json creds.json arcore.management

To generate a new token, add a --cache="" option to the fetch command.

oauth2l fetch --cache="" --json creds.json arcore.management

Alternatively, call oauth2l reset and call the fetch command again.

oauth2l reset
oauth2l fetch --json creds.json arcore.management

List all Cloud Anchors

Get the first page of Cloud Anchors, optionally sorted by expire_time, create_time, or last_localize_time.

Request:

export BEARER_TOKEN=`(oauth2l fetch --json creds.json arcore.management)`
curl -H "Authorization: Bearer $BEARER_TOKEN" \
   "https://arcore.googleapis.com/v1beta2/management/anchors?page_size=50&order_by=last_localize_time%20desc"

Response:

{
  "anchors": [
    {
      "name": "anchors/ua-a1cc84e4f11b1287d289646811bf54d1",
      "createTime": "...",
      "expireTime": "...",
      "lastLocalizeTime": "...",
      "maximumExpireTime": "..."
    },
   …
    {
      "name": "anchors/ua-41a3d0233471917875159f6f3c25ea0e",
      "createTime": "...",
      "expireTime": "...",
      "lastLocalizeTime": "...",
      "maximumExpireTime": "..."
    }
  ],
  nextPageToken: "some-long-string"
}

If the response comes back with a nextPageToken, there are more anchors to list. Use the next_page_token query parameter on the next request to retrieve the next set of results.

Request:

curl -H "Authorization: Bearer $BEARER_TOKEN" \
   "https://arcore.googleapis.com/v1beta2/management/anchors?page_size=50&order_by=last_localize_time%20desc&next_page_token=your-next-page-token-here"

When using next_page_token, page_size and order_by must be consistent across requests. page_size defaults to 1000 and order_by defaults to expire_time_desc.

Update a Cloud Anchor’s time to live to the maximum time allowed

Request a single Cloud Anchor to query its lastLocalizeTime and maximumExpireTime.

Request:

export BEARER_TOKEN=`(oauth2l fetch --json creds.json arcore.management)`
curl -H "Authorization: Bearer $BEARER_TOKEN" \
   "https://arcore.googleapis.com/v1beta2/management/anchors/your-anchor-id-here"

Response:

{
  "name": "anchors/ua-f21be53fd8ea57f0169c69fbf827f6b7",
  "createTime": "2020-06-29T21:00:00Z",
  "expireTime": "2020-08-28T22:00:00Z",
  "lastLocalizeTime": "2020-06-29T21:00:00Z",
  "maximumExpireTime": "2021-06-29T21:00:00Z"
}

Once you have the anchor, update its expireTime to its maximumExpireTime.

Request:

curl -H "Authorization: Bearer $BEARER_TOKEN" -H "Content-Type: application/json" -X "PATCH" \
   "https://arcore.googleapis.com/v1beta2/management/anchors/your-anchor-id-here?updateMask=expire_time" \
    -d '{ expireTime: "2021-06-29T21:00:00Z" }'

Response:

{
  "name": "anchors/ua-f21be53fd8ea57f0169c69fbf827f6b7",
  "createTime": "2020-06-29T21:00:00Z",
  "expireTime": "2021-06-29T21:00:00Z",
  "lastLocalizeTime": "2020-06-29T21:00:00Z",
  "maximumExpireTime": "2021-06-29T21:00:00Z"
}

Delete Cloud Anchors

Delete a single Cloud Anchor:

export BEARER_TOKEN=`(oauth2l fetch --json creds.json arcore.management)`
curl -H "Authorization: Bearer $BEARER_TOKEN" -X "DELETE" \
   "https://arcore.googleapis.com/v1beta2/management/anchors/your-anchor-id-here"

Delete a batch of Cloud Anchors:

export BEARER_TOKEN=`(oauth2l fetch --json creds.json arcore.management)`
curl -H "Authorization: Bearer $BEARER_TOKEN" -H "Content-Type: application/json" -X "POST" \
   "https://arcore.googleapis.com/v1beta2/management/anchors:batchDelete" \
    -d '{ names: [ "anchors/your-anchor-id-here", "anchors/your-anchor-id-here" ]}'