Open-Meteo Air Quality API

Real-time air quality data including AQI and pollutant measurements

Overview

Breeze uses the Open-Meteo Air Quality API to provide real-time air quality information for any location worldwide. This API returns the US Air Quality Index (AQI) along with detailed measurements of specific pollutants.

Base URL

https://air-quality-api.open-meteo.com/v1/air-quality

Endpoints Used

Get Current Air Quality

Fetches current air quality data for a specific location.

Query Parameters:

Parameter	Type	Description
latitude	Double	Geographic latitude of the location
longitude	Double	Geographic longitude of the location
current	String	Comma-separated list of pollutants to include
timezone	String	Timezone for the response (set to "auto")

Pollutants Requested:

• us_aqi - US Air Quality Index
• pm10 - Particulate Matter < 10 μm
• pm2_5 - Particulate Matter < 2.5 μm
• carbon_monoxide - CO concentration
• nitrogen_dioxide - NO₂ concentration
• sulphur_dioxide - SO₂ concentration
• ozone - O₃ concentration

Response Format

The API returns a JSON response with the following structure:

{
  "current": {
    "us_aqi": 42,
    "pm2_5": 12.5,
    "pm10": 18.3,
    "carbon_monoxide": 220.5,
    "nitrogen_dioxide": 15.2,
    "sulphur_dioxide": 3.8,
    "ozone": 45.6
  }
}

Response Model

Breeze decodes the response into these Swift models:

struct AirQualityResponse: Codable {
    let current: AirQuality?
}

struct AirQuality: Codable {
    let usAQI: Int
    let pm25: Double
    let pm10: Double
    let carbonMonoxide: Double
    let nitrogenDioxide: Double
    let sulphurDioxide: Double
    let ozone: Double
}

Usage Example

Here’s how Breeze fetches air quality data:

func fetchAirQuality(latitude: Double, longitude: Double) async throws -> AirQuality {
    var components = URLComponents(string: baseURL)!
    components.queryItems = [
        URLQueryItem(name: "latitude", value: String(latitude)),
        URLQueryItem(name: "longitude", value: String(longitude)),
        URLQueryItem(name: "current", value: "us_aqi,pm10,pm2_5,carbon_monoxide,nitrogen_dioxide,sulphur_dioxide,ozone"),
        URLQueryItem(name: "timezone", value: "auto")
    ]
    
    guard let url = components.url else {
        throw URLError(.badURL)
    }
    
    let (data, response) = try await URLSession.shared.data(from: url)
    
    guard let httpResponse = response as? HTTPURLResponse,
          httpResponse.statusCode == 200 else {
        throw URLError(.badServerResponse)
    }
    
    let decoder = JSONDecoder()
    let result = try decoder.decode(AirQualityResponse.self, from: data)
    
    guard let airQuality = result.current else {
        throw NSError(domain: "AirQualityService", code: 1, 
                     userInfo: [NSLocalizedDescriptionKey: "No air quality data available"])
    }
    
    return airQuality
}

See AirQualityService.swift:10

Multiple Location Queries

The API supports querying multiple locations simultaneously by passing comma-separated coordinates:

func fetchMultipleCities(_ cities: [TopCity]) async -> [(city: TopCity, aqi: Int?)] {
    let lats = cities.map { String($0.lat) }.joined(separator: ",")
    let lons = cities.map { String($0.lon) }.joined(separator: ",")
    
    var components = URLComponents(string: baseURL)!
    components.queryItems = [
        URLQueryItem(name: "latitude", value: lats),
        URLQueryItem(name: "longitude", value: lons),
        URLQueryItem(name: "current", value: "us_aqi")
    ]
    
    // ... fetch and parse response
}

See AirQualityService.swift:42

AQI Levels

Breeze interprets AQI values according to US EPA standards:

AQI Range	Level	Description
0-25	Excellent	Pristine air quality
26-50	Good	No health concerns
51-75	Moderate	Acceptable for most people
76-100	Slightly High	May affect sensitive groups
101-150	Unhealthy for Sensitive Groups	Children, elderly should limit outdoor exposure
151-200	Unhealthy	Everyone may experience effects
201-300	Very Unhealthy	Serious health concerns
300+	Hazardous	Emergency conditions

Rate Limits

Open-Meteo APIs are free and do not require an API key. They have generous rate limits suitable for most applications.

Reference

• Open-Meteo Air Quality API Documentation
• Service Implementation: BreezeApp/Services/AirQualityService.swift
• Data Models: BreezeApp/Models/AirQuality.swift