Skip to main content

Getting Started with Sites

Overview​

The Sites feature provides an API for querying hierarchical data in the Niantic Spatial platform. This guide will help you get started using Sites in your application.

The Sites feature organizes data in a hierarchical structure:

Organization → Site → Asset.

Your application starts at the Organization level, which is resolved directly from your access token (see below).

Requirements​

The Sites feature requires authentication using Niantic Spatial Auth. Your application must be authenticated before using any Sites API methods.

To authenticate:

  1. Ensure you have access the Niantic Spatial Portal where you can manage your organizations, sites, and assets.
  2. Set up auth in your application by following the Auth guide

Your access token and Organization​

Your access token is scoped to an Organization. That tells the SDK which Organization's data your app can access. Use requestSelfOrganizationInfo to get that Organization's information. For a code example, see Get your organization.

Basic Usage​

The Sites API follows a simple pattern: Make requests and handle results. All requests are asynchronous and return struct data that represents the Sites entity you are requesting.

1. Acquire a Sites Session​

Add the Sites component to your unity scene's gameobject

Sites Client Manager component in Unity Inspector

Then add a reference to the Sites component to your monobehaviour:

[SerializeField]
private SitesClientManager _sitesClientManager;

2. Get your organization​

Resolve your organization directly from the access token with requestSelfOrganizationInfo.

var orgResult = await _sitesClientManager.GetSelfOrganizationInfoAsync();
if (orgResult.Status == SitesRequestStatus.Success && orgResult.Organizations.Count > 0) {
    var organization = orgResult.Organizations[0];
    Debug.Log($"Organization: {organization.Name}");
    var orgId = organization.Id;
}

3. Query Sites​

Browse sites within an organization, using the orgId from the previous step:

var sitesResult = await _sitesClientManager.GetSitesForOrganizationAsync(orgId);
if (sitesResult.Status == SitesRequestStatus.Success) {
    foreach (var site in sitesResult.Sites) {
        Debug.Log($"Site: {site.Name}");
    }
}

4. Query Assets​

Discover spatial assets available at a site:

var assetsResult = await _sitesClientManager.GetAssetsForSiteAsync(siteId);
if (assetsResult.Status == SitesRequestStatus.Success) {
    foreach (var asset in assetsResult.Assets) {
        Debug.Log($"Asset: {asset.Name} ({asset.AssetType})");
    }
}

5. Choose a Site for VPS2 localization​

To precisely localize to a Site, retain its Site ID from the Site query and confirm it has a production VPS asset. The Site ID identifies the localization target; the localized asset ID identifies the VPS map that matched after localization.

var assetsResult = await _sitesClientManager.GetAssetsForSiteAsync(siteId);
bool canLocalize = false;
if (assetsResult.Status == SitesRequestStatus.Success) {
    foreach (var asset in assetsResult.Assets) {
        if (asset.AssetType == AssetType.VpsInfo &&
            asset.Deployment == AssetDeploymentType.Production) {
            canLocalize = true;
            // Use siteId with TryLocalize(...) to start map-relative localization.
            break;
        }
    }
}

To start map-relative localization for a Site, pass its Site ID to ARVps2Manager.TryLocalize(siteId). For an example that localizes to a Site and places content at the localized asset, see Place virtual content with VPS2. To learn which status to read while waiting for localization, see Tracking states.

Next Steps​