Metrics in measurements
Metric
A metric brings together several notions into a reportable quantity
- What is sensed (e.g. PM2.5, NO2, Wind)
- A measurable trait of above (e.g. Mass concentration, Speed, Compass direction)
- The aggregation applied (e.g. No aggregation, 1-Hour mean, 24-hour mean)
- The units or pollution index applied (e.g. μg/m³, ppb, US EPA AQI)
Attributes within a metric
Some metrics have ready-to-use values directly from the sensor. No further processing occurs. Examples are temperature, relative humidity and wind. Other metrics have raw data that can benefit from further processing in the cloud. We call these metrics cloud-calibrated. Examples are PM2.5 and NO2.
- Direct from sensor:
rawandvalueare the same - Cloud-calibrated:
rawis from sensor,valueis cloud-calibrated
This means you can consistently access the same attribute regardless of metric, with value being most appropriate for visualization and analysis. Keep an eye on the status field though (see Status table below).
If the response is a JSON format, the attributes are in an object, like this (where the word metric is a name from the dictionary below)
...
"metric": {
"raw":
"value":
"status":
}
...
If the response is tabular, like CSV or Parquet, the attributes are dot-notation column headers like this:
..., metric.raw, metric.value, metric.status, ...
Attribute details
Clarity Node - metric is direct from sensor
| attribute | description |
|---|---|
raw |
The sensed value direct from the device |
value |
Same as raw |
status |
sensor-ready |
Clarity Node - metric can be cloud-calibratred
| attribute | description |
|---|---|
raw |
The sensed value direct from the device |
value |
The calibration result. null if calibration has not occurred |
status |
see table below |
status for cloud-calibrated metrics
| status | description |
|---|---|
calibration-missing |
No calibrated value because a calibration was not assigned to the device durign the last processing |
calibration-processing |
Calibration is in process |
calibrated-reprocessing |
A calibrated value exists and a newer calibration is in process |
calibration-error |
Calibration failed for the data coming from the device |
calibrated-ready |
Calibration has completed |
calibrated-mixed |
Only for aggregations: The individual samples in the aggregation period do not all have the same calibration-status. To understand the mix of statuses, fetch the individual measurements |
For reference sites
| attribute | description |
|---|---|
raw |
null |
value |
The value direct from the reference provider |
status |
reference-ready |
Output frequency
The fields a measurement contains depend on the output frequency of the measurement. Your request to retrieve measurements includes an outputFrequency. Tables below list all the possible metrics, by output frequency.
| Output frequency | type of measurement |
|---|---|
minute |
And individual sample, received from a deployed device, containing everything that device sends |
hour |
An hourly aggregation |
day |
A daily aggrgegation, where a new day is defines in UTC time |
Metrics dictionary
Metric names
These v2 metric names are unique across individual measurements and hourly/daily aggregations. That was not the case for the older v1 API. If you have older API code, watch out for changed metric names
Individual Measurements
outputFrequency
minute
| metric | description |
|---|---|
| atmPressureIndividual | Atmospheric pressure, Individual sample (atm) |
| bcAllSourcesIndividual | Black carbon All sources mass concentration, Individual sample (ng/m³) |
| bcBiomassIndividual | Black carbon Biomass mass concentration, Individual sample (ng/m³) |
| bcFossilFuelIndividual | Black carbon Fossil fuel mass concentration, Individual sample (ng/m³) |
| bcSpectralBIndividual | Black carbon Spectral B mass concentration, Individual sample (ng/m³) |
| bcSpectralGIndividual | Black carbon Spectral G mass concentration, Individual sample (ng/m³) |
| bcSpectralIRIndividual | Black carbon Spectral IR mass concentration, Individual sample (ng/m³) |
| bcSpectralRIndividual | Black carbon Spectral R mass concentration, Individual sample (ng/m³) |
| bcSpectralUVIndividual | Black carbon Spectral UV mass concentration, Individual sample (ng/m³) |
| no2ConcIndividual | NO2 concentration, Individual sample (ppb) |
| o3ConcIndividual | Ozone, Individual sample (ppb) |
| pm10ConcMassIndividual | PM10 mass concentration, Individual sample (μg/m³) |
| pm10ConcNumIndividual | PM10 number concentration, Individual sample (#/cm³) |
| pm1ConcMassIndividual | PM1 mass concentration, Individual sample (μg/m³) |
| pm1ConcNumIndividual | PM1 number concentration, Individual sample (#/cm³) |
| pm2_5ConcMassIndividual | PM2.5 mass concentration, Individual sample (μg/m³) |
| pm2_5ConcNumIndividual | PM2.5 number concentration, Individual sample (#/cm³) |
| relHumidAmbientIndividual | Relative humidity ambient, Individual sample (%) |
| relHumidInternalIndividual | Relative humidity internal, Individual sample (%) |
| temperatureAmbientIndividual | Temperature ambient, Individual sample (°C) |
| temperatureInternalIndividual | Temperature internal, Individual sample (°C) |
| windDirectionIndividual | Wind direction, Individual sample (°) |
| windSpeedIndividual | Wind speed, Individual sample (m/sec) |
Hour Aggregations
outputFrequency
hour
| metric | description |
|---|---|
| atmPressure1HourMean | Atmospheric pressure, 1-hour mean (atm) |
| bcAllSources1HourMean | Black carbon All sources mass concentration, 1-hour mean (ng/m³) |
| bcBiomass1HourMean | Black carbon Biomass mass concentration, 1-hour mean (ng/m³) |
| bcFossilFuel1HourMean | Black carbon Fossil fuel mass concentration, 1-hour mean (ng/m³) |
| bcSpectralB1HourMean | Black carbon Spectral B mass concentration, 1-hour mean (ng/m³) |
| bcSpectralG1HourMean | Black carbon Spectral G mass concentration, 1-hour mean (ng/m³) |
| bcSpectralIR1HourMean | Black carbon Spectral IR mass concentration, 1-hour mean (ng/m³) |
| bcSpectralR1HourMean | Black carbon Spectral R mass concentration, 1-hour mean (ng/m³) |
| bcSpectralUV1HourMean | Black carbon Spectral UV mass concentration, 1-hour mean (ng/m³) |
| no2Conc1HourMean | NO2 concentration, 1-hour mean (ppb) |
| no2Conc1HourMeanUsEpaAqi | NO2 concentration, 1-hour mean, UsEpaAqi |
| no2Conc1HourMeanWaDwerAqi | NO2 concentration, 1-hour mean, WaDwerAqi |
| o3Conc1HourMean | Ozone, 1-hour mean (ppb) |
| o3Conc1HourMeanWaDwerAqi | Ozone, 1-hour mean, WaDwerAqi |
| pm10ConcMass1HourMean | PM10 mass concentration, 1-hour mean (μg/m³) |
| pm10ConcMass1HourMeanWaDwerAqi | PM10 mass concentration, 1-hour mean, WaDwerAqi |
| pm10ConcMass24HourRollingMean | PM10 mass concentration, 24-hour rolling mean (μg/m³) |
| pm10ConcNum1HourMean | PM10 number concentration, 1-hour mean (#/cm³) |
| pm10ConcNum24HourRollingMean | PM10 number concentration, 24-hour rolling mean (#/cm³) |
| pm1ConcMass1HourMean | PM1 mass concentration, 1-hour mean (μg/m³) |
| pm1ConcNum1HourMean | PM1 number concentration, 1-hour mean (#/cm³) |
| pm2_5ConcMass1HourMean | PM2.5 mass concentration, 1-hour mean (μg/m³) |
| pm2_5ConcMass1HourMeanWaDwerAqi | PM2.5 mass concentration, 1-hour mean, WaDwerAqi |
| pm2_5ConcMass24HourRollingMean | PM2.5 mass concentration, 24-hour rolling mean (μg/m³) |
| pm2_5ConcMassNowcast | PM2.5 mass concentration, Nowcast (μg/m³) |
| pm2_5ConcMassNowcastUsEpaAqi | PM2.5 mass concentration, Nowcast, UsEpaAqi |
| pm2_5ConcNum1HourMean | PM2.5 number concentration, 1-hour mean (#/cm³) |
| pm2_5ConcNum24HourRollingMean | PM2.5 number concentration, 24-hour rolling mean (#/cm³) |
| relHumidAmbient1HourMean | Relative humidity ambient, 1-hour mean (%) |
| relHumidInternal1HourMean | Relative humidity internal, 1-hour mean (%) |
| temperatureAmbient1HourMean | Temperature ambient, 1-hour mean (°C) |
| temperatureInternal1HourMean | Temperature internal, 1-hour mean (°C) |
| windDirection1HourMean | Wind direction, 1-hour mean (°) |
| windSpeed1HourMean | Wind speed, 1-hour mean (m/sec) |
Day Aggregations
outputFrequency
day
| metric | description |
|---|---|
| atmPressure24HourMean | Atmospheric pressure, 24-hour mean (atm) |
| bcAllSources24HourMean | Black carbon All sources mass concentration, 24-hour mean (ng/m³) |
| bcBiomass24HourMean | Black carbon Biomass mass concentration, 24-hour mean (ng/m³) |
| bcFossilFuel24HourMean | Black carbon Fossil fuel mass concentration, 24-hour mean (ng/m³) |
| bcSpectralB24HourMean | Black carbon Spectral B mass concentration, 24-hour mean (ng/m³) |
| bcSpectralG24HourMean | Black carbon Spectral G mass concentration, 24-hour mean (ng/m³) |
| bcSpectralIR24HourMean | Black carbon Spectral IR mass concentration, 24-hour mean (ng/m³) |
| bcSpectralR24HourMean | Black carbon Spectral R mass concentration, 24-hour mean (ng/m³) |
| bcSpectralUV24HourMean | Black carbon Spectral UV mass concentration, 24-hour mean (ng/m³) |
| no2Conc24HourMean | NO2 concentration, 24-hour mean (ppb) |
| o3Conc24HourMean | Ozone, 24-hour mean (ppb) |
| pm10ConcMass24HourMean | PM10 mass concentration, 24-hour mean (μg/m³) |
| pm10ConcMass24HourMeanUsEpaAqi | PM10 mass concentration, 24-hour mean, UsEpaAqi |
| pm10ConcNum24HourMean | PM10 number concentration, 24-hour mean (#/cm³) |
| pm1ConcMass24HourMean | PM1 mass concentration, 24-hour mean (μg/m³) |
| pm1ConcNum24HourMean | PM1 number concentration, 24-hour mean (#/cm³) |
| pm2_5ConcMass24HourMean | PM2.5 mass concentration, 24-hour mean (μg/m³) |
| pm2_5ConcMass24HourMeanUsEpaAqi | PM2.5 mass concentration, 24-hour mean, UsEpaAqi |
| pm2_5ConcNum24HourMean | PM2.5 number concentration, 24-hour mean (#/cm³) |
| relHumidAmbient24HourMean | Relative humidity ambient, 24-hour mean (%) |
| relHumidInternal24HourMean | Relative humidity internal, 24-hour mean (%) |
| temperatureAmbient24HourMean | Temperature ambient, 24-hour mean (°C) |
| temperatureInternal24HourMean | Temperature internal, 24-hour mean (°C) |
| windDirection24HourMean | Wind direction, 24-hour mean (°) |
| windSpeed24HourMean | Wind speed, 24-hour mean (m/sec) |