---
title: "Getting started (with Python)"
section: "Libraries: Python"
route: /pythongettingstarted
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# 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](https://pypi.org/project/bruce-models/)

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:

```bash
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.

```bash
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](/faqanalyzingvaluemapsinpython) for what it does.

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

```python
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:

```python
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](/pythonauth) 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.

```python
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:

```python
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.

```bash
bruce --help
```

Anything configured there is read by the library as well, so a script picks up the same defaults. See [CLI: Getting started](/cligettingstarted) and [CLI: Docker](/clidocker).

---

Urls on this page are resolved for account `{accountId}`.
Site index: https://docs.nextspace.host/llms.txt · whole site in one file: https://docs.nextspace.host/llms-full.txt
Human-readable version of this page: https://docs.nextspace.host/pythongettingstarted