Homebridge Air

The Homebridge Air plugin allows you monitor the current AirQuality for your Zip Code from HomeKit and Siri.

Installation

1. Search for "Air" on the plugin screen of Homebridge Config UI X.
2. Click Install.

Configuration

1. Login / create an account at https://www.airnow.gov/ or at https://aqicn.org/api/ as applicable for your location

2. Select your Provider: AirNow or Apicn

3. Enter your AirNow.gov or Aqicn API Key

4. Enter your City and Latitude / Longitude (4 decimal places is sufficient). Note that City may be ambiguous, so you should always enter Latitude and Longitude for location accuracy

5. Optional Matter settings (Homebridge v2.0+):

   • options.enableMatter: true to explicitly request Matter. If Matter is unavailable or disabled, the plugin logs a warning and falls back to HAP.
   • options.preferMatter: true to use Matter when available and enabled, but silently fall back to HAP otherwise.

6. Migration behavior:

   • Switching from HAP to Matter removes stale cached HAP accessories.
   • Switching from Matter to HAP removes stale cached Matter accessories.

7. Click Save

8. Restart Homebridge

Supported Air Quality Providers

Currently supports AQI Services:

• AirNow which is limited to the USA. A valid ZipCode is required.
• Aqicn which has international support, provided by the World Air Quality Index Project.

Depending on where exactly you would like to monitor AQI, one service may be more appropriate than the other.

Supported Air Quality Features

This plugin will create an AirQualitySensor element. The Home app works well, but the Eve app seems to show more measurements. Measurements retrieved are PM2.5, PM10, & O3 for AirNow. Aqicn adds NO2, SO2, CO...

Contributing

We welcome contributions! Please note our beta branch strategy:

• All PRs must target a beta branch first (format: beta-X.Y.Z)
• Issues must have semantic versioning labels (patch, minor, major) before assignment
• Use our helper script to create beta branches: ./scripts/create-beta-branch.sh
• See our Contributing Guide for detailed instructions

For GitHub Copilot users, please review our Copilot Instructions.

Thanks

Thank you to ToddGreenfield for the the work done on the accesorry based plugin homebridge-airnow.