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. Default: `500` Min: `1` Max: `20,000` if `Accept-Encoding=gzip` specified in the headers, else `5,000` Example: `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 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

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