API-Schnittstelle

Diese Seite erklärt, wie man Zugriff auf die Zeitreihendaten Ihres Gebäudes über die viboo GraphQL API erhält.

Introduction

viboo makes select data available to authorized customers through an industry standard GraphQL API.

API endpoint and interactive editor

The API is available at https://api.viboo.cloud/v1/graphql. Paste the URL into your browser to read data from the API with the free and easy-to-use GraphiQL editor.

You can also use this URL to access the API through tools such as Python code, Grafana and Excel Power Query.

Authenticating

To use the API, you must first create a JWT token. In the GraphiQL editor, paste the code below into the query area:

mutation authenticate {
  authenticate(input:{key: "<your email address>", secret: "<your viboo.cloud password>"}) {
    apiJwtToken
  }
}

It will return a response like:

{
  "data": {
    "authenticate": {
      "apiJwtToken": "<JWT>"
    }
  }
}

In GraphiQL, use the returned <JWT> token to create the Authorization header. Keep this header for the rest of your queries.

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

The screenshot below summarizes the steps you should take to authenticate:

Authentication process in GraphiQL visualized step-by-step.

All requests to the API (except authenticate) must include a valid HTTP Authorization header in order to be accepted by the server.

This API uses JWT for authorization.

Retrieving data

You can retrieve data from the API by pasting the queries below into the GraphiQL interface.

First, retrieve the metadata. This will tell you which devices are in which room and which rooms are in which unit. It will also give you the unit name, room name, device type and device name that belongs to each ID.

Next, retreive the timeseries data. These data contain the measurements from thermostats and sensors, as well as the temperature setpoint data on room level.

Metadata

This query will give you all units, rooms and devices that you can access with your API key.

{
  allUnits {
    nodes {
      unitId
      unitName
      roomsByUnitId {
        nodes {
          roomId
          roomName
          devicesByUnitIdAndRoomId {
            nodes {
              deviceId
              deviceType
              deviceName
              deviceStatus
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

Room timeseries

Sensor timeseries

Thermostat timeseries

Paste the query into the query area in GraphiQL and press "Run". Your data will appear on the right.

Loading the data into Microsoft Excel

The video below shows how to load your metadata into Excel. For the timeseries data, the process is the same.

Data model

If you want more info, here is an overview of our data model: