# wttr

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
```

## Usage

```bash
# Weather for your location (based on IP)
curl localhost:8002/

# Weather for a specific city
curl localhost:8002/London

# Weather for coordinates
curl localhost:8002/51.5074,-0.1278

# One-line format
curl localhost:8002/London?format=3

# JSON output
curl localhost:8002/London?format=j1
```

## 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 |
| `IP2LOCATION_API_KEY` | (none) | Optional IP geolocation fallback |

## External Services

### Required (No API Key)
- **Met.no Weather API** - Weather data provider (free, no registration)

### Optional
- **IP2Location.io** - Fallback IP geolocation
  - Sign up at https://www.ip2location.io/
  - Free tier: 30,000 requests/month
  - Set via `IP2LOCATION_API_KEY` environment variable

### Auto-Downloaded
- **MaxMind GeoLite2 City** - IP geolocation database
  - 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

```bash
# Build image
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)