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, so it already tells the SDK which organization's data you have access to. Resolve it with requestSelfOrganizationInfo (shown below).

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. Get a Site's VPS anchor payload​

To precisely localize to a Site — and place content on its anchor — you need the Site's anchor payload. It lives on the Site's production VPS asset: find the asset whose type is VPS info and whose deployment is production, then read its anchorPayload.

var assetsResult = await _sitesClientManager.GetAssetsForSiteAsync(siteId);
string anchorPayload = null;
if (assetsResult.Status == SitesRequestStatus.Success) {
    foreach (var asset in assetsResult.Assets) {
        if (asset.AssetType == AssetType.VpsInfo &&
            asset.Deployment == AssetDeploymentType.Production &&
            asset.VpsData.HasValue) {
            anchorPayload = asset.VpsData.Value.AnchorPayload;
            // Hand anchorPayload to VPS2 to begin precise (anchor) localization.
            break;
        }
    }
}
note

Fetching the payload doesn't localize anything by itself — precise (anchor) localization only engages once you track the anchor with this payload. See Place virtual content with VPS2 and, for the difference between device and anchor localization, VPS2: Device vs. anchor localization.

Next Steps​