Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/NASAARSET/PM2.5_AQ_Online_2026/llms.txt

Use this file to discover all available pages before exploring further.

F_get_OpenAQ_from_API retrieves ground-based air quality monitor measurements from the OpenAQ v3 REST API for any combination of pollutants, monitor types, geographic region, and time period. The function handles pagination automatically, converts all measurements to a consistent unit (µg/m³), and returns a tidy pandas.DataFrame indexed by (lat, lon, time) — the same format expected by F_compute_metrics. Use this function to build the observed side of a satellite-vs-ground validation workflow. It is the standard way to pull OpenAQ data throughout the ARSET PM2.5 case-study notebooks, and its output DataFrame can be merged directly with collocated satellite estimates produced by F_subset_and_combine.

​
Parameters

​
n_lon_min
float
required
Minimum (western) longitude of the bounding box, in decimal degrees.
​
n_lat_min
float
required
Minimum (southern) latitude of the bounding box, in decimal degrees.
​
n_lon_max
float
required
Maximum (eastern) longitude of the bounding box, in decimal degrees.
​
n_lat_max
float
required
Maximum (northern) latitude of the bounding box, in decimal degrees.
​
t_start
numpy.datetime64
required
Start of the time window. Must be a numpy.datetime64 object. Measurements before this timestamp are excluded from the result.
​
t_end
numpy.datetime64
required
End of the time window. Must be a numpy.datetime64 object. Measurements after this timestamp are excluded from the result.
​
l_variables
list[str]
default:"['PM2.5']"
List of pollutant variable names to query. The full set supported by the internal d_params lookup is:
NameOpenAQ parameter
'PM2.5'PM 2.5
'PM10'PM 10
'CO'Carbon monoxide
'O3'Ozone
'NO2'Nitrogen dioxide
'SO2'Sulfur dioxide
'BC'Black carbon
All returned concentration values are normalised to µg/m³ regardless of the original reporting unit (ppm, ppb, or µg/m³).
​
b_reference
bool
default:"True"
If True, results from reference-grade regulatory monitors (FEM/FRM instruments) are included. Set to False to exclude them.
​
b_lowcost
bool
default:"False"
If True, results from low-cost sensor networks are included alongside (or instead of) reference monitors. Low-cost data may have higher uncertainty; use with care in validation studies.
​
s_key
str
default:"s_key_openAQ"
Your OpenAQ API key. Defaults to the s_key_openAQ variable defined at the top of the notebook. Register for a free key at openaq.org.

​
Return Value

​
f_data
pandas.DataFrame | None
A pandas.DataFrame with a three-level MultiIndex of (lat, lon, time). Each row represents one hourly measurement at one monitor location. Columns include at minimum the requested pollutant name(s) (e.g., 'PM2.5').Returns None if no monitors or measurements are found in the specified region and time window.

​
API Endpoints Used

The function makes sequential requests to three OpenAQ v3 endpoints:
StepEndpointPurpose
1GET https://api.openaq.org/v3/parametersResolve pollutant name → numeric parameter ID
2GET https://api.openaq.org/v3/locations?limit=1000&page={n_page}&bbox=...List monitor locations inside the bounding box
3GET https://api.openaq.org/v3/sensors/{n_sensor_id}/measurements?limit=1000&page={n_page}&datetime_from=...&datetime_to=...Download time-series measurements per sensor
Pagination is handled automatically for both the locations and measurements requests; all pages are fetched and concatenated before the DataFrame is returned.

​
Usage Example

Fetch hourly PM2.5 readings from reference monitors in the Biobío region of Chile for January 2023: 
import numpy as np

# Biobío bounding box
n_lon_min, n_lon_max = -74.0, -71.0
n_lat_min, n_lat_max = -39.0, -36.0

t_start = np.datetime64('2023-01-01')
t_end   = np.datetime64('2023-01-31')

f_data_monitors_OpenAQ = F_get_OpenAQ_from_API(
    n_lon_min   = n_lon_min,
    n_lat_min   = n_lat_min,
    n_lon_max   = n_lon_max,
    n_lat_max   = n_lat_max,
    t_start     = t_start,
    t_end       = t_end,
    l_variables = ['PM2.5'],
    b_reference = True,
    b_lowcost   = False,
)

if f_data_monitors_OpenAQ is not None:
    print(f_data_monitors_OpenAQ.head())
    #                                    PM2.5
    # lat      lon      time
    # -37.4697 -72.3531 2023-01-01 00:00   8.2
    #                   2023-01-01 01:00  10.5
    #                   ...

​
Fetching multiple pollutants with low-cost sensors

f_multi = F_get_OpenAQ_from_API(
    n_lon_min   = -74.0,
    n_lat_min   = -39.0,
    n_lon_max   = -71.0,
    n_lat_max   = -36.0,
    t_start     = np.datetime64('2023-06-01'),
    t_end       = np.datetime64('2023-08-31'),
    l_variables = ['PM2.5', 'PM10'],
    b_reference = True,
    b_lowcost   = True,
    s_key       = 'YOUR_OPENAQ_KEY_HERE',
)
The OpenAQ v3 API requires authentication for sustained use. Unauthenticated requests are subject to very low rate limits. Set s_key to your personal API key or store it in the s_key_openAQ notebook variable before calling this function. Register at openaq.org.
The function returns None — not an empty DataFrame — when no data are found. Always guard downstream code with a None check before calling .head(), .merge(), or passing the result to F_compute_metrics.
if f_data_monitors_OpenAQ is None:
    print("No OpenAQ data found for this region/period.")
Unit conversion is applied automatically. Values originally reported in ppm or ppb are converted to µg/m³ using standard temperature and pressure (STP) factors before the DataFrame is assembled. No manual unit handling is required.
  • F_compute_metrics — pass the returned DataFrame directly as the ground-truth input for satellite validation metrics.
  • F_get_SINCA_from_web — an alternative data source for Chilean ground monitors not covered by OpenAQ.
  • F_plot_map — visualise monitor locations and concentrations on a map using a_data_plot_point.
  • OpenAQ Data Source — background on the OpenAQ platform and data quality tiers.

Build docs developers (and LLMs) love

Get started for freeTalk to us