The Airthings Business API now supports Gzip compression of the response payloads.

Why use compression?

As your sensor networks grow and the volume of historical data or device lists increases, API payloads can become quite large. Enabling Gzip compression can reduce the size of the data transferred by up to 80%, resulting in:

• Faster response times for your applications.
• Lower data consumption, which is particularly beneficial for high-frequency data polling applications.

How to enable Compression

To start receiving compressed data, simply add the Accept-Encoding header to your GET requests: Header: Accept-Encoding: gzip

NOTE: Most modern HTTP clients (like Axios, Python Requests, or Go’s http package) handle decompression automatically once this header is present, but make sure your client handles decompression before rolling out your changes.

🚀 Feature Release

Updating space names in batch is now possible via API. This new endpoint requires the access scope write:device. It allows 100 operations per request.

You can look at API Spec for further details.

Previously, configuring a webhook for specific locations required manual action and updates whenever a new location was added to an account. Now, you can configure webhooks to subscribe always to all locations in an account. See the sections below for more details.

Dashboard

You can configure webhooks in our dashboard at dashboard.airthings.com/integrations/webhooks:

Previously, the Select all checkbox did not account for new locations added in the future. Now, the Select all option automatically includes new locations as they are added.

API

Our API also enables webhook configuration. We have introduced a new field, subscribedToAll, which allows a webhook to subscribe to all locations. When this field is set to true, it is no longer possible to provide specific locations in the request. See our API reference for more information or see this example:

curl --request POST \
     --url 'https://ext-api.airthings.com/v1/webhooks?accountId=00000000-0000-0000-0000-0000000000' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $AUTH_TOKEN' \
     --header 'content-type: application/json' \
     --data '
{
  "active": true,
  "eventTypes": [
    "samle-feed"
  ],
  "subscribedToAll": true,
  "url": "https://webhook.site/00000000-0000-0000-0000-0000000000",
  "name": "My Webhook"
}
'

🚀 Feature Release

Updating/creating device labels in batch is now possible via API. This new endpoint requires the access scope write:device. It allows 1000 operations per request.

You can look at API Spec for further details.

🚀 Feature Release

Updating device names in batch is now possible via API. This new endpoint requires the access scope write:device. It allows 100 operations per request.

You can look at API Spec for further details.

✨ Improvements

Want to get the latest temperature samples in Fahrenheit? Or radon in pCi/L instead of Bq/m3?

measurementSystem, radonUnit, tempUnit , pressureUnit and vocUnit parameters are added to the latest-samples endpoints on Device and Location levels.

The details can be found in both /v1/devices/{serialNumber}/latest-samples and /v1/locations/{locationId}/latest-samples.

We added support for hourly radon also to webhooks known as hourly-radon-sample-feed. The sample-feed provides a 24-hour average, and sometimes it can be useful to subscribe to hourly events. The event feed is opt-in so it's necessary to update existing webhooks to use it. The value can be in Bq/m³ or pCi/L and it is possible to configure the preference in webhook configuration (using dashboard or API).

{
  "id": "00000000-0000-0000-0000-0000000000",
  "type": "airthings-webhook-cloudevent-hourly-radon-sample-feed",
  "source": "https://dashboard.airthings.com/integrations/webhooks/00000000-0000-0000-0000-0000000000",
  "dataContentType": "application/json",
  "labels": {},
  "data": [
    {
      "serialNumber": "0000000000",
      "hourlyRadon": 0.5,
      "ratings": {
        "hourlyRadon": "GOOD"
      },
      "sensorUnits": {
        "hourlyRadon": "pci"
      },
      "recorded": "2023-11-30T10:00:00Z"
    }
  ],
  "time": "2023-11-30T10:00:00.0Z",
  "specVersion": "0.2"
}

🚀 Feature Release

The "Hourly Radon" sensor is now available for the Space Plus devices, and is an improvement of the short term average data that has been the only way to interpret Radon values until now. While the radonShortTermAvg sensor provides a running average of the latest 24 hours, the hourlyRadon sensor presents data processed by an algorithm which uses the data collected from the device to estimate the current Radon level. This can be useful when controlling mitigation equipment or presenting Radon levels in buildings where the ventilation or other mitigation equipment isn't running 24/7. As the name suggests, the value is updated once an hour.

We added "hourly radon" samples to the latest-samples endpoints:

• GET /devices/{serialNumber}/latest-samples
• GET /locations/{locationId}/latest-samples

... and new endpoints for historical samples:

• GET /devices/{serialNumber}/hourly-radon-samples
• GET /segments/{segmentId}/hourly-radon-samples

Now, there is a new property in the response:

• hourlyRadon - hourly average radon level

We added a new webhook event type ventilation-sample-feed that provides samples from the ventilation rate virtual sensor. The event is triggered whenever the virtual sensor is calculated.

The data contains airflow in cubic meters per hour and number of air exchanges per hour as airExchangeRate:

{
	"id": "00000000-0000-0000-0000-0000000000",
	"type": "airthings-webhook-cloudevent-ventilation-sample-feed",
	"source": "https://dashboard.airthings.com/integrations/webhooks/00000000-0000-0000-0000-0000000000?version=v2",
	"dataContentType": "application/json",
	"labels": {},
	"data": [
		{
			"serialNumber": "0000000000",
			"recorded": "2024-07-08T20:00:00.0Z",
			"airflow": 98.93,
			"airExchangeRate": 4.46,
			"sensorUnits": {
				"airExchangeRate": "ach",
				"airflow": "m3h"
			}
		},
		// ... (next 23 samples)
	],
	"time": "2024-07-08T20:00:00.0Z",
	"specVersion": "0.2"
}

You can subscribe to this event using the dashboard or the API. See more about the event type here in the webhook documentation.

✨ Improvements

The purpose of our webhook event types is to deliver data as soon as it's generated in the Airthings platform with minimal latency and maximum performance. For this reason, the "occupancy-sample-feed" currently provides only the most recent occupancy data points. The algorithm providing the occupancy data does however calculate occupancy for the past two hours every time it runs - the reason for this being that the accuracy of the sensor improves over time when it has more data to digest. This means that webhook clients currently rely on using the API to collect the most accurate occupancy data from the history endpoint.

Since some of our webhook clients don't have an active API connection, we'd like to offer all the available data from the occupancy sensor in the webhook feed. This means that you will now receive 24 datapoints (2 hours of data with a 5 minute interval) from each device's occupancy sensor instead of 1 when subscribing to the occupancy data feed. The format of the data remains the same, with additional data objects added in the data array:

{
	"id": "fd28e5b5-a1c6-4c99-82fc-b7c73072e852",
	"type": "airthings-webhook-cloudevent-occupancy-sample-feed",
	"source": "https://dashboard.airthings.com/integrations/webhooks/3ae27258-314e-41ae-98ca-ae1702eea68d?version=v2",
	"dataContentType": "application/json",
	"labels": {},
	"data": [
		{
			"serialNumber": "2969000446",
			"recorded": "2023-07-06T07:15",
			"occupants": 2,
			"occupantsUpper": 4,
			"occupantsLower": 0,
			"sensorUnits": {
				"occupants": "occ"
			}
		}
	],
	"time": "2023-07-06T07:19:36.632024",
	"specVersion": "0.2"
}

{
	"id": "fd28e5b5-a1c6-4c99-82fc-b7c73072e852",
	"type": "airthings-webhook-cloudevent-occupancy-sample-feed",
	"source": "https://dashboard.airthings.com/integrations/webhooks/3ae27258-314e-41ae-98ca-ae1702eea68d?version=v2",
	"dataContentType": "application/json",
	"labels": {},
	"data": [
		{
			"serialNumber": "2969000446",
			"recorded": "2023-07-06T07:15",
			"occupants": 2,
			"occupantsUpper": 4,
			"occupantsLower": 0,
			"sensorUnits": {
				"occupants": "occ"
			}
		},
		{
			"serialNumber": "2969000446",
			"recorded": "2023-07-06T07:20",
			"occupants": 2,
			"occupantsUpper": 4,
			"occupantsLower": 0,
			"sensorUnits": {
				"occupants": "occ"
			}
		},
		{
			"serialNumber": "2969000446",
			"recorded": "2023-07-06T07:25",
			"occupants": 2,
			"occupantsUpper": 4,
			"occupantsLower": 0,
			"sensorUnits": {
				"occupants": "occ"
			}
		},
    // ... (next 21 objects)
	],
	"time": "2023-07-06T07:19:36.632024",
	"specVersion": "0.2"
}

"occupantsUpper" and "occupantsLower" data points will still only be available if room size information has been added to the space containing the device.