wttr — console-oriented weather forecast service

wttr is a console-oriented weather forecast service written in Zig, based on 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:

$ curl localhost:8002
Weather for City: Paris, France

     \   /     Clear
      .-.      10 – 11 °C
   ― (   ) ―   ↑ 11 km/h
      `-'      10 km
     /   \     0.0 mm

Or in PowerShell:

Invoke-RestMethod http://localhost:8002

Get weather for a specific location by adding it to the URL:

$ 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:

$ curl localhost:8002/muc      # Munich International Airport
$ curl localhost:8002/ham      # Hamburg Airport

Look up special locations (attractions, mountains, etc.) by prefixing with ~:

$ 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 @):

$ curl localhost:8002/@github.com
$ curl localhost:8002/@msu.ru

To get detailed information, access the help page:

$ 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:

$ 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:

$ 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

$ curl localhost:8002/Nuremberg:Hamburg:Berlin?format=3
Nuremberg: 🌦 +11⁰C
Hamburg: 🌦 +8⁰C
Berlin: 🌦 +8⁰C

Or process them all at once:

$ 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:

$ 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

In the data-rich output format (view code v2), additional weather and astronomical information is available:

$ curl localhost:8002/München?format=v2

JSON output

To fetch information in JSON format:

Note: Not yet fully implemented - see MISSING_FEATURES.md

$ curl localhost:8002/Detroit?format=j1

The result will look like:

{
  "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:

$ curl localhost:8002/Detroit?format=p1

A possible Prometheus configuration:

- job_name: 'wttr_in_detroit'
  static_configs:
    - targets: ['localhost:8002']
  metrics_path: '/Detroit'
  params:
    format: ['p1']

Building

# 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

# 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 - System architecture and design
• MISSING_FEATURES.md - Features not yet implemented

License

Apache v2, matching wttr.in project from which this is derived. See LICENSE