lobo/wttr
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions
wttr/API_ENDPOINTS.md

12 KiB
Raw Blame History

wttr.in API Endpoints Reference

Base URL

  • Production: https://wttr.in
  • Local: http://localhost:8082 (Go proxy) → http://localhost:8002 (Python backend)

Weather Query Endpoints

GET /

Get weather for IP-based location.

Response: ANSI weather report (or HTML if browser User-Agent)

Example:

curl wttr.in

GET /{location}

Get weather for specific location.

Path Parameters:

  • location - City name, coordinates, airport code, or special location

Location Formats:

  • City name: London, New York, Salt+Lake+City
  • Coordinates: 55.7558,37.6173
  • Airport (IATA): muc, ham
  • Search term: ~Eiffel+Tower, ~Kilimanjaro
  • Domain: @github.com, @msu.ru
  • IP address: 8.8.8.8
  • Auto-detect: MyLocation or empty
  • Moon: Moon, Moon@2016-12-25
  • Cyclic: London:Paris:Berlin (rotates based on time)

Special Prefixes:

  • ~ - Search for location (uses geolocator)
  • @ - Resolve domain to IP, then get location
  • No prefix - Exact location name

Query Parameters: See "Query Parameters" section below

Examples:

curl wttr.in/London
curl wttr.in/~Eiffel+Tower
curl wttr.in/@github.com
curl wttr.in/Moon
curl wttr.in/London:Paris:Berlin?period=60

GET /{location}.png

Get weather as PNG image.

Path Parameters:

  • location - Same as above, but with .png extension

PNG Filename Format:

{location}_{options}.png

Options in filename:

  • {width}x - Width in pixels (e.g., 200x)
  • x{height} - Height in pixels (e.g., x300)
  • {width}x{height} - Both dimensions (e.g., 200x300)
  • lang={code} - Language code (e.g., lang=ru)
  • Single-letter options: t, n, q, etc. (see below)
  • Separate multiple options with _

Examples:

curl wttr.in/Paris.png > paris.png
curl wttr.in/London_200x_t_lang=fr.png > london.png
curl wttr.in/Berlin_0tqp_lang=de.png > berlin.png

Note: Use _ instead of ? and & for PNG URLs

Special Pages

GET /:help

Display help page with usage instructions.

Query Parameters:

  • lang={code} - Language for help page

Example:

curl wttr.in/:help
curl wttr.in/:help?lang=de

GET /:bash.function

Get bash function for shell integration.

Example:

curl wttr.in/:bash.function >> ~/.bashrc

GET /:translation

Display translation information and supported languages.

Example:

curl wttr.in/:translation

GET /:iterm2

Get iTerm2 integration instructions.

Example:

curl wttr.in/:iterm2

Static Files

GET /files/{path}

Serve static files.

Path Parameters:

  • path - Relative path to file in share/static/

Example:

curl wttr.in/files/example-wttr-v2.png

GET /favicon.ico

Get favicon.

Query Parameters

Single-Letter Options

Combine multiple single-letter options in the query string without values:

curl wttr.in/London?Tnq

Available Options:

Option Description
A Force ANSI output (even for browsers)
n Narrow output (narrower terminal width)
m Use metric units (force metric even for US)
M Use m/s for wind speed
u Use imperial units (Fahrenheit, mph)
I Inverted colors
t Transparency for PNG (transparency=150)
T No terminal sequences (plain text)
p Add padding
0 Show current weather only (no forecast)
1 Show today + 1 day
2 Show today + 2 days
3 Show today + 3 days (default)
q Quiet mode (no caption)
Q Super quiet (no city name)
F No follow line (no "Follow @igor_chubin")

Unit System Defaults:

The service automatically selects units based on:

  1. Explicit query parameter (?u or ?m) - highest priority
  2. Language parameter (lang=us) - forces imperial
  3. Client IP geolocation - US IPs default to imperial
  4. Default - metric for all other locations

Examples:

curl wttr.in/London?T          # Plain text, no ANSI
curl wttr.in/London?u          # Imperial units
curl wttr.in/London?m          # Metric units
curl wttr.in/London?0          # Current weather only
curl wttr.in/London?Tnq        # Plain text, narrow, quiet

Named Parameters

Parameter Description Example
lang={code} Language code (2-letter ISO 639-1) lang=de
format={fmt} Output format (see below) format=3
view={view} View type (alias for format) view=v2
period={sec} Update interval for cyclic locations period=60
transparency={0-255} PNG transparency level transparency=100

Examples:

curl wttr.in/London?lang=fr
curl wttr.in/London?format=3
curl wttr.in/London:Paris?period=60

Combining Parameters

curl wttr.in/London?Tn&lang=de&format=3
curl wttr.in/Paris?u&format=v2

Output Formats

format=1 (One-line, compact)

curl wttr.in/London?format=1
# Output: London: ⛅️ +7°C

format=2 (One-line, with wind)

curl wttr.in/London?format=2
# Output: London: ⛅️ +7°C 🌬️↗11km/h

format=3 (One-line, detailed)

curl wttr.in/London?format=3
# Output: London: ⛅️ +7°C 🌬️↗11km/h 💧65%

format=4 (One-line, full)

curl wttr.in/London?format=4
# Output: London: ⛅️ +7°C 🌬️↗11km/h 💧65% ☀️06:45-16:32

format={custom} (Custom format)

Use % notation to create custom formats:

Code Description
%c Weather condition emoji
%C Weather condition text
%h Humidity
%t Temperature (actual)
%f Temperature (feels like)
%w Wind
%l Location
%m Moon phase 🌑🌒🌓🌔🌕🌖🌗🌘
%M Moon day
%p Precipitation (mm)
%o Probability of precipitation
%P Pressure (hPa)
%D Dawn time
%S Sunrise time
%z Zenith time
%s Sunset time
%d Dusk time

Examples:

curl wttr.in/London?format="%l:+%c+%t"
# Output: London: ⛅️ +7°C

curl wttr.in/London?format="%l:+%C+%t+%w"
# Output: London: Partly cloudy +7°C ↗11km/h

curl wttr.in/London?format="%D+%S+%z+%s+%d"
# Output: 06:30 06:45 12:15 16:32 17:00

Note: In tmux.conf, escape % as %%

format=v2 (Data-rich experimental)

Experimental format with additional information:

  • Temperature and precipitation graphs
  • Moon phase for 4 days
  • Current conditions with all metrics
  • Timezone information
  • Astronomical times (dawn, sunrise, zenith, sunset, dusk)
  • Precise GPS coordinates
curl wttr.in/London?format=v2
# or
curl v2.wttr.in/London
# or (Nerd Fonts)
curl v2d.wttr.in/London  # day variant
curl v2n.wttr.in/London  # night variant

Limitations:

  • Terminal only (no HTML)
  • English only

format=j1 (JSON)

Machine-readable JSON format with all weather data.

curl wttr.in/London?format=j1

Response Structure:

{
  "current_condition": [{
    "FeelsLikeC": "25",
    "FeelsLikeF": "76",
    "cloudcover": "100",
    "humidity": "76",
    "observation_time": "04:08 PM",
    "precipMM": "0.2",
    "pressure": "1019",
    "temp_C": "22",
    "temp_F": "72",
    "uvIndex": 5,
    "visibility": "16",
    "weatherCode": "122",
    "weatherDesc": [{"value": "Overcast"}],
    "winddir16Point": "NNE",
    "winddirDegree": "20",
    "windspeedKmph": "7",
    "windspeedMiles": "4"
  }],
  "nearest_area": [...],
  "request": [...],
  "weather": [...]
}

Weather Codes: See https://www.worldweatheronline.com/developer/api/docs/weather-icons.aspx

format=p1 (Prometheus Metrics)

Prometheus-compatible metrics format.

curl wttr.in/London?format=p1

Response:

# HELP temperature_feels_like_celsius Feels Like Temperature in Celsius
temperature_feels_like_celsius{forecast="current"} 7
# HELP temperature_feels_like_fahrenheit Feels Like Temperature in Fahrenheit
temperature_feels_like_fahrenheit{forecast="current"} 45
...

Prometheus Config Example:

- job_name: 'wttr_in_london'
  static_configs:
    - targets: ['wttr.in']
  metrics_path: '/London'
  params:
    format: ['p1']

Language Support

54 languages supported via lang parameter or subdomain:

curl wttr.in/London?lang=de
curl de.wttr.in/London

Supported Languages: af, ar, az, be, bg, bs, ca, cy, da, de, el, en, eo, es, et, eu, fa, fr, fy, ga, he, hr, hu, hy, ia, id, is, it, ja, kk, lv, mk, nb, nl, nn, oc, pl, pt, pt-br, ro, ru, sl, te, th, tr, uk, uz, vi, zh-cn, zh-tw

Language Detection Priority:

  1. Subdomain (e.g., de.wttr.in)
  2. lang parameter
  3. Accept-Language header
  4. Default (English)

Multiple Locations

Query multiple locations in one request using : separator:

curl wttr.in/London:Paris:Berlin?format=3
# Output:
# London: ⛅️ +7°C
# Paris: ☀️ +12°C
# Berlin: 🌧 +5°C

Cyclic Locations:

Rotate through locations based on time:

curl wttr.in/London:Paris:Berlin?period=60

This will show:

  • London for 60 seconds
  • Paris for next 60 seconds
  • Berlin for next 60 seconds
  • Repeat

Useful for tmux status bars or monitoring dashboards.

HTTP Headers

Request Headers

Header Purpose
User-Agent Determines output format (ANSI vs HTML)
Accept-Language Language preference
X-Forwarded-For Client IP (for location detection)
X-Real-IP Client IP (alternative)
X-PNG-Query-For Client IP (for PNG requests)

Response Headers

Header Value
Content-Type text/plain or text/html or image/png
Cache-Control no-cache, no-store, must-revalidate (PNG only)
Access-Control-Allow-Origin *

HTTP Status Codes

Code Meaning
200 Success
403 Forbidden (location blacklisted)
429 Too Many Requests (rate limit exceeded)
500 Internal Server Error
503 Service Unavailable (API error)

Rate Limits

Per-IP limits:

  • 300 requests per minute
  • 3600 requests per hour
  • 86400 requests per day

Response on limit exceeded:

  • HTTP 429
  • Body: "Too many queries" message

Caching

Responses are cached for 1000-2000 seconds (randomized).

Cache key includes:

  • User-Agent
  • Query string
  • Client IP
  • Language

Non-cacheable requests:

  • Cyclic locations (containing :)

Examples

Basic Usage

# Current location
curl wttr.in

# Specific city
curl wttr.in/London

# Airport
curl wttr.in/muc

# Coordinates
curl wttr.in/55.7558,37.6173

# Moon phase
curl wttr.in/Moon

Output Formats

# Plain text
curl wttr.in/London?T

# One-line
curl wttr.in/London?format=3

# JSON
curl wttr.in/London?format=j1

# PNG
curl wttr.in/London.png > weather.png

Units

# Metric
curl wttr.in/London?m

# Imperial
curl wttr.in/London?u

Languages

# German
curl wttr.in/London?lang=de
curl de.wttr.in/London

# French
curl fr.wttr.in/Paris

Customization

# Narrow, quiet, plain text
curl wttr.in/London?Tnq

# Current weather only
curl wttr.in/London?0

# Custom format
curl wttr.in/London?format="%l:+%c+%t+%w"

# Transparent PNG
curl wttr.in/London_t.png > weather.png

Shell Integration

# Add to .bashrc
weather() {
    curl wttr.in/$1
}

# Use it
weather London
weather "New York"

Tmux Status Bar

# In tmux.conf
set -g status-right '#(curl -s wttr.in/London?format="%%l:+%%c%%20%%t%%60%%w")'

Multiple Locations

# All at once
curl 'wttr.in/{London,Paris,Berlin}?format=3'

# Cyclic (for monitoring)
curl wttr.in/London:Paris:Berlin?period=60&format=3