# 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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
curl wttr.in/:help
curl wttr.in/:help?lang=de
```

### GET /:bash.function

Get bash function for shell integration.

**Example:**
```bash
curl wttr.in/:bash.function >> ~/.bashrc
```

### GET /:translation

Display translation information and supported languages.

**Example:**
```bash
curl wttr.in/:translation
```

### GET /:iterm2

Get iTerm2 integration instructions.

**Example:**
```bash
curl wttr.in/:iterm2
```

## Static Files

### GET /files/{path}

Serve static files.

**Path Parameters:**
- `path` - Relative path to file in share/static/

**Example:**
```bash
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:

```bash
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 |
| `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") |

**Examples:**
```bash
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:**
```bash
curl wttr.in/London?lang=fr
curl wttr.in/London?format=3
curl wttr.in/London:Paris?period=60
```

### Combining Parameters

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

## Output Formats

### format=1 (One-line, compact)

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

### format=2 (One-line, with wind)

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

### format=3 (One-line, detailed)

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

### format=4 (One-line, full)

```bash
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:**
```bash
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

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

```bash
curl wttr.in/London?format=j1
```

**Response Structure:**
```json
{
  "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.

```bash
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:**
```yaml
- 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:

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

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

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

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

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

```bash
# Metric
curl wttr.in/London?m

# Imperial
curl wttr.in/London?u
```

### Languages

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

# French
curl fr.wttr.in/Paris
```

### Customization

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

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

# Use it
weather London
weather "New York"
```

### Tmux Status Bar

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

### Multiple Locations

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

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