API References

Caching Strategy:

To prevent overloading the OpenData servers on every call, and to improve performance, this library uses a caching mechanism with the following strategy:

  • Cache Hit (Recent): If cached data is =<20 minutes old, use it immediately

  • ETag Validation: If cache is >=20 minutes old, perform HTTP-HEAD request with ETag

    • If server returns 304 (Not Modified), trust cache for another 20 minutes

    • If server returns 200 (Modified), download full data

  • Network Error: If network unavailable but cache exists, use stale cache with warning

This can be customized:

  • Force Refreshing: force_fetch_fresh() bypasses the age check

  • Disabling Caching: By using disable_caching=True to always fetch fresh data

EAQI scale

  • EAQI reported by this library is the highest sub-index among all pollutants.

 1EAQI_BANDS = {
 2    # Concentration breakpoints (µg/m³) and the corresponding EAQI level (1-6)
 3    # Format: (EAQI_Level, Upper_Concentration_Limit)
 4    "PM10": [
 5        (1, 20),    # Good: 0-20
 6        (2, 40),    # Fair: 20-40
 7        (3, 50),    # Moderate: 40-50
 8        (4, 100),   # Poor: 50-100
 9        (5, 150),   # Very Poor: 100-150
10        (6, float("inf"))  # Extremely Poor: ≥150
11    ],
12    "PM2_5": [
13        (1, 10),    # Good: 0-10
14        (2, 20),    # Fair: 10-20
15        (3, 25),    # Moderate: 20-25
16        (4, 50),    # Poor: 25-50
17        (5, 75),    # Very Poor: 50-75
18        (6, float("inf"))  # Extremely Poor: ≥75
19    ],
20    "O3": [
21        (1, 50),    # Good: 0-50
22        (2, 100),   # Fair: 50-100
23        (3, 130),   # Moderate: 100-130
24        (4, 240),   # Poor: 130-240
25        (5, 380),   # Very Poor: 240-380
26        (6, float("inf"))  # Extremely Poor: ≥380
27    ],
28    "NO2": [
29        (1, 40),    # Good: 0-40
30        (2, 90),    # Fair: 40-90
31        (3, 120),   # Moderate: 90-120
32        (4, 230),   # Poor: 120-230
33        (5, 340),   # Very Poor: 230-340
34        (6, float("inf"))  # Extremely Poor: ≥340
35    ],
36    "SO2": [
37        (1, 100),   # Good: 0-100
38        (2, 200),   # Fair: 100-200
39        (3, 350),   # Moderate: 200-350
40        (4, 500),   # Poor: 350-500
41        (5, 750),   # Very Poor: 500-750
42        (6, float("inf"))  # Extremely Poor: ≥750
43    ],
44}

Usable regions

  • Lowercase strings can be used as well

 1regions = [
 2    "Jihomoravský",
 3    "Jihočeský",
 4    "Karlovarský",
 5    "Královéhradecký",
 6    "Liberecký",
 7    "Moravskoslezský",
 8    "Olomoucký",
 9    "Pardubický",
10    "Plzeňský",
11    "Praha",
12    "Středočeský",
13    "Ústecký",
14    "Vysočina",
15    "Zlínský"
16]

Debugging

  • This library uses the standard Python logging module for debugging.

1import logging
2logging.getLogger("czech_air_quality").setLevel(logging.DEBUG)