Key Concepts

Authorization

All requests must include a valid API key in the x-api-key request header in order to be successfully authorized. See the Getting Started page for info on how to obtain an API key if you have not already done so.

Pagination

When making queries to endpoints which return a list of results, the results may be broken up into smaller "pages" rather than returning all data at once, since it may contain too many objects to be returned in a single response. The API uses Cursor-based Pagination in order to return a collection of data in smaller chunks.

The basic structure of endpoints that return a list of results is always the same:

{
    "data": [
        // ...Endpoint data is here
    ],
    "paging": {
        "cursors": {
            "after": "MTAxNTExOTQ1MjAwNzI5NDE="
        },
        "next": "url_to_fetch_next_page"
    }
}

A cursor refers to a random string of characters which marks a specific item in a list of data. The cursor will always point to the item, however it will be invalidated if the item is deleted or removed. Therefore, your app shouldn't store cursors or assume that they will be valid in the future.

The paging object(if included in the response) contains the following fields:

• cursors.after: This is the cursor that points to the end of the page of data that has been returned.
• next: The url of the API endpoint that will return the next page of data.

The API will always return a data list in responses, if no paging object is returned in the response, it means all the items in the list have been returned and there are no more pages to fetch.

The cursors.after string can be passed in as the cursor_after query parameter in requests to fetch the next page of data, or alternatively the next url can be called directly which already contains all the correct query parameters pre-filled to fetch the next page of data.

Rate Limiting

In order to prevent a single client from overloading the server with API requests, a rate limiter is enforced. The details of the rate limits that are applied by the server are subject to change as deemed necessary. If a client sends request beyond the allocated rate limit, a HTTP 429 - Too Many Requests response will be returned.

If your use case requires making many requests in a relatively short period of time, it is recommended to add a small wait interval in between sequential requests to avoid running into the rate limits.

The response headers of API requests include information about the rate limiting policy and the currently remaining quota as detailed in the table below:

header	description
RateLimit-Limit	containing the allowed requests quota
RateLimit-Remaining	containing the remaining requests quota in the current window
RateLimit-Reset	containing the time remaining in the current window, specified in seconds
RateLimit-Policy	A combined form of the RateLimit-Limit and RateLimit-Reset fields: request-quota; "w" "=" time-window. for example: 200;w=300

Measurement queries

Measurements for a given period can be queried 2 in ways: absolute or relative time window:

Absolute time window

Measurements can be queried for a specific period of time in the past. When a request is made for measurements data, the from and to query parameters must be provided. These parameters must be a valid ISO 8601 date string, for example: 2024-02-15T12:00:00.

Relative time window

Alternatively, measurements can be queried for a relative period in the past. In this case, the from and to query parameters should not be provided, and the previous query parameter should be used instead. This parameter accepts a duration string in the form integer[M, w, d, h] where valid duration units are :

• M: Months
• w: Weeks
• d: Days
• h: Hours

For example:

• 1d to retrieve the measurements of yesterday.
• 2w to retrieve the measurements of the previous two calendar weeks.
• 3M to retrieve the measurements of the previous three calendar months.
• 4h to retrieve the measurements of the previous four hours.

Additionally, -now can be added to the end of the parameter string, and when present the query will include measurement data up until the moment that the query is performed, for example:

• 1d-now to retrieve the measurements from yesterday up to now.
• 2w-now to retrieve the measurements from the previous two calendar weeks up to now.

Timezone

The API will assume that these parameters are in the timezone of the site, as it is configured in the webclient. Measurement time series data will be returned with ISO 8601 timestamps formatted in the site timezone, for example: 2024-02-15T12:00:00+02:00 if the site is in a timezone which is 2 hours ahead of UTC.

If preferred, you can specify a different timezone by including the optional timezone query parameter, for example: timezone=UTC. When this optional query parameter is provided, the API will treat the from and to query parameters, as well as the response data timestamps as being in the specified timezone.

Query aggregation

When querying measurement data an aggregation level must also be specified for the query. The aggregation level parameter consists of 2 parts: [amount][unit]. Each measurements endpoint specifies its valid options in its OpenAPI specification, for example: 1m (1 minute), 12h (12 hours), 5d (5 days), etc.

The aggregation method which gets applied differs depending on the type of measurements that are being queried. These aggregation methods are described in the tables below for each measurement type.

In order to prevent queries requesting too much data in a single request, the API enforces constraints on the aggregation level that the measurement data can be requested at based on the size of the time window(from -> to) of the request. These constraints are different per measurement type, and are shown in the tables below.

Electricity

query period	minimum aggregation level
> 1 day	15m
> 1 week	1h
> 5 weeks	1d
> 1 year	1w

Aggregation method:

• power: Average of the measured power values.
• energy: Sum of the measured energy values.

Water

query period	minimum aggregation level
> 1 day	15m
> 1 week	1h
> 5 weeks	1d
> 1 year	1d

Aggregation method:

• volume: Sum of the measured values
• flow: Average of the measured power values
• inlet temperature: Average of the measured power values
• outlet temperature: Average of the measured power values
• temperature difference: Average of the measured power values
• thermal energy: Sum of the measured power values

Gas

query period	minimum aggregation level
> 1 day	15m
> 1 week	1h
> 5 weeks	1d
> 1 year	1d

Aggregation method:

• energy: Sum of the measured energy values.
• power: Average of the measured power values.
• volume: Sum of the measured volume values.

Air - Flow, Temperature, and Pressure

query period	minimum aggregation level
> 1 day	15m
> 1 week	1h
> 5 weeks	1d
> 1 year	1d

Aggregation method:

• flow: Average of the flow measurements
• temperature: Average of the temperature measurements
• presssure: Average of the pressure measurements

Air - Volume

query period	minimum aggregation level
minimum	1h
> 2 days	1d
> 2 weeks	1w
> 1 year	1w

Aggregation method: Sum of the measured volume values.

Maintenance

query period	minimum aggregation level
> 1 day	1h
> 5 weeks	1d
> 26 weeks	1w

Aggregation method: The 95th percentile is calculated per aggregation interval. This removes rare peaks in the data series from the aggregated values.

Auto aggregation level

Most measurement endpoints also have an auto aggregation option. When querying measurement data with the auto aggregation level selected, the API will automatically select the best available aggregation level based on the query period.

API Response Codes

If the API request was handled successfully, a 2xx http response code will be returned along with the requested data. If there was an error processing the request, a 4xx or 5xx http response code will be returned, as well as a response body containing an error type code and message. The following errors may be returned by the API:

• 400 - INVALID_REQUEST_PARAMETERS: The query parameters sent to the endpoint did not pass validation. See the OpenAPI Docs of the related endpoint for info about valid query parameters.
• 403 - UNAUTHORIZED: Request is unauthorized, due to invalid or missing API key in the request headers.
• 404 - ENTITY_NOT_FOUND: The requested entity was not found in the database.
• 429: Rate limit exceeded. Too many requests were sent in a short period of time, see the Rate Limiting section for more info.
• 500 - INTERNAL_ERROR: An error occured on the server while trying to process the request, please contact us if the problem persists.