Skip to main content

Overview

Breeze uses multiple APIs to provide air quality, weather, and pollen data. Most APIs are free and require no configuration, but some features require API keys.

APIs Used

Free APIs (No Key Required)

Open-Meteo Air Quality

Real-time air quality data and pollutant levels

Open-Meteo Geocoding

City search and location autocomplete

Open-Meteo Historical Weather

Climate trends and historical temperature data
These APIs work out of the box with no setup required.

Optional APIs (Key Required)

Google Pollen API

Pollen and allergen data for grass, trees, and weeds

Google Pollen API Setup

The pollen feature requires a Google Pollen API key. Without this key, the app works normally but pollen data won’t be available.

Getting an API Key

  1. Go to the Google Cloud Console
  2. Create a new project or select an existing one
  3. Enable the Pollen API
  4. Navigate to APIs & Services → Credentials
  5. Click Create Credentials → API Key
  6. Copy your API key
Restrict your API key to the Pollen API and iOS app bundle identifier for security.

Adding the Key in Xcode

The app reads the API key from an environment variable at runtime:
  1. In Xcode, go to Product → Scheme → Edit Scheme (or press Cmd + Shift + ,)
  2. Select Run in the left sidebar
  3. Go to the Arguments tab
  4. Under Environment Variables, click the + button
  5. Add:
    • Name: GOOGLE_POLLEN_API_KEY
    • Value: your_api_key_here
Environment variables are stored in your local Xcode scheme file and won’t be committed to version control.

How the App Uses API Keys

Pollen Service Implementation

The app checks for the API key and handles its absence gracefully:
PollenService.swift
actor PollenService {
    static let shared = PollenService()
    
    // Backend proxy URL - production API
    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)
        }
        
        // Parse and return pollen data
        let decoder = JSONDecoder()
        let result = try decoder.decode(PollenResponse.self, from: data)
        // ... process pollen items
    }
}
Pollen requests are made through a backend proxy (breeze.earth/api/pollen), which handles the Google API authentication. This architecture keeps API keys secure and allows for rate limiting.

Dashboard Integration

The dashboard fetches pollen data asynchronously and doesn’t block other features:
DashboardViewModel.swift:132-143
// Fetch pollen data (non-blocking)
Task {
    do {
        let pollen = try await PollenService.shared.fetchPollen(
            latitude: latitude,
            longitude: longitude
        )
        self.pollenItems = pollen
    } catch {
        print("Pollen error: \(error)")
    }
}
If the pollen API fails (due to missing key or network issues), the app continues working normally with air quality and climate data.

What Works Without API Keys

Air Quality

US AQI index and all pollutant levels (PM2.5, PM10, NO₂, SO₂, O₃, CO)

Location Services

Current location detection and city search

Climate Data

Historical temperature trends and climate analysis

Pollen Data

Requires Google Pollen API key

Production Deployment

For production apps distributed via the App Store:
1

Use a backend proxy

Don’t embed API keys directly in the app. Use a backend service to proxy requests (like breeze.earth/api/pollen).
2

Implement rate limiting

Protect your API keys from abuse by implementing rate limiting on your backend.
3

Monitor usage

Track API usage in Google Cloud Console to avoid unexpected charges.
4

Set up billing alerts

Configure billing alerts in Google Cloud to be notified if usage exceeds thresholds.

Troubleshooting

  1. Verify the API key is correctly set in Edit Scheme → Environment Variables
  2. Check that the key is named exactly GOOGLE_POLLEN_API_KEY
  3. Ensure the Pollen API is enabled in Google Cloud Console
  4. Check Xcode console for error messages
For production apps, never embed API keys in the source code. Use a backend proxy service to handle authentication. The environment variable approach is only suitable for development.
If you hit Google’s rate limits, requests will fail with a 429 error. Consider:
  • Implementing caching to reduce API calls
  • Using a backend service with rate limiting
  • Upgrading your Google Cloud plan

Next Steps

Permissions

Learn about configuring location and other permissions

Build docs developers (and LLMs) love