Measurements

The measurements resources in the OpenAQ API provide measurement values from sensors. Measurement values are available from a number of different resources as their original values and different levels of aggregation.

Purpose and Use

In addition to providing raw measurement values as reported by providers, the API provides options for rolling up data into different aggregation periods.

Resources

Measurements

https://api.openaq.org/v3/sensors/{sensors_id}/measurements

The measurements resource is the original measurement value as reported by the upstream source.

Hours

https://api.openaq.org/v3/sensors/{sensors_id}/hours

The hours resource is the hourly average (mean) value of measurements.

Note

Many sensors on the OpenAQ platform report hourly values. In the case where the upstream reporting period is hourly, the hours resource and measurements resource are equivalent.

Days

https://api.openaq.org/v3/sensors/{sensors_id}/days

The days resource is the daily average (mean), computed from the hourly average values from 01:00 to 0:00 in local time.

Years

https://api.openaq.org/v3/sensors/{sensors_id}/years

The years resource is the yearly average (mean), computed from the hourly average values from January 01 at 01:00 to December 31 0:00 in local time.

Aggregation Periods

Additional aggregation is available and can be based on the above data groups

Caution

Aggregating from measurements, e.g. /v3/sensors/{sensors_id}/measurements/yearly, can be computationally slow and may not resolve, resulting in a 408 Request Timeout error. For most reliable results, limit queries to smaller time periods using the date_from and date_to query parameters.

Hourly

https://api.openaq.org/v3/sensors/{sensors_id}/measurements/hourly

The hourly aggregator returns the average (mean) value for each hour across the selected time range.

Note

A call to the /v3/sensors/{sensors_id}/measurements/hourly is functionally the same as /v3/sensors/{sensors_id}/hours. The /hours options is the preferred resource.

Daily

https://api.openaq.org/v3/sensors/{sensors_id}/measurements/daily

https://api.openaq.org/v3/sensors/{sensors_id}/hours/daily

The daily aggregator returns the average (mean) value for each day across the selected time range.

Note

A call to the /v3/sensors/{sensors_id}/hours/daily is functionally the same as /v3/sensors/{sensors_id}/days. The /days options is the preferred resource.

Monthly

https://api.openaq.org/v3/sensors/{sensors_id}/measurements/monthly

https://api.openaq.org/v3/sensors/{sensors_id}/hours/monthly

https://api.openaq.org/v3/sensors/{sensors_id}/days/monthly

The monthly aggregator returns the average (mean) value for each month across the selected time range.

Yearly

https://api.openaq.org/v3/sensors/{sensors_id}/measurements/yearly

https://api.openaq.org/v3/sensors/{sensors_id}/hours/yearly

https://api.openaq.org/v3/sensors/{sensors_id}/days/yearly

The yearly aggregator returns the average (mean) value for each year across the selected time range.

Note

A call to the /v3/sensors/{sensors_id}/hours/yearly is functionally the same as /v3/sensors/{sensors_id}/years. The /years options is the preferred resource.

Hour of day

https://api.openaq.org/v3/sensors/{sensors_id}/hours/hourofday

The hourofday aggregator returns the average (mean) value for each hour in a 24 hour day, across the selected time range. This allows analyzing air quality trends on an hourly basis, offering insights into daily patterns and peak pollution times, such as diurnal patterns.

Day of week

https://api.openaq.org/v3/sensors/{sensors_id}/measurements/dayofweek

https://api.openaq.org/v3/sensors/{sensors_id}/hours/dayofweek

The dayofweek aggregator returns the average (mean) value for each day in a week (Monday-Sunday), across the selected time range. This allows analyzing air quality trends on an daily basis, offering insights into daily patterns and peak pollution days.

Month of year

https://api.openaq.org/v3/sensors/{sensors_id}/measurements/monthofyear

https://api.openaq.org/v3/sensors/{sensors_id}/hours/monthofyear

https://api.openaq.org/v3/sensors/{sensors_id}/days/monthofyear

The monthofyear aggregator returns the average (mean) value for each month in a year (January-December), across the selected time range. This allows analyzing air quality trends on an monthly basis, offering insights into seasonal patterns.

Response details

Summary

The summary object provides summary statistics about a aggregated measurement value. The object includes the minimum and maximum values, quartile values (25th, 50th and 75th), average (mean), high percentile (98th) and low percentile (2nd) and standard deviation. When requesting measuremements this field is null.

{
  "min": 0.001,
  "q02": 0.002,
  "q25": 0.025,
  "median": 0.033,
  "q75": 0.043,
  "q98": 0.05669999999999999,
  "max": 0.063,
  "avg": 0.03316917293233082,
  "sd": 0.013343557164562366
}

Coverage

The coverage object provides information on the coverage of measurements when aggregating values over time. When requesting measuremements this field is will show expectedCount and observedCount values of 1, and percentComplete of 100.

{
  "expectedCount": 273,
  "expectedInterval": "273:00:00",
  "observedCount": 266,
  "observedInterval": "266:00:00",
  "percentComplete": 97.0,
  "percentCoverage": 97.0,
  "datetimeFrom": {
    "utc": "2024-01-01T10:00:00Z",
    "local": "2024-01-01T03:00:00-07:00"
  },
  "datetimeTo": {
    "utc": "2024-10-01T09:00:00Z",
    "local": "2024-10-01T03:00:00-06:00"
  }
}

Key fields

• value - The average (mean) value in aggregate, except in the measurements resource value is the original reported measurement value.
• parameter - An object decribing the parameter measured by the sensor.
• period - An object that describes the period agreggate includes a label of the interval, the interval in hours, and a date range of the period aggregated.
• coordinates - The coordinates of the measurement value for mobile monitoring. null for stationary monitoring.
• summary - An object that provides summary statistics of the aggregated data. Includes mininimum, maximum, median and quartile values. This object will be null for measurements
• coverage - An object that provides coverage information of the aggregated data. Includes expected counts, observed count, percent complete and a date range for the values aggregated.

Example response payload

{
  "meta": {
    "name": "openaq-api",
    "website": "/",
    "page": 1,
    "limit": 1000,
    "found": ">1000"
  },
  "results": [
    {
      "value": 0.043,
      "parameter": {
        "id": 10,
        "name": "o3",
        "units": "ppm",
        "displayName": null
      },
      "period": {
        "label": "raw",
        "interval": "01:00:00",
        "datetimeFrom": {
          "utc": "2016-03-06T19:00:00Z",
          "local": "2016-03-06T12:00:00-07:00"
        },
        "datetimeTo": {
          "utc": "2016-03-06T20:00:00Z",
          "local": "2016-03-06T13:00:00-07:00"
        }
      },
      "coordinates": null,
      "summary": null,
      "coverage": {
        "expectedCount": 1,
        "expectedInterval": "01:00:00",
        "observedCount": 1,
        "observedInterval": "01:00:00",
        "percentComplete": 100.0,
        "percentCoverage": 100.0,
        "datetimeFrom": {
          "utc": "2016-03-06T19:00:00Z",
          "local": "2016-03-06T12:00:00-07:00"
        },
        "datetimeTo": {
          "utc": "2016-03-06T20:00:00Z",
          "local": "2016-03-06T13:00:00-07:00"
        }
      }
    }
  ]
}

Was this page helpful?

Thank you for your feedback