Home
Attribution
FAQ
How do I gather Entities in Python?
How do I get an Entity ontology in Python?
API Reference
OpenAPI documentation
Authentication
Entities
Entity Types
Entity Type: Data Schema
Data Schema: Data Mapping
Entity Styles
Pending Actions (Server Jobs)
Client and temp files
Entity Attachments
Entity Links
Entity Tags
Entity LODs (representations)
Entity Type LODs
Import Assemblies
Import CSV
Import GeoJSON
Import JSON
Import KML / KMZ
Export BRZ
DataLab queries
DataLab actions
DataLab secondary queries
Entity historic data
Entity Scenarios
Project Views and Bookmarks
Project View Menu Items
Project View Data
Custom Forms
Relationship Types
Relationships
Libraries: Web
Getting started
Setup: No framework
Setup: Typescript + React
Setup: Typescript + Angular
Setup: React Native + Expo
Authentication
Default widgets
Drawing tools
Entity interaction
Render Project Views
Render Entities
Render Cesium Tilesets
Render terrain and basemaps
Styling Entities
Styling Tilesets
Request Entity records
File uploads
Libraries: Python
Getting started
Authentication
Entities
Entity Types
Web Navigator
Plugins
Plugins - Developer environment
Loading in an iFrame
Operator
Annotated documents
Other apps
IBM Maximo
Unreal Engine 5
Omniverse

Entity historic data


Entity historic records are time-stamped snapshots of an Entity's data. You can assign a set of your attributes to be tied to one of your date-time attributes, and the system will automatically create a new historic record each time the date-time attribute changes.

You can have multiple date-time attributes that create different historic records for different sets of attributes.

We call these date-times "Historic keys", and attributes that change "Historic attributes".


You can flag an attribute as tied to a historic key by setting the HistoricKey property on the attribute in the Entity Type's Data Schema.

See below a preview of the Data Schema definition that you can find more information about in the Entity Type Data Schema documentation.

export interface IAttribute {
    ...

    // The historic key (if any) this attribute is associated with.
    // This is a date-time attribute that drives the change for this attribute value.
    // Attribute path segments are separated by a forward slash. Eg: 'address/city'.
    HistoricKey?: string;
}

Once set, updating Entities in that Entity Type will check for valid date-time values in that key and create/update historic records based on the changes.


If you update an Entity with no valid date-time, then the default attribute values are updated within the 'normal' Entity record.

These default values are returned when querying an Entity without a timestamp, or when no historic records are found for the timestamp provided.

Note that there is a default limit of 1,000 historic records per Entity ID unless an upgraded limit is discussed.

To request for historic data, simply use the "HistoricPoint=an_iso_8601_date_time" query parameter during Entity or DataLab requests.

The latest historic record to that point in time will be returned. Records in the future will not be returned.

Note that historic records are applied to found Entity records after the filtering and sorting is done.

Returned records will have additional metadata on what historic records were overlaid on the Entity record.

Below is a preview of how an Entity's data structure is extended to include historic metadata.

interface IEntity {
    // Bruce is a code-word for the Nextspace API.
    // These are internal fields.
    Bruce: {
        // Outline on what parts of the Entity were loaded from where.
        // This is a preview on what properties are available (focused on Historic here).
        "Outline"?: {
            // Indicates that this is the baseline source of Entity data.
            // If true, then any attributes not specified by another source are assumed to be from this one.
            "Baseline"?: boolean;
            // Human readable name of the source.
            "Source.Name": string;
            // Foreign-key, for historic data this is the date-time attribute path.
            "ForeignKey"?: string;
            // DateTime representing the time of the record.
            "DateTime"?: string;
            // Indicates that this source is editable.
            // When false, inputs for the related attribute are disabled.
            "Editable": boolean;
            // Array of attribute paths that were loaded from this source.
            // If Baseline=true, then all attributes that weren't specified are loaded from this source.
            "Attribute"?: string[];
        }[];
    }
}

Get records directly

If you want to look through historic records directly without having them overlay on the Entity data, then you can use the below request.

Currently, it will return up 1,000 records within the specified date-time range for each requested for Entity ID.

Get historic records

Response
interface IResponse {
    // Map of Entity IDs mapped to an array of found records.
    "recordsByIds": Map<string, {
        // ISO 8601 date-time of the record.
        "dateTime": string;
        // Entity attributes at that date-time.
        data: any;

        // Please note that we retain the full snapshot of the below fields even if only a subset of them are marked as historic.
        // When requesting Entities with a historic point in time, only the subset is overlaid on the Entity data.

        // Entity location JSON at that date-time.
        // This is only available if location attributes are being tracked (marked as historic).
        location: any;
        // Entity transform JSON at that date-time.
        // This is only available if transform attributes are being tracked (marked as historic).
        transform: any;
        // Entity boundaries JSON at that date-time.
        // This is only available if boundary attributes are being tracked (marked as historic).
        boundaries: any;
        // Entity vector geometry JSON at that date-time.
        // This is only available if geometry attributes are being tracked (marked as historic).
        geometry: any;
    }[]>;
    // Limit per Entity ID that was enforced.
    "recordsByIds": number;
}
Javascript example

Get stats

You can request stats about either an Entity Type or set of Entity IDs to get an overview of the historic data.

Get record stats for Entity IDs

Request body
interface IRequest {
    // Array of Entity IDs to get stats for.
    entityIds: string[];
}
Response
interface IResponse {
    "stats": {
        // Path to the date-time attribute. Eg: "my_datetime".
        attrKey: string;
        // ISO-8601 date-time string.
        dateTimeMax: string;
        // ISO-8601 date-time string.
        dateTimeMin: string;
        // Number of historic records.
        count: number;
    }[];
}

Get record stats for Entity Type ID

Request body
interface IRequest {
    entityTypeId: string;
}
Response
interface IResponse {
    "stats": {
        // Path to the date-time attribute. Eg: "my_datetime".
        attrKey: string;
        // ISO-8601 date-time string.
        dateTimeMax: string;
        // ISO-8601 date-time string.
        dateTimeMin: string;
        // Number of historic records.
        count: number;
    }[];
}

Update records directly

You can skip the automatic creation of historic records by updating them directly.

Note that there is a default limit of 1,000 historic records per Entity ID unless an upgraded limit is discussed.

Update historic records

Request body
interface IRequest {
    records: {
        // Related Entity ID to create/update this record for.
        "entityId": string;
        // ISO 8601 to create/update this record for.
        "dateTime": string;
        // The historic key to create/update this record for.
        "attrKey": string;

        // The data to set for this record.
        "data": any;

        // Optional internal fields related to the geographic position to set.
        "location"?: any;
        "transform"?: any;
        "boundaries"?: any;
        "geometry"?: any;
    }[];
}
Response
interface IResponse {
    // Array of any encountered errors.
    "error"?: string[];
}

Delete records

You can delete historic records by requesting a date range to delete records within.

Delete historic records

Javascript example