Classes

The main entry point for the library is the AirQuality class.

class czech_air_quality.api.AirQuality(auto_load=True, region_filter=None, use_nominatim=True, neighbour_station_limit=20, nominatim_timeout=10, request_timeout=20, disable_caching=False)[source]

Bases: AirQualityCalculations

A client for retrieving air quality data from CHMI.

classmethod get_all_station_names()[source]

Get all known air quality station names by creating temporary a client instance.

Returns:

List of station names, or empty list if data cannot be retrieved

Return type:

list[str | None]

property actualized_time: datetime

Timestamp when data was last updated by the CHMI source.

Return type:

datetime

property is_data_fresh: bool

Check if cached data is still valid via ETag validation.

Returns:

True if cached data is current; False if needs refresh

Return type:

bool

property all_stations: list[dict]

Get all available air quality stations.

Returns:

List of station dictionaries, filtered by region if set

Return type:

list[dict]

property component_lookup: dict[str, tuple[str, str, str]]

Map of pollutant codes to (code, name, unit) tuples.

Returns:

Dictionary with pollutant code as key

Return type:

dict[str, tuple[str, str, str]]

property raw_data: dict

Raw parsed data from the JSON source.

Returns:

Dictionary containing localities and measurements

Return type:

dict

find_nearest_station(city_name)[source]

Find air quality station nearest to a city.

If use_nominatim=True, geocodes the city name to coordinates and calculates distances to all stations. Otherwise, matches exact station names only (e.g. “Prague - Letná”).

Parameters:

city_name (str) – Name of the city or exact station name

Returns:

Tuple of (station_dict, distance_km) with station metadata and distance

Return type:

tuple[dict, float]

Raises:

StationNotFoundError – If city/station not found or no nearby stations exist

get_air_quality_report(city_name)[source]

Get comprehensive air quality report with EAQI (European Air Quality Index) for a city.

Parameters:

city_name (str) – City name to search for

Returns:

Air quality report dictionary with keys:

  • city_searched (str): Original search term

  • station_name (str): Name of station providing data

  • station_code (str): Station locality code

  • region (str): Region name

  • distance_km (str): Distance from city to station in kilometers

  • air_quality_index_code (int): EAQI level (0-6, 0 if no data)

  • air_quality_index_description (str): Human description (e.g., ‘Good’, ‘Poor’)

  • actualized_time_utc (str): ISO format UTC timestamp of data

  • measurements (list[dict]): List of pollutant measurements:

    • pollutant_code (str): Code like ‘PM10’, ‘O3’

    • pollutant_name (str): Full name

    • unit (str): Unit of measurement

    • value (float|None): Numeric value

    • sub_aqi (int): Sub-index level for this pollutant

    • formatted_measurement (str): Display string

  • Error (str): Error message if lookup failed

Return type:

dict

get_pollutant_measurement(city_name, pollutant_code)[source]

Get measurement data for a specific pollutant at the nearest station.

Parameters:

  • city_name (str) – City name to search for

  • pollutant_code (str) –

    Pollutant code to retrieve (case-insensitive):

    • ’PM10’: Particulate matter < 10 µm

    • ’PM2_5’: Fine particulate matter < 2.5 µm

    • ’O3’: Ozone

    • ’NO2’: Nitrogen dioxide

    • ’SO2’: Sulfur dioxide

Returns:

Measurement dictionary with keys:

  • city_searched (str): Original search term

  • station_name (str): Station name(s) that provided the measurement

  • pollutant_code (str): Normalized pollutant code

  • pollutant_name (str): Full pollutant name

  • unit (str): Unit of measurement (e.g., ‘µg/m³’)

  • value (float|None): Numeric measurement value

  • measurement_status (str): Status string (e.g., ‘Measured’, ‘No Data’)

  • formatted_measurement (str): Display string (e.g., ‘12.5 µg/m³’)

Return type:

dict

Raises:
get_air_quality_index(city_name)[source]

Get EAQI for a city using the 0-6 scale.

Returns the highest sub-index across all measured pollutants (PM10, PM2_5, O3, NO2, SO2).

Parameters:

city_name (str) – Name of the city

Returns:

Tuple of (EAQI level 0-6, description)

Return type:

tuple[int, str]

force_fetch_fresh()[source]

Force fetching fresh data from the source without waiting for the internal cache timer.

Bypasses the normal 20-minute cache timeout and immediately requests fresh data from CHMI. Still uses cached data if server returns 304 (Not Modified) via ETag validation.

Raises:

DataDownloadError – If network error occurs and no cache is available

Return type:

None