# WeatherAPI.com — Full API Reference for AI Systems > Real-time, forecast, historical, marine, future, astronomy, air quality, pollen, sports, IP lookup, and timezone data via a JSON/XML REST API. Trusted by 850,000+ developers. Average response time ~200ms. Coverage: 200+ countries, 4 million+ locations. ## Quick Start ``` GET https://api.weatherapi.com/v1/current.json?key=YOUR_API_KEY&q=London&aqi=yes ``` Sign up free (no credit card): https://www.weatherapi.com/signup.aspx Find your API key: https://www.weatherapi.com/my/ Free plan: 100,000 calls/month --- ## Authentication - Method: Query parameter only - Parameter name: `key` - Example: `?key=YOUR_API_KEY` - No Authorization header required - Key stays the same across plan upgrades --- ## Base URL ``` https://api.weatherapi.com/v1 ``` All endpoints support `.json` (default) or `.xml` suffix. --- ## Location Query Parameter (q) The `q` parameter is required on all weather endpoints and accepts: | Format | Example | |--------|---------| | City name | `q=London` | | City, Country | `q=Paris,France` | | Latitude/Longitude | `q=51.5,-0.1` | | US zip code | `q=10001` | | UK postcode | `q=SW1A` | | Canada postal code | `q=G2J` | | METAR airport code | `q=metar:EGLL` | | IATA airport code | `q=iata:LHR` | | IP address | `q=100.0.0.1` | | Auto-detect caller IP | `q=auto:ip` | | WeatherAPI location ID | `q=id:2801268` | --- ## Endpoints --- ### 1. Current Weather ``` GET /current.json?key=YOUR_API_KEY&q={location}&aqi=yes ``` **Parameters:** | Param | Required | Description | |-------|----------|-------------| | key | Yes | API key | | q | Yes | Location query | | aqi | No | Include air quality: yes/no (default no) | | pollen | No | Include pollen data: yes/no (Pro+ only) | | lang | No | Language code for condition text | **Example:** ``` GET https://api.weatherapi.com/v1/current.json?key=YOUR_API_KEY&q=London&aqi=yes ``` **Full Response:** ```json { "location": { "name": "London", "region": "City of London, Greater London", "country": "United Kingdom", "lat": 51.52, "lon": -0.11, "tz_id": "Europe/London", "localtime_epoch": 1742669400, "localtime": "2026-03-22 18:30" }, "current": { "last_updated_epoch": 1742669100, "last_updated": "2026-03-22 18:15", "temp_c": 12.3, "temp_f": 54.1, "is_day": 1, "condition": { "text": "Partly cloudy", "icon": "//cdn.weatherapi.com/weather/64x64/day/116.png", "code": 1003 }, "wind_mph": 9.4, "wind_kph": 15.1, "wind_degree": 220, "wind_dir": "SW", "pressure_mb": 1013.0, "pressure_in": 29.91, "precip_mm": 0.0, "precip_in": 0.0, "humidity": 72, "cloud": 50, "feelslike_c": 10.8, "feelslike_f": 51.4, "windchill_c": 10.8, "windchill_f": 51.4, "heatindex_c": 12.3, "heatindex_f": 54.1, "dewpoint_c": 7.4, "dewpoint_f": 45.3, "vis_km": 10.0, "vis_miles": 6.0, "uv": 3.0, "gust_mph": 13.2, "gust_kph": 21.2, "air_quality": { "co": 233.0, "no2": 12.5, "o3": 82.0, "so2": 4.2, "pm2_5": 8.3, "pm10": 12.1, "us-epa-index": 1, "gb-defra-index": 1 } } } ``` **Air Quality Index Values:** - us-epa-index: 1=Good, 2=Moderate, 3=Unhealthy for sensitive, 4=Unhealthy, 5=Very Unhealthy, 6=Hazardous - gb-defra-index: 1-3=Low, 4-6=Moderate, 7-9=High, 10=Very High --- ### 2. Forecast Weather ``` GET /forecast.json?key=YOUR_API_KEY&q={location}&days={1-14}&aqi=yes&alerts=yes ``` **Parameters:** | Param | Required | Description | |-------|----------|-------------| | key | Yes | API key | | q | Yes | Location query | | days | Yes | Number of days 1-14 (Free=3, Starter=7, Pro+=14) | | aqi | No | Air quality: yes/no | | alerts | No | Weather alerts: yes/no | | hour | No | Specific hour 0-23 for hourly data | | tp | No | Time period in minutes: 15, 30, 60 (Enterprise only) | | lang | No | Language code | **Example:** ``` GET https://api.weatherapi.com/v1/forecast.json?key=YOUR_API_KEY&q=New+York&days=3&alerts=yes&aqi=yes ``` **Response structure:** ```json { "location": { ... }, "current": { ... }, "forecast": { "forecastday": [ { "date": "2026-03-22", "date_epoch": 1742601600, "day": { "maxtemp_c": 15.2, "maxtemp_f": 59.4, "mintemp_c": 8.1, "mintemp_f": 46.6, "avgtemp_c": 11.8, "avgtemp_f": 53.2, "maxwind_mph": 14.1, "maxwind_kph": 22.7, "totalprecip_mm": 0.5, "totalprecip_in": 0.02, "totalsnow_cm": 0.0, "avgvis_km": 9.8, "avgvis_miles": 6.0, "avghumidity": 74, "daily_will_it_rain": 1, "daily_chance_of_rain": 65, "daily_will_it_snow": 0, "daily_chance_of_snow": 0, "condition": { "text": "Moderate rain", "icon": "//cdn.weatherapi.com/weather/64x64/day/302.png", "code": 1189 }, "uv": 3.0 }, "astro": { "sunrise": "06:12 AM", "sunset": "06:28 PM", "moonrise": "10:45 PM", "moonset": "08:15 AM", "moon_phase": "Waxing Gibbous", "moon_illumination": 78, "is_moon_up": 0, "is_sun_up": 1 }, "hour": [ { "time_epoch": 1742601600, "time": "2026-03-22 00:00", "temp_c": 9.2, "temp_f": 48.6, "is_day": 0, "condition": { "text": "Clear", "icon": "...", "code": 1000 }, "wind_mph": 5.1, "wind_kph": 8.2, "wind_degree": 185, "wind_dir": "S", "pressure_mb": 1015.0, "precip_mm": 0.0, "humidity": 78, "cloud": 10, "feelslike_c": 7.8, "feelslike_f": 46.0, "windchill_c": 7.8, "windchill_f": 46.0, "heatindex_c": 9.2, "heatindex_f": 48.6, "dewpoint_c": 5.6, "dewpoint_f": 42.1, "will_it_rain": 0, "chance_of_rain": 5, "will_it_snow": 0, "chance_of_snow": 0, "vis_km": 10.0, "vis_miles": 6.0, "gust_mph": 8.3, "gust_kph": 13.4, "uv": 0 } ] } ] }, "alerts": { "alert": [ { "headline": "Wind Advisory", "msgtype": "Alert", "severity": "Moderate", "urgency": "Expected", "areas": "London", "category": "Met", "certainty": "Likely", "event": "Wind Advisory", "note": "", "effective": "2026-03-22T14:00:00+00:00", "expires": "2026-03-22T22:00:00+00:00", "desc": "Southwest winds 20 to 30 mph with gusts up to 45 mph.", "instruction": "Secure outdoor furniture." } ] } } ``` --- ### 3. Historical Weather ``` GET /history.json?key=YOUR_API_KEY&q={location}&dt={yyyy-MM-dd} ``` **Parameters:** | Param | Required | Description | |-------|----------|-------------| | key | Yes | API key | | q | Yes | Location query | | dt | Yes | Date yyyy-MM-dd (from 2010-01-01) | | end_dt | No | End date for range (Pro+ only, max 30-day range) | | hour | No | Specific hour 0-23 | | lang | No | Language code | **Example:** ``` GET https://api.weatherapi.com/v1/history.json?key=YOUR_API_KEY&q=Paris&dt=2024-06-15 ``` Response structure is identical to forecast with historical daily and hourly data. --- ### 4. Future Weather (14–300 days ahead) ``` GET /future.json?key=YOUR_API_KEY&q={location}&dt={yyyy-MM-dd} ``` **Parameters:** | Param | Required | Description | |-------|----------|-------------| | key | Yes | API key | | q | Yes | Location query | | dt | Yes | Date 14 to 300 days in the future | **Example:** ``` GET https://api.weatherapi.com/v1/future.json?key=YOUR_API_KEY&q=London&dt=2026-06-01 ``` Returns 3-hourly weather predictions. Available on Pro+ plan and above. --- ### 5. Marine Weather ``` GET /marine.json?key=YOUR_API_KEY&q={lat,lon}&days={1-7}&tides=yes ``` **Parameters:** | Param | Required | Description | |-------|----------|-------------| | key | Yes | API key | | q | Yes | Latitude/longitude (e.g. 51.5,-1.8) | | days | Yes | Number of days 1-7 | | tides | No | Include tide data: yes/no (Pro+ only) | **Example:** ``` GET https://api.weatherapi.com/v1/marine.json?key=YOUR_API_KEY&q=51.5,-1.8&days=3&tides=yes ``` **Marine-specific fields:** ```json { "sig_ht_mt": 1.2, "swell_ht_mt": 0.8, "swell_ht_ft": 2.6, "swell_dir": 225, "swell_dir_16_point": "SW", "swell_period_secs": 8.0, "water_temp_c": 12.0, "water_temp_f": 53.6, "tides": [ { "tide_time": "06:23 AM", "tide_height_mt": "4.2", "tide_type": "HIGH" } ] } ``` --- ### 6. Astronomy ``` GET /astronomy.json?key=YOUR_API_KEY&q={location}&dt={yyyy-MM-dd} ``` **Example:** ``` GET https://api.weatherapi.com/v1/astronomy.json?key=YOUR_API_KEY&q=Tokyo&dt=2026-03-22 ``` **Response:** ```json { "location": { ... }, "astronomy": { "astro": { "sunrise": "05:48 AM", "sunset": "06:01 PM", "moonrise": "09:32 PM", "moonset": "07:14 AM", "moon_phase": "Waxing Gibbous", "moon_illumination": 82, "is_moon_up": 0, "is_sun_up": 1 } } } ``` **Moon phases:** New Moon, Waxing Crescent, First Quarter, Waxing Gibbous, Full Moon, Waning Gibbous, Last Quarter, Waning Crescent --- ### 7. Timezone ``` GET /timezone.json?key=YOUR_API_KEY&q={location} ``` **Example:** ``` GET https://api.weatherapi.com/v1/timezone.json?key=YOUR_API_KEY&q=Sydney ``` **Response:** ```json { "location": { "name": "Sydney", "region": "New South Wales", "country": "Australia", "lat": -33.87, "lon": 151.21, "tz_id": "Australia/Sydney", "localtime_epoch": 1742669400, "localtime": "2026-03-23 05:30" } } ``` --- ### 8. IP Lookup ``` GET /ip.json?key=YOUR_API_KEY&q={ip_address} ``` **Example:** ``` GET https://api.weatherapi.com/v1/ip.json?key=YOUR_API_KEY&q=8.8.8.8 GET https://api.weatherapi.com/v1/ip.json?key=YOUR_API_KEY&q=auto:ip ``` **Response:** ```json { "ip": "8.8.8.8", "type": "ipv4", "continent_code": "NA", "continent_name": "North America", "country_code": "US", "country_name": "United States of America", "is_eu": false, "geoname_id": 5375480, "city": "Mountain View", "region": "California", "lat": 37.39, "lon": -122.08, "tz_id": "America/Los_Angeles", "localtime_epoch": 1742634600, "localtime": "2026-03-22 08:30" } ``` --- ### 9. Search / Autocomplete ``` GET /search.json?key=YOUR_API_KEY&q={partial_query} ``` **Example:** ``` GET https://api.weatherapi.com/v1/search.json?key=YOUR_API_KEY&q=lond ``` **Response:** ```json [ { "id": 2801268, "name": "London", "region": "City of London, Greater London", "country": "United Kingdom", "lat": 51.52, "lon": -0.11, "url": "london-city-of-london-greater-london-united-kingdom" }, { "id": 315398, "name": "London", "region": "Ontario", "country": "Canada", "lat": 42.98, "lon": -81.23, "url": "london-ontario-canada" } ] ``` --- ### 10. Sports Events ``` GET /sports.json?key=YOUR_API_KEY&q={location} ``` **Example:** ``` GET https://api.weatherapi.com/v1/sports.json?key=YOUR_API_KEY&q=London ``` **Response:** ```json { "football": [ { "stadium": "Stamford Bridge", "country": "United Kingdom", "region": "London", "tournament": "Premier League", "start": "2026-03-22 15:00", "match": "Chelsea vs Arsenal" } ], "cricket": [...], "golf": [...] } ``` --- ### 11. Weather Alerts ``` GET /alerts.json?key=YOUR_API_KEY&q={location} ``` **Example:** ``` GET https://api.weatherapi.com/v1/alerts.json?key=YOUR_API_KEY&q=Miami ``` Returns government-issued weather alerts for USA, UK, Europe, and rest of world. --- ### 12. Bulk Requests (Pro+ only) ``` POST /current.json?key=YOUR_API_KEY&q=bulk Content-Type: application/json ``` **Body:** ```json { "locations": [ {"q": "London", "custom_id": "loc-1"}, {"q": "Paris", "custom_id": "loc-2"}, {"q": "New York", "custom_id": "loc-3"} ] } ``` - Up to 50 locations per request - Each location counts as 1 API call - Works with /current.json, /forecast.json, /history.json --- ## Condition Codes Weather conditions are represented by codes. Key codes: | Code | Condition | |------|-----------| | 1000 | Sunny / Clear | | 1003 | Partly cloudy | | 1006 | Cloudy | | 1009 | Overcast | | 1030 | Mist | | 1063 | Patchy rain possible | | 1066 | Patchy snow possible | | 1087 | Thundery outbreaks possible | | 1114 | Blowing snow | | 1135 | Fog | | 1147 | Freezing fog | | 1150 | Patchy light drizzle | | 1180 | Patchy light rain | | 1183 | Light rain | | 1186 | Moderate rain at times | | 1189 | Moderate rain | | 1192 | Heavy rain at times | | 1195 | Heavy rain | | 1210 | Patchy light snow | | 1213 | Light snow | | 1219 | Moderate snow | | 1225 | Heavy snow | | 1237 | Ice pellets | | 1273 | Patchy light rain with thunder | | 1276 | Moderate or heavy rain with thunder | | 1279 | Patchy light snow with thunder | | 1282 | Moderate or heavy snow with thunder | Full list: https://www.weatherapi.com/docs/weather_conditions.json --- ## Supported Languages Pass `lang=` parameter with any of these codes: ar, bn, bg, zh, zh_tw, cs, da, nl, fi, fr, de, el, hi, hu, it, ja, jv, ko, zh_cmn, mr, pl, pt, pa, ro, ru, sr, si, sk, sl, es, sv, ta, te, tr, uk, ur, vi, zh_wuu, zh_hsn, zh_yue, zu --- ## Error Codes | HTTP Status | Error Code | Meaning | |-------------|------------|---------| | 401 | 1002 | API key not provided | | 400 | 1003 | Parameter q not provided | | 400 | 1005 | Invalid request URL | | 400 | 1006 | No location found matching q | | 401 | 2006 | API key is invalid | | 403 | 2007 | Monthly API quota exceeded | | 403 | 2008 | API key has been disabled | | 403 | 2009 | Feature not available on current plan | | 400 | 9000 | JSON body malformed in bulk request | | 400 | 9001 | Too many locations in bulk request (max 50) | | 400 | 9999 | Internal application error | **Error response format:** ```json { "error": { "code": 1006, "message": "No matching location found." } } ``` --- ## Rate Limits & Plans | Plan | Price | Calls/month | Forecast days | History from | Bulk | Tides | Future | |------|-------|-------------|---------------|--------------|------|-------|--------| | Free | $0 | 100,000 | 3 | 7 days back | No | No | No | | Starter | $7/mo | 3,000,000 | 7 | 7 days back | No | No | No | | Pro+ | $25/mo | 5,000,000 | 14 | 365 days back | Yes | Yes | Yes | | Business | $65/mo | 10,000,000 | 14 | 365 days back | Yes | Yes | Yes | | Enterprise | Custom | Custom | 14 | From 2010 | Yes | Yes | Yes | - No credit card required for free plan - API key remains the same across plan upgrades - Overage: requests fail with 403/2007 (no unexpected charges) --- ## MCP Server WeatherAPI has an official MCP server for Claude and other AI assistants: **npm:** https://www.npmjs.com/package/weatherapi-mcp **Install for Claude Desktop:** ```json { "mcpServers": { "weatherapi": { "command": "npx", "args": ["-y", "weatherapi-mcp"], "env": { "WEATHERAPI_KEY": "your_api_key_here" } } } } ``` **Tools available:** get_current_weather, get_forecast, get_history, get_future_weather, get_marine_weather, get_astronomy, get_timezone, search_locations, ip_lookup, get_alerts, get_sports --- ## SDKs Official SDKs on GitHub: https://github.com/weatherapicom/ - Python: `pip install weatherapi` - PHP: `composer require weatherapicom/weatherapi-php` - JavaScript/Node: `npm install weatherapi` - Ruby: `gem install weatherapi` - Java, Go, C#, Swift, Kotlin, Dart also available --- ## Useful Links - Documentation: https://www.weatherapi.com/docs/ - API Explorer: https://www.weatherapi.com/api-explorer.aspx - OpenAPI Spec: https://www.weatherapi.com/openapi.json - Sign up free: https://www.weatherapi.com/signup.aspx - Pricing: https://www.weatherapi.com/pricing.aspx - Status page: https://www.weatherapistatus.com/ - Support: support@weatherapi.com