Skip to content

Commit b611390

Browse files
rushhiiirushhiii
committed
Update aqi-widget.md
1 parent b7d59f2 commit b611390

1 file changed

Lines changed: 298 additions & 0 deletions

File tree

‎Web Docs/docs/widgets/aqi-widget.md‎

Lines changed: 298 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,298 @@
1+
# OpenWeather AQI + Temperature Widget
2+
3+
![Scriptable](https://img.shields.io/badge/Scriptable-Compatible-purple)
4+
![Widget Size](https://img.shields.io/badge/Supports-Small%20Widget-blue)
5+
![Data Source](https://img.shields.io/badge/Data-OpenWeatherMap-brightgreen)
6+
![Customization](https://img.shields.io/badge/Configurable-AQI%20%2B%20Temperature%20%2B%20Themes-orange)
7+
![Status](https://img.shields.io/badge/Status-Stable-brightgreen)
8+
![Last Updated](https://img.shields.io/badge/Updated-July%202025-yellow)
9+
10+
<!-- ![OpenWeatherAQI Showcase](https://github.com/rushhiii/Scriptable-IOSWidgets/blob/main/.assets/aqi/openweatheraqi_showcase.png) -->
11+
12+
<img width="500px" src="https://github.com/rushhiii/Scriptable-IOSWidgets/blob/main/.assets/aqi/openweatheraqi_showcase.png" atl="OpenWeatherAQI Showcase" />
13+
14+
A powerful dual-mode widget for Scriptable that displays either **Air Quality Index (AQI)** or **Temperature** information with beautiful color-coded backgrounds. Built for iOS using the [Scriptable app](https://scriptable.app) and powered by OpenWeatherMap APIs.
15+
16+
> **Inspiration & Credits:** This widget was inspired by and adapted from [Jason Snell's PurpleAir AQI Scriptable Widget](https://github.com/jasonsnell/PurpleAir-AQI-Scriptable-Widget). Special thanks to Jason for the original concept and design patterns that made this enhanced version possible.
17+
18+
> **Note:** All example screenshots in this documentation are shown in **light mode**. If your phone is in dark mode, the widget background will appear pitch black by default. If you prefer the colorful backgrounds shown in the examples, add `"light"` to your widget parameter to force light theme colors.
19+
20+
## ✨ Features
21+
22+
### 🌡️ **Temperature Mode**
23+
* Current temperature with large, easy-to-read display
24+
* Daily high and low temperatures
25+
* Temperature difference from "feels like" temperature
26+
* Daily temperature range information
27+
* City/location name display
28+
* Temperature-based color themes (hot = red/orange, cold = blue)
29+
30+
### 🌍 **Air Quality Mode (Default)**
31+
* Real-time Air Quality Index (AQI) for your location
32+
* Color-coded AQI levels following US EPA standards
33+
* PM2.5 and PM10 pollution measurements
34+
* AQI category labels (Good, Moderate, Unhealthy, etc.)
35+
* SF Symbol icons for different AQI levels
36+
* Last updated timestamp
37+
38+
### 🎨 **Smart Theming**
39+
* **Auto Theme**: Adapts to your device's light/dark mode
40+
* **Light Theme**: Force colorful backgrounds (as shown in examples)
41+
* **Dark Theme**: Force dark backgrounds with colored text
42+
* Dynamic colors based on AQI levels or temperature ranges
43+
44+
## 🚀 How It Works
45+
46+
The widget uses two OpenWeatherMap APIs:
47+
1. **Air Pollution API**: Fetches real-time air quality data including PM2.5, PM10, and calculates US AQI
48+
2. **Weather API**: Retrieves current temperature, high/low, and location information
49+
50+
## 🔧 Setup
51+
52+
### 1. Get OpenWeatherMap API Key
53+
54+
1. Go to [OpenWeatherMap](https://openweathermap.org/api)
55+
2. Create a free account
56+
3. Navigate to the API Keys section
57+
4. Generate a new API key (free tier includes 1,000 calls/day)
58+
59+
### 2. Install the Script
60+
61+
**Option A - Direct Download:**
62+
1. Download [`OpenWeatherAQI.js`](https://github.com/rushhiii/Scriptable-IOSWidgets/blob/main/Widgets/AQI%20Widget/OpenWeatherAQI.js)
63+
2. Save it to the `Scriptable` folder in your iCloud Drive
64+
65+
**Option B - Manual Copy:**
66+
1. Open Scriptable app
67+
2. Tap the **+** icon to create a new script
68+
3. Copy and paste the entire script content
69+
4. Save with a name like "OpenWeather AQI"
70+
71+
### 3. Configure API Key
72+
73+
1. Open the script in Scriptable
74+
2. Find this line at the top:
75+
```javascript
76+
const API_KEY = "YOUR_API_HERE"; // OpenWeatherMap API key
77+
```
78+
3. Replace `YOUR_API_HERE` with your actual API key:
79+
```javascript
80+
const API_KEY = "abc123def456ghi789"; // Your actual API key
81+
```
82+
4. Save the script
83+
84+
### 4. Add Widget to Home Screen
85+
86+
1. Long-press your iOS Home Screen to enter edit mode
87+
2. Tap the **+** icon in the top left
88+
3. Search for and select **Scriptable**
89+
4. Choose **Small** widget size (this widget is optimized for small widgets)
90+
5. Place the widget on your home screen
91+
6. Tap the widget to configure it:
92+
- **Script**: Select your "OpenWeather AQI" script
93+
- **When Interacting**: Choose "Run Script"
94+
- **Parameter**: Enter your desired parameter (see configuration options below)
95+
96+
### 5. Enable Location Access
97+
98+
1. When the widget runs for the first time, it will request location access
99+
2. Choose "Allow While Using App" or "Allow Once"
100+
3. For the widget to work on your home screen, you may need to grant "Always Allow" location access to Scriptable in Settings > Privacy & Security > Location Services
101+
102+
## ⚙️ Widget Parameters
103+
104+
Configure your widget by adding parameters in the widget settings. Multiple parameters can be combined with commas.
105+
106+
### Available Parameters:
107+
108+
| Parameter | Description | Example |
109+
|-----------|-------------|---------|
110+
| *(empty)* | Default AQI mode with auto theme | No parameter needed |
111+
| `temp` | Switch to temperature mode | `temp` |
112+
| `light` | Force light theme (colorful backgrounds) | `light` |
113+
| `dark` | Force dark theme (dark backgrounds) | `dark` |
114+
| `temp,light` | Temperature mode with light theme | `temp,light` |
115+
| `temp,dark` | Temperature mode with dark theme | `temp,dark` |
116+
117+
### Parameter Examples:
118+
119+
- **Default AQI Mode**: Leave parameter field empty
120+
- **AQI with Light Theme**: `light`
121+
- **AQI with Dark Theme**: `dark`
122+
- **Temperature Mode**: `temp`
123+
- **Temperature with Light Theme**: `temp,light`
124+
- **Temperature with Dark Theme**: `temp,dark`
125+
126+
## 📊 AQI Color Coding
127+
128+
The widget follows US EPA Air Quality Index standards:
129+
130+
| AQI Range | Level | Color | Health Implications |
131+
|-----------|-------|-------|-------------------|
132+
| 0-50 | Good | 🟢 Green | Air quality is satisfactory |
133+
| 51-100 | Moderate | 🟡 Yellow | Acceptable for most people |
134+
| 101-150 | Unhealthy for Sensitive Groups | 🟠 Orange | Sensitive individuals may experience problems |
135+
| 151-200 | Unhealthy | 🔴 Red | Everyone may experience problems |
136+
| 201-300 | Very Unhealthy | 🟣 Purple | Health alert for everyone |
137+
| 301+ | Hazardous | 🟤 Maroon | Emergency conditions |
138+
139+
## 🌡️ Temperature Color Coding
140+
141+
Temperature mode uses different color schemes based on temperature ranges:
142+
143+
| Temperature | Color Scheme | Description |
144+
|-------------|--------------|-------------|
145+
| 35°C+ (95°F+) | Red to Dark Red | Very Hot |
146+
| 25-34°C (77-93°F) | Orange | Warm |
147+
| 15-24°C (59-76°F) | Blue | Comfortable |
148+
| Below 15°C (59°F) | Light Blue | Cool |
149+
150+
## 🎨 Dark Mode vs Light Mode
151+
152+
**Important Theme Information:**
153+
154+
### Auto Theme (Default)
155+
- Automatically adapts to your device's appearance setting
156+
- **Light Mode**: Shows colorful backgrounds as seen in examples
157+
- **Dark Mode**: Shows dark/black backgrounds with colored text
158+
159+
### Force Light Theme
160+
- Add `light` parameter to always show colorful backgrounds
161+
- Recommended if you prefer the colorful appearance regardless of your device theme
162+
- Example: Set parameter to `light` or `temp,light`
163+
164+
### Force Dark Theme
165+
- Add `dark` parameter to always show dark backgrounds
166+
- Text and accents will be colored, background remains dark
167+
- Example: Set parameter to `dark` or `temp,dark`
168+
169+
## 📷 Widget Examples
170+
171+
> **Note:** All screenshots below show the widget in **light mode** with colorful backgrounds. If your device is in dark mode and you want these colorful backgrounds, add `"light"` to your widget parameter.
172+
173+
### 🌍 Air Quality Index (AQI) Mode
174+
175+
| AQI Level | Example | Description |
176+
|-----------|---------|-------------|
177+
| Hazardous (350 AQI) | ![Hazardous AQI](https://github.com/rushhiii/Scriptable-IOSWidgets/blob/main/.assets/aqi/openweatheraqi_s_1.png) | Purple/Maroon background, shows severe air pollution |
178+
| Moderate (51 AQI) | ![Moderate AQI](https://github.com/rushhiii/Scriptable-IOSWidgets/blob/main/.assets/aqi/openweatheraqi_s_2.png) | Yellow background, acceptable air quality |
179+
180+
**AQI Mode displays:**
181+
- "AIR QUALITY" header
182+
- AQI level name (Good, Moderate, Unhealthy, etc.)
183+
- Numerical AQI value (large font)
184+
- City name
185+
- PM2.5 and PM10 values
186+
- Last updated time
187+
- SF Symbol icon indicating air quality level
188+
189+
### 🌡️ Temperature Mode
190+
191+
| Temperature Range | Example | Description |
192+
|-------------------|---------|-------------|
193+
| Cool Weather (23°C) | ![Cool Temperature](https://github.com/rushhiii/Scriptable-IOSWidgets/blob/main/.assets/aqi/openweatheraqi_s_3.png) | Blue background for comfortable temperatures |
194+
195+
**Temperature Mode displays:**
196+
- Large current temperature
197+
- Daily high and low temperatures
198+
- Temperature difference from "feels like"
199+
- Daily temperature range
200+
- City name
201+
202+
## 🔍 Widget Information Display
203+
204+
### AQI Mode Layout:
205+
```
206+
┌─────────────────────┐
207+
│ AIR QUALITY 🔶 │
208+
│ Moderate │
209+
│ │
210+
│ 51 │
211+
│ │
212+
│ Woodbridge │
213+
│ PM2.5: 12.2│PM10: 12.5│
214+
│ Updated 7:05 PM │
215+
└─────────────────────┘
216+
```
217+
218+
### Temperature Mode Layout:
219+
```
220+
┌─────────────────────┐
221+
│ │
222+
│ 23° │
223+
│ │
224+
│ High 23° Low 21° │
225+
│ 1° warmer than feels│
226+
│ like │
227+
│ 2° range today │
228+
│ │
229+
│ Woodbridge │
230+
└─────────────────────┘
231+
```
232+
233+
## 🛠️ Troubleshooting
234+
235+
### Common Issues:
236+
237+
**1. Widget shows "Error" message:**
238+
- Verify your API key is correct and active
239+
- Check internet connection
240+
- Ensure location services are enabled for Scriptable
241+
242+
**2. Location not detected:**
243+
- Go to Settings > Privacy & Security > Location Services
244+
- Find Scriptable and set to "While Using App" or "Always"
245+
- Try running the script manually in Scriptable first
246+
247+
**3. Widget appears black (in dark mode):**
248+
- This is normal behavior when your device is in dark mode
249+
- Add `light` parameter to force colorful backgrounds
250+
- Or add `dark` parameter for a consistent dark theme
251+
252+
**4. Data not updating:**
253+
- Widgets automatically refresh based on iOS system scheduling
254+
- Manually refresh by tapping the widget
255+
- Check if you've exceeded API rate limits (1,000 calls/day on free tier)
256+
257+
**5. Wrong location displayed:**
258+
- The widget uses your device's current location
259+
- Ensure location services are enabled and working
260+
- The script doesn't support manual location setting
261+
262+
### API Rate Limits:
263+
- Free OpenWeatherMap accounts allow 1,000 API calls per day
264+
- Each widget refresh uses 2 API calls (1 for weather, 1 for AQI)
265+
- This allows approximately 500 widget refreshes per day
266+
- iOS typically refreshes widgets 10-20 times per day
267+
268+
## 📱 iOS Compatibility
269+
270+
- **Requires**: iOS 14+ (for widget support)
271+
- **App**: Scriptable (free on App Store)
272+
- **Widget Size**: Small (optimized for small widgets only)
273+
- **Permissions**: Location access required
274+
275+
## 🔗 Data Sources
276+
277+
- **Air Quality Data**: [OpenWeatherMap Air Pollution API](https://openweathermap.org/api/air-pollution)
278+
- **Weather Data**: [OpenWeatherMap Current Weather API](https://openweathermap.org/current)
279+
- **AQI Calculation**: Follows US EPA Air Quality Index standards
280+
281+
## 🙌 Feedback & Support
282+
283+
Have questions, suggestions, or issues? Reach out:
284+
285+
- **Instagram**: [@the.tirth12](https://www.instagram.com/the.tirth12)
286+
- **Email**: [rushiofficial1205@gmail.com](mailto:rushiofficial1205@gmail.com)
287+
- **GitHub Issues**: Create an issue in this repository
288+
289+
## 📜 License
290+
291+
This project is licensed under the **MIT License**. Feel free to fork, modify, and share with attribution.
292+
293+
#
294+
295+
<p align="center">
296+
<strong>Enjoy monitoring your air quality and weather! 🌍🌡️</strong><br>
297+
~ RP
298+
</p>

0 commit comments

Comments
 (0)