viboo GraphQL API

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

Die viboo GraphQL API ist momentan nur für Beta-Nutzer verfügbar.

Diese Seite ist momentan nur auf Englisch verfügbar.

Introduction

viboo makes select data available to authorized customers through an industry standard GraphQL API. This short guide is intended to get users of this API up and running quickly, it is not meant as an introduction to GraphQL.

Registering

Before being able to use the API, a user needs an API key and an API secret. The key identifies the user and the secret authenticates them.

Please contact us via email to obtain your key and secret, and please make sure to keep the API secret confidential.

If you suspect your API secret has been compromised please contact us immediately.

API endpoint and interactive editor

The URL for the viboo GraphQL API endpoint is

https://api.prod.viboo.cloud/v1/graphqlapi.prod.viboo.cloud

(clicking on it will not work since GraphQL requires POST requests).

There is an interactive GraphiQL editor for experimentation at

https://api.prod.viboo.cloud/v1/graphiqlapi.prod.viboo.cloud

(clicking on it will work and is encouraged).

The examples in this guide will use this editor (referred to as GraphiQL), and are applicable by analogy to access the API with other tools or programming languages.

Authenticating

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, which means the Authorization header will have to look like

Authorization: Bearer <token>

and the authentication flow boils down to obtaining the <token> through the authenticate mutation.

The corresponding GraphQL query is

mutation authenticate {
  authenticate(input:{key: "<your API key>", secret: "<your API secret>"}) {
    apiJwtToken
  }
}

which will return a response like

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

In GraphiQL, use the returned <JWT> to create the Authorization header.

Retrieving data

Cursors and pagination

The viboo GraphQL API follows the GraphQL Cursor Connections Specification regarding pagination and result set navigation.

Data model

For more details please check the GraphiQL online documentation.

Structural data

The following query returns all units, rooms and devices the current API key can access.

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

Timeseries data

You can retrieve room, sensor and thermostat timeseries with the following queries. You do not have to specify parameter values, the default values for the parameters are as follows:

• unitIdP : all units accessible to the user

• roomIdP: all rooms accessible to the user

• deviceIds: all devices accessible to the user

• from: one hour ago

• to: now

Room timeseries

To query room timeseries you can provide a unit_id, a room_id and a time range in the from and to parameters as ISO 8601 timestamps. If you don't specify a value for any parameter, the default value documented above will be used.

query {
  roomDatapointsForTimeRange(
    unitIdP: "5"
    roomIdP: "78471871"
    from: "2025-02-01T13:45"
    to: "2025-02-06T13:45"
  ) {
    nodes {
      datetime
      unitId
      roomId
      temperatureSetpoint
      valveSetpoint
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

Sensor timeseries

Thermostat timeseries