# OpenWeatherMap API Reference

## Base URL
```
https://api.openweathermap.org
```

## Authentication
- **API Key: REQUIRED.** Register for a free key at https://home.openweathermap.org/users/sign_up
- Pass as query parameter: `&appid=YOUR_KEY`
- Free tier key activates within a few hours of registration.

## Rate Limits (Free Tier)
- **60 calls per minute** (1,000 calls/day for some endpoints).
- **Current weather, 5-day forecast, geocoding:** Available on free tier.
- **One Call 3.0:** Requires subscription (1,000 free calls/day with credit card on file).
- **Historical data, air pollution history:** Requires paid plan for extended ranges.

---

## Key Endpoints

### 1. Current Weather
```
GET /data/2.5/weather
```

**Parameters:**
| Parameter | Type   | Required | Default  | Description |
|-----------|--------|----------|----------|-------------|
| `q`       | string | Cond.    | -        | City name, optionally with state/country: `London`, `London,GB`, `Portland,OR,US`. |
| `lat`     | float  | Cond.    | -        | Latitude (use with `lon`). |
| `lon`     | float  | Cond.    | -        | Longitude (use with `lat`). |
| `id`      | int    | Cond.    | -        | City ID (from OWM city list). |
| `zip`     | string | Cond.    | -        | Zip/postal code with country: `90210,US`, `SW1,GB`. |
| `units`   | string | No       | `standard` | `standard` (Kelvin), `metric` (Celsius), `imperial` (Fahrenheit). |
| `lang`    | string | No       | `en`     | Language code for descriptions. |
| `appid`   | string | Yes      | -        | API key. |

One location parameter (`q`, `lat`+`lon`, `id`, or `zip`) is required.

**Example:**
```
https://api.openweathermap.org/data/2.5/weather?lat=40.7128&lon=-74.0060&units=metric&appid=YOUR_KEY
```

**Response:**
```json
{
  "coord": {"lon": -74.006, "lat": 40.7128},
  "weather": [
    {
      "id": 800,
      "main": "Clear",
      "description": "clear sky",
      "icon": "01d"
    }
  ],
  "base": "stations",
  "main": {
    "temp": 22.5,
    "feels_like": 21.8,
    "temp_min": 20.1,
    "temp_max": 24.3,
    "pressure": 1013,
    "humidity": 55,
    "sea_level": 1013,
    "grnd_level": 1010
  },
  "visibility": 10000,
  "wind": {"speed": 3.6, "deg": 220, "gust": 5.1},
  "clouds": {"all": 0},
  "dt": 1700000000,
  "sys": {
    "country": "US",
    "sunrise": 1699960000,
    "sunset": 1699996000
  },
  "timezone": -18000,
  "id": 5128581,
  "name": "New York",
  "cod": 200
}
```

### 2. 5-Day / 3-Hour Forecast (Free)
```
GET /data/2.5/forecast
```
Returns forecast data in 3-hour intervals for 5 days (40 data points). Same location parameters as current weather.

**Additional Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `cnt`     | int  | Number of 3-hour steps to return (max 40). |

**Example:**
```
https://api.openweathermap.org/data/2.5/forecast?q=London,GB&units=metric&cnt=8&appid=YOUR_KEY
```

**Response:**
```json
{
  "cod": "200",
  "message": 0,
  "cnt": 8,
  "list": [
    {
      "dt": 1700000000,
      "main": {
        "temp": 10.5,
        "feels_like": 8.2,
        "temp_min": 9.8,
        "temp_max": 10.5,
        "pressure": 1020,
        "humidity": 80
      },
      "weather": [{"id": 802, "main": "Clouds", "description": "scattered clouds", "icon": "03d"}],
      "clouds": {"all": 40},
      "wind": {"speed": 4.1, "deg": 250},
      "visibility": 10000,
      "pop": 0.2,
      "dt_txt": "2024-01-15 12:00:00"
    }
  ],
  "city": {
    "id": 2643743,
    "name": "London",
    "coord": {"lat": 51.5085, "lon": -0.1257},
    "country": "GB",
    "population": 1000000,
    "timezone": 0,
    "sunrise": 1699950000,
    "sunset": 1699982000
  }
}
```
`pop` is probability of precipitation (0.0 to 1.0).

### 3. Geocoding
```
GET /geo/1.0/direct
GET /geo/1.0/reverse
GET /geo/1.0/zip
```

**Direct geocoding (city name to coordinates):**
```
https://api.openweathermap.org/geo/1.0/direct?q=London,GB&limit=5&appid=YOUR_KEY
```
Returns array of `{name, lat, lon, country, state}`.

**Reverse geocoding (coordinates to city name):**
```
https://api.openweathermap.org/geo/1.0/reverse?lat=51.5085&lon=-0.1257&limit=1&appid=YOUR_KEY
```

**Zip code geocoding:**
```
https://api.openweathermap.org/geo/1.0/zip?zip=90210,US&appid=YOUR_KEY
```

### 4. One Call API 3.0 (Subscription Required)
```
GET /data/3.0/onecall
```
Comprehensive endpoint returning current, minutely (1h), hourly (48h), daily (8d), and alerts in one call.

**Parameters:**
| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| `lat`     | float  | Yes      | Latitude. |
| `lon`     | float  | Yes      | Longitude. |
| `exclude` | string | No       | Comma-separated parts to exclude: `current`, `minutely`, `hourly`, `daily`, `alerts`. |
| `units`   | string | No       | `standard`, `metric`, `imperial`. |
| `appid`   | string | Yes      | API key. |

**Example:**
```
https://api.openweathermap.org/data/3.0/onecall?lat=40.7128&lon=-74.006&exclude=minutely,alerts&units=metric&appid=YOUR_KEY
```

### 5. Air Pollution
```
GET /data/2.5/air_pollution
GET /data/2.5/air_pollution/forecast
GET /data/2.5/air_pollution/history
```

**Parameters:** `lat`, `lon`, `appid` (required). For history: `start` and `end` (Unix timestamps).

**Example:**
```
https://api.openweathermap.org/data/2.5/air_pollution?lat=40.7128&lon=-74.006&appid=YOUR_KEY
```

**Response:**
```json
{
  "coord": {"lon": -74.006, "lat": 40.7128},
  "list": [
    {
      "main": {"aqi": 2},
      "components": {
        "co": 230.31,
        "no": 0.5,
        "no2": 15.0,
        "o3": 68.0,
        "so2": 2.5,
        "pm2_5": 8.1,
        "pm10": 12.3,
        "nh3": 1.0
      },
      "dt": 1700000000
    }
  ]
}
```
AQI scale: 1=Good, 2=Fair, 3=Moderate, 4=Poor, 5=Very Poor. Components in ug/m3.

---

## Weather Condition Codes
| Range   | Category |
|---------|----------|
| 2xx     | Thunderstorm |
| 3xx     | Drizzle |
| 5xx     | Rain |
| 6xx     | Snow |
| 7xx     | Atmosphere (fog, mist, haze) |
| 800     | Clear |
| 80x     | Clouds |

Weather icons: `https://openweathermap.org/img/wn/{icon}@2x.png`

## Free Tier vs Paid Summary
| Endpoint | Free | Subscription |
|----------|------|-------------|
| Current weather | Yes | Yes |
| 5-day/3-hour forecast | Yes | Yes |
| Geocoding | Yes | Yes |
| Air pollution (current) | Yes | Yes |
| One Call 3.0 | 1000/day (credit card required) | Yes |
| Historical weather | No | Yes |
| Daily forecast 16-day | No | Yes |
| Climatic forecast 30-day | No | Yes |

## Notes
- All timestamps (`dt`, `sunrise`, `sunset`) are **Unix epoch seconds (UTC)**.
- `timezone` field is offset in seconds from UTC (e.g. -18000 = UTC-5).
- Default temperature unit is Kelvin. Always specify `units=metric` or `units=imperial`.
- City name queries (`q=`) can be ambiguous. Prefer `lat`+`lon` for precision, using geocoding first if needed.
- Weather icon URL pattern: `https://openweathermap.org/img/wn/{icon}@2x.png` (e.g. `01d` for clear day).
- Error responses return `{"cod": 401, "message": "Invalid API key"}` or similar.