Recent measurements

POST {baseUrl}/v2/recent-datasource-measurements-query

By Device

This query is only by Datasource ID. To query by device or reference site, use the historical measurements report.

Returns a list of measurements in time descending order.

Example
url: https://clarity-data-api.clarity.io/v2/recent-datasource-measurements-query
body:

{
    org: "myorg1234",
    datasourceIds: ["DS123456", "DS987654"],
    outputFrequency: "hour",
}

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 including it in the headers to reduce response payload size. Example: `Accept-Encoding: gzip`

Request

You must include org on all requests. Provide a list of datasources in datasourceIds, or for all the organization's datasources, pass "allDatasources": true.

body parameter		description
`org`	string required	Find the organization ID in Clarity Dashboard by clicking on your user profile icon in the upper right, then look in the column `Org ID`. Example org ID: `"myorgVD43"`
`datasourceIds`	array of string	A list of modern datasource ids as returned from `/v2/datasources`. Only measurements from periods when then datasource was subscribed by the requested org are returned.
`allDatasources`	bool	Pass `true` to retrieve measurements for all datasources in the specified organization for which you have access. Pass `false` or omit the parameter if you want to retrict using `datasourceIds`.

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.
`startTime`	string	Timestamp of earliest measurement desired. If not specified, 24 hours prior to time of request. Measurements are returned from a cache of recent measurements that is limited to the last 48 hours. Earlier times are accepted in the parameter, but only data from the cache will be returned. Example: `startTime: "2023-09-01T00:00:00Z"`

Response

Column Headers

Automation that processes this response should not assume specifc columns or column ordering. Interpret based on the header row of the response.

The response is like a CSV file: A comma-separated string with an initial header row identifying the columns and with newlines separating the measurements. The set of columns returned depends on the outputFrequency requested.

Identifying Columns (for all output frequencies)

column header	description
datasourceId	Unique identifier of the datasource. (string)
sourceId	Unique identifier of the underlying device or reference site. (string)
sourceType	Either `CLARITY_NODE` or `REFERENCE_SITE`. (string)
outputFrequency	The output frequency; one of `minute`, `hour`, or `day`. (string)

Individual Measurements (outputFrequency=`minute`)

Metric names in the header

Not yet final
Still to come: A JSON response that is parallel to this tabular response. These metric names will evolve to harmonize between the two kinds of response.

column header	description
time	The time of the measurement in ISO 8601 format. (string)
atmPressureRawIndividual	Atmospheric Pressure Highest Resolution Raw [hPa]
no2ConcCalibratedIndividual	NO2 Highest Resolution Concentration Calibrated [ppb]
no2ConcRawIndividual	NO2 Highest Resolution Concentration Raw [ppb]
o3ConcRawIndividual	O3 Highest Resolution Concentration Raw [ppb]
pm10ConcMassCalibratedIndividual	PM10 Highest Resolution Mass Concentration Calibrated [ug/m3]
pm10ConcMassRawIndividual	PM10 Highest Resolution Mass Concentration Raw [ug/m3]
pm10ConcNumRawIndividual	PM10 Highest Resolution Number Concentration Raw [#/m3]
pm1ConcMassCalibratedIndividual	PM1 Highest Resolution Mass Concentration Calibrated [ug/m3]
pm1ConcMassRawIndividual	PM1 Highest Resolution Mass Concentration Raw [ug/m3]
pm1ConcNumRawIndividual	PM1 Highest Resolution Number Concentration Raw [#/m3]
pm2_5ConcMassCalibratedIndividual	PM2.5 Highest Resolution Mass Concentration Calibrated [ug/m3]
pm2_5ConcMassRawIndividual	PM2.5 Highest Resolution Mass Concentration Raw [ug/m3]
pm2_5ConcNumRawIndividual	PM2.5 Highest Resolution Number Concentration Raw [#/m3]
relHumidAmbientRawIndividual	Rel. Humidity Ambient Highest Resolution Raw [%]
relHumidInternalRawIndividual	Rel. Humidity Internal Highest Resolution Raw [%]
temperatureAmbientRawIndividual	Temperature Ambient Highest Resolution Raw [degC]
temperatureInternalRawIndividual	Temperature Internal Highest Resolution Raw [degC]
windDirectionRawIndividual	Wind Highest Resolution Direction Raw [deg]
windSpeedRawIndividual	Wind Highest Resolution Speed Raw [m/s]

Hour Aggregations (outputFrequency=`hour`)

Metric names in the header

Not yet final
Still to come: A JSON response that is parallel to this tabular response. These metric names will evolve to harmonize between the two kinds of response.

column header	description
startOfPeriod	Start of the reported hour in ISO 8601 format. (string)
endOfPeriod	End of the reported hour in ISO 8601 format. (string)
atmPressureRaw1HourMean	Atmospheric Pressure 1-Hour Mean Raw [hPa]
no2ConcCalibrated1HourMean	NO2 1-Hour Mean Concentration Calibrated [ppb]
no2ConcCalibrated1HourMeanUsEpaAqi	NO2 1-Hour Mean AQI (US EPA) Calibrated
no2ConcCalibrated1HourMeanWaDwerAqi	NO2 1-Hour Mean AQI (WA DWER) Calibrated
no2ConcRaw1HourMean	NO2 1-Hour Mean Concentration Raw [ppb]
no2ConcRaw1HourMeanUsEpaAqi	NO2 1-Hour Mean AQI (US EPA) Raw
no2ConcRaw1HourMeanWaDwerAqi	NO2 1-Hour Mean AQI (WA DWER) Raw
o3ConcRaw1HourMean	O3 1-Hour Mean Concentration Raw [ppb]
o3ConcRaw1HourMeanWaDwerAqi	O3 1-Hour Mean AQI (WA DWER) Raw
pm10ConcMassCalibrated1HourMean	PM10 1-Hour Mean Mass Concentration Calibrated [ug/m3]
pm10ConcMassCalibrated1HourMeanWaDwerAqi	PM10 1-Hour Mean AQI (WA DWER) Calibrated
pm10ConcMassCalibrated24HourRollingMean	PM10 24-Hour Rolling Mean Mass Concentration Calibrated [ug/m3]
pm10ConcMassRaw1HourMean	PM10 1-Hour Mean Mass Concentration Raw [ug/m3]
pm10ConcMassRaw1HourMeanWaDwerAqi	PM10 1-Hour Mean AQI (WA DWER) Raw
pm10ConcMassRaw24HourRollingMean	PM10 24-Hour Rolling Mean Mass Concentration Raw [ug/m3]
pm10ConcNumRaw1HourMean	PM10 1-Hour Mean Number Concentration Raw [#/m3]
pm10ConcNumRaw24HourRollingMean	PM10 24-Hour Rolling Mean Number Concentration Raw [#/m3]
pm1ConcMassCalibrated1HourMean	PM1 1-Hour Mean Mass Concentration Calibrated [ug/m3]
pm1ConcMassRaw1HourMean	PM1 1-Hour Mean Mass Concentration Raw [ug/m3]
pm1ConcNumRaw1HourMean	PM1 1-Hour Mean Number Concentration Raw [#/m3]
pm2_5ConcMassCalibrated1HourMean	PM2.5 1-Hour Mean Mass Concentration Calibrated [ug/m3]
pm2_5ConcMassCalibrated1HourMeanWaDwerAqi	PM2.5 1-Hour Mean AQI (WA DWER) Calibrated
pm2_5ConcMassCalibrated24HourRollingMean	PM2.5 24-Hour Rolling Mean Mass Concentration Calibrated [ug/m3]
pm2_5ConcMassCalibratedNowCast	PM2.5 NowCast Mass Concentration Calibrated [ug/m3]
pm2_5ConcMassCalibratedNowCastAqi	PM2.5 NowCast AQI (US EPA) Calibrated
pm2_5ConcMassRaw1HourMean	PM2.5 1-Hour Mean Mass Concentration Raw [ug/m3]
pm2_5ConcMassRaw1HourMeanWaDwerAqi	PM2.5 1-Hour Mean AQI (WA DWER) Raw
pm2_5ConcMassRaw24HourRollingMean	PM2.5 24-Hour Rolling Mean Mass Concentration Raw [ug/m3]
pm2_5ConcMassRawNowCast	PM2.5 NowCast Mass Concentration Raw [ug/m3]
pm2_5ConcMassRawNowCastAqi	PM2.5 NowCast AQI (US EPA) Raw
pm2_5ConcNumRaw1HourMean	PM2.5 1-Hour Mean Number Concentration Raw [#/m3]
pm2_5ConcNumRaw24HourRollingMean	PM2.5 24-Hour Rolling Mean Number Concentration Raw [#/m3]
relHumidAmbientRaw1HourMean	Rel. Humidity Ambient 1-Hour Mean Raw [%]
relHumidInternalRaw1HourMean	Rel. Humidity Internal 1-Hour Mean Raw [%]
temperatureAmbientRaw1HourMean	Temperature Ambient 1-Hour Mean Raw [degC]
temperatureInternalRaw1HourMean	Temperature Internal 1-Hour Mean Raw [degC]
windDirectionRaw1HourMean	Wind 1-Hour Mean Direction Raw [deg]
windSpeedRaw1HourMean	Wind 1-Hour Mean Speed Raw [m/s]

Day Aggregations (outputFrequency=`day`)

Metric names in the header

Not yet final
Still to come: A JSON response that is parallel to this tabular response. These metric names will evolve to harmonize between the two kinds of response.

column header	description
startOfPeriod	Start of the reported day in ISO 8601 format. (string)
endOfPeriod	End of the reported day in ISO 8601 format. (string)
atmPressureRaw24HourMean	Atmospheric Pressure 24-Hour Mean Raw [hPa]
no2ConcCalibrated24HourMean	NO2 24-Hour Mean Concentration Calibrated [ppb]
no2ConcRaw24HourMean	NO2 24-Hour Mean Concentration Raw [ppb]
o3ConcRaw24HourMean	O3 24-Hour Mean Concentration Raw [ppb]
pm10ConcMassCalibrated24HourMean	PM10 24-Hour Mean Mass Concentration Calibrated [ug/m3]
pm10ConcMassCalibrated24HourMeanUsEpaAqi	PM10 24-Hour Mean AQI (US EPA) Calibrated
pm10ConcMassRaw24HourMean	PM10 24-Hour Mean Mass Concentration Raw [ug/m3]
pm10ConcMassRaw24HourMeanUsEpaAqi	PM10 24-Hour Mean AQI (US EPA) Raw
pm10ConcNumRaw24HourMean	PM10 24-Hour Mean Number Concentration Raw [#/m3]
pm1ConcMassCalibrated24HourMean	PM1 24-Hour Mean Mass Concentration Calibrated [ug/m3]
pm1ConcMassRaw24HourMean	PM1 24-Hour Mean Mass Concentration Raw [ug/m3]
pm1ConcNumRaw24HourMean	PM1 24-Hour Mean Number Concentration Raw [#/m3]
pm2_5ConcMassCalibrated24HourMean	PM2.5 24-Hour Mean Mass Concentration Calibrated [ug/m3]
pm2_5ConcMassCalibrated24HourMeanUsEpaAqi	PM2.5 24-Hour Mean AQI (US EPA) Calibrated
pm2_5ConcMassRaw24HourMean	PM2.5 24-Hour Mean Mass Concentration Raw [ug/m3]
pm2_5ConcMassRaw24HourMeanUsEpaAqi	PM2.5 24-Hour Mean AQI (US EPA) Raw
pm2_5ConcNumRaw24HourMean	PM2.5 24-Hour Mean Number Concentration Raw [#/m3]
relHumidAmbientRaw24HourMean	Rel. Humidity Ambient 24-Hour Mean Raw [%]
relHumidInternalRaw24HourMean	Rel. Humidity Internal 24-Hour Mean Raw [%]
temperatureAmbientRaw24HourMean	Temperature Ambient 24-Hour Mean Raw [degC]
temperatureInternalRaw24HourMean	Temperature Internal 24-Hour Mean Raw [degC]
windDirectionRaw24HourMean	Wind 24-Hour Mean Direction Raw [deg]
windSpeedRaw24HourMean	Wind 24-Hour Mean Speed Raw [m/s]

Example Response

datasourceId,sourceId,sourceType,periodType,startOfPeriod,endOfPeriod,locationLatitude,locationLongitude,atmPressureRaw1HourMean,no2ConcCalibrated1HourMean,no2ConcCalibrated1HourMeanUsEpaAqi,no2ConcCalibratedWaDwerAqi,no2ConcRaw1HourMean,no2ConcRaw1HourMeanUsEpaAqi,no2ConcRawWaDwerAqi,o3ConcRaw1HourMean,o3ConcRawWaDwerAqi,pm10ConcMassCalibrated1HourMean,pm10ConcMassCalibrated24HourRollingMean,pm10ConcMassCalibratedWaDwerAqi,pm10ConcMassRaw1HourMean,pm10ConcMassRaw24HourRollingMean,pm10ConcMassRawWaDwerAqi,pm10ConcNumRaw1HourMean,pm10ConcNumRaw24HourRollingMean,pm1ConcMassCalibrated1HourMean,pm1ConcMassRaw1HourMean,pm1ConcNumRaw1HourMean,pm2_5ConcMassCalibrated1HourMean,pm2_5ConcMassCalibrated24HourRollingMean,pm2_5ConcMassCalibratedNowCast,pm2_5ConcMassCalibratedNowCastAqi,pm2_5ConcMassCalibratedWaDwerAqi,pm2_5ConcMassRaw1HourMean,pm2_5ConcMassRaw24HourRollingMean,pm2_5ConcMassRawNowCast,pm2_5ConcMassRawNowCastAqi,pm2_5ConcMassRawWaDwerAqi,pm2_5ConcNumRaw1HourMean,pm2_5ConcNumRaw24HourRollingMean,relHumidAmbientRaw1HourMean,relHumidInternalRaw1HourMean,temperatureAmbientRaw1HourMean,temperatureInternalRaw1HourMean,windDirectionRaw1HourMean,windSpeedRaw1HourMean
DCQYT1459,AXGCR7WJ,CLARITY_NODE,hour,2023-09-01T17:00:00Z,2023-09-01T18:00:00Z,37.878635,-122.301728,,,,,,,,,,,,,0.71,12.45,1,0.91,13.27,,0.0,0.85,,,,,,0.0,9.67,0.02,0,0,0.88,13.18,,54.68,,21.33,,
DDWLW0383,SF3FLYVL,CLARITY_NODE,hour,2023-09-01T17:00:00Z,2023-09-01T18:00:00Z,19.746,-155.087,,,,,9.23,9,9,,,,,,7.27,7.27,7,8.76,8.76,,4.69,8.38,,,,,,7.08,7.08,7.08,30,7,8.72,8.72,,45.12,,21.81,,
DEFSL2364,RW1075XQ,REFERENCE_SITE,hour,2023-09-01T17:00:00Z,2023-09-01T18:00:00Z,45.4369,-75.7261,,,,,,,,31.0,31,,,,,,,,,,,,6.4,,,,6,6.4,,,,6,,,,,,,,

Example code

The following sample Python code selects just the columns you want and converts to native Python types.

# simple demo using Clarity Data API

import requests
import os
import csv
import pprint
import datetime


BASEURL = 'https://clarity-data-api.clarity.io'
HEADERS = {
    'Accept-Encoding': 'gzip',
    'x-api-key': os.environ.get('MY_CLARITY_API_KEY') # put your key in the environment or directly here
}


def check_can_connect():
    # verify can reach the API
    response = requests.get(BASEURL, HEADERS)
    http_code = response.status_code
    connected = (http_code == 200)
    if connected:
        print('Connected to Clarity')
    else:
        print(f'{http_code}  :(  Cannot connect')


def get_recent_measurements(org, datasourceIds, outputFrequency):
    # Fetch measurements from the API
    url = BASEURL + '/v2/recent-datasource-measurements-query'
    request_body = {
        'org': org,
        'datasourceIds': datasourceIds,
        'outputFrequency': outputFrequency
    }
    response = requests.post(url, headers=HEADERS, json=request_body)
    response.raise_for_status()
    return response.text


def csv_to_typed(csv_data, fields_to_extract):
    # slice specific columns out of the CSV-style response
    # convert each to best Python type
    # return dictionary

    def convert_to_best_type(value):
        # Try these types in order: float, datetime, else string
        try:
            return float(value)
        except Exception:
            try:
                return datetime.datetime.strptime(value, '%Y-%m-%dT%H:%M:%SZ')
            except Exception:
                return value

    reader = csv.DictReader(csv_data.splitlines())
    return [{field: convert_to_best_type(row[field]) for field in fields_to_extract} for row in reader]


check_can_connect()

tabular = get_recent_measurements(
        org='myorgVD43',
        datasourceIds=['DEXAM0123'],
        outputFrequency='hour'
    )

measurements = csv_to_typed(tabular, [
    'datasourceId',
    'sourceId',
    'startOfPeriod',
    'pm2_5ConcMassRawNowCastAqi'
    ])

pprint.pprint(measurements)

Recent measurements

Headers

Request

Response

Identifying Columns (for all output frequencies)

Individual Measurements (outputFrequency=minute)

Hour Aggregations (outputFrequency=hour)

Day Aggregations (outputFrequency=day)

Example Response

Example code

Individual Measurements (outputFrequency=`minute`)

Hour Aggregations (outputFrequency=`hour`)

Day Aggregations (outputFrequency=`day`)