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
- Go to the Google Cloud Console
- Create a new project or select an existing one
- Enable the Pollen API
- Navigate to APIs & Services → Credentials
- Click Create Credentials → API Key
- Copy your API key
Adding the Key in Xcode
The app reads the API key from an environment variable at runtime:- In Xcode, go to Product → Scheme → Edit Scheme (or press Cmd + Shift + ,)
- Select Run in the left sidebar
- Go to the Arguments tab
- Under Environment Variables, click the + button
- Add:
- Name:
GOOGLE_POLLEN_API_KEY - Value:
your_api_key_here
- Name:
How the App Uses API Keys
Pollen Service Implementation
The app checks for the API key and handles its absence gracefully:PollenService.swift
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
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: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).Implement rate limiting
Protect your API keys from abuse by implementing rate limiting on your backend.
Troubleshooting
Pollen data not showing
Pollen data not showing
- Verify the API key is correctly set in Edit Scheme → Environment Variables
- Check that the key is named exactly
GOOGLE_POLLEN_API_KEY - Ensure the Pollen API is enabled in Google Cloud Console
- Check Xcode console for error messages
API key security concerns
API key security concerns
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.
Rate limit exceeded
Rate limit exceeded
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