Atrius™ Spaces API provides programmatic access to space utilization services such as tenant or employee occupancy and usage of space within a physical room, floor or building.  This document will briefly cover terminology and concepts fundamental to developing on the platform.

Spaces API Documentation

https://portal.us.atrius-iot.io/products/spaces

Using the API

The Spaces API is accessed on https://api.us.atrius-iot.io/api/v1/spaces.  The Atrius Admin API can be used together with the Spaces API on the same client application.  The Insights API enforces HTTPS, therefore attempts to access an endpoint with HTTP will result in an error message.

The Spaces API output JSON.  The API is versioned (currently version “one”) and the version is specified as the first path element of any resource URL.  For example, version one is represented in the URL as the “v1” path element you see:  https://api.us.atrius-iot.io/api/v1/spaces.

API Organization

The Spaces API represents a set of operations available to developers and itself is known as a Product.  Products are how APIs are surfaced to you the developer.  Each Product has one or more internal API, with each internal API being comprised of one or more Operation.  Access to Products is managed by a permission hierarchy known as a Group. Products grant visibility to groups, and developers can view and subscribe to the products that are visible to the groups in which they belong.

Authorization Request Headers

In order to ensure requestors, have access to a given resource, every Atrius API operation is authenticated via an API Key strategy which is accomplished by supplying a combination of 4 request headers on each request:

  • atr-partner-id – A GUID which validates the Atrius Partner to which the requested resource belongs
  • atr-subscription-key – Also referred to as an API Key. This string is unique to both an Atrius API Product (e.g. Atrius Insights or Atrius Administration) and an Organization setup by an Atrius Partner. Ultimately this string ensures the resource requested belongs to the Organization to which the key is associated
  • atr-environment-id – The environment in which to execute the request. Each Atrius Partner has access to 3 isolated environments:
    • DEV – A “sandbox” environment used for development related activities
    • DEMO – An environment for which to execute demonstrations of solutions.
    • PROD – An Environment for which all production related activities should execute.
  • atr-request-source – An invalidated string value that’s purely informational in purpose and serves as a record of source on the request. Typically, the value will be a specific userid, username, or application name issuing the request which could be useful in subsequent auditing or troubleshooting activities

The keys and identifiers can be generated using the Atrius partner management console.  Please contact your Atrius partner manager for more information on how to gain access to these keys.

HTTP Verbs & Typical Response Codes

The Spaces API primarily a read-only API and therefore typically only uses:

  • GET retrieves data

A successful request will return a HTTP 200-series response along with the JSON response representing the object.

An error will return a HTTP 400 or 500-series response along with the JSON response containing the error response and correlation id (for further debugging).

Rate Limits

API requests are subject to rate limiting.

In-line Parameters

Most resource URLs feature one ore more in-line parameter.  Many URLs also take explicitly declared parameters on the query string.

In-line parameters are denoted with a prefix and suffix brace (“{}”) in the Request URL section of each resource.  For example, if the building you were working on was identified is identified as “abc1”, you would access that site by using the URL https://api.us.atrius-iot.io/api/v1/spaces/buildings/abc1.  By specifying the in-line buildingId parameter described in the resource URL, you’ve scoped the request to objects associated only with that building.

Time

Datetime values are always returned in UTC time.  Datetimes, when required, are often formatted as either ‘yyyyMMdd’ or ‘yyyyMMddHH’ when used in a requesting operation.