✨ 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.
🚀 Feature Release
Locations included in a webhook can now be updated using the API. This new endpoint requires the access scope write:device.
The endpoint is created using the PATCH method, applying the concept from this RFC allowing the user to perform multiple operations on a resource.
The endpoint at this stage only takes the locations path.
Note that we do not allow adding an empty location to the webhook, therefore, a device must be added to a location before it can be added to the webhook.
To edit locations on a webhook, use the following endpoint with the example request body:
PATCH /webhooks/{webhookId}?organizationId={organizationId}
{
"operations": [
// Add location to a webhook
{
"op": "ADD",
"path": "locations",
"value": [
"69cbabbf-74a3-47c9-8c23-0ec8b59e886b",
"1ddc4b5a-ca8c-4ac3-93a4-e7c6d418549c",
"0f6f41fb-42a1-4aaa-8337-fb642176e136",
"8e40dff9-98c3-4bf4-9aa8-dfe76c2652c6"
]
},
// Remove certain locations from a webhook
{
"op": "REMOVE",
"path": "locations",
"value": [
"337d2956-8ba4-45c1-9ae1-50a2a1a46f69",
"580c4513-20e4-4d4e-b842-79aa5c053442"
]
},
// Remove all locations from a webhook
{
"op": "REMOVE",
"path": "locations"
}
]
}
✨ Improvements
Battery is reported to the cloud per each sample. The battery level of a device however does not change that often.
We are therefore updating the API to only provide battery samples when there is a change in battery level.
The response format will remain the same.
GET /v1/devices/{serialNumber}/battery
GET /v1/devices/{serialNumber}/latest-battery
🚀 Feature Release
Locations can now be added using the API. This new endpoint requires the access scope write:device.
The lat and lng variables are required on this endpoint to determine whether the radio frequency of the location is supported by Airthings.
Metadata fields such as buildingType, ventilationType, floors, etc. are optional. However, providing metadata information about the location will result in more accurate insights. Note that measurement system used by this endpoint is METRIC.
To add a location, use POST /locations?organizationId={organizationId} with the following example request body:
{
"name": "My location",
"lat": 59.918899,
"lng": 10.7296083,
"address": "Wergelandsveien 7, 0167 Oslo",
"buildingType": "OFFICE",
"ventilationType": "BALANCED",
"floors": 11,
"timezone": "Europe/Oslo",
"buildingYear": 1950,
"buildingHeight": 35.74,
"buildingSize": 10000,
"buildingVolume": 22333.8,
"usageHours": {
"monday": {
"from": "07:00",
"to": "17:00",
"closed": false
},
"tuesday": {
"from": "07:00",
"to": "17:00",
"closed": false
},
"wednesday": {
"from": "07:30",
"to": "17:00",
"closed": false
},
"thursday": {
"from": "07:00",
"to": "17:00",
"closed": false
},
"friday": {
"from": "09:00",
"to": "16:00",
"closed": false
},
"saturday": {
"closed": true
},
"sunday": {
"closed": true
}
}
}
✨ Improvements
Added missing required text on organizationId in some webhooks endpoints
🚀 Feature Release
Webhooks can now be created and retrieved using the API.
To create a webhook, use POST /webhooks?organizationId={{organization_id}} with the following example request body:
{
"name": "My webhook",
"url": "https://myurl.com",
"labels": {"key": "value"},
"headers": { "key": "value" },
"measurementSystem": "METRIC/US",
"devices": ["293000000"],
"locations": ["0aaac9e8-c26b-4141-9177-1105b65736ae"],
"active": true
}
{
"name": "My webhook",
"url": "https://myurl.com",
"labels": { "key": "value" },
"headers": { "key": "value" },
"measurementSystem": "METRIC/US",
"locations": [
{
"id": "591df93d-ec4e-4780-959c-e8c474e29d7a",
"name": "Oslo",
"labels": {}
}
],
"devices": [
{
"id": "293000000",
"deviceType": "WAVE_PLUS",
"sensors": ["temp"],
"segment": {
"id": "017dd064-0ccd-4902-825e-32e7960edd73",
"name": "Device name",
"started": "2021-06-03T15:18:56",
"active": true
}
}
],
"active": true,
"eventTypes": [
"hub-meta-data-feed",
"mold-sample-feed",
"sample-feed",
"virus-risk-sample-feed"
]
}
Note that except name and url, all other parameters in the request body are optional.
See Webhooks for more information.
Use GET /webhooks?organizationId={{organization_id}} to fetch your list of webhooks.
🚀 Feature Release
"Add device" endpoint is now available. This allows you to automate the process by calling the API instead of adding the devices manually in the dashboard.
This new endpoint requires the new access scope write:device. To use this, make sure your API client is configured with this scope in the dashboard, and use the scope accordingly in the token endpoint as described in the API documentation.
Use POST /location/{locationId}/devices?organizationId={{organization_id}} with the body:
{
"serialNumber": "2930012345",
"id": "QWERTYU",
"name": "Office"
}
Note that while we are using the id property here as the id on the back of the device, id is not always used to describe this. For instance, on the GET endpoints the id might be used as the serial number.