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-08-02	Create new version of the API
2023-09-05	Add getLiveKPIs endpoint
2023-09-20	Add getAvailableKPIs endpoint
2023-10-03	Update the Glossary and add API chart
2023-10-04	Update fields descriptions
2023-10-24	Update examples, remove chart, update glossary

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.

Devices

There are several types of devices supported by V2 KPIs. They can be counting devices (for example cameras or counting mats), or they could also be air quality devices, energy sensors, presence detectors, etc... The list is not exhaustive, and as soon as our team integrate new sensors in the product, they will be available on this API. A device is always linked to a zone or a passage.

KPIs

KPIs are linked either to a Zone a passage or a device. They contain the data from the various sensors transformed into a number. When we integrate new sensor types, we will creat new KPI types, and they will be available in this API V2. You can use the getAvailableKPIs query to get the list of available KPis dor a given zone passage or device.

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 this 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 informations 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 only.
• API V2: gives you access to all the second-generation KPIs.

Here is a list about the most used/useful queries in this API V2.

To get your cartography, zones and passages Ids:

query GetCarto {
  getCartographies{
    installation {
      id
      name
    }
    zones {
      id
      name
      parentIds
      childIds
      passageIds
    }
    passages {
      id
      padIds
      name
      zoneOutIds
      zoneInIds
    }
  }
}

The answer returned will look like :

  "data": {
    "getCartographies": [
      {
        "installation": {
          "id": 1,
          "name": "Building Simulation"
        },
        "zones": [
          {
            "id": 1,
            "name": "Building Simulation",
            "parentIds": [],
            "childIds": [
              1,
              ...
            ],
            "passageIds": [
              1
            ]
          },
          ...
        ]
        "passages": [
          {
            "id": 1,
            "padIds": [
              Pad_1,
            ]
            "name": "Building Simulation",
            "zoneOutIds": 1,
            "zoneInIds": 2
          }
          ...
        ]
      }
    ]
  }

To get your live data :

query GetLiveDataExample {
  inside: getLiveKPIs(zoneId: 1, kpiName: INSIDE)
  entries: getLiveKPIs(zoneId: 1, kpiName: AFFLUENCE_IN)
}

The answer returned will look like :

{
  "data": {
    "inside": 35,
    "entries": 130
  }
}

To get your historical data :

query GetHistoricalDataExample {
  getKPIs(zoneId: 1, kpiName : AFFLUENCE_IN,granularity : DAY, dateBegin :"2023-09-20", dateEnd:"2023-09-21")
}

The answer returned will look like :

{
  "data": {
    "getKPIs": {
      "kpiName": "AFFLUENCE_IN",
      "timezone": "Europe/Zurich",
      "dateBegin": "2023-09-20",
      "dateEnd": "2023-09-21",
      "granularity": "DAY",
      "values": [
        {
          "value": 3688,
          "timestamp": "2023-09-20T00:00:00.000"
        },
        {
          "value": 3197,
          "timestamp": "2023-09-21T00:00:00.000"
        }
      ]
    }
  }
}

To get the list of available Metrics :

query GetMetrics {
  getAvailableKPIs(zoneId: 1){
    zoneId
    kpis {
      kpiName 
      descriptors
    }
  }
}

The answer returned will look like :

"data": {
    "getAvailableKPIs": {
      "zoneId": 1,
      "kpis": [
        {
          "kpiName": "AFFLUENCE_IN",
          "descriptors": {
            "genders": [
              "MALE",
              "FEMALE",
              "UNKNOWN",
              "ALL"
            ],
            "ageCategories": [
              "CHILD",
              "ADULT",
              "UNKNOWN",
              "ALL"
            ]
          }
        }
        ...
      ]
    }
}