267 lines
6.4 KiB
Markdown
267 lines
6.4 KiB
Markdown
# wttr — console-oriented weather forecast service
|
||
|
||
*wttr* is a console-oriented weather forecast service written in Zig, based on [wttr.in](https://wttr.in).
|
||
|
||
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
|
||
$ curl localhost:8002
|
||
Weather for City: Paris, France
|
||
|
||
\ / Clear
|
||
.-. 10 – 11 °C
|
||
― ( ) ― ↑ 11 km/h
|
||
`-' 10 km
|
||
/ \ 0.0 mm
|
||
```
|
||
|
||
Or in PowerShell:
|
||
|
||
```powershell
|
||
Invoke-RestMethod http://localhost:8002
|
||
```
|
||
|
||
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`
|
||
|
||
**Note:** Wttr.in claims that you can do multiple locations at one with a ':'
|
||
separator, but that does not appear to work
|
||
|
||
```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
|
||
|
||
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
|
||
|
||
All configuration is via environment variables:
|
||
|
||
| Variable | Default | Description |
|
||
|----------|---------|-------------|
|
||
| `WTTR_LISTEN_HOST` | `0.0.0.0` | Listen address |
|
||
| `WTTR_LISTEN_PORT` | `8002` | Listen port |
|
||
| `WTTR_CACHE_DIR` | `~/.cache/wttr` | Cache directory |
|
||
| `WTTR_CACHE_SIZE` | `10000` | Max cached responses |
|
||
| `WTTR_GEOLITE_PATH` | `~/.cache/wttr/GeoLite2-City.mmdb` | GeoIP database path |
|
||
| `WTTR_GEOCACHE_FILE` | `~/.cache/wttr/geocache.json` | Location name cache |
|
||
| `IP2LOCATION_API_KEY` | (none) | Optional IP geolocation fallback |
|
||
| `IP2LOCATION_CACHE_FILE` | `~/.cache/wttr/ip2location.cache` | IP2Location cache file |
|
||
| `METNO_TOS_IDENTIFYING_EMAIL` | (none) | Email for Met.no API identification |
|
||
|
||
## External Services
|
||
|
||
### Required
|
||
- **Met.no Weather API** - Weather data provider (free, no registration)
|
||
- Set METNO_TOS_IDENTIFYING_EMAIL to identify yourself to Met.No
|
||
- **IP2Location.io** - IP geolocation service
|
||
- Sign up at https://www.ip2location.io/
|
||
- Free tier: 30,000 requests/month
|
||
- Set `IP2LOCATION_API_KEY` environment variable for higher limits
|
||
|
||
### Auto-Downloaded
|
||
- **MaxMind GeoLite2 City** - IP geolocation database
|
||
- Downloaded automatically if missing
|
||
- Stored in `~/.cache/wttr/GeoLite2-City.mmdb`
|
||
|
||
## 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:<shortsha>` for a specific revision
|
||
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
|
||
## Documentation
|
||
|
||
- [ARCHITECTURE.md](ARCHITECTURE.md) - System architecture and design
|
||
- [MISSING_FEATURES.md](MISSING_FEATURES.md) - Features not yet implemented
|
||
|
||
## License
|
||
|
||
Apache v2, matching wttr.in project from which this is derived. See [LICENSE](LICENSE)
|