566 lines
11 KiB
Markdown
566 lines
11 KiB
Markdown
# 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
|
||
```
|