Skip to content

Retrieving data from the platform

Info

The following examples use version 2 of the Obelisk HTTP API (recommended)

Prerequisites

Any registered client can become a consumer of the Obelisk Query APIs regardless of the authentication method (client on behalf of the user or client as itself, see Security). However, there are two prerequisites before queries can be executed:

  1. A Scope must be defined for the project or experiment that "owns" the values to be queried (see also Scopes explained)
  2. The client used for submitting the queries must be assigned the appropriate (read) access rights for this Scope. Contact a system administrator or project manager to acquire these rights (see Request access).

Meta data

The Obelisk HTTP API provides a range of endpoints for querying metadata information for Scopes, available Things and Metrics. This metadata allows applications to (automatically) discover what types of sensor / event data can be queried and where it is available. The following example explains a metadata query for a typical use case. For more information on metadata queries we refer to the Swagger UI.

Example: Get metadata for all the Things that produce data for a specific Metric
Say we need to retrieve the ids of all the Things that produce data for a Metric with id airquality.pm10.ref::number in a Scope called dencity. For the purpose of this example, we will limit the returned results to a maximum of 5.

HTTP Request:

1
2
GET /api/v2/scopes/dencity/things
    ?fields=id,metrics=airquality.pm10.ref::number&limit=5

Tip

Don't forget to authorize the request by setting the appropiate request header:

Authorization: Bearer <your token>

HTTP Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "data": [
    {
      "id": "VMM_40AL01_Linkeroever"
    },
    {
      "id": "VMM_40AL02_Beveren"
    },
    {
      "id": "VMM_40AL03_Beveren"
    },
    {
      "id": "VMM_40AL04_Beveren"
    },
    {
      "id": "VMM_40AL05_Beveren"
    }
  ],
  "pagination": {
    "hasNextPage": true,
    "nextCursor": "NQ=="
  }
}

All Obelisk HTTP Responses for Collection Metadata Operations (/scopes, ../things, ../metrics) will consistently return a JSON Object containing two top-level attributes:

  1. data: A JSON Array of JSON Objects containing the requested data.
  2. pagination: A JSON Object used for pagination. It indicates whether the request can be repeated (if hasNextPage: true) by providing the String contained in the optional nextCursor attribute to get additional results for the query.

Info

The Obelisk v2 API always applies pagination to protect the system against queries that would return an unreasonably large resultset.

Example: retrieving the next page
Say we want to retrieve all Thing ids for the specified Metric, we can continue by executing the following request:

HTTP Request:

1
2
GET /api/v2/scopes/dencity/things
    ?fields=id,metrics=airquality.pm10.ref::number&limit=5&cursor=NQ==

Notice that the request is identical to the original request, but we add a query parameter cursor set to the value of the nextCursor contained in the previous response.

HTTP Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "data": [
    {
      "id": "VMM_40HB23_Hoboken"
    },
    {
      "id": "VMM_40SA04_Hoevenen"
    },
    {
      "id": "VMM_42M802_Antwerpen"
    },
    {
      "id": "VMM_42R801_Borgerhout"
    },
    {
      "id": "VMM_42R802_Borgerhout"
    }
  ],
  "pagination": {
    "hasNextPage": true,
    "nextCursor": "MTA="
  }
}

We can continue getting additional pages until pagination.hasNextPage: false (this is the end condition for the paging loop).

Event data

One of the core features of Obelisk is retreiving raw and statistical data for measurements that were registered with the platform. The two main data query endpoints (../events and ../stats) are the most powerful operations in the HTTP API, but are also the most complex in terms of number of parameters and available options. Fortunately, most of the parameters are optional. The following example gives an example of how the stats operation can be leveraged for a typical use case. For more complete information we refer to the Swagger UI.

Example: Get average values in the last hour for a Metric in 10 minute intervals
Say we want to display a graph showing the evolution of the average value for a Metric power::number in a Scope called office-lab for the last hour in 10 minute intervals. After first calculating the timestamp in milliseconds (which in this case was 1561633200000) from which the stats should be calculated, the following request can be submitted:

HTTP Request:

1
2
GET /api/v2/scopes/office-lab/metrics/power::number/stats
    ?fields=mean&from=1561633200000&groupByTime=10m

Note

Notice that the query parameter fields that we used for the metadata query can also be used here to select the mean attribute containing the average value. We tried to introduce a maximum level of consistency throughout the various endpoints in order to reduce the learning curve.

HTTP Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
  "data": {
    "columns": [
      "time",
      "mean"
    ],
    "values": [
      [
        1561633200000,
        10.273684210526316
      ],
      [
        1561633800000,
        9.941666666666666
      ],
      [
        1561634400000,
        10.25
      ],
      [
        1561635000000,
        10.233333333333333
      ],
      [
        1561635600000,
        10.16
      ],
      [
        1561636200000,
        10.238493723849372
      ],
      [
        1561636800000,
        10.040345821325648
      ]
    ]
  },
  "pagination": {
    "hasNextPage": false
  }
}

The response is also structured in a similar way to the Metada query. It has a data attribute that describes which columns are returned and contains the returned values. The pagination JSON Object type is identical for all our Operations, but this time the resultset is complete and there is no next page available.