Skip to main content
Breeze uses Swift actors for thread-safe API communication. All services follow the singleton pattern and provide async/await methods for data fetching.

​
AirQualityService

Fetches air quality data from the Open-Meteo Air Quality API.
​
shared
AirQualityService
required
Singleton instance for app-wide access

​
fetchAirQuality

Retrieves current air quality data for specific coordinates.
BreezeApp/Services/AirQualityService.swift
actor AirQualityService {
    static let shared = AirQualityService()
    
    private let baseURL = "https://air-quality-api.open-meteo.com/v1/air-quality"
    
    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
    }
}
​
latitude
Double
required
Latitude coordinate (-90 to 90)
​
longitude
Double
required
Longitude coordinate (-180 to 180)
​
return
AirQuality
Complete air quality data including AQI and all pollutant concentrations

​
fetchMultipleCities

Fetches AQI values for multiple cities simultaneously (used for ticker display).
BreezeApp/Services/AirQualityService.swift
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")
    ]
    
    guard let url = components.url else {
        return cities.map { ($0, nil) }
    }
    
    do {
        let (data, _) = try await URLSession.shared.data(from: url)
        
        if let json = try JSONSerialization.jsonObject(with: data) as? [[String: Any]] {
            return zip(cities, json).map { city, data in
                let current = data["current"] as? [String: Any]
                let aqi = current?["us_aqi"] as? Int
                return (city, aqi)
            }
        }
    } catch {
        print("Error fetching multiple cities: \(error)")
    }
    
    return cities.map { ($0, nil) }
}
​
cities
[TopCity]
required
Array of cities to fetch AQI data for
​
return
[(city: TopCity, aqi: Int?)]
Array of tuples containing city and optional AQI value

​
GeocodingService

Searches for cities using the Open-Meteo Geocoding API.
BreezeApp/Services/GeocodingService.swift
actor GeocodingService {
    static let shared = GeocodingService()
    
    private let baseURL = "https://geocoding-api.open-meteo.com/v1/search"
    
    func searchCities(query: String) async throws -> [City] {
        guard query.count >= 2 else { return [] }
        
        var components = URLComponents(string: baseURL)!
        components.queryItems = [
            URLQueryItem(name: "name", value: query),
            URLQueryItem(name: "count", value: "5"),
            URLQueryItem(name: "language", value: "en"),
            URLQueryItem(name: "format", value: "json")
        ]
        
        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(GeocodingResponse.self, from: data)
        
        return result.results ?? []
    }
}

​
searchCities

Searches for cities matching a query string.
​
query
String
required
Search term (minimum 2 characters)
​
return
[City]
Up to 5 matching cities with coordinates and location details
The service returns an empty array if the query is less than 2 characters to avoid unnecessary API calls.

​
PollenService

Fetches pollen data through a backend proxy that communicates with the Google Pollen API.
BreezeApp/Services/PollenService.swift
actor PollenService {
    static let shared = PollenService()
    
    private let baseURL = "https://breeze.earth/api/pollen"
    
    func fetchPollen(latitude: Double, longitude: Double) async throws -> [PollenItem] {
        let urlString = "\(baseURL)?lat=\(latitude)&lon=\(longitude)"
        
        guard let url = URL(string: urlString) 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(PollenResponse.self, from: data)
        
        var items: [PollenItem] = []
        
        if let dailyInfo = result.dailyInfo?.first {
            // Add pollen types (Grass, Tree, Weed)
            if let pollenTypes = dailyInfo.pollenTypeInfo {
                for type in pollenTypes {
                    items.append(PollenItem(
                        id: type.code,
                        name: type.displayName,
                        value: type.indexInfo?.value ?? 0,
                        category: type.indexInfo?.category ?? "Low",
                        isPlant: false,
                        imageUrl: nil,
                        family: nil,
                        season: nil,
                        appearance: nil,
                        healthRecommendations: type.healthRecommendations
                    ))
                }
            }
            
            // Add specific plants
            if let plants = dailyInfo.plantInfo {
                for plant in plants {
                    items.append(PollenItem(
                        id: plant.code,
                        name: plant.displayName,
                        value: plant.indexInfo?.value ?? 0,
                        category: plant.indexInfo?.category ?? "Low",
                        isPlant: true,
                        imageUrl: plant.plantDescription?.picture,
                        family: plant.plantDescription?.family,
                        season: plant.plantDescription?.season,
                        appearance: plant.plantDescription?.specialColors,
                        healthRecommendations: plant.healthRecommendations
                    ))
                }
            }
        }
        
        return items
    }
}

​
fetchPollen

Retrieves pollen data for specific coordinates via backend proxy.
​
latitude
Double
required
Latitude coordinate
​
longitude
Double
required
Longitude coordinate
​
return
[PollenItem]
Array of pollen items including general types (Grass, Tree, Weed) and specific plants (Oak, Birch, etc.)
This service requires a backend proxy at breeze.earth/api/pollen to handle Google Pollen API authentication. Direct API calls from the iOS app are not supported.

​
ClimateService

Fetches historical temperature data from the Open-Meteo Historical Weather API.
BreezeApp/Services/ClimateService.swift
actor ClimateService {
    static let shared = ClimateService()
    
    private let baseURL = "https://archive-api.open-meteo.com/v1/archive"
    
    func fetchClimateData(latitude: Double, longitude: Double) async throws -> [ClimateDataPoint] {
        let today = Date()
        let calendar = Calendar.current
        let month = calendar.component(.month, from: today)
        let day = calendar.component(.day, from: today)
        let currentYear = calendar.component(.year, from: today)
        
        let years = [1980, 1990, 2000, 2010, 2020, currentYear]
        
        var dataPoints: [ClimateDataPoint] = []
        
        for year in years {
            let dateString = String(format: "%d-%02d-%02d", year, month, day)
            
            var components = URLComponents(string: baseURL)!
            components.queryItems = [
                URLQueryItem(name: "latitude", value: String(latitude)),
                URLQueryItem(name: "longitude", value: String(longitude)),
                URLQueryItem(name: "start_date", value: dateString),
                URLQueryItem(name: "end_date", value: dateString),
                URLQueryItem(name: "daily", value: "temperature_2m_max"),
                URLQueryItem(name: "timezone", value: "auto")
            ]
            
            guard let url = components.url else { continue }
            
            do {
                let (data, _) = try await URLSession.shared.data(from: url)
                let decoder = JSONDecoder()
                let result = try decoder.decode(ClimateArchiveResponse.self, from: data)
                
                if let temp = result.daily?.temperatureMax?.first {
                    dataPoints.append(ClimateDataPoint(year: year, temperature: temp))
                }
            } catch {
                print("Error fetching climate data for \(year): \(error)")
            }
        }
        
        return dataPoints.sorted { $0.year < $1.year }
    }
}

​
fetchClimateData

Retrieves historical maximum temperature data for today’s date across multiple decades.
​
latitude
Double
required
Latitude coordinate
​
longitude
Double
required
Longitude coordinate
​
return
[ClimateDataPoint]
Array of temperature data points for years 1980, 1990, 2000, 2010, 2020, and current year
This method fetches data for the current day of the year across multiple decades to visualize climate change trends. Each year’s data is fetched in parallel for better performance.

​
Error Handling

All services use Swift’s native error handling with async throws:
  • URLError.badURL - Invalid URL construction
  • URLError.badServerResponse - Non-200 HTTP status code
  • DecodingError - JSON parsing failure
  • Custom NSError - Service-specific errors (e.g., no data available)
do {
    let airQuality = try await AirQualityService.shared.fetchAirQuality(
        latitude: 37.7749,
        longitude: -122.4194
    )
    // Handle success
} catch {
    print("Error: \(error.localizedDescription)")
    // Handle error
}

​
Thread Safety

All services are implemented as Swift actor types, ensuring:
  • Thread-safe access to shared state
  • No data races
  • Automatic synchronization across concurrent calls
// Safe concurrent access
async let airQuality = AirQualityService.shared.fetchAirQuality(lat: lat, lon: lon)
async let pollen = PollenService.shared.fetchPollen(lat: lat, lon: lon)
async let climate = ClimateService.shared.fetchClimateData(lat: lat, lon: lon)

let (aq, pol, clim) = try await (airQuality, pollen, climate)

Build docs developers (and LLMs) love

Get started for freeTalk to us