Measurements

Deprecated

/v1/measurements is replaced by multiple endpoints and will be turned off in July 2024

Please navigate to v2 measurements

GET {baseUrl}/v1/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 code or datasource id. Specify only one of these parameters. If more than one is provided, only one will be used.

query parameter description

code

string

The node ID (marked on the physical device). Only measurements for the specified nodes will be returned.

In Clarity Dashboard this value is also called the Clarity Device Id or the source ID of a Datasource

Specify multiple items by using a comma-separated list.

🛈 In the upcoming v2 endpoint this will be renamed to nodeId

datasourceId

string

A legacy datasource id to filter on. Only measurements for the specified datasources will be returned.
Specify multiple items by using a comma-separated list.

⚠ For new client code, please use code above to select specific sources

⚠ In the upcoming v2 endpoint this id, returned by /v1/datasources, will change. Please do not retain the current id in your data systems

org

string
optional

Find all measurements from the given organization. If the API key provided identifies a user who has a role in more than one organization, then the org parameter specifies which org. If the parameter is not provided, then the default is to use the first org for that user.
Find the org ID by clicking on your user icon in Dashboard.
Example org ID: "myorgVD43"

🛈 In the upcoming v2 endpoint, this parameter will become required

And then add these parameters

additional query 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`. 🛈 In the upcoming v2 endpoint, this paramter will be dropped. It is superseded by `outputFrequency`.
`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` 🛈 In the upcoming v2 endpoint, this will be replaced with a different pagination control
`limit`	integer	The maximum number of measurements to be returned. Default: `500` Min: `1` Max: `20,000` if `Accept-Encoding=gzip` specified in the headers, else `5,000` Example: `limit=100` 🛈 In the upcoming v2 endpoint, this will be replaced with a different pagination control
`aqi`	string	Note: We strongly recommend not to use this feature as the output does not comply with AQI standards. 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` 🛈 In the upcoming v2 endpoint, this will be dropped

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. 🛈 In the upcoming v2 endpoint, this will be dropped
`recId`	string	The unique ID of the measurement. 🛈 In the upcoming v2 endpoint, this will be dropped
`deviceCode`	string	The node ID (marked on the physical device). Example: `"AHYGZ6WT"` 🛈 In the upcoming v2 endpoint, this will be renamed -- the value will be reliable across versions
`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 1-Hour Mean aggregation of measurements acquired from `2021-10-12T02:00:00.000Z` to `2021-10-12T03:00:00.000Z` → `2021-10-12T02:00:00.000Z` 24-Hour Rolling Mean aggregation of measurements acquired from `2021-10-11T03:00:00.000Z` to `2021-10-12T03:00:00.000Z` → `2021-10-12T02:00:00.000Z` NowCast aggregation of measurements acquired from `2021-10-11T15:00:00.000Z` to `2021-10-12T03:00:00.000Z` → `2021-10-12T02:00:00.000Z` Example3: `outputFrequency=day` → the start of the day at the end of which the aggregation is calculated 24-Hour Mean aggregation of measurements acquired from `2021-10-11T00:00:00.000Z` to `2021-10-12T00:00:00.000Z` → `2021-10-11T00:00:00.000Z`
`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

{
    "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 `minute` → Highest Resolution `hour` → 1-Hour Mean `day` → 24-Hour Mean	%
`relHumidAmbient`	Relative Humidity Ambient `minute` → Highest Resolution `hour` → 1-Hour Mean `day` → 24-Hour Mean	%
`temperature`	Temperature Internal `minute` → Highest Resolution `hour` → 1-Hour Mean `day` → 24-Hour Mean	°C
`temperatureAmbient`	Temperature Ambient `minute` → Highest Resolution `hour` → 1-Hour Mean `day` → 24-Hour Mean	°C
`pm2_5ConcMass`	PM2.5 Mass Concentration `minute` → Highest Resolution `hour` → 1-Hour Mean `day` → 24-Hour Mean	μg/m3
`pm2_5ConcNum`	PM2.5 Number Concentration `minute` → Highest Resolution `hour` → 1-Hour Mean `day` → 24-Hour Mean	#/cm3
`pm2_5ConcMass_NowCast`	`minute` → N/A `hour` → PM2.5 NowCast Mass Concentration `day` → N/A	μg/m3
`pm2_5NowCastAqi`	`minute` → N/A `hour` → PM2.5 AQI (US EPA) `day` → N/A
`pm2_5ConcMass_24HourRollingMean`	`minute` → N/A `hour` → PM2.5 24-Hour Rolling Mean Mass Concentration `day` → N/A	μg/m3
`pm2_5ConcNum_24HourRollingMean`	`minute` → N/A `hour` → PM2.5 24-Hour Rolling Mean Number Concentration `day` → N/A	#/cm3
`pm2_5WaDwerAqi`	`minute` → N/A `hour` → PM2.5 1-Hour Mean AQI (WA DWER) `day` → N/A
`pm2_5UsEpaAqi`	`minute` → N/A `hour` → N/A `day` → PM2.5 24-Hour Mean AQI (US EPA)
`pm1ConcMass`	PM1 Mass Concentration `minute` → Highest Resolution `hour` → 1-Hour Mean `day` → 24-Hour Mean	μg/m3
`pm1ConcNum`	PM1 Number Concentration `minute` → Highest Resolution `hour` → 1-Hour Mean `day` → 24-Hour Mean	#/cm3
`pm10ConcMass`	PM10 Mass Concentration `minute` → Highest Resolution `hour` → 1-Hour Mean `day` → 24-Hour Mean	μg/m3
`pm10ConcNum`	PM10 Number Concentration `minute` → Highest Resolution `hour` → 1-Hour Mean `day` → 24-Hour Mean	#/cm3
`pm10ConcMass_24HourRollingMean`	`minute` → N/A `hour` → PM10 24-Hour Rolling Mean Mass Concentration `day` → N/A	μg/m3
`pm10ConcNum_24HourRollingMean`	`minute` → N/A `hour` → PM10 24-Hour Rolling Mean Number Concentration `day` → N/A	#/cm3
`pm10WaDwerAqi`	`minute` → N/A `hour` → PM10 1-Hour Mean AQI (WA DWER) `day` → N/A
`pm10UsEpaAqi`	`minute` → N/A `hour` → N/A `day` → PM10 24-Hour Mean AQI (US EPA)
`no2Conc`	NO2 Concentration `minute` → Highest Resolution `hour` →1-Hour Mean `day` → 24-Hour Mean	ppb
`no2UsEpaAqi`	`minute` → N/A `hour` → NO2 1-Hour Mean AQI (US EPA) `day` → N/A
`no2WaDwerAqi`	`minute` → N/A `hour` → NO2 1-Hour Mean AQI (WA DWER) `day` → N/A
`windSpeed`	Wind Speed `minute` → Highest Resolution `hour` → 1-Hour Mean `day` → 24-Hour Mean	m/s
`windDirection`	Wind Direction `minute` → Highest Resolution `hour` → 1-Hour Mean `day` → 24-Hour Mean Note: direction indicates where the wind blows from	compass degrees N=0° E=90° S=180° W=270°
`atmPressure`	Atmospheric Pressure `minute` → Highest Resolution `hour` → 1-Hour Mean `day` → 24-Hour Mean	hPa
`o3Conc`	O3 Concentration `minute` → Highest Resolution `hour` → 1-Hour Mean `day` → 24-Hour Mean	ppb
`o3WaDwerAqi`	`minute` → N/A `hour` → O3 1-Hour Mean AQI (WA DWER) `day` → N/A

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",
        "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"
    }
]