Weather Forecast MVP

A lightweight Python application that provides 3-day ensemble weather forecasts for any city worldwide. It uses probabilistic forecasting to quantify prediction uncertainty.

What It Does

• Geocodes cities to coordinates using Open-Meteo Geocoding API
• Fetches ensemble forecasts from Open-Meteo Ensemble API (multiple weather model runs)
• Computes statistical aggregates per day: mean, percentiles (P10, P50, P90), and uncertainty
• Provides results via CLI or REST API

Setup

Before running anything, set up the virtual environment:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

VS Code Interpreter

If VS Code does not automatically select the repo venv, open the Command Palette and choose Python: Select Interpreter, then pick .venv.

Running the Weather Forecast

CLI (Command Line)

.\scripts\run_cli.ps1 -cities "Paris,NYC" -days 3

Output shows a table with forecast data and saves JSON to outputs/forecast.json.

REST API

Start the API server:

.\scripts\run_api.ps1

Then visit http://localhost:8000/docs for interactive API documentation.

Understanding "Certainty"

Spread = P90 − P10 (range between 90th and 10th percentiles)

• High: spread ≤ 2°C → forecast models largely agree
• Medium: 2°C < spread ≤ 5°C → moderate disagreement
• Low: spread > 5°C → ensemble members diverge significantly

Running Tests

.\scripts\run_tests.ps1              # Run all tests
.\scripts\run_tests.ps1 -coverage    # Run with coverage report

External Dependencies

This application requires internet connectivity to call:

• Open-Meteo Geocoding API – to convert city names to coordinates
• Open-Meteo Ensemble API – to fetch probabilistic forecasts

No API keys required – both services are free and public.