Authentication

If you don't have an API token yet, you'll need to go to the admin panel of the dashboard and create a new token that will allow us to authenticate you during queries.

Then, replace <YOUR_TOKEN_HERE> in the example to the right with the one you just created in the admin panel.

The server expects for the authorization bearer token to be included in all API requests to the server in a http header.

Playground

You can test the api at our GraphQL V1 Playground or our GraphQL V2 Playground.

{
  "Authorization": "Bearer <YOUR_TOKEN_HERE>"
}

Date	Changes
2023-10-03	Update the Glossary and add API chart
2023-10-04	Update fields descriptions
2023-10-24	Update examples

Installations, zones and passages

An Installation represents the physical part of the system. It is made up of Zones (which may or may not have sub-zones) connected to each other or to the outside via Passages.

Events

Events that correspond to a (long) counting duration defined by the client. Events have a start and end date that indicates when they start and end. Some Events are in “never ending” mode and do not necessarily have an end date. An Event is made up of Counting Periods which are automatically generated one or two days in advance and correspond to a short counting period (generally 1 day).

Devices, brands, models, and status

There are 2 types of devices, the counting devices (named Pads) that can be cameras or counting mats. And the air quality devices (named atmosphere devices). Those devices are linked to a passage (for counting devices) or a zone (for atmosphere devices), and generate some counts (for counting devices) or KPIs (for atmosphere devices). They also generate live status, and the history of passed statuses is also accessible via this API.

KPIs & counts

KPIs and Counts are linked either to a Period or an Event (sum of the Periods globally) and to a Passage or to a Zone. They contain the data from the various sensors transformed into a number.

API V1 and API V2

As we have recently created new KPIs and reworked our calculation method for the metering and air quality KPIs, we have created a second API. This allows you to access the V2 KPI database. So you have two APIs to access your data:

• API V1: to access the first-generation KPIs, as well as information on installations, events, zones and passages, and finally devices and their status. The available KPI's in this API are the Counting Kpis, and the air quality Kpis.
• API V2: gives you access to second-generation KPIs only.

Here is a list about the most used/useful queries in this API V1. . Note that if you need to access Kpis that are not basic counting or air quality KPis, you should use the API V2.

To get all of your information about your installations :

query topology {
  allInstallations {
    zones {
      name
      id
    }
    events {
      name
      id
    }
  }
}

The answer returned will look like :

{
  "data": {
    "allInstallations": [
      {
        "name": "Building Simulation",
        "zones": [
          {
            "name": "Building Simulation",
            "id": 1
          },
          {
            "name": "Hall",
            "id": 2
          },
          {
            "name": "Open Space",
            "id": 3
          }
        ],
        "events": [
          {
            "name": "Building Simulation",
            "id": 1
          }
        ]
      }
    ]
  }
}

To get your counts at a certain date and time :

query liveDataLegacy {
  zoneById(zoneId: 1) {
    counts(eventId: 1, dates: [1690374617000]) {
      in
      out
    }
  }
}

The answer returned will look like :

{
  "data": {
    "zoneById": {
      "counts": [
        {
          "in": 1357,
          "out": 1357
        }
      ]
    }
  }
}

To get your Kpis at a certain date :

query KPIsDataLegacy {
  zoneById(zoneId: 1) {
    kpis(eventId: 1, dates: [1690374617000]) {
      dateBegin
      inside
    }
  }
}

The answer returned will look like :

{
  "data": {
    "zoneById": {
      "kpis": [
        {
          "dateBegin": 1690322400000,
          "inside": [
            0,
            0,
            0,
            ...
            1313,
            1315,
            1317,
            ...
            ]
        }
      ]
    }
  }
}