Measurements
GET {baseUrl}/measurements
Returns a list of measurements in time descending order.
Example
https://clarity-data-api.clarity.io/v1/measurements?code=A000001&limit=1000
Headers
parameter | description | |
---|---|---|
x-api-key |
string | The API key string. |
Accept-Encoding |
string | Encoding options, gzip is supported to compress data. Note: We strongly recommend to include it in the headers to reduce response payload size. Example: Accept-Encoding: gzip |
Request
You can request measurements by device id, device code, or datasource id. Specify only one of these parameters. If more than one is provided, only one will be used.
parameter | description | |
---|---|---|
device |
string | The long device ID(s) to filter on. Use comma separated strings to query multiple devices. Measurements will only be returned for devices specified. Example: device=5cf56f698bfb2c5f878ff8ad,5cf56f698bfb2c5f878ff8ae will only return measurements for the two devices |
code |
string | The short device ID(s) to filter on. The code is a short ID that's labeled on the physical device, usually starting with "A". Use comma separated string to query multiple devices. Example: code=AHYGZ6WT,AYQR5N87 will only return measurements for the two devices. |
datasourceId |
string | A single datasource id to filter on. Measurements will only be returned for the datasource specified. |
And then add these parameters
additional parameter | description | |
---|---|---|
outputFrequency |
string | The output frequency of the aggregations to return in the measurement. One of minute (default), hour or day are supported. Example1: outputFrequency=minute returns highest resolution measurements, with no aggregation applied.Example2: outputFrequency=hour returns 1-Hour Mean, 24-Hour Rolling Mean and NowCast aggregations, and AQIs which are calculated on these aggregations as per their standard.Example3: outputFrequency=day returns 24-Hour Mean aggregations, and AQIs which are calculated on these aggregations as per their standard. |
average |
string | Equivalent to outputFrequency . Will be dropped in the next version. |
startTime |
string | Timestamp of earliest measurement desired. If provided, all measurements with time earlier than startTime will be filtered out. Date string is expected to be in ISO 8601 format. Example: startTime=2019-01-01T00:00:00Z |
endTime |
string | Timestamp of the most recent measurement desired. If provided, all measurements with time later than endTime will be filtered out. Date string is expected to be in ISO 8601 format. Default: UTC current time. Example: endTime=2019-01-02T00:00:00Z |
skip |
integer | The number of records to skip. Can be used together with limit for pagination. Default: 0 Example: skip=5 |
limit |
integer | The maximum number of measurements to be returned.
limit=100 |
aqi |
string | Note: We strongly recommend not to use this feature as the output does not comply with AQI standards. The feature will be dropped in the next version. Use comma separated string to calculate AQI for multiple pollutants. Currently, only pm2_5ConcMass and no2Conc are supported. The requested AQIs are found in the resulting measurements, nested in the specified characteristic. AQI calculation uses US EPA specified breakpoints but is performed regardless of the aggregation applied to the measurements, thus it does not conform to the standard. Standard AQIs are found in the measurements as separate characteristics and will always be returned when available. Please use those.Example: aqi=pm2_5ConcMass,no2Conc |
Response
Structure
List of Measurements. Measurements are sorted by time from latest to earliest. The measurements returned start from endTime
and go backwards in time until either startTime
or limit
is reached. A Measurement is composed of multiple characteristics, all with the same reporting time, coming from the same device, and with the same output frequency.
attribute | description | |
---|---|---|
_id |
string | The ID of the measurement. It is not guaranteed to be unique among all measurements. Therefore, we do not recommend using it. |
recId |
string | The unique ID of the measurement. |
device |
string | The long ID of the device that produced the Measurement Example: "5cf56f698bfb2c5f878ff8ad" |
deviceCode |
string | The short ID of the device that produced the Measurement, usually starting with "A". Example: "AHYGZ6WT" |
time |
string | The measurement reporting time. Example1: outputFrequency=minute → the time at which the measurement was acquired → 2021-10-12T02:11:05.860Z Example2: outputFrequency=hour → the start of the hour at the end of which the aggregation is calculated
outputFrequency=day → the start of the day at the end of which the aggregation is calculated
|
outputFrequency |
string | The requested output frequency Example: "hour" |
average |
string | Same as outputFrequency . Will be dropped in the next version |
datasourceType |
string | Currently, always equals CLARITY_NODE |
location |
GeoJSON object | The location at which the measurement was taken Example: See below |
characteristics |
object | Nested object of multiple characteristics See characteristics section |
Example GeoJSON object
"location": {
"coordinates": [
-122.2687187, // longitude
37.8712728 // latitude
],
"type": "Point"
}
Characteristics
Characteristics are pollutants and other qualities we measure
Characteristics that may be returned in a measurement
These characteristics are guaranteed to be provided:
- PM2.5 Mass Concentration
- PM2.5 Number Concentration
- Relative Humidity
- Temperature
Additional characteristics are provided based on device version, output frequency requested, and presence of add-on modules connected to devices. More characteristics may be added later.
characteristic | description for outputFrequency = |
units |
---|---|---|
relHumid |
Relative Humidity Internal
|
% |
temperature |
Temperature Internal
|
°C |
pm2_5ConcMass |
PM2.5 Mass Concentration
|
μg/m3 |
pm2_5ConcNum |
PM2.5 Number Concentration
|
#/cm3 |
pm2_5ConcMass_NowCast |
|
μg/m3 |
pm2_5NowCastAqi |
|
|
pm2_5ConcMass_24HourRollingMean |
|
μg/m3 |
pm2_5ConcNum_24HourRollingMean |
|
#/cm3 |
pm2_5WaDwerAqi |
|
|
pm2_5UsEpaAqi |
|
|
pm1ConcMass |
PM1 Mass Concentration
|
μg/m3 |
pm1ConcNum |
PM1 Number Concentration
|
#/cm3 |
pm10ConcMass |
PM10 Mass Concentration
|
μg/m3 |
pm10ConcNum |
PM10 Number Concentration
|
#/cm3 |
pm10ConcMass_24HourRollingMean |
|
μg/m3 |
pm10ConcNum_24HourRollingMean |
|
#/cm3 |
pm10WaDwerAqi |
|
|
pm10UsEpaAqi |
|
|
no2Conc |
NO2 Concentration
|
ppb |
no2UsEpaAqi |
|
|
no2WaDwerAqi |
|
|
windSpeed |
Wind Speed
|
m/s |
windDirection |
Wind Direction
|
compass degrees N=0° E=90° S=180° W=270° |
o3Conc |
O3 Concentration
|
ppb |
o3WaDwerAqi |
|
Content of a characteristic
Currently, only value
is guaranteed to be present
key | description |
---|---|
value |
The value of the characteristic. It equals calibratedValue If calibratedValue is available, otherwise it equals raw. |
calibratedValue |
The calibrated value of the characteristic. |
raw |
The raw value of the characteristic. |
weight |
The number of Measurements used to derive the above values by aggregation. |
aqi |
The non-standard AQI based on the characteristic. Calculated regardless of the aggregation applied. Note: We suggest not to use it. It will be dropped in the next version. |
Example 200 Response
Request:
https://clarity-data-api.clarity.io/v1//measurements?average=hour&code=AS49Z5V6&limit=1
Response:
[
{
"_id": "6176731bd3e709d1002c9cdc",
"device": "5cd35291d99ad500015acb78",
"deviceCode": "AS49Z5V6",
"time": "2021-10-25T08:00:00.000Z",
"location": {
"coordinates": [
-0.31987555,
51.45527
],
"type": "Point"
},
"recId": "averaged:AY72DXZF:hour:2021-10-25T09:00:00",
"characteristics": {
"relHumid": {
"value": 84.64,
"weight": 8,
"raw": 84.64
},
"temperature": {
"value": 13.98,
"weight": 8,
"raw": 13.98
},
"pm2_5ConcNum": {
"value": 5.17,
"weight": 8,
"raw": 5.17
},
"pm2_5ConcMass": {
"value": 3.22,
"weight": 8,
"raw": 3.22
},
"pm1ConcNum": {
"value": 5.0,
"weight": 8,
"raw": 5.0
},
"pm1ConcMass": {
"value": 1.67,
"weight": 8,
"raw": 1.67
},
"pm10ConcNum": {
"value": 5.24,
"weight": 8,
"raw": 5.24
},
"pm10ConcMass": {
"value": 9.13,
"weight": 8,
"raw": 9.13
},
"no2Conc": {
"value": 20.62,
"weight": 8,
"raw": 20.62
},
"pm2_5ConcMass_24HourRollingMean": {
"value": 3.6,
"weight": 196,
"raw": 3.6
},
"pm2_5ConcNum_24HourRollingMean": {
"value": 5.73,
"weight": 196,
"raw": 5.73
},
"pm10ConcMass_24HourRollingMean": {
"value": 8.3,
"weight": 196,
"raw": 8.3
},
"pm10ConcNum_24HourRollingMean": {
"value": 5.8,
"weight": 196,
"raw": 5.8
},
"pm2_5ConcMass_NowCast": {
"value": 7.29
},
"pm2_5NowCastAqi": {
"value": 30
},
"no2UsEpaAqi": {
"raw": 19,
"value": 19
},
"pm2_5WaDwerAqi": {
"raw": 14,
"value": 14
},
"pm10WaDwerAqi": {
"raw": 17,
"value": 17
},
"no2WaDwerAqi": {
"raw": 17,
"value": 17
}
},
"datasourceType": "CLARITY_NODE",
"outputFrequency": "hour",
"average": "hour"
}
]