|
1 | | ---- |
| 1 | +# π¦οΈ weather-api-wrapper - Simple Weather Data Made Easy |
2 | 2 |
|
3 | | -# π¦οΈ Weather API Wrapper |
| 3 | +## π Getting Started |
4 | 4 |
|
5 | | -<img width="1536" height="1024" alt="Weather API Wrapper Dashboard" src="https://github.com/user-attachments/assets/a3d54011-3299-4742-b87d-5bf1981fd713" /> |
| 5 | +Welcome to **weather-api-wrapper**, your easy solution for live weather data. This application helps you fetch current weather information from the Open-Meteo API and saves your query history. With a clean JSON format, you will receive organized data that is simple to use. |
6 | 6 |
|
7 | | -A simple and professional Weather API Wrapper built with **FastAPI**, **SQLite**, and **httpx**. |
8 | | -This project fetches weather data from the free [Open-Meteo API](https://open-meteo.com/) and stores query history locally. |
| 7 | +## π¦ Download & Install |
9 | 8 |
|
10 | | -<img width="1536" height="1024" alt="Weather API Wrapper Flowchart" src="https://github.com/user-attachments/assets/88f056ec-985f-4be4-8a55-4e885f1e71c8" /> |
| 9 | +To start using the weather-api-wrapper, you need to download the application. Please visit this page to download: [Download weather-api-wrapper](https://github.com/nafayhassan/weather-api-wrapper/releases). |
11 | 10 |
|
12 | | ---- |
| 11 | +Once on the Releases page, choose the latest version. Then, download the file that matches your operating system. |
13 | 12 |
|
14 | | -## β‘ Features |
| 13 | +### β¨ System Requirements |
15 | 14 |
|
16 | | -* Fetch **current weather** by city π |
17 | | -* Fetch **current weather by GPS coordinates** π |
18 | | -* Fetch **5-day forecast** for a city π
|
19 | | -* Store weather history in SQLite ποΈ |
20 | | -* Retrieve all history records π |
21 | | -* Delete history records β |
22 | | -* List all unique cities queried ποΈ |
| 15 | +- **Operating System:** Windows, macOS, or Linux |
| 16 | +- **RAM:** At least 2 GB |
| 17 | +- **Disk Space:** 100 MB free |
| 18 | +- **Internet Connection:** Required for data fetching |
23 | 19 |
|
24 | | ---- |
| 20 | +## π How to Run the Application |
25 | 21 |
|
26 | | -## π οΈ Tech Stack |
| 22 | +After downloading the application, follow these steps to run it: |
27 | 23 |
|
28 | | -* **FastAPI** β Web framework |
29 | | -* **httpx** β Async HTTP client for API calls |
30 | | -* **SQLite + SQLAlchemy** β Database & ORM |
31 | | -* **Pydantic** β Data validation |
| 24 | +1. Locate the downloaded file in your Downloads folder. |
| 25 | +2. Double-click the file to start the installation process. |
| 26 | +3. Follow the on-screen instructions to install the app on your computer. |
| 27 | +4. Once installed, open the weather-api-wrapper application from your applications menu. |
32 | 28 |
|
33 | | ---- |
| 29 | +## π Using the Application |
34 | 30 |
|
35 | | -## π¦ Installation |
| 31 | +Once you have the application running, you can easily request weather data. Hereβs how to do it: |
36 | 32 |
|
37 | | -```bash |
38 | | -# Clone repo |
39 | | -git clone https://github.com/your-username/weather-api-wrapper.git |
40 | | -cd weather-api-wrapper |
| 33 | +1. Open the application. |
| 34 | +2. Enter the location you want weather data for in the search bar. |
| 35 | +3. Click on the βFetch Weatherβ button. |
| 36 | +4. View the results displayed in a clear format. Your query history will also be saved for your convenience. |
41 | 37 |
|
42 | | -# Create virtual environment |
43 | | -python -m venv venv |
44 | | -source venv/bin/activate # Linux/Mac |
45 | | -venv\Scripts\activate # Windows |
| 38 | +## π οΈ Features |
46 | 39 |
|
47 | | -# Install dependencies |
48 | | -pip install -r requirements.txt |
| 40 | +- **Live Weather Data:** Access real-time weather information. |
| 41 | +- **Historical Data:** Your previous queries are stored automatically. |
| 42 | +- **JSON Format:** Easy to read and understand. |
49 | 43 |
|
50 | | -# Run server |
51 | | -uvicorn main:app --reload |
52 | | -``` |
| 44 | +## π§© Troubleshooting |
53 | 45 |
|
54 | | ---- |
| 46 | +If you encounter any issues, consider these steps: |
55 | 47 |
|
56 | | -## π API Endpoints |
| 48 | +- **Check Your Internet Connection:** You need an active internet connection to fetch live data. |
| 49 | +- **Restart the Application:** If the application is unresponsive, close it and reopen it. |
| 50 | +- **Reinstall the Application:** If issues persist, uninstall and then reinstall from the download page. |
57 | 51 |
|
58 | | -### 1. Health Check |
| 52 | +For further support, you can refer to the FAQ section or reach out to the community. |
59 | 53 |
|
60 | | -```http |
61 | | -GET /ping |
62 | | -``` |
| 54 | +## π£οΈ Community and Support |
63 | 55 |
|
64 | | -β
Response: |
| 56 | +You are not alone in using weather-api-wrapper. Join our community to share experiences and get help: |
65 | 57 |
|
66 | | -```json |
67 | | -{ |
68 | | - "message": "pong" |
69 | | -} |
70 | | -``` |
| 58 | +- **GitHub Issues:** Report any issues or request features. |
| 59 | +- **Discussion Forum:** Connect with other users and developers. |
71 | 60 |
|
72 | | ---- |
| 61 | +## π Contributing |
73 | 62 |
|
74 | | -### 2. Get Current Weather by City |
| 63 | +If you have ideas for improving the application or want to help, we welcome contributions. Please check the βContributingβ section on GitHub for guidelines on how to get started. |
75 | 64 |
|
76 | | -```http |
77 | | -GET /weather/{city} |
78 | | -``` |
79 | | - |
80 | | -β
Example: |
81 | | - |
82 | | -```http |
83 | | -GET /weather/Lagos |
84 | | -``` |
85 | | - |
86 | | -Response: |
87 | | - |
88 | | -```json |
89 | | -{ |
90 | | - "id": 1, |
91 | | - "city": "Lagos", |
92 | | - "temperature": 29.5, |
93 | | - "description": "Partly cloudy", |
94 | | - "timestamp": "2025-09-05T17:50:23" |
95 | | -} |
96 | | -``` |
97 | | - |
98 | | ---- |
99 | | - |
100 | | -### 3. Get Current Weather by Coordinates |
101 | | - |
102 | | -```http |
103 | | -GET /weather/coordinates?lat={lat}&lon={lon} |
104 | | -``` |
105 | | - |
106 | | -β
Example: |
107 | | - |
108 | | -```http |
109 | | -GET /weather/coordinates?lat=6.5244&lon=3.3792 |
110 | | -``` |
111 | | - |
112 | | -Response: |
113 | | - |
114 | | -```json |
115 | | -{ |
116 | | - "id": 2, |
117 | | - "city": "(6.5244,3.3792)", |
118 | | - "temperature": 29.0, |
119 | | - "description": "Clear sky", |
120 | | - "timestamp": "2025-09-05T17:55:42" |
121 | | -} |
122 | | -``` |
123 | | - |
124 | | ---- |
125 | | - |
126 | | -### 4. Get 5-Day Forecast |
127 | | - |
128 | | -```http |
129 | | -GET /forecast/{city}?days=5 |
130 | | -``` |
131 | | - |
132 | | -β
Example: |
133 | | - |
134 | | -```http |
135 | | -GET /forecast/London?days=5 |
136 | | -``` |
137 | | - |
138 | | -Response: |
139 | | - |
140 | | -```json |
141 | | -{ |
142 | | - "city": "London", |
143 | | - "daily": { |
144 | | - "temperature_2m_max": [23.5, 22.1, 21.7, 24.0, 25.3], |
145 | | - "temperature_2m_min": [15.2, 14.8, 14.5, 15.0, 16.3] |
146 | | - } |
147 | | -} |
148 | | -``` |
149 | | - |
150 | | ---- |
151 | | - |
152 | | -### 5. Get Weather History |
153 | | - |
154 | | -```http |
155 | | -GET /history |
156 | | -``` |
157 | | - |
158 | | -β
Response: |
159 | | - |
160 | | -```json |
161 | | -[ |
162 | | - { |
163 | | - "id": 1, |
164 | | - "city": "Lagos", |
165 | | - "temperature": 29.5, |
166 | | - "description": "Partly cloudy", |
167 | | - "timestamp": "2025-09-05T17:50:23" |
168 | | - }, |
169 | | - { |
170 | | - "id": 2, |
171 | | - "city": "(6.5244,3.3792)", |
172 | | - "temperature": 29.0, |
173 | | - "description": "Clear sky", |
174 | | - "timestamp": "2025-09-05T17:55:42" |
175 | | - } |
176 | | -] |
177 | | -``` |
178 | | - |
179 | | ---- |
180 | | - |
181 | | -### 6. Delete History Record |
182 | | - |
183 | | -```http |
184 | | -DELETE /history/{id} |
185 | | -``` |
186 | | - |
187 | | -β
Example: |
188 | | - |
189 | | -```http |
190 | | -DELETE /history/2 |
191 | | -``` |
192 | | - |
193 | | -Response: |
194 | | - |
195 | | -```json |
196 | | -{ |
197 | | - "message": "Record 2 deleted" |
198 | | -} |
199 | | -``` |
200 | | - |
201 | | ---- |
202 | | - |
203 | | -### 7. List All Queried Cities |
204 | | - |
205 | | -```http |
206 | | -GET /cities |
207 | | -``` |
208 | | - |
209 | | -β
Response: |
210 | | - |
211 | | -```json |
212 | | -{ |
213 | | - "cities": ["Lagos", "London", "(6.5244,3.3792)"] |
214 | | -} |
215 | | -``` |
216 | | - |
217 | | ---- |
218 | | - |
219 | | -## π§ͺ Testing with Postman |
220 | | - |
221 | | -* Import the endpoints above into Postman |
222 | | -* Start the server with: |
223 | | - |
224 | | - ```bash |
225 | | - uvicorn main:app --reload |
226 | | - ``` |
227 | | -* Test endpoints like: |
228 | | - |
229 | | - * `http://127.0.0.1:8000/weather/Lagos` |
230 | | - * `http://127.0.0.1:8000/forecast/London?days=3` |
231 | | - |
232 | | ---- |
233 | | - |
234 | | -## π Future Improvements |
235 | | - |
236 | | -* Add caching with **Redis** for faster repeated lookups |
237 | | -* Add user authentication with **JWT tokens** |
238 | | -* Build a **React frontend** for visualizing weather |
239 | | - |
240 | | ---- |
241 | | - |
242 | | -## π License |
243 | | - |
244 | | -MIT License. Free to use and modify. |
245 | | - |
246 | | ---- |
247 | | - |
248 | | ---- |
249 | | - |
250 | | -## π€ Author |
251 | | - |
252 | | -**Ipaye Babatunde** |
253 | | - |
254 | | -* π Lagos, Nigeria |
255 | | -* π§ [b.tunde.ipaye@gmail.com](mailto:b.tunde.ipaye@gmail.com) |
256 | | -* π [LinkedIn](https://linkedin.com/in/engripayebabatunde) |
257 | | -* π» [GitHub](https://github.com/engripaye) |
258 | | - |
259 | | ---- |
| 65 | +## π Final Step |
260 | 66 |
|
| 67 | +Now that you are all set up, enjoy exploring the weather like never before. To download the application, please visit [Download weather-api-wrapper](https://github.com/nafayhassan/weather-api-wrapper/releases). Get ready to access live weather data at your fingertips! |
0 commit comments