Entities

Entities are the core of Nextspace. An Entity is a record that can represent anything based on your own level of categorization, attribution, and tagging.

Examples of Entity records can be a certain building, a person, or a vehicle.

Data model

To avoid repeating the data model in the documentation, we'll cover it once here.

Please refer to the terminology section for a definition if you're unsure what an Entity is.

Below is a minimal example of an Entity record. Your custom attributes will sit alongside the Nextspace ones.

// @Warning this example is primarily focused at non-assembly Entities.
// Assembly Entities have relative positions to their parent.
interface IEntity {
    // Bruce is a code-word for the Nextspace API.
    // These are internal fields.
    "Bruce": {
        "ID": string,
        "EntityType.ID": string,
        "CreatedBy.User.ID": string,
        // Array of Entity Tag IDs.
        "Layer.ID": number[],
        // Created/updated date/time in ISO 8601 UTC.
        "Created": string;
        "Updated": string;
        "Location"?: {
            // Lat/long are in degrees.
            "latitude": number,
            "longitude": number
            // Altitude is in meters.
            // The Entity's Style will dictate what this is relative to.
            // For example the Style may say "relative-to-ground" which would mean-
            // this altitude value should be added to the ground elevation.
            "altitude"?: number
        },
        "Boundaries"?: {
            // Lat/long are in degrees.
            "maxLatitude": number;
            "maxLongitude": number;
            "minLatitude": number;
            "minLongitude": number;
            // Altitude is in meters.
            "maxAltitude"?: number;
            "minAltitude"?: number;
        },
        "Transform"?: {
            // H/P/R are in degrees.
            "heading"?: number,
            "pitch"?: number,
            "roll"?: number,
            // Scale is a multiplier.
            // This will be multiplied by the Entity Style scale as well.
            "scale"?: number
        },
        // Outline on what parts of the Entity loaded from where.
        // Only available when there are >1 sources of data, or if the only source has something of interest.
        "Outline"?: {
            // Human readable name of the source.
            "Source.Name": string;
            // Indicates if this is the baseline source.
            // This means that the base list of attributes are sourced from here.
            // Other sources will be overlaid on top of this one.
            "Baseline"?: boolean;
            // Array of attribute paths that were sourced from here.
            // If Baseline is true, then this isn't specified and all unspecified attributes are sourced from here.
            "Attribute"?: string[];
            // Indicates if this source is editable.
            // If false, inputs for related attributes will be disabled.
            "Editable": boolean;
            // If the record itself or attributes were sourced from here.
            "Kind": "ATTRIBUTE" | "ENTITY";
            // ID of the source, if any.
            "Source.ID"?: number;
            // Entity Type source ID, if any.
            "EntityType.Source.ID"?: number;
            // Related DateTime if any (for Historic data).
            "DateTime"?: string;
            // Related Scenario record if any.
            "Scenario"?: string | number;
            // Related linking attribute.
            // Eg: for historic data this is the date-time key, for sources it's the FK.
            "ForeignKey"?: string;
        }[];
    },
    // There can be any number of custom attributes defined by you.
    "MyAttribute": string,
    "MyOtherAttribute": {
        "MySubAttribute": number
    }
}

Entity data model

Requesting an Entity record

The simplest way to retrieve an Entity record is through an HTTPS GET request.

It is best to include a session header as Entities can be restricted through tags.

Get a single record by ID

Request urlhttps://

{accountId}

.api.nextspace-dev.net/v3/entity/

{entity_id}

Type={entityTypeId}

$expand=location

Request type

GET

Requirements

Account ID

Response

// Response is the same as the Entity definition.
// It returns the Entity JSON directly.

Javascript example

Requesting list by IDs

You can also request a list of Entities by their IDs.

Get list of records by IDs

Request urlhttps://

{accountId}

.api.nextspace-dev.net/v3/getEntities

Request type

POST

Requirements

Account ID

Request body

interface IPostBody {
    "Filter": {
        ID: {
            // Array of IDs you'd like to request.
            in: string[]
        }
    },
    // Unfortunately, this is required.
    // Set it to length of ID array, otherwise it will use a server default length.
    "PageSize": number
}

Response

interface IResponse {
    "Items": IEntity[];
}

Javascript example

Requesting list with an attribute query

Below is a breakdown of how the basics of attribute queries work when requesting a list of Entities.

Supported microservices will apply these filters when requesting external data (for example Maximo) by reversing the data mapping between the two sources.

It is recommended to use DataLab for more advanced queries.

Get list of records with attribute queries

Request urlhttps://

{accountId}

.api.nextspace-dev.net/v3/getEntities

Request type

POST

Requirements

Account ID

Request body

interface IPostBody {
    "Filter": {
        // Attribute path segments are separated by a forward slash. Eg: 'address/city'.
        "an-attribute-path": {
            "an-operator": "a-value"
        }
    },
    "PageSize": number
}

interface ISamples {
    "Filter": {
        // Nested string attribute containing "queen".
        // This is case-insensitive.
        "address/street": {
            "contains": "queen"
        },
        // Nested string attribute equal to "auckland".
        "address/city": {
            "=": "auckland"
        },
        // Numeric attribute between 0 and 100.
        "value-1": {
            "between": [0, 100]
        },
        // Numeric attribute bigger than 100.
        "value-2": {
            ">": 100
        },
        // Date time attribute equal or after 2024-03-15T02:00:52Z.
        "founded-date": {
            // ISO 8601 format.
            ">=": "2024-03-15T02:00:52Z"
        },
        // Date time attribute between 2024-03-15T02:00:52Z and 2024-03-15T02:00:52Z.
        "founded-date-2": {
            // ISO 8601 format.
            "between": ["2024-03-15T02:00:52Z", "2024-03-15T02:00:52Z"]
        },
        // String attribute starting with "a".
        "something-1": {
            "startswith": "a"
        }
        // String attribute ending with "b".
        "something-2": {
            "endswith": "b"
        }
        // Boolean attribute equal to true.
        "is-active": {
            "=": true
        }
    },
    "PageSize": 2
}

Requesting list with a geographic query

Below is how you can perform a basic geographic boundary query when requesting a list of Entities.

Get list of records by IDs

Request urlhttps://

{accountId}

.api.nextspace-dev.net/v3/getEntities

Request type

POST

Requirements

Account ID

Request body

interface IPostBody {
    "Filter": {
        "boundaries": {
            "intersects": [
                // South (min latitude).
                0,
                // North (max latitude).
                0,
                // West (min longitude).
                0,
                // East (max longitude).
                0
            ]
        }
    },
    "PageSize": number
}

Updating and creating records

You can request an update or create an Entity record by performing an HTTPS POST request with the Entity's data within the body.

If the Entity ID is not provided, a new Entity will be created.

Create or update an Entity record

Request urlhttps://

{accountId}

.api.nextspace-dev.net/v3/entity/

{entity_id}

Type={entityTypeId}

DataOverride={true/false}

Request type

POST

Requirements

Account ID

Logged in user auth token

Request body

// Body is the same as the Entity definition.
// Pass the Entity JSON directly.

Response

// Response is the same as the Entity definition.
// It returns the Entity JSON directly.

Javascript example

Create or update an array of Entity records

Request urlhttps://

{accountId}

.api.nextspace-dev.net/v3/entities?

Type={entityTypeId}

DataOverride={true/false}

Request type

POST

Requirements

Account ID

Logged in user auth token

Request body

Items: IEntity[]

Response

Items: IEntity[]

Javascript example