/PurpleAir-AQI-Scriptable-Widget

Generate Scriptable app widget to query PurpleAir sensor and display local AQI.

Primary LanguageJavaScriptThe UnlicenseUnlicense

PurpleAir-AQI-Scriptable-Widget

Project operated by Jason Snell jsnell@sixcolors.com with enormous contributions from Matt Silverlock, Rob Silverii, Adam Lickel, Alexander Ogilvie, Brian Donovan, Jon Sadka, and anonymous others!

About this project

This project generates a widget that displays local air quality on the home screen of devices running iOS or iPadOS 14. It is displayed via the Scriptable app by Simon Støvring.

The widget uses data from the PurpleAir network of low-cost, consumer air quality sensors. While in America the EPA has a large, established network of sensors, the nearest sensor to you may not be experiencing the same conditions as you are, especially in extreme events such as wildfires. This widget exists because the nearest EPA sensor to me (Jason Snell) did not accurately reflect my local air quality during heavy wildfire smoke conditions. You can read more about the origin of this project if you like.

How to use this

To use this widget, make a new script inside Scriptable and paste in the contents of purpleair-aqi.js.

You can run the script from within the app, or add a new Small widget on your home screen, set it to Scriptable, and choose the script by tapping and holding on the widget, choosing Edit Widget, and choosing the script by tapping on the Script field.

PurpleAir has changed its API. This widget now requires a PurpleAir API key. If you don't have one, you'll need to request one from https://www2.purpleair.com/pages/contact-us and enter your READ KEY in the API key variable in the script.

The widget is designed to use Location Services to find the nearest PurpleAir station to your location. If that's not working, you can specify a PurpleAir station manually by tapping and holding on the widget, choosing Edit Widget, and then entering the PurpleAir ID of the station you want to monitor in the Parameter field.

How does this widget calculate AQI?

This widget uses an EPA calculation designed for low-cost sensors like PurpleAir in areas where wood smoke is an issue, such as during wildfires. You can read about the backstory here and see the EPA document here.

PurpleAir refers to this calculation as US EPA, which you can choose from the Conversion popup on the PurpleAir web map.

What matters more, the numbers or the words/colors?

The words and colors! The real point of AQI isn't the number, it's the level -- the words and color. But we all like numbers, so it displays a number too. Also, the widget does display a trend if one exists, so if you're in volatile conditions, you should be able to tell at a glance if your air quality is improving or worsening.