Skip to content

Commit a1f5304

Browse files
fedjofedjo
authored
Implement Weather Data Caching, API Enhancements, and Documentation (#67)
* Add model, schemas and crud api to cache locations * Add model, schemas, apis to save hourly and daily data from OM and provide them based on nearest loc. If no near loc data are fetch on demand from OM * Fetch and cache last months data. Then use a daily task to get yesterday's data and delete the oldest one (sliding window) * Delete cached location and all related history data * Add default daily, hourly history variables * Add JWT authentication to history, locations api * Add trailing slash to all endpoints (#3) * Add trailing slash to all endpoints * Replace underscore '_' with hyphen '-' in urls * Patch 1 - Update Dockerfile Signed-off-by: fedjo <mari.giorgos@gmail.com> * Register history routes to GK (#4) * Add contribution guide and README (#5) * Add contribution guide and README * Update CONTRIBUTE.md * Fix format * Add project status * Highlight impact * Add version env var * Fix small issue when no gatekeeper * Remove version from compose file * Add authenticatio and OWM Api key section * Typo --------- Signed-off-by: fedjo <mari.giorgos@gmail.com> --------- Signed-off-by: fedjo <mari.giorgos@gmail.com>
1 parent cc9a57c commit a1f5304

28 files changed

Lines changed: 992 additions & 111 deletions

‎CONTRIBUTE.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Contributing to Weather Service
2+
3+
We’re excited that you’re interested in contributing to Weather Service! 🎉
4+
This project is licensed under the EUPL v1.2 and welcomes contributors of all backgrounds and experience levels.
5+
6+
## 🚀 How to Contribute
7+
8+
### Fork & Clone
9+
10+
- Fork the repository on GitHub.
11+
12+
- Clone your fork locally:
13+
14+
git clone https://github.com/your-username/weather-service.git
15+
cd weather-service
16+
17+
### Create a Branch
18+
19+
Always create a new branch for your work:
20+
21+
git checkout -b feature/my-new-feature
22+
23+
### Make Your Changes
24+
25+
Add or update tests when making changes.
26+
27+
### Commit & Push
28+
29+
Write clear, descriptive commit messages:
30+
31+
git commit -m "Add support for caching weather locations"
32+
git push origin feature/my-new-feature
33+
34+
### Open a Pull Request
35+
36+
Go to the main repo and open a PR (Pull Request).
37+
38+
Describe:
39+
40+
- What your change does
41+
42+
- Why it’s needed
43+
44+
- Any related issues
45+
46+
Maintainers will review your PR and may request changes. Don’t worry — feedback is part of the process!
47+
48+
49+
### 📝 Reporting Issues
50+
51+
Check the issue tracker first.
52+
53+
If not already reported, open a new issue with:
54+
55+
- A clear description
56+
57+
- Steps to reproduce (if a bug)
58+
59+
- Expected vs actual behavior
60+
61+
### 🌱 First-Time Contributors
62+
63+
We especially welcome first-time contributors! Some good first steps:
64+
65+
Look for issues labeled good first issue.
66+
67+
Improve documentation (typos, examples, guides).
68+
69+
Add tests for untested parts of the code.
70+
71+
### 🙏 Acknowledgments
72+
73+
Every contribution — big or small — matters. Thank you for helping improve!

‎Dockerfile‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -25,10 +25,6 @@ WORKDIR /weather-service
2525
COPY --from=builder /usr/local/lib/python3.12/site-packages/ /usr/local/lib/python3.12/site-packages/
2626
COPY --from=builder /usr/local/bin/ /usr/local/bin/
2727

28-
# ßshared objects *.so files and fonts for building er-diagram
29-
COPY --from=builder /usr/lib/*-linux-gnu /usr/lib/
30-
COPY --from=builder /usr/share/fonts /usr/share/fonts
31-
3228
ARG USER_ID=1001
3329
ARG GROUP_ID=1001
3430
RUN groupadd -r openagri --gid $GROUP_ID && \
@@ -47,4 +43,4 @@ ENV USER_ID=$USER_ID \
4743
PROJECT_DIR=/weather-service \
4844
PYTHONPATH=/weather-service
4945

50-
CMD ["./run.sh", "prod"]
46+
CMD ["./run.sh", "prod"]

‎README.md‎

Lines changed: 167 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,96 +1,208 @@
11
# Weather Service
22

3-
🇪🇺 *This service was created in the context of OpenAgri project (https://horizon-openagri.eu/). OpenAgri has received funding from the EU’s Horizon Europe research and innovation programme under Grant Agreement no. 101134083.*
3+
[![License: EUPL-1.2](https://img.shields.io/badge/License-EUPL%201.2-blue.svg)](./LICENSE)
4+
![Python](https://img.shields.io/badge/python-3.12+-blue)
5+
![Docker](https://img.shields.io/badge/docker-ready-brightgreen)
46

5-
## Description
6-
Fast, reliable weather API providing 5-day forecasts, agricultural indicators like
7-
[Temperature-Humidity Index](https://www.pericoli.com/en/temperature-humidity-index-what-you-need-to-know-about-it/),
8-
UAV flight condition predictions, and spray condition forecasts. Built with FastAPI for high performance.
9-
Easy to integrate, deploy, and scale.
7+
Fast, reliable weather API with 5-day forecasts, agricultural indicators, UAV flight condition predictions, and spray condition forecasts.
8+
Built with [FastAPI](https://fastapi.tiangolo.com/) for high performance and easy integration.
109

10+
**IMPORTANT**: This project is in an early stage. Some parts are stable, others need refactoring. We welcome contributors who want to help improve tests, documentation, and code quality.
1111

12-
Project is fully functional, compatible with Python 3.12.
13-
Is built using [FastAPI](https://fastapi.tiangolo.com/) framework and served with [Uvicorn](https://www.uvicorn.org).
12+
---
1413

15-
The application is containerized using Docker. To install it please firstly install `docker`
14+
## About
1615

17-
You can follow [this guide](https://docs.docker.com/engine/install/ubuntu/) to install `docker` on Ubuntu.
16+
This service was created in the context of the [OpenAgri project](https://horizon-openagri.eu/), funded by the EU’s Horizon Europe research and innovation programme (Grant Agreement no. 101134083).
1817

19-
## Requirements
20-
- git
21-
- docker
22-
- docker-compose
18+
The Weather Service provides:
2319

24-
## Installation
25-
After installing `docker` you can simply run
20+
- **Forecasts** – 5-day forecasts in JSON and JSON-LD (OCSM) formats
21+
- **Current weather conditions** – temperature, humidity, wind, sky conditions
22+
- **Agricultural indicators** – Temperature-Humidity Index (THI)
23+
- **UAV flight forecasts** – 5-day predictions for UAV flight conditions (by model, filterable)
24+
- **Spray condition forecasts** – support for agricultural spraying planning
25+
- **Historical weather API** – daily and hourly values
26+
- **Offline support** – cache last month’s history for specific locations
27+
- **Containerized builds** – multi-arch Docker images (AMD64 and ARM64)
2628

27-
```
28-
docker compose up --build
29-
```
29+
---
3030

31-
to run the application.
31+
## Roadmap
3232

33-
The application is served by default on `http://127.0.0.1:8000`
33+
High-level next steps for the Weather Service:
3434

35-
## Documentation
35+
- [ ] Connect with local weather stations for improved ground-truth data
36+
- [ ] Integrate with additional 3rd party weather APIs
37+
- [ ] Enhance accuracy of weather, UAV, and spray forecasts by combining multiple data sources
3638

37-
**GET**
38-
```
39-
/api/data/forecast5?lat={latitude}&lon={longitude}
40-
```
41-
Retrieves a 5-day weather forecast with 3-hour intervals for a specific location. Response is in standard JSON format
39+
---
4240

43-
**GET**
44-
```
45-
/api/linkeddata/forecast5?lat={latitude}&lon={longitude}
46-
```
47-
Retrieves the same 5-day weather forecast with 3-hour intervals, but returns data in OCSM JSON-LD format
41+
## Quickstart
42+
43+
### Requirements
44+
45+
- `git`
46+
- `docker`
47+
- `docker-compose`
48+
49+
### Installation
50+
51+
## Clone repository:
4852

49-
**GET**
53+
```bash
54+
git clone https://github.com/openagri-eu/OpenAgri-WeatherService.git
55+
cd OpenAgri-WeatherService
56+
cp env.example .env
5057
```
51-
/api/data/thi?lat={latitude}&lon={longitude}
58+
You will then need to grab an api key for OpenWeatherMap API
59+
60+
## Getting an OpenWeather API Key
61+
62+
Some features of Weather Service use the [OpenWeather API](https://openweathermap.org/api).
63+
You’ll need your own API key to enable those calls.
64+
65+
1. Create a free account at [openweathermap.org](https://home.openweathermap.org/users/sign_up).
66+
2. After signing up, go to your [API keys page](https://home.openweathermap.org/api_keys).
67+
3. Copy the **default key** or generate a new one.
68+
4. Add it to your `.env` file:
69+
```env
70+
WEATHER_SRV_OPENWEATHERMAP_API_KEY=your-api-key-here
71+
```
72+
## Build & Run the service
73+
74+
```bash
75+
docker compose up
5276
```
53-
Provides the Temperature Humidity Index for a specific location in standard JSON format
5477

55-
**GET**
78+
By default, the API documentation is available at:
79+
80+
http://127.0.0.1:8010/docs
81+
82+
To build local docker image:
83+
```bash
84+
docker compose up --build
5685
```
57-
/api/linkeddata/thi?lat={latitude}&lon={longitude}
86+
87+
## Authentication
88+
89+
All API endpoints require a JWT.
90+
91+
### Get a token
92+
Request a token using the dev credentials:
93+
94+
```bash
95+
curl -X 'POST' \
96+
'http://localhost:8010/api/v1/auth/token' \
97+
-H 'Content-Type: application/x-www-form-urlencoded' \
98+
-d 'grant_type=&username=test&password=test&scope=&client_id=&client_secret='
5899
```
59-
Provides the Temperature Humidity Index for a specific location in OCSM JSON-LD format
60100

61-
**GET**
101+
**Response:**
102+
```bash
103+
{"jwt_token": "<JWT>"}
62104
```
63-
/api/data/flight_forecast5/{uavmodel}?lat={latitude}&lon={longitude}
105+
106+
**Use the token**
107+
108+
Pass the token as a Bearer header:
109+
```bash
110+
TOKEN="<paste JWT here>"
111+
curl -s "http://127.0.0.1:8010/api/data/weather/?lat=35.0&lon=33.23/?lat=35.0&lon=33.23" \
112+
-H "Authorization: Bearer $TOKEN"
64113
```
65-
Retrieves a 5-day flight forecast with 3-hour intervals for a specific UAV model at the given location.
66-
Response is in standard JSON format
67114

68-
**GET**
115+
Tip: In Swagger UI (/docs), click Authorize and paste `Bearer <JWT>`.
116+
117+
## API Overview
118+
119+
### Forecasts
120+
121+
- `GET /api/data/forecast5/?lat={lat}&lon={lon}` – 5-day forecast (3-hour intervals, JSON)
122+
- `GET /api/linkeddata/forecast5/?lat={lat}&lon={lon}` – 5-day forecast (JSON-LD/OCSM)
123+
124+
### Temperature-Humidity Index (THI)
125+
126+
- `GET /api/data/thi/?lat={lat}&lon={lon}` – THI (JSON)
127+
- `GET /api/linkeddata/thi/?lat={lat}&lon={lon}` – THI (JSON-LD/OCSM)
128+
129+
### UAV Flight Forecast
130+
131+
- `GET /api/data/flight_forecast5/{uavmodel}/?lat={lat}&lon={lon}` – 5-day UAV forecast (by model)
132+
- `GET /api/data/flight_forecast5/?lat={lat}&lon={lon}&uavmodels={model}&status_filter={status}` – 5-day UAV forecast (filterable)
133+
134+
### Current Weather
135+
136+
- `GET /api/data/weather/?lat={lat}&lon={lon}` – Current conditions (JSON)
137+
138+
### Historical weather data
139+
140+
- `POST /api/v1/history/hourly/` - Hourly history
141+
- `POST /api/v1/history/daily/` - Daily history
142+
143+
---
144+
145+
## Documentation
146+
147+
- Interactive API docs: [http://127.0.0.1:8010/docs](http://127.0.0.1:8010/docs) (Swagger UI)
148+
- Full OpenAPI specification (JSON + OCSM JSON-LD) available via endpoints
149+
- Use [Swagger Editor](https://editor.swagger.io/) to explore the API specification
150+
151+
---
152+
153+
## Example Requests
154+
155+
### Current Weather
156+
157+
```bash
158+
curl "http://127.0.0.1:8010/api/data/weather?lat=35.2&lon=33.3"
69159
```
70-
/api/data/flight_forecast5?lat={latitude}&lon={longitude}&uavmodels={model}&status_filter={status}
160+
**Sample response:**
161+
162+
```json
163+
{
164+
"temperature": 28.5,
165+
"humidity": 62,
166+
"wind_speed": 4.2,
167+
"conditions": "Clear sky",
168+
"timestamp": "2025-09-18T12:00:00Z"
169+
}
71170
```
72-
Retrieves a 5-day flight forecast with 3-hour intervals for UAVs at a specific location.
73-
You can filter results by UAV model types and status conditions. Response is in standard JSON format
74171

172+
### 5-Day Forecast
75173

76-
**GET**
174+
```bash
175+
curl "http://127.0.0.1:8010/api/data/forecast5?lat=35.2&lon=33.3"
77176
```
78-
/api/data/weather?lat={latitude}&lon={longitude}
177+
178+
### Daily history
179+
```bash
180+
curl -X POST "http://127.0.0.1:8010/api/v1/history/daily" \
181+
-H "Content-Type: application/json" \
182+
-d '{
183+
"lat": 35.0,
184+
"lon": 33.2,
185+
"start": "2025-07-01",
186+
"end": "2025-07-03",
187+
"variables": ["temperature_2m_max", "temperature_2m_min"],
188+
"radius_km": 10
189+
}'
79190
```
80-
Returns current weather conditions for a specific location in standard JSON format
81191

82-
Get a complete list of the OpenApi specification compatible with [OCSM](OCSM.md) and [JSON](API.md)
192+
## Contributing
193+
194+
We welcome first-time contributions!
83195

84-
## Swagger Live Docs
85-
Use the [Online Swagger Editor](https://editor-next.swagger.io/?url=https://raw.githubusercontent.com/agstack/openagri-weather-service/refs/heads/main/openapi.yml) to visualise the current API specification and documentation.
196+
See our [Contributing Guide](CONTRIBUTE.md)
86197

87-
## Contribute
198+
You can also open an issue to discuss ideas.
88199

89-
Please contanct the repository maintainer.
200+
Weather Service is part of OpenAgri project, building tools for agriculture & climate data. Your contribution helps farmers and researchers.
90201

91202
## License
92203

93-
[European Union Public Licence](LICENSE)
204+
This project is licensed under the European Union Public Licence (EUPL) v1.2.
205+
See the [European Union Public Licence](LICENSE) file for details.
94206

95207

96208

‎docker-compose.yml‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,6 @@
1-
version: '3'
2-
3-
41
services:
52
app:
6-
image: ghcr.io/openagri-eu/weather-service:${TAG}
3+
image: ghcr.io/openagri-eu/openagri-weatherservice:${TAG}
74
build: .
85
depends_on:
96
- mongodb

.env.example renamed to env.example

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
# Version
2+
TAG=latest
3+
14
# Weather service
25
LOGGING_LEVEL=DEBUG
36
WEATHER_SRV_PORT=8010

0 commit comments

Comments
 (0)