-
Notifications
You must be signed in to change notification settings - Fork 10
OpenAQ API V3
The OpenAQ API version 3 is still under development and not intended for production use.
The OpenAPI specification is available at staging.openaq.org/docs. The staging.openaq.org domain does not contain the full OpenAQ dataset and as such is not intended to provide full access.
There is no longer a root /measurements endpoint. All measurements are a child resource of a location and so must be referenced from the parent location. In v2 location filtering is available as a query parameter, in v3 locations_id is now only a path parameter.
/v2/measurements?location_id=2178
/v3/locations/2178/measurements
Measurement data can now be “rolled up” to different time scales. By default the measurements endpoint provides all measurements at the hour interval, except in cases where the time interval is greater than 1 hour. In the case of locations that report at a sub-hour interval, hourly measurement values represent the average (mean) value of the preceding hour, i.e. 10:00 represents the mean of all measurements from 09:01 to 10:00. Other options include day, month, year.
With the added option of averaging measurement values, the API now provides a summary object to accompany the averaged value. This object provides additional context on the distribution of values within the given averaging period. The values included are:
| Statistic | Description |
|---|---|
| min | the minimum value in the period |
| q02 | the 2nd percentile of the period |
| q25 | the 25th percentile of the period |
| median | median or 50th percentile of the period |
| q75 | 75th percentile of the period |
| Q98 | 98th percentile of the period |
| Max | maximum value in the period |
| Sd | the standard deviation of the period |
"summary": {
"min": 0,
"q02": 0,
"q25": 0,
"median": 0,
"q75": 0,
"q98": 0,
"max": 0,
"sd": 0
},When summarizing data the coverage of the period being averaged is essential to understand the validity of the averaged value. The coverage object provides information on data coverage for a given period of time. This object provides expected, observed and information on the time period covered.
E.g. a sensor that returns data every 2 minutes (Purple) will have an expected count of 30 for a given hour. If 3 measurements are missing from a given hour period the observedCount will be 27 and the percentComplete will
"coverage": {
"expectedCount": 0,
"expectedInterval": "string",
"observedCount": 0,
"observedInterval": "string",
"percentComplete": 0,
"percentCoverage": 0,
"datetimeFrom": {
"utc": "string",
"local": "string"
},
"datetimeTo": {
"utc": "string",
"local": "string"
}
}The providers resource represents the entity from which OpenAQ has ingested the data. This concept is similar to the sources concept in v1 and v2. Providers have a specific semantic distinction in that a provider is not necessarily the entity creating the data. Some providers on the OpenAQ platform are aggregators themselves, such as the US EPA AirNow platform which aggregates data from state or municipal jurisdictions across the US that manage the monitoring stations.
Results can be filtered by the type of instrument based on two categories: reference grade and air sensor. Air sensor is the new language used for “low cost sensors”. By default both types are included in the results. Endpoints include a monitor query parameter which accepts a boolean (true/false), when true only includes reference grade monitor, when false only air sensors.
V3 exposes an additional layer of the hierarchy of how data are stored within OpenAQ, sensors. Sensors are child objects of locations and are synonymous with the actual device collecting measurements. Accessing sensors in v3 provides additional information specifically in cases where a pollutant may be measured multiple times are a single location by different sensors.