Skip to content
OpenAQ Python SDK

Querying measurements

A common task with the OpenAQ API is fetching historical measurements from one or more monitoring stations. This guide covers the basics:

What was the daily average PM2.5 in Mueang Chaiyaphum, Thailand for 2025?

This guide assumes you have installed the OpenAQ Python SDK and have a valid OpenAQ API key.

Steps

Section titled “Steps”

The OpenAQ API works top-down. For this task, that means moving through three resources: Locations, Sensors, and Measurements. The steps are:

  1. Find the IDs of monitoring stations within the city of Mueang Chaiyaphum.
  2. Pick one location, then use the Locations resource with that location’s ID to find the ID of the sensor measuring PM2.5 at that location.
  3. Use the Measurements resource with that sensor’s ID to get data at the granularity and timeframe you want.

Below is the step-by-step workflow with code you can run in a Python notebook.

  1. Instantiate the client.

    from openaq import OpenAQ
    from datetime import date
    

    client = OpenAQ(api_key="replace-with-valid-openaq-api-key")

  2. Retrieve the ID of one location in Mueang Chaiyaphum, Thailand. Search 10 km (10,000 meters) around Chaiyaphum’s central coordinates, 15.81207, 102.02316, for locations that measure PM2.5 and pick the first result for simplicity.

    locations = client.locations.list(
        parameters_id=2,
        coordinates=(15.81207, 102.02316),
        radius=1000,
        limit=1000
    )
    

    locations_id = locations.results[0].id

  3. Retrieve the ID of the sensor that measures PM2.5 at the chosen location.

    sensors = client.locations.sensors(locations_id)
    pm25_sensors_id = 0
    

    for sensor in sensors.results:
        if "pm25" in sensor.name:
            pm25_sensors_id = sensor.id
            break

  4. Fetch the daily average measurements.

    response = client.measurements.list(pm25_sensors_id,
                                        data="days",
                                        date_from=date(2025, 1, 1),
                                        date_to=date(2025, 12, 31)
                                        )
    

    measurements = response.results
    

    client.close()
    

    print(measurements)

    You will now have the daily measurements for 2025 at the chosen location in Mueang Chaiyaphum stored as a list in measurements and printed to your console.

While you can get the results set of this example in the first page of the response (i.e. we are expecting up top 365 records in the results of this query), there will be instances where the records will be spread across several pages when you query at different granularity levels (for example hours) or over a longer period of time. In those cases, it will be necessary to page the results to get the full data you request.

Now that you have the measurements, if you want to work with the datasets using a data frame library like Pandas, we have a tutorial on basic pandas integration. We also have a guide where you can instead output the data to a .csv file for later use.