|
1 | | -# 🌬️ AQI Widget |
| 1 | +# 🌬️ AQI Widget + Temp Widget |
2 | 2 |
|
3 | 3 |  |
4 | | - |
5 | | - |
| 4 | + |
| 5 | + |
| 6 | + |
| 7 | + |
| 8 | + |
| 9 | + |
6 | 10 |
|
7 | | -Monitor air quality in your area with real-time Air Quality Index (AQI) data. Stay informed about pollution levels and make better decisions about outdoor activities. |
| 11 | + |
8 | 12 |
|
9 | | - |
| 13 | +A dynamic and customizable air quality and temperature widget built using the [Scriptable app](https://scriptable.app), powered by OpenWeatherMap. This widget displays the air quality index (AQI) and temperature for your location directly on your iOS home screen. |
10 | 14 |
|
11 | | -## ✨ Features |
12 | | - |
13 | | -- 🌬️ **Real-time AQI Data**: Current air quality measurements |
14 | | -- 📍 **Location-based**: Automatic location detection or custom coordinates |
15 | | -- 🎨 **Color-coded Display**: Visual indicators for air quality levels |
16 | | -- 📊 **Detailed Breakdown**: PM2.5, PM10, O3, NO2, SO2, CO levels |
17 | | -- ⚠️ **Health Recommendations**: Suggestions based on current AQI |
18 | | -- 🔄 **Auto Refresh**: Regular updates throughout the day |
19 | | - |
20 | | -## � Screenshots |
21 | | - |
22 | | -### Medium Widget |
23 | | -Comprehensive air quality overview with detailed pollutant breakdown. |
24 | | - |
25 | | -| Medium Widget - Full AQI Dashboard | |
26 | | -|:--:| |
27 | | -|  | |
28 | | - |
29 | | -### Small Widget |
30 | | -Essential AQI information in a compact, glanceable format. |
| 15 | +> **Mention:** Air quality and temperature widget |
| 16 | +> If the links don't work, check the [backup](./backup) folder. |
31 | 17 |
|
32 | | -| Small Widget - AQI Overview | |
33 | | -|:--:| |
34 | | -|  | |
35 | | - |
36 | | -### AQI Level Indicators |
37 | | -Color-coded displays for different air quality levels. |
| 18 | +## ✨ Features |
38 | 19 |
|
39 | | -| Good (Green) | Moderate (Yellow) | Unhealthy (Red) | |
40 | | -|:--:|:--:|:--:| |
41 | | -|  |  |  | |
| 20 | +* 🌡️ **Temperature Display**: Displays current temperature, high, low, and hourly changes. |
| 21 | +* 🌍 **Air Quality Index (AQI)**: Real-time AQI for your location, with color-coded severity. |
| 22 | +* 🌬️ **Pollution Data**: PM2.5, PM10, and other pollutants. |
| 23 | +* 🎨 **Customizable Layout**: Select small, medium, or large widget sizes. |
| 24 | +* 📶 **Offline Fallback**: Automatically switches to cached data when offline. |
42 | 25 |
|
43 | | -### Pollutant Details |
44 | | -Detailed breakdown view showing individual pollutant levels. |
| 26 | +## 🚀 How It Works |
45 | 27 |
|
46 | | -| PM2.5 Focus | Multi-Pollutant | Health Advisory | |
47 | | -|:--:|:--:|:--:| |
48 | | -|  |  |  | |
| 28 | +The widget fetches data from the OpenWeatherMap API to display: |
49 | 29 |
|
50 | | -## �🚀 Quick Setup |
| 30 | +* **Current Temperature** and weather details. |
| 31 | +* **Air Quality Index** based on the OpenWeatherMap AQI scale. |
| 32 | +* **Pollution Levels** for PM2.5, PM10, etc. |
| 33 | +* Customizable icon and color scheme based on AQI severity. |
51 | 34 |
|
52 | | -### 1. Get OpenWeather API Key |
| 35 | +## 🔧 Setup |
53 | 36 |
|
54 | | -1. Visit [OpenWeatherMap](https://openweathermap.org/api) |
55 | | -2. Sign up for a free account |
56 | | -3. Navigate to API Keys section |
57 | | -4. Generate and copy your API key |
| 37 | +### 1. Get OpenWeatherMap API Key |
58 | 38 |
|
59 | | -### 2. Configure the Widget |
| 39 | +1. Go to [OpenWeatherMap](https://openweathermap.org/). |
| 40 | +2. Create an account and generate an API key. |
60 | 41 |
|
61 | | -```javascript |
62 | | -// API Configuration |
63 | | -const API_KEY = "your_openweather_api_key"; |
| 42 | +### 2. Update the Script |
64 | 43 |
|
65 | | -// Location Settings (optional - uses GPS if not set) |
66 | | -const CUSTOM_LAT = null; // e.g., 40.7128 |
67 | | -const CUSTOM_LON = null; // e.g., -74.0060 |
68 | | -``` |
| 44 | +In the `air_widget.js` script, update the `API_KEY` variable with your OpenWeatherMap API key. |
69 | 45 |
|
70 | | -### 3. Install and Run |
71 | | - |
72 | | -1. Download [`OpenWeatherAQI.js`](https://github.com/rushhiii/Scriptable-IOSWidgets/blob/main/AQI%20Widget/OpenWeatherAQI.js) |
73 | | -2. Create new script in Scriptable |
74 | | -3. Paste code and configure settings |
75 | | -4. Add to home screen |
76 | | - |
77 | | -## 📊 AQI Scale & Colors |
78 | | - |
79 | | -| AQI Range | Level | Color | Health Impact | |
80 | | -|-----------|-------|-------|---------------| |
81 | | -| 0-50 | Good | 🟢 Green | Minimal impact | |
82 | | -| 51-100 | Moderate | 🟡 Yellow | Sensitive groups may experience minor issues | |
83 | | -| 101-150 | Unhealthy for Sensitive Groups | 🟠 Orange | Sensitive individuals should limit outdoor activity | |
84 | | -| 151-200 | Unhealthy | 🔴 Red | Everyone may experience health effects | |
85 | | -| 201-300 | Very Unhealthy | 🟣 Purple | Health alert - everyone should avoid outdoor activity | |
86 | | -| 301+ | Hazardous | 🟤 Maroon | Emergency conditions - all outdoor activity discouraged | |
87 | | - |
88 | | -## 📱 Widget Display |
89 | | - |
90 | | -### Small Widget |
91 | | -- Current AQI value |
92 | | -- Air quality level (Good, Moderate, etc.) |
93 | | -- Color-coded background |
94 | | -- Location name |
95 | | - |
96 | | -### Medium Widget |
97 | | -- All small widget features |
98 | | -- Detailed pollutant breakdown |
99 | | -- Health recommendations |
100 | | -- Last update timestamp |
101 | | - |
102 | | -## ⚙️ Customization Options |
103 | | - |
104 | | -### Display Preferences |
105 | | - |
106 | | -```javascript |
107 | | -// Widget configuration |
108 | | -const CONFIG = { |
109 | | - showDetailedPollutants: true, |
110 | | - showHealthAdvice: true, |
111 | | - showLastUpdate: true, |
112 | | - use24HourFormat: true, |
113 | | - temperatureUnit: "celsius" // or "fahrenheit" |
114 | | -}; |
| 46 | +```js |
| 47 | +const API_KEY = "YOUR_API_HERE"; // OpenWeatherMap API key |
115 | 48 | ``` |
116 | 49 |
|
117 | | -### Health Recommendations |
118 | | - |
119 | | -The widget provides contextual advice based on AQI levels: |
120 | | - |
121 | | -- **Good (0-50)**: "Great day for outdoor activities! 🌟" |
122 | | -- **Moderate (51-100)**: "Air quality is acceptable for most people 👍" |
123 | | -- **Unhealthy for Sensitive Groups (101-150)**: "Sensitive individuals should limit outdoor exposure ⚠️" |
124 | | -- **Unhealthy (151-200)**: "Consider reducing outdoor activities 🚫" |
125 | | -- **Very Unhealthy (201-300)**: "Avoid outdoor activities! Stay indoors 🏠" |
126 | | -- **Hazardous (301+)**: "Emergency conditions! Minimize exposure ☣️" |
| 50 | +### 3. Add the Script to Scriptable |
127 | 51 |
|
128 | | -## 🔬 Pollutant Details |
129 | | - |
130 | | -### Primary Pollutants Tracked |
131 | | - |
132 | | -**PM2.5 (Fine Particulate Matter)** |
133 | | -- Size: ≤ 2.5 micrometers |
134 | | -- Sources: Vehicle emissions, industrial processes |
135 | | -- Health impact: Respiratory and cardiovascular issues |
136 | | - |
137 | | -**PM10 (Coarse Particulate Matter)** |
138 | | -- Size: ≤ 10 micrometers |
139 | | -- Sources: Dust, pollen, construction |
140 | | -- Health impact: Respiratory irritation |
141 | | - |
142 | | -**O3 (Ground-level Ozone)** |
143 | | -- Formation: Chemical reaction in sunlight |
144 | | -- Sources: Vehicle and industrial emissions |
145 | | -- Health impact: Lung irritation, breathing difficulties |
146 | | - |
147 | | -**NO2 (Nitrogen Dioxide)** |
148 | | -- Sources: Vehicle emissions, power plants |
149 | | -- Health impact: Respiratory problems, especially for asthmatics |
150 | | - |
151 | | -**SO2 (Sulfur Dioxide)** |
152 | | -- Sources: Fossil fuel combustion, industrial processes |
153 | | -- Health impact: Respiratory system irritation |
154 | | - |
155 | | -**CO (Carbon Monoxide)** |
156 | | -- Sources: Vehicle emissions, incomplete combustion |
157 | | -- Health impact: Reduces oxygen delivery to organs |
158 | | - |
159 | | -## 🌍 Location Services |
160 | | - |
161 | | -### Automatic Location Detection |
162 | | -- Uses iOS GPS services |
163 | | -- Requires location permission for Scriptable |
164 | | -- Updates based on current location |
165 | | - |
166 | | -### Custom Location Setup |
167 | | -```javascript |
168 | | -// Set specific coordinates |
169 | | -const CUSTOM_LAT = 40.7128; // New York City |
170 | | -const CUSTOM_LON = -74.0060; |
171 | | -const USE_CUSTOM_LOCATION = true; |
172 | | -``` |
| 52 | +1. **Option A – Upload Method**: |
173 | 53 |
|
174 | | -### Multiple Locations |
175 | | -You can create multiple widget instances for different locations: |
176 | | -1. Duplicate the script |
177 | | -2. Set different coordinates for each |
178 | | -3. Name them distinctly (e.g., "AQI Home", "AQI Work") |
| 54 | + * Download the [`air_widget.js`](./air_widget.js) script. |
| 55 | + * Move it to the `Scriptable` folder in your **iCloud Drive**. |
179 | 56 |
|
180 | | -## 🔧 Troubleshooting |
| 57 | +2. **Option B – Manual Method**: |
181 | 58 |
|
182 | | -### Common Issues |
| 59 | + * Open Scriptable, tap the **+** icon, and paste the script content. |
| 60 | + * Name the script (e.g., `Smart Air Widget`). |
183 | 61 |
|
184 | | -**"Location not available":** |
185 | | -- Enable Location Services for Scriptable in iOS Settings |
186 | | -- Check internet connection |
187 | | -- Try running script manually first |
| 62 | +### 4. Add Widget to Home Screen |
188 | 63 |
|
189 | | -**API errors:** |
190 | | -- Verify OpenWeather API key is valid |
191 | | -- Check if you've exceeded free tier limits (1000 calls/day) |
192 | | -- Ensure API key has Air Pollution access |
| 64 | +1. Long-press your iOS Home Screen to enter "jiggle mode." |
| 65 | +2. Tap the **+** icon, scroll to add a **Scriptable** widget. |
| 66 | +3. Choose the desired widget size (Small/Medium/Large). |
| 67 | +4. Edit the widget settings: |
193 | 68 |
|
194 | | -**Outdated data:** |
195 | | -- Widget updates every hour automatically |
196 | | -- Manual refresh by running script in Scriptable |
197 | | -- Check OpenWeather service status |
| 69 | + * Select the script (`Smart Air Widget`). |
| 70 | + * Configure widget parameters (temperature, AQI, etc.). |
198 | 71 |
|
199 | | -### API Limits |
| 72 | +## ⚙️ Configure Parameters |
200 | 73 |
|
201 | | -OpenWeather free plan: |
202 | | -- **1,000 API calls per day** |
203 | | -- **Hourly updates** = 24 calls per day |
204 | | -- Well within free limits |
| 74 | +You can modify the following parameters: |
205 | 75 |
|
206 | | -## 🔄 Data Updates |
| 76 | +| Option | Defaults | Change to | |
| 77 | +| ------------------- | ---------------- | ---------------------------------- | |
| 78 | +| Script | Smart Air Widget | Your script name | |
| 79 | +| Parameters | Text | For example, `temp`, `aqi`, `city` | |
| 80 | +| Temperature Display | `temp` | `true` or `false` | |
| 81 | +| AQI Display | `aqi` | `true` or `false` | |
| 82 | +| City | Automatically | Set a specific city | |
207 | 83 |
|
208 | | -### Refresh Schedule |
209 | | -- **Automatic**: Every 60 minutes |
210 | | -- **Manual**: Run script in Scriptable app |
211 | | -- **Background**: Updates when widget is visible |
| 84 | +> Note: The widget will show the temperature and AQI data for your current location by default. You can configure the widget to display specific cities or data. |
212 | 85 |
|
213 | | -### Offline Support |
214 | | -- Caches last known values |
215 | | -- Shows cached data when offline |
216 | | -- Indicates when data is stale |
| 86 | +## 📷 Screenshots |
217 | 87 |
|
218 | | -## 🌟 Pro Tips |
| 88 | +> *Small Widgets* |
219 | 89 |
|
220 | | -### Best Practices |
221 | | -- Check AQI before outdoor workouts |
222 | | -- Use for planning daily activities |
223 | | -- Monitor trends over time |
224 | | -- Share alerts with family members |
| 90 | +| <img src="../.src/air_widget_s.png" width="160"/> | <img src="../.src/air_widget_s_2.png" width="160"/> | |
| 91 | +| :-----------------------------------------------: | :-------------------------------------------------: | |
| 92 | +| Temperature Display | AQI Level | |
225 | 93 |
|
226 | | -### Health-Conscious Usage |
227 | | -- Set up multiple locations (home, work, gym) |
228 | | -- Check before opening windows |
229 | | -- Plan outdoor activities around better AQI times |
230 | | -- Use data to make informed health decisions |
| 94 | +> *Medium Widgets* |
231 | 95 |
|
232 | | -## 📱 Integration Ideas |
| 96 | +| <img src="../.src/air_widget_m.png" width="260"/> | <img src="../.src/air_widget_m_2.png" width="260"/> | |
| 97 | +| :-----------------------------------------------: | :-------------------------------------------------: | |
| 98 | +| Air Quality Info | City & Pollution | |
233 | 99 |
|
234 | | -### With Other Widgets |
235 | | -- Combine with Weather Widget for complete environmental data |
236 | | -- Use alongside Calendar for outdoor event planning |
237 | | -- Pair with Fitness widgets for workout timing |
| 100 | +> *Large Widgets* |
238 | 101 |
|
239 | | -### Automation Ideas |
240 | | -- iOS Shortcuts integration for AQI-based notifications |
241 | | -- Combine with smart home systems |
242 | | -- Weather app comparison and validation |
| 102 | +| <img src="../.src/air_widget_l.png" width="360"/> | <img src="../.src/air_widget_l_2.png" width="360"/> | |
| 103 | +| :-----------------------------------------------: | :-------------------------------------------------: | |
| 104 | +| Full Data View | Detailed City Info | |
243 | 105 |
|
244 | | -## 📝 License |
| 106 | +## 🙌 Feedback |
245 | 107 |
|
246 | | -This project is licensed under the MIT License - see the [LICENSE](https://github.com/rushhiii/Scriptable-IOSWidgets/blob/main/LICENSE) file for details. |
| 108 | +Have suggestions or issues? DM me on [Instagram](https://www.instagram.com/the.tirth12) or email at [rushiofficial1205@gmail.com](mailto:rushiofficial1205@gmail.com). |
247 | 109 |
|
248 | | -## 🤝 Contributing |
| 110 | +## 📜 License |
249 | 111 |
|
250 | | -Help improve air quality monitoring: |
| 112 | +This project is licensed under the **MIT License**. |
251 | 113 |
|
252 | | -1. [Report issues](https://github.com/rushhiii/Scriptable-IOSWidgets/issues) |
253 | | -2. [Suggest features](https://github.com/rushhiii/Scriptable-IOSWidgets/discussions) |
254 | | -3. Share customizations and improvements |
255 | | -4. Help with translations for international users |
| 114 | +Feel free to fork, build upon, and remix with attribution. |
256 | 115 |
|
257 | | ---- |
| 116 | +## |
258 | 117 |
|
259 | | -**Made with ❤️ by [rushhiii](https://github.com/rushhiii)** | **Stay safe, breathe clean! 🌱** |
| 118 | +<p align="center"> |
| 119 | +Enjoy using this widget ~ RP |
| 120 | +</p> |
0 commit comments