Skip to main content

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:
ParameterTypeDescription
latitudeDoubleGeographic latitude of the location
longitudeDoubleGeographic longitude of the location
currentStringComma-separated list of pollutants to include
timezoneStringTimezone 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 RangeLevelDescription
0-25ExcellentPristine air quality
26-50GoodNo health concerns
51-75ModerateAcceptable for most people
76-100Slightly HighMay affect sensitive groups
101-150Unhealthy for Sensitive GroupsChildren, elderly should limit outdoor exposure
151-200UnhealthyEveryone may experience effects
201-300Very UnhealthySerious health concerns
300+HazardousEmergency 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

Build docs developers (and LLMs) love