diff --git a/MISSING_FEATURES.md b/MISSING_FEATURES.md index ba6dee9..1a683f6 100644 --- a/MISSING_FEATURES.md +++ b/MISSING_FEATURES.md @@ -29,3 +29,6 @@ Features not yet implemented in the Zig version: - Calculate dawn, sunrise, zenith, sunset, dusk times - Based on location coordinates and timezone - Display in custom format output + +## 7. Json output +- Does not match wttr.in format diff --git a/README.md b/README.md index 851697f..fbd6bb9 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,217 @@ -# wttr +# wttr — console-oriented weather forecast service -Weather forecast service written in Zig, based on [wttr.in](https://wttr.in). +*wttr* is a console-oriented weather forecast service written in Zig, based on [wttr.in](https://wttr.in). -## Quick Start - -```bash -# Build -zig build - -# Run with defaults -./zig-out/bin/wttr - -# With custom configuration -WTTR_LISTEN_PORT=8080 ./zig-out/bin/wttr -``` +wttr supports various information representation methods like terminal-oriented +ANSI-sequences for console HTTP clients (curl, httpie, or wget), HTML for web +browsers, or PNG for graphical viewers. ## Usage +You can access the service from a shell or from a Web browser: + ```bash -# Weather for your location (based on IP) -curl localhost:8002/ +$ curl localhost:8002 +Weather for City: Paris, France -# Weather for a specific city -curl localhost:8002/London + \ / Clear + .-. 10 – 11 °C + ― ( ) ― ↑ 11 km/h + `-' 10 km + / \ 0.0 mm +``` -# Weather for coordinates -curl localhost:8002/51.5074,-0.1278 +Or in PowerShell: -# One-line format -curl localhost:8002/London?format=3 +```powershell +Invoke-RestMethod http://localhost:8002 +``` -# JSON output -curl localhost:8002/London?format=j1 +Get weather for a specific location by adding it to the URL: + +```bash +$ curl localhost:8002/London +$ curl localhost:8002/Moscow +$ curl localhost:8002/Salt+Lake+City +``` + +If you omit the location name, you'll get the report for your current location based on your IP address. + +Use 3-letter airport codes to get weather at a specific airport: + +```bash +$ curl localhost:8002/muc # Munich International Airport +$ curl localhost:8002/ham # Hamburg Airport +``` + +Look up special locations (attractions, mountains, etc.) by prefixing with `~`: + +```bash +$ curl localhost:8002/~Vostok+Station +$ curl localhost:8002/~Eiffel+Tower +$ curl localhost:8002/~Kilimanjaro +``` + +You can also use IP addresses or domain names (prefixed with `@`): + +```bash +$ curl localhost:8002/@github.com +$ curl localhost:8002/@msu.ru +``` + +To get detailed information, access the help page: + +```bash +$ curl localhost:8002/:help +``` + +## Weather Units + +By default the USCS units are used for the queries from the USA and the metric +system for the rest of the world. You can override this behavior by adding `?u` +or `?m` to a URL: + +```bash +$ curl localhost:8002/Amsterdam?u # USCS (used by default in US) +$ curl localhost:8002/Amsterdam?m # metric (SI) (used by default everywhere except US) +``` + +## One-line output + +For one-line output format, specify the `format` parameter: + +```bash +$ curl localhost:8002/Nuremberg?format=3 +Nuremberg: 🌦 +11⁰C +``` + +Available preconfigured formats: 1, 2, 3, 4 and custom format using percent notation. + +* `format=1`: `🌦 +11⁰C` +* `format=2`: `🌦 🌡️+11°C 🌬️↓4km/h` +* `format=3`: `Nuremberg: 🌦 +11⁰C` +* `format=4`: `Nuremberg: 🌦 🌡️+11°C 🌬️↓4km/h` + +You can specify multiple locations separated with `:`: + +**Note:** Not yet fully implemented - see [MISSING_FEATURES.md](MISSING_FEATURES.md) + +```bash +$ curl localhost:8002/Nuremberg:Hamburg:Berlin?format=3 +Nuremberg: 🌦 +11⁰C +Hamburg: 🌦 +8⁰C +Berlin: 🌦 +8⁰C +``` + +Or process them all at once: + +```bash +$ curl -s 'localhost:8002/{Nuremberg,Hamburg,Berlin}?format=3' +``` + +To specify your own custom output format, use the special `%`-notation: + +``` + c Weather condition emoji + C Weather condition textual name + h Humidity + t Temperature (Actual) + f Temperature (Feels Like) + w Wind + l Location + m Moon phase 🌑🌒🌓🌔🌕🌖🌗🌘 + M Moon day + p Precipitation (mm/3 hours) + P Pressure (hPa) + + D Dawn + S Sunrise + z Zenith + s Sunset + d Dusk +``` + +Example: + +```bash +$ curl localhost:8002/London?format="%l:+%c+%t" +London: ⛅️ +7⁰C +``` + +## Data-rich output format (v2) + +**Note:** Not yet fully implemented - see [MISSING_FEATURES.md](MISSING_FEATURES.md) + +In the data-rich output format (view code `v2`), additional weather and astronomical information is available: + +```bash +$ curl localhost:8002/München?format=v2 +``` + +## JSON output + +To fetch information in JSON format: + +**Note:** Not yet fully implemented - see [MISSING_FEATURES.md](MISSING_FEATURES.md) + +```bash +$ curl localhost:8002/Detroit?format=j1 +``` + +The result will look like: + +```json +{ + "current_condition": [{ + "FeelsLikeC": "25", + "FeelsLikeF": "76", + "cloudcover": "100", + "humidity": "76", + "temp_C": "22", + "temp_F": "72", + "weatherCode": "122", + "weatherDesc": [{"value": "Overcast"}], + "windspeedKmph": "7" + }], + ... +} +``` + +## Prometheus Metrics Output + +**Note:** Not yet implemented - see [MISSING_FEATURES.md](MISSING_FEATURES.md) + +To fetch information in Prometheus format: + +```bash +$ curl localhost:8002/Detroit?format=p1 +``` + +A possible Prometheus configuration: + +```yaml +- job_name: 'wttr_in_detroit' + static_configs: + - targets: ['localhost:8002'] + metrics_path: '/Detroit' + params: + format: ['p1'] +``` + +## Building + +```bash +# Debug build +zig build + +# Release build +zig build -Doptimize=ReleaseSafe + +# Run tests +zig build test + +# Run +./zig-out/bin/wttr ``` ## Configuration @@ -51,8 +231,8 @@ All configuration is via environment variables: ### Required (No API Key) - **Met.no Weather API** - Weather data provider (free, no registration) + - Set METNO_TOS_IDENTIFYING_EMAIL to identify yourself to Met.No -### Optional - **IP2Location.io** - Fallback IP geolocation - Sign up at https://www.ip2location.io/ - Free tier: 30,000 requests/month @@ -63,65 +243,26 @@ All configuration is via environment variables: - Downloaded automatically if missing - Stored in `~/.cache/wttr/GeoLite2-City.mmdb` -## Output Formats - -- **ANSI** (default) - Colored terminal output -- **Line formats** (`?format=1-4`) - One-line weather -- **JSON** (`?format=j1`) - Machine-readable -- **v2** (`?format=v2`) - Data-rich format -- **Custom** (`?format=%l:+%c+%t`) - Custom format string - -## Query Parameters - -- `?u` - Imperial units (°F, mph) -- `?m` - Metric units (°C, km/h) -- `?format=N` - Output format -- `?lang=XX` - Language (auto-detected by default) - -## Building - -```bash -# Debug build -zig build - -# Release build -zig build -Doptimize=ReleaseFast - -# Run tests -zig build test -``` - ## Docker +Prebuilt images are available from https://git.lerch.org/lobo/-/packages/container/wttr/latest +and can be pulled with `docker pull git.lerch.org/lobo/wttr:latest` or +`docker pull git.lerch.org/lobo/wttr:` for a specific revision + + ```bash -# Build image +# Build image. Note the binary must be in the directory docker build -t wttr -f docker/Dockerfile . # Run container docker run -p 8002:8002 wttr ``` -## Prometheus Integration - -**Note:** Not yet implemented - see [MISSING_FEATURES.md](MISSING_FEATURES.md) - -```yaml -# prometheus.yml -scrape_configs: - - job_name: 'weather' - static_configs: - - targets: ['localhost:8002'] - metrics_path: '/London' - params: - format: ['p1'] -``` - ## Documentation - [ARCHITECTURE.md](ARCHITECTURE.md) - System architecture and design -- [API_ENDPOINTS.md](API_ENDPOINTS.md) - Complete API reference - [MISSING_FEATURES.md](MISSING_FEATURES.md) - Features not yet implemented ## License -See [LICENSE](LICENSE) +Apache v2, matching wttr.in project from which this is derived. See [LICENSE](LICENSE)