REST API - GET Sensor Values
- Julie Isebaert
Difficulty: expert
Content
Learning Objectives
After reading this article, you’ll be able to:
use GET Sensor Values API in Workplace
This page provides more information about the GET Sensor Values API, which allows you to export the sensor values that are stored in Workplace for your devices.
For more information about Workplace APIs in general (best practices on how to reach out, test, validate and troubleshoot APIs), see Rest API.
GET Sensor Values API presents 3 fields in order to specify which data you want to retrieve: Device ID, From- and To-Date/Time fields.
This page contains some tips & tricks on how to best work with these fields.
From-To Date/Time fields
Provide specific date-time information following ISO 8601 format (for example: 2025-02-16T10:00:00+01:00) to get concrete data for that time frame
Fill in “latest” in the From field and leave To field empty to just get the latest value that is available in the Workplace database
This API cannot return range greater than one day, so limit the time span between From-To request to max 24 hours
Device ID field
In Device ID field, provide Device ID following the format “prefix|Device ID|suffix”, which refers to
the original source of the data (before it came into Workplace),
the unique device identifier as it’s known in the Workplace database and
the exact sensor type that you want to receive data for.
As there are many components and potential deviations in using the GET SensorValues API, make sure to test at least 1 device ID in the Workplace API Test to validate your request.
Prefix
The prefix refers to the original source of the data (before it came into Workplace):
for all Spacewell LoRa devices, use “tracknet” (see LoRa Sensors and Gateways | Spacewell LoRa devices)
for proprietary devices like Pointgrab, VergeSense, Xovis, Signify etc, use this vendor name (“pointgrab”, “vergesense”, “xovis”, “signify”)
for devices for which data is populated through Generic Endpoint, use Device Type ID as configured in the Custom Device Type (see Custom Device Types | General), usually preceded by “generic|”.
Device ID
The Device ID refers to the unique device identifier as it’s known in the Workplace database. In most cases, this is the Device ID that is mentioned in the Studio Device Overview (and Device Export). Yet sometimes it’s different, which is why we suggest to always check the device ID that is mentioned in the Studio Device Label URL (see Sensor Management | Device Info).
As a rule, we can state that if Studio shows a device ID that adheres to one of the next categories, then it’s best to check the URL of the device:
if device ID in Studio Device Overview contains pipe (|) or colon (:)
if the device data comes in through Generic Endpoint (see External Data Sources)
Depending on the browser, you can immediately verify the prefix+device ID to use in the GET API request with what is listed in the URL behind “https://studio.cobundu.com/…/devices/” or the browser might encode the pipe character as “%7C” and then you’ll need to work or read around it.
In this example, we’re looking at a VergeSense device, which in the Studio Device Overview (and Device Export) is listed with Device ID “spacewell|Spacewell-Arnhem|Floor 1|1.01”.
This “pretty” device ID is constructed by Workplace based on the information that is provided by VergeSense. But the real device ID as it’s known by the Workplace Database is different if we check the URL in the Device Label (see Sensor Management | Device Info).
In the URL, we see that the Database Device ID is “B6B662F080F2FEA967F903B8A3D8807B”.
In the above screenshot, you might have noticed that the URL behind “https://studio.cobundu.com/…/devices/” reads “vergesense|B6B662F080F2FEA967F903B8A3D8807B”. This indeed is the prefix & device ID as we need them in the GET Sensor Values API.
Unfortunately, not every Browser uses the pipe character, as you can see below:
Check out https://en.wikipedia.org/wiki/Percent-encoding for more details on proper encoding of special characters.
Suffix
Use the suffix part of your request to specify for which exact sensor type you want to receive data. If you have a comfort sensor and want to fetch the data for humidity and temperature, then you will have to send 2 requests to the API: one for “prefix|Device ID|humidity” and one for “prefix|Device ID|temperature”.
Use this table to define the suffix for your request:
Sensor Type enabled in Workplace | suffix to use in SensorValues API |
|---|---|
Temperature | temperature |
CO2 | co2 |
Humidity | humidity |
VOC | voc |
Light % | light-pct |
Radon | radon |
Pressure | pressure |
Presence | pir |
Headcount | headcount |
Footfall (in) | in |
Footfall (out) | out |
Pulse | door |
Battery | battery |
If you’re unsure which Sensor Type is enabled in Workplace for your sensor, check Devices Overview or Devices Advanced Export (see Sensor Management | General). Also the Device Label screen provides information about the enabled sensors for this device.
Examples
Troubleshooting
Check out the best practices highlighted in Rest API | How to use Workplace API
Search