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. 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;
            // Pass anchorPayload to VPS2 to start map-relative localization for this Site.
            break;
        }
    }
}

Fetching the anchor payload alone does not start map-relative localization. To start map-relative localization for a Site, pass the payload to trackAnchor(). For an example that passes the payload to trackAnchor() and places content on the tracked anchor, see Place virtual content with VPS2. To learn which status to read while waiting for localization, see Check device status and anchor status.

Next Steps​