Skip to content

Repository files navigation

Breathe (iOS)

"Breathe, breathe in the air. Don't be afraid to care." - Pink Floyd, The Dark Side of the Moon

App Icon

Screenshot 1 Screenshot 2 Screenshot 3 Screenshot 4 Screenshot 5 Screenshot 6

Note: This repository is specifically for the iOS version of Breathe. If you are looking for the original Android version, please visit the Breathe (Android) repository.

Breathe is a native iOS app for real-time Air Quality Index (AQI) levels across J&K & Ladakh. It is built with Swift and SwiftUI, shows the US AQI (EPA breakpoints) by default and can switch to India's National Air Quality Index (NAQI).

  • Check the breathe api repo to know how the AQI is calculated.

Download

Download on the App Store


Features

  • Native iOS design with cards, Dynamic Type, and light and dark mode
  • US AQI and Indian NAQI, switchable in Settings
  • Segmented AQI gauge with a guide to what every band means
  • Every sensor is its own place, listed by district and division in Explore
  • Raw readings from the sensors before AirGradient's correction, switchable everywhere including the widget
  • 24 hour trend and hourly charts you can drag across to read any hour
  • Extended history for AQI, PM2.5, PM10, temperature and humidity, calibrated, raw or both, with time in each category, an hour of day chart, weather filters and sensor comparison
  • Map of every sensor, grouped when zoomed out, with a full overview sheet for each place
  • Swipe between pinned places, with context menus and haptics
  • Cigarette equivalence
  • Home screen widgets
  • iPhone Duo, with bars on the side, Home grids that split at the fold and a map legend that stays clear of the camera
  • Follows Reduce Motion

Tech Stack

  • Language: Swift
  • UI Framework: SwiftUI, Swift Charts and MapKit
  • Architecture: MVVM (Model-View-ViewModel)
  • Networking: URLSession
  • Concurrency: Swift Concurrency (async/await)

Structure

Breathe/
├── Breathe/App/
│   └── BreatheApp.swift        # Application entry point
├── Models/
│   └── Models.swift            # API models, shared with the widget
├── Networking/
│   └── BreatheAPI.swift        # API client, shared with the widget
├── Util/
│   ├── HistoryAnalysis.swift   # Bucketing, summaries and sensor comparison
│   ├── Places.swift            # Districts, raw readings and health advice
│   ├── ShotHooks.swift         # DEBUG only launch arguments for CI screenshots
│   ├── Theme.swift             # AQI palette, bands and card style
│   └── WeatherHistory.swift    # Weather filters for extended history
├── ViewModel/
│   └── BreatheViewModel.swift
└── Views/
    ├── HomeView.swift          # Home, hero card, concentrations, about the sensor
    ├── AqiGauge.swift          # Segmented gauge and band guide
    ├── GraphView.swift         # 24 hour trend chart
    ├── DotHistoryView.swift    # Hourly bars
    ├── ExtendedHistoryView.swift
    ├── ExtendedDotGrid.swift   # Calendar view of extended history
    ├── ChartComponents.swift
    ├── NodeReadingCard.swift   # Sensor cards and sheet
    ├── MapView.swift           # Map and the overview sheet for a place
    ├── SearchView.swift        # Explore
    ├── SettingsView.swift
    ├── DataSourcesView.swift
    ├── HomeOverviewViews.swift # Welcome screen and pinned overview
    ├── ReorderPinnedView.swift
    └── MainTabView.swift
BreatheWidget/                  # Widget extension

Build and deploy locally

Prerequisites

  • Xcode 26 or newer. The app supports iOS 17.6 and later.
  • A running instance of the Breathe Backend (Python/FastAPI), or the public one at api.breatheoss.app.

Installation

  1. Clone the repository: git clone https://github.com/breathe-OSS/breathe-ios && cd breathe-ios

  2. Open in Xcode: Open Breathe.xcodeproj.

  3. Configure the API Endpoint:

    • Update the API URL in Breathe/Networking/BreatheAPI.swift to point to your backend server.
  4. Build and Run:

    • Select your target device or simulator in Xcode and hit Cmd + R (Run).

CI

Workflows only run when app, widget or project files change, and build with Xcode 27.2.

  • Simulator Screenshots shoots iPhone, iPad and iPhone Duo in parallel. The Duo leg folds the simulator with hinge and covers closed, open, book and laptop poses. When the version or build number changes on main, it also refreshes the README screenshots.
  • iOS Build archives main and uploads it to TestFlight when the version or build number changed.
  • App Store Submit sends a build for review with release notes and screenshots.

AQI Data Providers

Why this exists

Publicly available AQI data for the J&K & Ladakh region is currently unreliable. Most standardized sources rely on sparse sensor networks or algorithmic modeling that does not accurately reflect ground-level realities. This results in widely varying values across different platforms. Google, for example, shows values that are insanely low, but they are usually off by a huge margin.

Breathe aims to solve this by strictly curating sources and building a ground-truth network.

Current Data Sources

Open-Meteo

Used for all pollutant values for most regions in J&K & Ladakh. Open-Meteo's satellite-based air quality model provides stable and consistent values that generally fall within the expected range of nearby ground measurements.

AirGradient

Used for other regions where we have gotten contributions to, the sensors are deployed in real time.

This provides accurate values of PM10 and PM2.5. Other values are fetched from Open-Meteo (like O₃ and NO₂)

Call for Contributors (Hardware)

The limitations of our current project is that we do not have ground sensors in every region and are mostly relying on satellite data, so the data is not 100% accurate.

We are actively working to deploy custom physical sensors to improve data density in Jammu. If you are interested in hosting a sensor node, please contact us at: contact@breatheoss.app

We have deployed AirGradient sensors in Bandipora, Doda, Ganderbal, Jammu, Kargil, Kathua, Leh, Rajouri, Reasi, Samba, Srinagar & Udhampur (21 sensors across 12 cities as of 24/10/26), which provide an accurate measurement of PM10 and PM2.5 values. The live list is always at api.breatheoss.app/sensor-info. We are working to deploy them in all other regions.

Credits

This project is fully Free & Open Source Software (FOSS). Everyone who has helped build it, in code or otherwise, is listed on about.breatheoss.app. The list lives in breathe-OSS/.github.

Releases

Packages

Contributors

Languages