✨ Improvements

accountId is added in replacement for userGroupId in query parameter of all endpoints.
Consider using accountId instead of userGroupId in your requests.

✨ Improvements

We are introducing the concept of "accounts" in place of "organizations" and "user groups" to make it simpler for clients to access our data.

As part of this update, a new endpoint is added for users to get their accounts information. The payload contains account ID and name:

GET /accounts

{
  "id": "95cf8d10-fd0d-47c4-bb48-11c01e36060e",
  "name": "An account"
}

✨ Improvements

sensorUnits is now removed from the request to create webhook.

We are in progress of improving the usage of sensor units in our webhook service. This field is therefore temporary removed from the request for creating webhook and will be added again in a future release.

✨ Improvements

There's a limit to the size of a response from our API, so to avoid breaking that limit, we've added pagination to the /devices endpoint.

The limit to number of devices returned from the request can be defined by using the limit parameter, with a maximum of 5 000 devices per page. If the parameter is not set, and there are more than 5 000 devices in the account, the API will provide a 400 Bad Request response and let you know that pagination should be used for the request.

The response from the /devices endpoint with pagination enabled will return the offset used to retrieve the next page, as well as the total amount of devices in the account.

Example response from GET /devices?limit=1&offset=50 :

{
    "devices": [
        {
            "id": "2930000000",
            "deviceType": "WAVE_PLUS",
            "sensors": [
                "radonShortTermAvg",
                "temp",
                "humidity",
                "pressure",
                "co2",
                "voc",
                "light",
                "virusRisk"
            ],
            "segment": {
                "id": "00000000-0000-0000-0000-0000000000",
                "name": "Device Name",
                "started": "2021-07-09T14:00:06",
                "active": true
            },
            "location": {
                "id": "00000000-0000-0000-0000-0000000000",
                "name": "Location Name"
            }
        }
    ],
    "limit": 1,
    "offset": 51,
    "total": 554
}

✨ Improvements

The response from the /devices and /segments endpoints can be used to identify when devices have been added or removed from accounts, but for accounts with a lot of registered devices, the response from these endpoints can become quite large. Parameters have been added to both these endpoints to help reduce the size of the response in case they are being used for this purpose.

segmentStartedAfter has been added as a parameter to the /devices and /segments endpoints, and will return all devices/segments registered/started after the specified time.

segmentEndedAfter has been added as a parameter to the /segment endpoint, and will return all segments ended after the specified time.

🚀 Feature release

Released the MQTT service as an integration option to complement our already existing RESTful API and Webhooks. Head over to the MQTT documentation to learn how you can get started setting up your MQTT client and subscribe to Airthings data.

✨ Improvements

"Add location" endpoint now allows adding locations with the same latitude and longitude. However, location with the same name will not be allowed, following the same design as our dashboard.

✨ Improvements

Add device endpoint now requires either organizationId or userGroupId query params.

✨ Improvements

Get location endpoint now returns more information.

GET /locations/{locationId}

{
    "id": "00000000-0000-0000-0000-0000000000",
    "name": "Office",
    "labels": {},
    "devices": [
        {
            "id": "2920000000",
            "deviceType": "WAVE_MINI",
            "segment": {
                "id": "00000000-0000-0000-0000-0000000000",
                "name": "Mini",
                "started": "2019-03-13T13:37:37",
                "active": true
            }
        },
        {
            "id": "2920001111",
            "deviceType": "WAVE_MINI",
            "segment": {
                "id": "00000000-0000-0000-0000-0000000001",
                "name": "Mini reception",
                "started": "2019-03-13T13:37:37",
                "active": true
            }
        },
        {
            "id": "2820002222",
            "deviceType": "HUB",
            "segment": {
                "id": "00000000-0000-0000-0000-0000000002",
                "name": "TestHub",
                "started": "2021-12-07T12:43:41",
                "active": true
            }
        }
    ],
    "address": "Oslo, Norway",
    "countryCode": "NO",
    "lat": 59.913868,
    "lng": 10.752245,
    "buildingType": "Office",
    "buildingYear": 2000,
    "ventilationType": "Balanced",
    "timezone": "Europe/Oslo",
    "usageHours": {
        "friday": {
            "closed": false,
            "from": "07:00",
            "to": "17:00"
        },
        "monday": {
            "closed": false,
            "from": "07:00",
            "to": "17:00"
        },
        "saturday": {
            "closed": true
        },
        "sunday": {
            "closed": true
        },
        "thursday": {
            "closed": false,
            "from": "08:00",
            "to": "17:00"
        },
        "tuesday": {
            "closed": false,
            "from": "07:00",
            "to": "17:00"
        },
        "wednesday": {
            "closed": false,
            "from": "07:00",
            "to": "20:00"
        }
    },
    "buildingHeight": 5.0,
    "buildingSize": 190.0,
    "buildingVolume": 907986.0,
    "floors": 2
}

✨ Improvements

As part of our goal to deliver a better experience for API clients, sensorUnits is now available alongside measurementSystem in our Webhook endpoints.

Please note that we will start the process of adding sensorUnits to all endpoints that are currently using measurementSystem, and will start removing measurementSystem from our API endpoints shortly after. We will notify you before the removal process take place.