--- title: "OpenWeatherMap API Reference" description: "**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 (" type: skill canonical_url: https://claudary.paisolsolutions.com/skills/openweathermap source: "Claudary" difficulty: intermediate author: "Claude Code Knowledge Pack" date: 2026-07-10T11:31:31.999Z license: CC-BY-4.0 attribution: "OpenWeatherMap API Reference — Claudary (https://claudary.paisolsolutions.com/skills/openweathermap)" --- # OpenWeatherMap API Reference **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 ( ## Overview # 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. --- Source: [Claudary](https://claudary.paisolsolutions.com/skills/openweathermap) · https://claudary.paisolsolutions.com