Skip to content

Measurements

Deprecated

/v1/measurements is replaced by /v2/recent-datasource-measurements-query and /v2/report-requests.

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.000Z2021-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.000Z2021-10-12T02:00:00.000Z
  • NowCast aggregation of measurements acquired from 2021-10-11T15:00:00.000Z to 2021-10-12T03:00:00.000Z2021-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.000Z2021-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"
        }
    ]