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"
}
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:
... and new endpoints for historical samples:
Now, there is a new property in the response:
hourlyRadon - hourly average radon levelWe 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.
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.
We deprecated support for subscribing to single devices. In the future, only subscribing to locations will be supported.
For example, it is recommended to not provide devices in EXT-API endpoint POST ext-api.airthings.com/v1/webhooks:
{
"name": "webhook with locations only",
"url": "https://webhooks.airthings.com/samples",
"locations": ["...", "..."]
// Deprecated: "devices": []
}
Most clients either include all locations in an account or specific locations when configuring a webhook. The option to select specific devices included in the configuration has been available, but since it is rarely used by anyone, we made the decision to remove it.
The configuration list that previously looked like this:
Will now look like this:
This change will greatly improve the user experience when managing webhooks in an account with a high amount of buildings and devices.
Webhook Latest Event Object
The "content" field has been removed from the "mostRecentEvents" object returned from requests to webhooks-related endpoints. We identified that the field did not offer any valuable information, while it was also causing unnecessary data transfer. The latest event object now only includes the following fields:
{
"hookId": "string",
"correlationId": "string",
"url": "string",
"createdAt": "string",
"completedAt": "string",
"updatedAt": "string",
"statusCode": 0,
}
Cubic feet per minute (CFM) is now supported for segment samples history - ventilation endpoint.
Conversion is done by setting lengthUnit query parameter to ft when calling the endpoint.