wttr

Weather forecast service written in Zig, based on wttr.in.

Quick Start

# Build
zig build

# Run with defaults
./zig-out/bin/wttr

# With custom configuration
WTTR_LISTEN_PORT=8080 ./zig-out/bin/wttr

Usage

# 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

# Debug build
zig build

# Release build
zig build -Doptimize=ReleaseFast

# Run tests
zig build test

Docker

# 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

# prometheus.yml
scrape_configs:
  - job_name: 'weather'
    static_configs:
      - targets: ['localhost:8002']
    metrics_path: '/London'
    params:
      format: ['p1']

Documentation

• ARCHITECTURE.md - System architecture and design
• API_ENDPOINTS.md - Complete API reference
• MISSING_FEATURES.md - Features not yet implemented

License

See LICENSE