update readme/missing features
This commit is contained in:
parent
e78a2e275e
commit
35c9831ba8
GPG key ID:
A7B62D657EF764F8
2 changed files with 215 additions and 71 deletions
|
|
@ -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
|
||||
|
|
|
|||
283
README.md
283
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:<shortsha>` 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)
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue