Getting started (with Python)

Nextspace provides a Python library to interact with the Nextspace API.
The library is available on PyPi and can be installed using pip. Page link

It is deliberately lighter than the web library and does not aim to match it feature for feature. What is covered is Entities and Entity Types, Data Lab queries and actions, Change Sets, historic data, Client Files including Value Maps, Scenarios, Sessions, Accounts and Pending Actions.

Setup

This library needs Python 3.8 or above. That floor exists to meet the interpreters partner installations actually ship with rather than to track upstream, so anything newer is fine.

To install, simply use the following command:

pip install bruce-models

The base install pulls in requests and nothing else. Reading a Value Map needs real array and image handling, which is too heavy to put on an install that only wants the API models, so it lives behind an extra. Install it now if you plan to analyse Value Maps, rather than finding out at the point of decoding a frame.

pip install bruce-models[valuemap]

Everything else works without it. Importing the Value Map module on a base install succeeds too, and only the decoding fails, with a message naming the command above. See FAQ: Analyzing Value Maps for what it does.

Verify the installation by importing the library in your Python script.

import bruce_models as BM

You will be using two API instances for your communication with the Nextspace API. The Guardian API and the Bruce API.

The Guardian API is used for authentication and account management, while the Bruce API is your personal API for your account.

Here is how you create an instance of each API:

import bruce_models as BM

# Creating an instance of our Guardian API.
# By default, this communicates to our production login server.
guardian = BM.GuardianApi()

# Creating an instance of our Bruce API.
bruce = BM.BruceApi({
    "account_id": "your-account-id",
    "session_id": "session-if-already-known",
    # Pass in your instance so it doesn't generate its own.
    # This is optional and an optimization.
    "guardian": guardian
})

# Perform a test request to verify everything is correctly working.
test = bruce.GET("test")
print(test)

The session_id accepts either a session token from a login or a long-lived access token. See Authentication for both.

Identify your account with account_id and let the library resolve where its API lives. That lookup happens once, through Guardian, and it is what makes the same code work against any account in any region without changing a url.

What is available

Almost everything is reachable off the top-level module. The exception is noted below.

import bruce_models as BM

# Connecting.
BM.GuardianApi            # Authentication and account management.
BM.BruceApi               # Your account's API.
BM.Session                # Logging in and out.
BM.Account                # Account records and where their API lives.

# Records.
BM.Entity                 # Entity records, and reading/writing their values.
BM.EntityType             # Entity Type records.
BM.EntityHistoricData     # Timestamped values on an Entity.
BM.EntityIndex            # Index definitions for an Entity Type.
BM.Scenario               # Scenario records.
BM.Tileset                # Tileset records.

# Querying.
BM.DataLabBuilder         # Builds and runs Data Lab queries and actions.
BM.DataLabPairing         # Secondary queries, from DataLabBuilder.secondary().
BM.Ref                    # Compares against another attribute, or the primary.

# Writing in bulk.
BM.ChangeSetBuilder       # Queues edits locally, then applies or saves them.
BM.ChangeSet              # The Change Set record itself.

# Files.
BM.ClientFile             # File uploads and downloads.
BM.ClientFileQueryBuilder # Finding files by purpose, data or layer.
BM.Uploader               # The multi-part upload used for large files.

# Jobs and errors.
BM.PendingAction          # Monitoring server-side background jobs.
BM.ApiError               # A request that failed outright. Unauthorized,
                          # Forbidden, NotFound and ServerError derive from it.
BM.PartialFailure         # A 2xx that reported some of the work did not happen.
                          # Separate from ApiError: the request succeeded.

# Helpers.
BM.PathUtils              # Attribute paths to and from their quoted form.
BM.GeometryBuilder        # Builds the shapes spatial criteria take.
BM.Bounds                 # An Entity's extent, from its geometry and points.
BM.GeoJson                # GeoJSON in and out.
BM.LRUCache               # A bounded cache, for a walk that repeats work.

ClientFileValueMap is the one thing not exported from the top level, because it belongs to the optional extra. Import it by path:

from bruce_models.client_file.client_file_value_map import ClientFileValueMap

The command line

The library is not only importable. Installing it also installs a bruce command, so the same models drive a command line that configures once and then answers one-off questions without a script: who a credential is, what it can reach, what an Account holds, and seeded end-to-end tests against an installation. There is a public Docker image too, for a machine with no Python on it.

bruce --help

Anything configured there is read by the library as well, so a script picks up the same defaults. See CLI: Getting started and CLI: Docker.