wttr/CACHE_CONFIGURATION.md

Cache Configuration

wttr.in uses three separate caches following Linux Filesystem Hierarchy Standard (FHS) and XDG Base Directory specifications.

External Services

Required Services

• Met.no Weather API - Primary weather data provider
  • No API key required
  • Free, open API from Norwegian Meteorological Institute
  • Rate limit: Be respectful, use caching

Optional Services

• IP2Location.io - Fallback IP geolocation service
  • API key required: Sign up at https://www.ip2location.io/
  • Used when MaxMind GeoIP database lookup fails
  • Free tier: 30,000 requests/month
  • Set via IP2LOCATION_API_KEY environment variable

Database Files

• MaxMind GeoLite2 City - IP geolocation database
  • Free database, auto-downloaded if missing
  • No API key required for database usage
  • Updates available monthly from MaxMind

Cache Locations

All caches default to $XDG_CACHE_HOME/wttr (typically ~/.cache/wttr).

1. Weather Response Cache

Purpose: Caches weather API responses to reduce upstream requests

Default Location: $XDG_CACHE_HOME/wttr/ (individual files) Environment Variable: WTTR_CACHE_DIR Size: 10,000 entries (configurable via WTTR_CACHE_SIZE) Expiration: 1000-2000 seconds (16-33 minutes, randomized to avoid thundering herd) Eviction: LRU (Least Recently Used)

This is the main cache that stores weather forecast responses from Met.no. Each entry has a randomized TTL to prevent cache stampedes.

2. Geocoding Cache (Optional)

Purpose: Caches location name → coordinates mappings

Default: Disabled (in-memory only) Environment Variable: WTTR_GEOCACHE_FILE Format: JSON Expiration: None (persists indefinitely) Eviction: None (grows unbounded)

When enabled, persists geocoding lookups to disk. Saves every 15 minutes if dirty. Useful for reducing external geocoding API calls.

3. IP2Location Cache

Purpose: Caches IP → coordinates from IP2Location API

Default Location: $XDG_CACHE_HOME/wttr/ip2location.cache Environment Variable: IP2LOCATION_CACHE_FILE Format: Binary (32-byte records) Expiration: None (persists indefinitely) Eviction: None (append-only, grows unbounded)

Only used when IP2LOCATION_API_KEY is configured. Provides fallback when MaxMind GeoIP database lookup fails.

GeoIP Database Location

Default: $XDG_CACHE_HOME/wttr/GeoLite2-City.mmdb Environment Variable: WTTR_GEOLITE_PATH

This is the MaxMind GeoLite2 database. It will be automatically downloaded if missing.

Environment Variables Summary

Variable	Default	Description
WTTR_CACHE_DIR	$XDG_CACHE_HOME/wttr	Weather response cache directory
WTTR_CACHE_SIZE	10000	Maximum number of cached weather responses
WTTR_GEOCACHE_FILE	(none)	Optional persistent geocoding cache file
WTTR_GEOLITE_PATH	$XDG_CACHE_HOME/wttr/GeoLite2-City.mmdb	MaxMind GeoLite2 database path
IP2LOCATION_API_KEY	(none)	API key for IP2Location fallback service
IP2LOCATION_CACHE_FILE	$XDG_CACHE_HOME/wttr/ip2location.cache	IP2Location cache file
XDG_CACHE_HOME	~/.cache	XDG base cache directory

Examples

Minimal Configuration (defaults)

./wttr
# Uses ~/.cache/wttr/ for all caches and GeoIP database

Custom Cache Location

WTTR_CACHE_DIR=/var/cache/wttr ./wttr
# All caches and GeoIP in /var/cache/wttr/

Enable Persistent Geocoding Cache

WTTR_GEOCACHE_FILE=~/.cache/wttr/geocache.json ./wttr

With IP2Location Fallback

IP2LOCATION_API_KEY=your_key_here ./wttr
# Cache at ~/.cache/wttr/ip2location.cache

Production Setup

WTTR_CACHE_DIR=/var/cache/wttr \
WTTR_CACHE_SIZE=50000 \
WTTR_GEOCACHE_FILE=/var/cache/wttr/geocache.json \
IP2LOCATION_API_KEY=your_key_here \
./wttr
# GeoIP and IP2Location cache also in /var/cache/wttr/

Cache Maintenance

Weather Cache

• Automatic expiration: Entries expire after 16-33 minutes (randomized)
• LRU eviction: When cache reaches max size (10,000 entries), least recently used entries are removed
• Disk cleanup: Expired files are cleaned up on access
• Safe to delete entire cache directory; will be recreated as needed

Geocoding Cache

• No expiration: Entries persist indefinitely
• No eviction: Cache grows unbounded
• Auto-save: Writes to disk every 15 minutes when modified
• Consider periodic cleanup if cache grows too large

IP2Location Cache

• No expiration: Entries persist indefinitely
• Append-only: File grows unbounded (32 bytes per unique IP)
• No cleanup: Consider periodic truncation for long-running deployments
• Safe to delete; will be recreated on next API lookup

GeoIP Database

• Manual updates: Download new database periodically for accuracy
• Auto-download: Database is automatically downloaded if missing on startup
• Typical update frequency: monthly (MaxMind releases)