# OpenWeather — full content export > Complete Markdown export of all active CMS pages. # Build with Weather Data From real-time forecasts to 47+ years of global climate history, OpenWeather provides instant access to weather APIs through self-service subscriptions for developers, analysts, and businesses Access real-time weather, hourly & daily forecasts, national alerts, and historical data — through a unified timeline-based API. Whether you’re building apps, analytics, AI workflows, dashboards, and enterprise weather solutions, One Call API 4.0 is your all-purpose solution. Start with 1,000 free API calls per day. Scale with pay-as-you-call pricing. ### [object Object] Real-time weather data for any location on Earth, delivered with high accuracy and low latency. From live conditions to key atmospheric parameters, get the insights you need, exactly when you need them. ### [object Object] Global forecasts from minute-level resolution to long-term outlooks. Whether you need short-term precision or extended climate trends, we deliver the insights to support confident, data-driven decisions. ### [object Object] Explore decades of global weather history, from hourly records to long-term climate trends. Whether you’re analysing past conditions or building predictive models, our archives give you the depth and reliability you need. Access reliable global weather data through clear documentation, quickstart examples, and flexible self-service plans. Integrate current, forecast, and historical data into your products and workflows in minutes. Enterprise-grade weather services for organisations with operational and business-critical needs. Access contractual delivery, broader licensing, onboarding support, and account coordination to strengthen planning, continuity, and decision-making at scale. Industry-focused weather solutions for organisations managing complex operational and sector-specific risks. Access tailored services, analytics, weather stations and sensors, and expert support to improve resilience, planning, asset protection, and decision-making across critical environments. --- # Weather APIs for Every Use Case OpenWeather provides global weather data APIs for current conditions, forecasts, historical archives, air quality, maps, and industry-specific use cases. Explore the product families below to find the API that fits your application, workflow, or business need. ## Featured API ## One Call API 4.0 ### All-in-One Weather Data, One Simple Call **One Call API 4.0** Access real-time weather, hourly & daily forecasts, national alerts, and historical data — through a unified timeline-based API. Whether you’re building apps, analytics, AI workflows, dashboards, and enterprise weather solutions, One Call API 4.0 is your all-purpose solution. [Read the Detailed Product Description](/api/one-call-4-desciption.md) - **Current Conditions**: Real-time weather conditions including temperature, humidity, wind, pressure, clouds, and more. - **1-Minute Forecast**: Minute-by-minute precipitation forecast for the next 60 minutes. - **15-Minute Forecast Timeline**: High-resolution 15-minute forecast timeline for the next 48 hours powered by the OWHL™ hyper-local model. - **Hourly Weather Timeline**: Explore 47+ years+ years of hourly historical weather data and up to 48 hours of forecast records through a unified weather timeline endpoint. - **Daily Weather Timeline**: Access long-range daily weather timelines combining 47+ years+ years of historical archive with forecasts up to 1.5 years ahead. - **National Weather Alerts**: Government-issued weather alerts and detailed metadata from official national meteorological agencies (e.g. NOAA, EUMETNET) - [Subscribe](https://home.openweathermap.org/subscriptions/unauth_subscribe/onecall_40/base) - [Explore API Doc](/api/one-call-4.md) ### Current Weather Data - Access current weather data for any location - We collect and process weather data from different sources such as global and local weather models, satellites, radars and a vast network of weather stations - JSON, XML, and HTML formats - Included in both free and paid subscriptions ### Hourly Forecast 4 days - Hourly forecast is available for 4 days - Forecast weather data for 96 timestamps - JSON and XML formats - Included in the Developer, Professional and Expert subscription plans ### Daily Forecast 16 days - 16 days forecast is available for any location on the globe - 1-day step for 16 days - JSON and XML formats - Included in all paid subscription plans ### Climatic Forecast 30 days - Forecast weather data for 30 days - JSON format - Included in the Developer, Professional and Expert subscription plans ### Bulk Current Data - Current weather, a variety of weather forecasts and their 7-day archive via regularly updated files - Weather bulks are grouped by types of weather data and location lists (global city lists or ZIP code lists of EU, UK, and US) - Bulk files are available via CSV and JSON formats - Included in the Professional and Expert subscription plans ### 5 Day / 3 Hour Forecast - 5 day forecast for any location on the globe - 5 day forecast with a 3-hour step - JSON and XML formats - Included in both free and paid subscriptions ### Road Risk API - Specify your route and get weather data and national alerts for the point of destination and along the route - Current, forecast for 5 days and historical weather data for 1 year for your route - Weather data are available for any point on the globe - To receive information on price and get a quote, please [contact us](mailto:info@openweathermap.org) ### Solar Irradiance API - Get the solar data by particular location and calculate energy generation! - [GHI](/api/solar-irradiance.md), [DNI](/api/solar-irradiance.md), [DHI](/api/solar-irradiance.md) indices for clear sky and cloudy sky models - Current data and forecast for 15 days ahead solar irradiation data - 47+ years of historical data (from January 1, 1979) - Daily aggregation with 1-hour and 15-minutes step detalization for specified day - Available worldwide ### Solar Irradiance History Bulk - Solar Irradiance History Bulk provides historical weather data for any location for more than 47+ years back (from January 1, 1979) - [GHI](/api/solar-irradiance.md), [DNI](/api/solar-irradiance.md), [DHI](/api/solar-irradiance.md) indices for clear sky and cloudy sky models - Data is available in 15-minutes and 1-hour steps - CSV and JSON formats - Available worldwide - Available through our [Marketplace](https://home.openweathermap.org/marketplace) ### Solar Irradiance History Forecast Bulk - Solar Irradiance History Bulk provides historical weather data for any location for more than 47+ years back (from January 1, 1979) - [GHI](/api/solar-irradiance.md), [DNI](/api/solar-irradiance.md), [DHI](/api/solar-irradiance.md) indices for clear sky and cloudy sky models - Data is available in 15-minutes and 1-hour steps - CSV and JSON formats - Available worldwide - Available through our [Marketplace](https://home.openweathermap.org/marketplace) ### Solar Panel Energy Prediction Get the particular solar panel power output, based on the panel’s technical characteristics! - Create unlimited number of solar panels for particular location with the desired specifications - Current and forecast for 15 days ahead solar panel power output data - 47+ years of historical data (from January 1, 1979) - Daily aggregation with 1-hour and 15-minutes step detalization for specified day - Available worldwide ### Weather History API - Through our API we provide historical weather data for any location on the globe - Weather data have 1-hour step - Weather History API is available in Professional and Expert subscription plans - JSON format ### History Bulk - History Bulk provides weather data for **any** location for 47+ years back (from January 01, 1979). - Available through our [Marketplace](https://home.openweathermap.org/marketplace) - CSV and JSON formats ### History Forecast Bulk - Historical archive of 16-days forecast weather data - Historical forecast data is available from October 7, 2017 - CSV and JSON formats - You can purchase the product from our [Marketplace](https://home.openweathermap.org/marketplace) ### Statistical Weather API - Statistical data on main weather parameters for any day and month of the year - The statistics are calculated based on our [Historical weather data](/history.md) - JSON format - The weather data updated every hour - Statistical Weather Data API is available in Expert subscription plan ### Accumulated Parameters - Accumulated temperature and precipitation data - Accumulated Parameters are available in Professional and Expert subscription plans - JSON format - More opportunities for agriculture in our [Agricultural API](https://agromonitoring.com/api/agro-api) ### Weather Maps 2.0 3-hour step - Forecast, Historical, Current weather maps with 3-hour step - 15 weather map layers - The maps can be used as layers in Direct Tiles, OpenLayers, Leaflet, and Google Maps - Included in Developer, Professional and Expert subscription plans ### Weather Maps 2.0 1-hour step - Forecast, Historical, Current weather maps with 1-hour step - 14 weather map layers - The maps can be used as layers in Direct Tiles, OpenLayers, Leaflet, and Google Maps ### Weather Maps 1.0 - Weather maps include precipitation, clouds, pressure, temperature, wind, and more - Integrate our weather maps to your mobile applications and websites - Use as layers in Direct Tiles, OpenLayers, Leaflet, and Google Maps - Included in both free and paid subscriptions ### Global Precipitation Maps Historical data - Current and historical weather maps for the previous 2 days - Historical precipitation data with 10-minutes step - Resolution higher than 1 km - Use as layers in Direct Tiles, OpenLayers, Leaflet, and Google Maps - Included in Professional and Expert subscription plans ### Global Precipitation Maps Historical & Forecast data - Current, forecast and historical precipitation maps - Forecast is available for the next 6 hours for the US territory and for the next 2 hours for other global areas - The historical weather map for the previous 2 days - Data update period is every 10 minutes - Resolution higher than 1 km - Use as layers in Direct Tiles, OpenLayers, Leaflet, and Google Maps ### Relief Maps - The combination of a layer tint (colored raster) and a hillshade - Customizable color palette - Use as layers in Direct Tiles, OpenLayers, Leaflet, and Google Maps - Included in Developer, Professional and Expert subscription plans ### Air Pollution API - Current, forecast and historical air pollution data - Forecast for 4 days ahead with 1-hour step - Air Pollution API includes both Air Quality Index and indices for CO, NO, NO2, O3, SO2, NH3, PM2.5, PM10 - Included in both free and paid subscriptions ### Fire Weather Index Maps - Current and 5 days daily forecast fire weather index maps - Use as layers in Direct Tiles, OpenLayers, Leaflet, and Google Maps ### Fire Weather Index API - Current fire index and daily forecast for 5 days are available for any geo location (lat/lon) - JSON format - Please [contact us](mailto:info@openweathermap.org) to get a quote ### Geocoding API - Geocoding API supports both the direct and reverse methods, working at the level of city names, areas and districts, countries and states - You can cap how many locations with the same name or the nearby geographic coordinates will be seen in the API response - Included in both free and paid subscriptions ### Weather Stations - API for managing your personal weather stations - Connect your stations and transfer the measurements - Receive the aggregated measurements from the station - Included in both free and paid subscriptions ### Sign Up & Get Your API Key Create an account on OpenWeather to access your dashboard and generate your unique API key. This key is required for all API requests. ### Choose the Right API OpenWeather offers a variety of APIs to fit different needs. Get full technical documentation, response examples, and integration tips. ### FAQ Find quick answers to common questions about APIs, data coverage, limits, and integration. --- ## Accumulated Parameters The Accumulated Parameters include accumulated temperature and accumulated precipitation. - Accumulated temperature is the sum, counted in degrees, by which the actual air temperature rises above or falls below a threshold level during the chosen time period. - Accumulated precipitation is the sum, counted in millimeters, of daily precipitation during the chosen time period. ## Accumulated temperature ### API call ```text http://history.openweathermap.org/data/2.5/history/accumulated_temperature?lat={lat}&lon={lon}&start={start}&end={end}&threshold={threshold}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat, lon` | Yes | Geographical coordinates (latitude, longitude). If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md). | | `start` | Yes | Start date (unix time, UTC time zone), e.g. start=1586853378 | | `end` | Yes | End date (unix time, UTC time zone), e.g. end=1589445367 | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `threshold` | optional | All values smaller than indicated value are not taken into account | > Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around. > > Please note that [built-in geocoder](#geocoding) has been deprecated. Although it is still available for use, bug fixing and updates are no longer available for this functionality. ### Example of API call ```text http://history.openweathermap.org/data/2.5/history/accumulated_temperature?lat=51.51&lon=-0.13&start=1586853378&end=1589445367&threshold=284&appid={API key} ``` ### Example of API response ```json { "date": "2020-4-17", "temp": 574.37, "count": 2 }, ``` ### Fields in API response - `date` Date - `temp` Temperature accumulated indicator, Kelvin - `count` Number of data measurements ## Accumulated precipitation ### API call ```text http://history.openweathermap.org/data/2.5/history/accumulated_precipitation?lat={lat}&lon={lon}&start={start}&end={end}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat, lon` | Yes | Geographical coordinates (latitude, longitude). If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md). | | `start` | Yes | Start date (unix time, UTC time zone), e.g. start=1586853378 | | `end` | Yes | End date (unix time, UTC time zone), e.g. end=1589445367 | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | > Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around. > > Please note that [built-in geocoder](#geocoding) has been deprecated. Although it is still available for use, bug fixing and updates are no longer available for this functionality. ### Example of API call ```text http://history.openweathermap.org/data/2.5/history/accumulated_precipitation?lat=51.51&lon=-0.12&start=1586853378&end=1589445367&appid={API key} ``` ### Example of API response ```json { "date": "2020-4-15", "rain": 0.6, "count": 2 }, ``` ### Fields in API response - `date` Date - `rain` Precipitation accumulation indicator, mm - `count` Number of data measurements > The threshold parameter is not used. The whole ammount of precipitation data is provided for specified period. ## Other features ### Geocoding API Requesting API calls by geographical coordinates is the most accurate way to specify any location. If you need to convert city names and zip-codes to geo coordinates and the other way around automatically, please use our [Geocoding API](/api/geocoding-api.md). ### Built-in geocoding > Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around. > > **Please note that API requests by **[**city name**](/api/accumulated-parameters.md#name)** and **[**city id**](/api/accumulated-parameters.md#cityid)** have been deprecated. Although they are still available for use, bug fixing and updates are no longer available for this functionality.** ### Built-in API request by city name Please use the parameter `q` instead of the parameters `lat,lon` to specify the city name in the API requests. | Parameters | | | | --- | --- | --- | | `q` | Yes | City name, state code and country code divided by comma, please refer to [ISO 3166](https://www.iso.org/obp/ui/) for the state codes or country codes. You can specify the parameter not only in English. In this case, the API response should be returned in the same language as the language of requested location name if the location is in our predefined list of more than 200,000 locations. | ### Example of API calls ### Accumulated temperature ```text http://history.openweathermap.org/data/2.5/history/accumulated_temperature?q=London,GB&start=1586853378&end=1589445367&threshold=284&appid={API key} ``` ### Accumulated precipitation ```text http://history.openweathermap.org/data/2.5/history/accumulated_precipitation?q=London,GB&start=1586853378&end=1589445367&appid={API key} ``` ### Built-in API request by city id Please use the parameter `id` instead of the parameters `lat,lon` to specify the city id in the API requests. | Parameters | | | | --- | --- | --- | | `id` | Yes | City ID. The list of city IDs 'city.list.json.gz' can be downloaded [here](http://bulk.openweathermap.org/sample/). | ### Example of API calls ### Accumulated temperature ```text http://history.openweathermap.org/data/2.5/history/accumulated_temperature?id=2885679&start=1586853378&end=1589445367&threshold=284&appid={API key} ``` ### Accumulated precipitation ```text http://history.openweathermap.org/data/2.5/history/accumulated_precipitation?id=2885679&start=1586853378&end=1589445367&appid={API key} ``` --- ## Migration Guide from AccuWeather API Free Tier to OpenWeather API ### Welcome to OpenWeather **AccuWeather has recently updated its API access model.** If you’re reviewing your integration strategy, OpenWeather is here as a reliable alternative, offering clear terms, a stable platform, and optional migration support to ensure a smooth transition. Trusted by thousands of businesses and millions of developers worldwide, OpenWeather provides accurate, global weather data through reliable, developer-friendly APIs. Best of all, **our free tier is here to stay.** What makes OpenWeather a great choice: - **Flexible Usage:** Enjoy up to 1,000 API calls per day, 60 calls per minute, and up to 1,000,000 calls per month (depending on the API type) — perfect for projects of any size. - **Comprehensive Weather Data:** Get extended daily forecasts, detailed hourly updates, and a wide range of weather insights, all included in our free plan. - **Long-Term Reliability:** Our free plan is designed for ongoing access, ensuring stability and consistency for your applications. - **Developer-Friendly:** Easy integration and flexible APIs help you build faster and more efficiently. With OpenWeather, you get a **stable, scalable, and future-proof solution** for both everyday use and long-term development. ## How to choose the right OpenWeather product for your migration | | | | --- | --- | | **AccuWeather API Free Tier** | **OpenWeather FREE** | | Locations | [Geocoding (Direct/Reverse)](/api/geocoding-api.md) query by city name or **lat/lon** | | Current Conditions | [Current Weather](/current.md)/ [One Call 3.0: Current](/api/one-call-3.md) | | Daily Forecast (5 Days) | [One Call 3.0: Daily 8 days](/api/one-call-3.md)/ [3-hour Forecast 5 days](/forecast5.md) | | Hourly Forecast (12 Hours) | [One Call 3.0: Hourly 48 hours](/api/one-call-3.md) | | 24h Historical Current Conditions | [One Call 3.0: Timemachine](/api/one-call-3.md) any timestamp from 1979 | | Indices (5 Days) | [UV Index (One Call 3.0)](/api/one-call-3.md) & [Air Pollution (AQI)](/api/air-pollution.md) | ## Save More with OpenWeather By using OpenWeather, you’re not only keeping access to all the essential free services you already rely on — you’re also unlocking premium-grade features **at no additional cost**. | | | | | --- | --- | --- | | **Service / Feature** | **AccuWeather (paid tier & price)** | **OpenWeather (Free)** | | Minute forecast (1 hour) | MinuteCast® add-on — $25/mo (Standard) · $100/mo (Elite) | Minute-by-minute precipitation (1 hour) — [One Call 3.0 minutely](/api/one-call-3.md) | | National weather alerts | Available only with paid packages (Prime/Elite); base package $250–$500/mo | National weather alerts — [One Call 3.0 alerts](/api/one-call-3.md) | | Hourly forecast | Free tier includes 12 hours; longer horizons require paid packages (from $250/mo) | Hourly forecast 48 hours — [One Call 3.0 hourly](/api/one-call-3.md) | | Daily forecast | Free tier shows 5 days; extended daily in paid packages (from $250/mo) | Daily forecast 8 days — [One Call 3.0 daily](/api/one-call-3.md) | | Historical weather. | Not provided in the developer portal | Historical by timestamp (since 1979) — [One Call 3.0 timemachine](/api/one-call-3.md) | | | | | | --- | --- | --- | | **Service / Feature** | **One Call 3.0** | **OpenWeather Free** | | [Current weather data](/current.md) | ✔ | ✔ | | [Minute forecast (1 hour)](/api/one-call-3.md) | ✔ | | | [Hourly forecast (up to 48h)](/api/hourly-forecast.md) | ✔ | | | [Daily forecast (up to 8d)](/api/one-call-3.md) | ✔ | | | [3-hour forecast (5 days)](/forecast5.md) | | ✔ | | [Historical weather (since 1979)](https://openweathermap.org/api/one-call-3#history) | ✔ | | | [Air quality index (AQI)](/api/air-pollution.md) | | ✔ | | UV index | ✔ | | | [National weather alerts](/openweather-alerts.md) | ✔ | | | [Geocoding (direct/reverse)](/api/geocoding-api.md) | | ✔ | | Time zone data | ✔ | | | Subscription | Separate subscription | Activated upon receiving an API key | | Credit card required | ✔ | | | Calls limit | 1,000 API calls/day | 60 calls/minute and 1,000,000 calls/month | ## How to get an OpenWeather API key 1. [Sign up](https://home.openweathermap.org/users/sign_up) and get an API key (APPID) on [your account page](https://home.openweathermap.org/users/sign_in). 2. Verify your email address via a confirmation letter that will be sent to you. 1 hour after registering, it is possible to resend the confirmation yourself in the profile settings. 3. After verification, check your Inbox again to find our welcome email that contains your API key and important information. > Congratulations! Now you have an OpenWeather account with a free [subscription plan](https://home.openweathermap.org/subscriptions) and can immediately start using our services. ## One Call API 3.0 — direct replacement for AccuWeather API FREE services. 1. [Free access and pay-as-you-call subscription](/full-price.md) One Call API 3.0 has its own, separate subscription that has a variable cost, in proportion to your actual use of the API. **1,000 API calls per day is included for free**. Users can configure and limit their usage to ensure that they don’t make more request than expected. Read more on the [pricing page](/price.md) and in the [FAQ](/faq.md). 2. One Call API 3.0 contains 4 endpoints and provides access to various data: 3. - [Current weather and forecasts:](/api/one-call-3.md#current) - minute forecast for 1 hour - hourly forecast for 48 hours - daily forecast for 8 days - and government weather alerts - [Weather data for any timestamp](/api/one-call-3.md#history) for 47+ years historical archive and 4 days ahead forecast - [Daily aggregation](/api/one-call-3.md#history_daily_aggregation) of weather data for 47+ years archive and 1.5 years ahead forecast - [Weather overview](/api/one-call-3.md#weather_overview) with a human-readable weather summary for today and tomorrow's forecast - [AI Weather Assistant](/api/one-call-3.md#ai_weather_assistant) for retrieving weather data and weather-related advice in a human-readable and friendly format 4. Matching parameters of Accuweather APIs and OpenWeather APIs you can find under description of each specific parameter > If you don’t need the full One Call 3.0 stack or don’t want to add a card. Use our Free Access APIs without subscribing to One Call 3.0 or adding a card. ## Our Free Solutions If you don’t need the full One Call 3.0 stack or don’t want to add a card. Use our **Free Access** APIs without subscribing to One Call 3.0 or adding a card: - [Current Weather Data](/current.md) for weather live conditions - [Air Pollution (AQI)](/api/air-pollution.md) for air quality and pollutant concentrations - [Geocoding](/api/geocoding-api.md) to convert place names to coordinates - **5-day / 3-hour Forecast** 5 days ahead forecast with 3-hour step Free Access limits are **60 calls/minute** and **1,000,000 calls/month**. Connection steps and request examples are provided below in instructions. These options are not mutually exclusive. You can use One Call 3.0 as well as other API services at the same time. ## Looking for more options? In addition to the features listed above, OpenWeather also provides a wide range of other solutions designed for different business and development needs. - You can explore the full range of products and pricing on our [Pricing page](/full-price.md) - For tailored advice or enterprise solutions, feel free to contact our [Sales team](mailto:info@openweathermap.org) ## Matching products ### 1. Locations API AccuWeather’s Locations API gives you a place ID for later calls. In OpenWeather you don’t need that ID — all weather endpoints accept latitude and longitude. Our [Geocoding API](/api/geocoding-api.md) turns city names into coordinates and vice versa, so you can show a city name in your app and call weather data by coordinates. - **AccuWeather URL:** [`http://dataservice.accuweather.com/locations/v1/cities/geoposition/search`](http://dataservice.accuweather.com/locations/v1/cities/geoposition/search) - **OpenWeather URLs:** - **Direct Geocoding (by name):** `http://api.openweathermap.org/geo/1.0/direct?q={city name},{state code},{country code}&limit={limit}&appid={API key}` - **Reverse Geocoding (by coordinates):** `http://api.openweathermap.org/geo/1.0/reverse?lat={lat}&lon={lon}&limit={limit}&appid={API key}` | AccuWeather | OpenWeather | Meaning | | --- | --- | --- | | Version | — | API version. | | Key | — | AccuWeather location key (identifier). | | Type | — | Location type (e.g., City, PostalCode, POI, LatLong). | | Rank | — | Location rank (importance/population). | | LocalizedName | `name` | Location name in the requested/local language. | | EnglishName | `local_names.en` | Location name in English. | | PrimaryPostalCode | — | Primary postal/ZIP code for the location. | | AccuWeather | OpenWeather | Meaning | | Version | — | API version. | | Key | — | AccuWeather location key (identifier). | | Type | — | Location type (e.g., City, PostalCode, POI, LatLong). | | Rank | — | Location rank (importance/population). | | LocalizedName | `name` | Location name in the requested/local language. | | EnglishName | `local_names.en` | Location name in English. | | PrimaryPostalCode | — | Primary postal/ZIP code for the location. | | Region.ID | — | Unique region code (continent/major region). | | Region.LocalizedName | — | Region name in local language. | | Region.EnglishName | — | Region name in English. | | Country.ID | `country` | Country code (ISO 3166-1 alpha-2). | | Country.LocalizedName | — | Country name in local language. | | Country.EnglishName | — | Country name in English. | | AdministrativeArea.ID | — | Administrative area ID. | | AdministrativeArea.LocalizedName | `state` | Administrative area (state/province) name, if available. | | AdministrativeArea.EnglishName | `state` | Administrative area (state/province) name, if available. | | AdministrativeArea.Level | — | Administrative subdivision level. | | AdministrativeArea.LocalizedType | — | Localized type of administrative area. | | AdministrativeArea.EnglishType | — | English type of administrative area. | | AdministrativeArea.CountryID | `country` | Country code for the administrative area. | | TimeZone.Code | — | Time zone code/abbreviation. | | TimeZone.Name | — | Time zone name. | | TimeZone.GmtOffset | — | GMT offset in hours. | | TimeZone.IsDaylightSaving | — | Whether daylight saving time is observed now. | | TimeZone.NextOffsetChange | — | Next DST/offset change timestamp. | | GeoPosition.Latitude | `lat` | Geographic latitude. | | GeoPosition.Longitude | `lon` | Geographic longitude. | | GeoPosition.Elevation.Metric.Value | — | Elevation value (metric). | | GeoPosition.Elevation.Metric.Unit | — | Elevation unit (metric). | | GeoPosition.Elevation.Metric.UnitType | — | Elevation unit type ID (metric). | | GeoPosition.Elevation.Imperial.Value | — | Elevation value (imperial). | | GeoPosition.Elevation.Imperial.Unit | — | Elevation unit (imperial). | | GeoPosition.Elevation.Imperial.UnitType | — | Elevation unit type ID (imperial). | | IsAlias | — | Whether the location is an alias/alternate name. | | ParentCity | — | Parent metropolitan area object. | | ParentCity.Key | — | Parent city location key. | | ParentCity.LocalizedName | — | Parent city name (local language). | | ParentCity.EnglishName | — | Parent city name (English). | | SupplementalAdminAreas.Level | — | Supplemental admin area level. | | SupplementalAdminAreas.LocalizedName | — | Supplemental admin area name (local). | | SupplementalAdminAreas.EnglishName | — | Supplemental admin area name (English). | | DataSets | — | Available location-specific product datasets. | | Details.Key | — | Location key (details section). | | Details.StationCode | — | Weather station code. | | Details.StationGmtOffset | — | Weather station GMT offset. | | Details.BandMap | — | Temperature/precipitation band map code. | | Details.Climo | — | Climatology data source. | | Details.LocalRadar | — | Local radar code. | | Details.MediaRegion | — | Media region. | | Details.Metar | — | Associated METAR station. | | Details.NXMetro | — | City-level radar code. | | Details.NXState | — | State-level radar code. | | Details.Population | — | Reported population (may be null). | | Details.PrimaryWarningCountyCode | — | Primary warning county code. | | Details.PrimaryWarningZoneCode | — | Primary warning zone code. | | Details.Satellite | — | Associated satellite. | | Details.Synoptic | — | Associated synoptic station. | | Details.MarineStation | — | Marine station code. | | Details.MarineStationGMTOffset | — | Marine station GMT offset. | | Details.VideoCode | — | City/region video code. | | Details.PartnerID | — | DMA partner ID. | | Details.DMA.ID | — | Designated Market Area (DMA) ID. | | Details.DMA.EnglishName | — | DMA name (English). | | Details.Sources.DataType | — | Type of data provided by the source. | | Details.Sources.Source | — | Source/provider name. | | Details.Sources.SourceId | — | Source/provider ID. | | Details.CanonicalPostalCode | — | Canonical/optimized postal code. | | Details.CanonicalLocationKey | — | Canonical/optimized location key. | | Details.LocationStem | — | Internal location path. | | — | `local_names.ascii` | Internal field. | | — | `local_names.feature_name` | Internal field. | ## 2. Current Conditions For real-time weather, our [Current Weather API](/current.md) or the "current" section of our [One Call API 3.0](/api/one-call-3.md) are the perfect replacements. Both provide richer data fields than the AccuWeather equivalent. - **AccuWeather URL:** `http://dataservice.accuweather.com/currentconditions/v1/{locationKey}` - **OpenWeather URLs:** - [Current Weather API](/current.md): `https://api.openweathermap.org/data/2.5/weather?lat={lat}&lon={lon}&appid={API key}` - [One Call API 3.0](/api/one-call-3.md): `https://api.openweathermap.org/data/3.0/onecall?lat={lat}&lon={lon}&exclude={minutely,hourly,daily}&appid={API key}` Units of measurement: standard, metric and imperial units are available. If you do not use the units parameter, standard units will be applied by default. [Units documentation](/weather-data.md) | AccuWeather Current | OpenWeather One Call 3.0 Current | OpenWeather Current Weather | Meaning | | --- | --- | --- | --- | | LocalObservationDateTime | `current.dt` | `dt` | Observation time; adjust by timezone. | | EpochTime | — | — | Unix time. | | WeatherText | `current.weather.description` | `weather.description` | Weather description. | | WeatherIcon | `current.weather.icon` | `weather.icon` | Icon code. | | LocalSource.Id | — | — | Local source ID. | | LocalSource.Name | — | — | Local source name. | | LocalSource.WeatherCode | — | — | Local source code. | | IsDayTime | — | — | Daytime flag. | | Temperature.Metric.Value | `current.temp` | `main.temp` | Air temperature. | | Temperature.Metric.Unit | — | — | Unit label. | | Temperature.Metric.UnitType | — | — | Unit type code. | | Temperature.Imperial.Value | `current.temp` | `main.temp` | Air temperature. | | Temperature.Imperial.Unit | — | — | Unit label. | | Temperature.Imperial.UnitType | — | — | Unit type code. | | RealFeelTemperature | `current.feels_like` | `main.feels_like` | Feels like temperature. | | RealFeelTemperatureShade | — | — | Feels like in shade. | | RelativeHumidity | `current.humidity` | `main.humidity` | Humidity %. | | DewPoint | `current.dew_point` | — | Dew point. | | Wind.Direction.Degrees | `current.wind_deg` | `wind.deg` | Wind direction degrees. | | Wind.Direction.English | — | — | Wind direction text. | | Wind.Direction.Localized | — | — | Localized wind text. | | Wind.Speed | `current.wind_speed` | `wind.speed` | Wind speed. | | WindGust.Speed | `current.wind_gust` | `wind.gust` | Wind gust. | | UVIndex | `current.uvi` | — | UV index. | | UVIndexText | — | — | UV index label. | | Visibility | `current.visibility` | `visibility` | Visibility m. | | ObstructionsToVisibility | — | — | Visibility cause. | | CloudCover | `current.clouds` | `clouds.all` | Cloudiness %. | | Ceiling | — | — | Cloud ceiling. | | Pressure | `current.pressure` | `main.pressure` | Pressure hPa. | | PressureTendency.LocalizedText | — | — | Pressure tendency text. | | PressureTendency.Code | — | — | Pressure tendency code. | | Past24HourTemperatureDeparture | — | — | Temp change 24h. | | ApparentTemperature | `current.feels_like` | `main.feels_like` | Apparent temperature. | | WindChillTemperature | — | — | Wind chill. | | WetBulbTemperature | — | — | Wet-bulb temperature. | | WetBulbGlobeTemperature | — | — | WBGT. | | Precip1hr | — | — | Precip last hour mm. | | PrecipitationSummary.Precipitation | — | — | Deprecated precip summary. | | PrecipitationSummary.PastHour | — | — | Precip 1h mm. | | PrecipitationSummary.Past3Hours | — | — | Precip 3h. | | PrecipitationSummary.Past6Hours | — | — | Precip 6h. | | PrecipitationSummary.Past9Hours | — | — | Precip 9h. | | PrecipitationSummary.Past12Hours | — | — | Precip 12h. | | PrecipitationSummary.Past18Hours | — | — | Precip 18h. | | PrecipitationSummary.Past24Hours | — | — | Precip 24h. | | TemperatureSummary.Past6HourRange.Minimum | — | — | Min 6h. | | TemperatureSummary.Past6HourRange.Maximum | — | — | Max 6h. | | TemperatureSummary.Past12HourRange.Minimum | — | — | Min 12h. | | TemperatureSummary.Past12HourRange.Maximum | — | — | Max 12h. | | TemperatureSummary.Past24HourRange.Minimum | — | — | Min 24h. | | TemperatureSummary.Past24HourRange.Maximum | — | — | Max 24h. | | MobileLink | — | — | Mobile link. | | Link | — | — | Web link. | | HasPrecipitation | — | — | Precip present. | | PrecipitationType | `current.weather.main` | `weather.main` | Precip type. | | IndoorRelativeHumidity | — | — | Indoor humidity. | | — | `lat` | `coord.lat` | Latitude. | | — | `lon` | `coord.lon` | Longitude. | | — | `timezone` | `timezone` | Timezone name or shift. | | — | `timezone_offset` | `timezone` | UTC shift seconds. | | — | `current.sunrise` | `sys.sunrise` | Sunrise time. | | — | `current.sunset` | `sys.sunset` | Sunset time. | | — | `current.weather.id` | `weather.id` | Condition ID. | | — | `current.weather.main` | `weather.main` | Condition group. | | — | `current.weather.description` | `weather.description` | Condition text. | | — | `current.weather.icon` | `weather.icon` | Icon code. | | — | `current.rain` | `rain` | Rain object. | | — | `current.snow` | `snow` | Snow object. | | — | — | `main.temp_min` | Min temperature. | | — | — | `main.temp_max` | Max temperature. | | — | — | `main.sea_level` | Sea-level pressure. | | — | — | `main.grnd_level` | Ground pressure. | | — | — | `sys.country` | Country code. | | — | — | `id` | City ID. | | — | — | `name` | City name. | | — | — | `base` | Internal. | | — | — | `sys.type` | Internal. | | — | — | `sys.id` | Internal. | | — | — | `sys.message` | Internal. | | — | — | `cod` | Internal. | ## 3. 24 Hours Historical Current Conditions While AccuWeather provided 24 hours of historical data, our [One Call API 3.0](/api/one-call-3.md) gives you access to historical weather for any timestamp from **January 1, 1979**, to 4 days ahead. - **AccuWeather URL:** `http://dataservice.accuweather.com/currentconditions/v1/{locationKey}/historical/24` - **OpenWeather URL:** - **Historical Data: ** `https://api.openweathermap.org/data/3.0/onecall/timemachine?lat={lat}&lon={lon}&dt={time}&appid={API key}` Units of measurement: standard, metric and imperial units are available. If you do not use the units parameter, standard units will be applied by default. [Units documentation](/weather-data.md) | AccuWeather Historical | OpenWeather One Call 3.0 Historical | Meaning | | --- | --- | --- | | LocalObservationDateTime | `data.dt` | Observation time. | | EpochTime | `data.dt` | Unix time. | | WeatherText | `data.weather.description` | Weather description. | | WeatherIcon | `data.weather.icon` | Icon code. | | LocalSource.Id | — | Local source ID. | | LocalSource.Name | — | Local source name. | | LocalSource.WeatherCode | — | Local source code. | | IsDayTime | — | Daytime flag. | | Temperature.Metric.Value | `data.temp` | Air temperature. | | Temperature.Metric.Unit | — | Unit label. | | Temperature.Metric.UnitType | — | Unit type code. | | Temperature.Imperial.Value | `data.temp` | Air temperature. | | Temperature.Imperial.Unit | — | Unit label. | | Temperature.Imperial.UnitType | — | Unit type code. | | RealFeelTemperature | `data.feels_like` | Feels like temperature. | | RealFeelTemperatureShade | — | Feels like in shade. | | RelativeHumidity | `data.humidity` | Humidity percent. | | DewPoint | `data.dew_point` | Dew point. | | Wind.Direction.Degrees | `data.wind_deg` | Wind direction degrees. | | Wind.Direction.English | — | Wind direction text. | | Wind.Direction.Localized | — | Localized wind text. | | Wind.Speed | `data.wind_speed` | Wind speed. | | WindGust.Speed | `data.wind_gust` | Wind gust. | | UVIndex | `data.uvi` | UV index. | | UVIndexText | — | UV index label. | | Visibility | `data.visibility` | Visibility meters. | | ObstructionsToVisibility | — | Visibility cause. | | CloudCover | `data.clouds` | Cloudiness percent. | | Ceiling | — | Cloud ceiling. | | Pressure | `data.pressure` | Pressure hPa. | | PressureTendency.LocalizedText | — | Pressure tendency text. | | PressureTendency.Code | — | Pressure tendency code. | | Past24HourTemperatureDeparture | — | Temp change 24h. | | ApparentTemperature | `data.feels_like` | Apparent temperature. | | WindChillTemperature | — | Wind chill. | | WetBulbTemperature | — | Wet bulb temperature. | | WetBulbGlobeTemperature | — | WBGT. | | Precip1hr | — | Precipitation last hour mm. | | PrecipitationSummary.Precipitation | — | Deprecated precipitation summary. | | PrecipitationSummary.PastHour | — | Precipitation 1h mm. | | PrecipitationSummary.Past3Hours | — | Precipitation 3h. | | PrecipitationSummary.Past6Hours | — | Precipitation 6h. | | PrecipitationSummary.Past9Hours | — | Precipitation 9h. | | PrecipitationSummary.Past12Hours | — | Precipitation 12h. | | PrecipitationSummary.Past18Hours | — | Precipitation 18h. | | PrecipitationSummary.Past24Hours | — | Precipitation 24h. | | TemperatureSummary.Past6HourRange.Minimum | — | Minimum 6h. | | TemperatureSummary.Past6HourRange.Maximum | — | Maximum 6h. | | TemperatureSummary.Past12HourRange.Minimum | — | Minimum 12h. | | TemperatureSummary.Past12HourRange.Maximum | — | Maximum 12h. | | TemperatureSummary.Past24HourRange.Minimum | — | Minimum 24h. | | TemperatureSummary.Past24HourRange.Maximum | — | Maximum 24h. | | MobileLink | — | Mobile link. | | Link | — | Web link. | | HasPrecipitation | — | Precipitation present. | | PrecipitationType | `data.weather.main` | Precipitation type. | | IndoorRelativeHumidity | — | Indoor humidity. | | — | `lat` | Latitude. | | — | `lon` | Longitude. | | — | `timezone` | Timezone name. | | — | `timezone_offset` | UTC shift seconds. | | — | `data.sunrise` | Sunrise time. | | — | `data.sunset` | Sunset time. | | — | `data.weather` | Weather object. | | — | `data.weather.id` | Condition ID. | | — | `data.weather.main` | Condition group. | | — | `data.weather.description` | Condition text. | | — | `data.weather.icon` | Icon code. | | — | `data.rain` | Rain object. | | — | `data.rain.1h` | Rain last hour mm. | | — | `data.snow` | Snow object. | | — | `data.snow.1h` | Snow last hour mm. | ## 4. Daily Forecast (5 Days) You can easily migrate your 5-day forecast to our [One Call API 3.0](/api/one-call-3.md), which provides a more extensive **8-day daily forecast**. - **AccuWeather URL:** `http://dataservice.accuweather.com/forecasts/v1/daily/5day/{locationKey}` - **OpenWeather URL:** - **8-Day Forecast:** `https://api.openweathermap.org/data/3.0/onecall?lat={lat}&lon={lon}&exclude=current,minutely,hourly&appid={API key}` - **3-hour Forecast 5 days: ** `https://api.openweathermap.org/data/3.0/onecall?lat={lat}&lon={lon}&exclude=current,minutely,hourly&appid={API key}` Units of measurement: standard, metric and imperial units are available. If you do not use the units parameter, standard units will be applied by default. [Units documentation](/weather-data.md) | AccuWeather Forecast | OpenWeather One Call 3.0 8 days Forecast | OpenWeather 5 days 3 hours Forecast | Meaning | | --- | --- | --- | --- | | Headline.EffectiveDate | — | — | Start time | | Headline.EffectiveEpochDate | — | — | Start time unix | | Headline.Severity | — | — | Severity index | | Headline.Text | — | — | Alert text | | Headline.Category | — | — | Alert event | | Headline.EndDate | — | — | End time | | Headline.EndEpochDate | — | — | End time unix | | Headline.MobileLink | — | — | Mobile link | | Headline.Link | — | — | Web link | | DailyForecasts.Date | `daily.dt` | `list.dt_txt` | Day time | | DailyForecasts.EpochDate | — | — | Day time unix | | DailyForecasts.Sun.Rise | `daily.sunrise` | `city.sunrise` | Sunrise | | DailyForecasts.Sun.EpochRise | — | — | Sunrise unix | | DailyForecasts.Sun.Set | `daily.sunset` | `city.sunset` | Sunset | | DailyForecasts.Sun.EpochSet | — | — | Sunset unix | | DailyForecasts.Moon.Rise | `daily.moonrise` | — | Moonrise | | DailyForecasts.Moon.EpochRise | — | — | Moonrise unix | | DailyForecasts.Moon.Set | `daily.moonset` | — | Moonset | | DailyForecasts.Moon.EpochSet | — | — | Moonset unix | | DailyForecasts.Moon.Phase | `daily.moon_phase` | — | Moon phase | | DailyForecasts.Moon.Age | — | — | Moon age | | DailyForecasts.Temperature.Minimum.Value | `daily.temp.min` | `list.main.temp_min` | Min temp | | DailyForecasts.Temperature.Minimum.Unit | — | — | Unit label | | DailyForecasts.Temperature.Minimum.UnitType | — | — | Unit type | | DailyForecasts.Temperature.Maximum.Value | `daily.temp.max` | `list.main.temp_max` | Max temp | | DailyForecasts.Temperature.Maximum.Unit | — | — | Unit label | | DailyForecasts.Temperature.Maximum.UnitType | — | — | Unit type | | DailyForecasts.RealFeelTemperature.Minimum.Value | — | — | RealFeel min | | DailyForecasts.RealFeelTemperature.Minimum.Unit | — | — | Unit label | | DailyForecasts.RealFeelTemperature.Minimum.UnitType | — | — | Unit type | | DailyForecasts.RealFeelTemperature.Maximum.Value | — | — | RealFeel max | | DailyForecasts.RealFeelTemperature.Maximum.Unit | — | — | Unit label | | DailyForecasts.RealFeelTemperature.Maximum.UnitType | — | — | Unit type | | DailyForecasts.RealFeelTemperatureShade.Minimum.Value | — | — | RealFeel shade min | | DailyForecasts.RealFeelTemperatureShade.Minimum.Unit | — | — | Unit label | | DailyForecasts.RealFeelTemperatureShade.Minimum.UnitType | — | — | Unit type | | DailyForecasts.RealFeelTemperatureShade.Maximum.Value | — | — | RealFeel shade max | | DailyForecasts.RealFeelTemperatureShade.Maximum.Unit | — | — | Unit label | | DailyForecasts.RealFeelTemperatureShade.Maximum.UnitType | — | — | Unit type | | DailyForecasts.HoursOfSun | — | — | Sun hours | | DailyForecasts.DegreeDaySummary.Heating.Value | — | — | Heating degree days | | DailyForecasts.DegreeDaySummary.Heating.Unit | — | — | Unit label | | DailyForecasts.DegreeDaySummary.Heating.UnitType | — | — | Unit type | | DailyForecasts.DegreeDaySummary.Cooling.Value | — | — | Cooling degree days | | DailyForecasts.DegreeDaySummary.Cooling.Unit | — | — | Unit label | | DailyForecasts.DegreeDaySummary.Cooling.UnitType | — | — | Unit type | | DailyForecasts.AirAndPollen.Name | — | — | Air or pollen name | | DailyForecasts.AirAndPollen.Value | — | — | Air or pollen value | | DailyForecasts.AirAndPollen.Category | — | — | Air or pollen category | | DailyForecasts.AirAndPollen.CategoryValue | — | — | Category value | | DailyForecasts.AirAndPollen.Type | — | — | Pollutant type | | DailyForecasts.Day.Icon | `daily.weather.icon` | `list.weather.icon` | Day icon | | DailyForecasts.Day.IconPhrase | `daily.weather.description` | `list.weather.description` | Day phrase | | DailyForecasts.Day.LocalSource.Id | — | — | Local source id | | DailyForecasts.Day.LocalSource.Name | — | — | Local source name | | DailyForecasts.Day.LocalSource.WeatherCode | — | — | Local code | | DailyForecasts.Day.HasPrecipitation | — | — | Precip present | | DailyForecasts.Day.PrecipitationType | `daily.weather.main` | `list.weather.main` | Precip type | | DailyForecasts.Day.PrecipitationIntensity | — | — | Precip intensity | | DailyForecasts.Day.ShortPhrase | `daily.weather.description` | `list.weather.description` | Short phrase | | DailyForecasts.Day.LongPhrase | `daily.weather.description` | `list.weather.description` | Long phrase | | DailyForecasts.Day.PrecipitationProbability | `daily.pop` | `list.pop` | Precip probability | | DailyForecasts.Day.ThunderstormProbability | — | — | Thunder probability | | DailyForecasts.Day.RainProbability | — | — | Rain probability | | DailyForecasts.Day.SnowProbability | — | — | Snow probability | | DailyForecasts.Day.IceProbability | — | — | Ice probability | | DailyForecasts.Day.Wind.Speed.Value | `daily.wind_speed` | `list.wind.speed` | Wind speed | | DailyForecasts.Day.Wind.Speed.Unit | — | — | Unit label | | DailyForecasts.Day.Wind.Speed.UnitType | — | — | Unit type | | DailyForecasts.Day.Wind.Direction.Degrees | `daily.wind_deg` | `list.wind.deg` | Wind direction | | DailyForecasts.Day.Wind.Direction.Localized | — | — | Direction text local | | DailyForecasts.Day.Wind.Direction.English | — | — | Direction text en | | DailyForecasts.Day.WindGust.Speed.Value | `daily.wind_gust` | `list.wind.gust` | Wind gust | | DailyForecasts.Day.WindGust.Speed.Unit | — | — | Unit label | | DailyForecasts.Day.WindGust.Speed.UnitType | — | — | Unit type | | DailyForecasts.Day.TotalLiquid.Value | — | — | Total liquid | | DailyForecasts.Day.TotalLiquid.Unit | — | — | Unit label | | DailyForecasts.Day.TotalLiquid.UnitType | — | — | Unit type | | DailyForecasts.Day.Rain.Value | `daily.rain` | `list.rain.3h` | Rain volume | | DailyForecasts.Day.Rain.Unit | — | — | Unit label | | DailyForecasts.Day.Rain.UnitType | — | — | Unit type | | DailyForecasts.Day.Snow.Value | `daily.snow` | `list.snow.3h` | Snow volume | | DailyForecasts.Day.Snow.Unit | — | — | Unit label | | DailyForecasts.Day.Snow.UnitType | — | — | Unit type | | DailyForecasts.Day.Ice.Value | — | — | Ice volume | | DailyForecasts.Day.Ice.Unit | — | — | Unit label | | DailyForecasts.Day.Ice.UnitType | — | — | Unit type | | DailyForecasts.Day.HoursOfPrecipitation | — | — | Hours with precip | | DailyForecasts.Day.HoursOfRain | — | — | Hours with rain | | DailyForecasts.Day.CloudCover | `daily.clouds` | `list.clouds.all` | Cloudiness | | DailyForecasts.Day.Evapotranspiration.Value | — | — | Evapotranspiration | | DailyForecasts.Day.Evapotranspiration.Unit | — | — | Unit label | | DailyForecasts.Day.Evapotranspiration.UnitType | — | — | Unit type | | DailyForecasts.Day.SolarIrradiance.Value | — | — | Solar irradiance | | DailyForecasts.Day.SolarIrradiance.Unit | — | — | Unit label | | DailyForecasts.Day.SolarIrradiance.UnitType | — | — | Unit type | | DailyForecasts.Day.RelativeHumidity.Minimum | — | — | RH min | | DailyForecasts.Day.RelativeHumidity.Maximum | — | — | RH max | | DailyForecasts.Day.RelativeHumidity.Average | `daily.humidity` | `list.main.humidity` | RH average | | DailyForecasts.Day.WetBulbTemperature.Minimum.Value | — | — | Wet bulb min | | DailyForecasts.Day.WetBulbTemperature.Minimum.Unit | — | — | Unit label | | DailyForecasts.Day.WetBulbTemperature.Minimum.UnitType | — | — | Unit type | | DailyForecasts.Day.WetBulbTemperature.Maximum.Value | — | — | Wet bulb max | | DailyForecasts.Day.WetBulbTemperature.Maximum.Unit | — | — | Unit label | | DailyForecasts.Day.WetBulbTemperature.Maximum.UnitType | — | — | Unit type | | DailyForecasts.Day.WetBulbTemperature.Average.Value | — | — | Wet bulb average | | DailyForecasts.Day.WetBulbTemperature.Average.Unit | — | — | Unit label | | DailyForecasts.Day.WetBulbTemperature.Average.UnitType | — | — | Unit type | | DailyForecasts.Day.WetBulbGlobeTemperature.Minimum.Value | — | — | WBGT min | | DailyForecasts.Day.WetBulbGlobeTemperature.Minimum.Unit | — | — | Unit label | | DailyForecasts.Day.WetBulbGlobeTemperature.Minimum.UnitType | — | — | Unit type | | DailyForecasts.Day.WetBulbGlobeTemperature.Maximum.Value | — | — | WBGT max | | DailyForecasts.Day.WetBulbGlobeTemperature.Maximum.Unit | — | — | Unit label | | DailyForecasts.Day.WetBulbGlobeTemperature.Maximum.UnitType | — | — | Unit type | | DailyForecasts.Day.WetBulbGlobeTemperature.Average.Value | — | — | WBGT average | | DailyForecasts.Day.WetBulbGlobeTemperature.Average.Unit | — | — | Unit label | | DailyForecasts.Day.WetBulbGlobeTemperature.Average.UnitType | — | — | Unit type | | DailyForecasts.Night.Icon | — | `list.weather.icon` | Night icon | | DailyForecasts.Night.IconPhrase | — | `list.weather.description` | Night phrase | | DailyForecasts.Night.LocalSource.Id | — | — | Local source id | | DailyForecasts.Night.LocalSource.Name | — | — | Local source name | | DailyForecasts.Night.LocalSource.WeatherCode | — | — | Local code | | DailyForecasts.Night.HasPrecipitation | — | — | Precip present | | DailyForecasts.Night.PrecipitationType | — | `list.weather.main` | Precip type | | DailyForecasts.Night.PrecipitationIntensity | — | — | Precip intensity | | DailyForecasts.Night.ShortPhrase | — | `list.weather.description` | Short phrase | | DailyForecasts.Night.LongPhrase | — | `list.weather.description` | Long phrase | | DailyForecasts.Night.PrecipitationProbability | — | `list.pop` | Precip probability | | DailyForecasts.Night.ThunderstormProbability | — | — | Thunder probability | | DailyForecasts.Night.RainProbability | — | — | Rain probability | | DailyForecasts.Night.SnowProbability | — | — | Snow probability | | DailyForecasts.Night.IceProbability | — | — | Ice probability | | DailyForecasts.Night.Wind.Speed | — | `list.wind.speed` | Wind object | | DailyForecasts.Night.Wind.Direction | — | `list.wind.deg` | Direction object | | DailyForecasts.Night.WindGust.Speed | — | `list.wind.gust` | Wind gust object | | DailyForecasts.Night.TotalLiquid | — | — | Total liquid | | DailyForecasts.Night.Rain | — | `list.rain.3h` | Rain object | | DailyForecasts.Night.Snow | — | `list.snow.3h` | Snow object | | DailyForecasts.Night.Ice | — | — | Ice object | | DailyForecasts.Night.HoursOfPrecipitation | — | — | Hours with precip | | DailyForecasts.Night.HoursOfRain | — | — | Hours with rain | | DailyForecasts.Night.CloudCover | — | `list.clouds.all` | Cloudiness | | DailyForecasts.Night.Evapotranspiration.Value | — | — | Evapotranspiration | | DailyForecasts.Night.Evapotranspiration.Unit | — | — | Unit label | | DailyForecasts.Night.Evapotranspiration.UnitType | — | — | Unit type | | DailyForecasts.Night.SolarIrradiance.Value | — | — | Solar irradiance | | DailyForecasts.Night.SolarIrradiance.Unit | — | — | Unit label | | DailyForecasts.Night.SolarIrradiance.UnitType | — | — | Unit type | | DailyForecasts.Night.RelativeHumidity.Minimum | — | — | RH min | | DailyForecasts.Night.RelativeHumidity.Maximum | — | — | RH max | | DailyForecasts.Night.RelativeHumidity.Average | — | — | RH average | | DailyForecasts.Night.WetBulbTemperature.Minimum.Value | — | — | Wet bulb min | | DailyForecasts.Night.WetBulbTemperature.Minimum.Unit | — | — | Unit label | | DailyForecasts.Night.WetBulbTemperature.Minimum.UnitType | — | — | Unit type | | DailyForecasts.Night.WetBulbTemperature.Maximum.Value | — | — | Wet bulb max | | DailyForecasts.Night.WetBulbTemperature.Maximum.Unit | — | — | Unit label | | DailyForecasts.Night.WetBulbTemperature.Maximum.UnitType | — | — | Unit type | | DailyForecasts.Night.WetBulbTemperature.Average.Value | — | — | Wet bulb average | | DailyForecasts.Night.WetBulbTemperature.Average.Unit | — | — | Unit label | | DailyForecasts.Night.WetBulbTemperature.Average.UnitType | — | — | Unit type | | DailyForecasts.Night.WetBulbGlobeTemperature.Minimum.Value | — | — | WBGT min | | DailyForecasts.Night.WetBulbGlobeTemperature.Minimum.Unit | — | — | Unit label | | DailyForecasts.Night.WetBulbGlobeTemperature.Minimum.UnitType | — | — | Unit type | | DailyForecasts.Night.WetBulbGlobeTemperature.Maximum.Value | — | — | WBGT max | | DailyForecasts.Night.WetBulbGlobeTemperature.Maximum.Unit | — | — | Unit label | | DailyForecasts.Night.WetBulbGlobeTemperature.Maximum.UnitType | — | — | Unit type | | DailyForecasts.Night.WetBulbGlobeTemperature.Average.Value | — | — | WBGT average | | DailyForecasts.Night.WetBulbGlobeTemperature.Average.Unit | — | — | Unit label | | DailyForecasts.Night.WetBulbGlobeTemperature.Average.UnitType | — | — | Unit type | | DailyForecasts.Sources | — | — | Forecast sources | | DailyForecasts.MobileLink | — | — | Mobile link | | DailyForecasts.Link | — | — | Web link | | — | `lat` | `city.coord.lat` | Latitude | | — | `lon` | `city.coord.lon` | Longitude | | — | `timezone` | — | Timezone | | — | `timezone_offset` | `city.timezone` | UTC offset | | — | `daily` | — | Daily block | | — | `daily.dt` | — | Day time | | — | `daily.sunrise` | — | Sunrise | | — | `daily.sunset` | — | Sunset | | — | `daily.moonrise` | — | Moonrise | | — | `daily.moonset` | — | Moonset | | — | `daily.moon_phase` | — | Moon phase | | — | `summary` | — | Day summary | | — | `daily.temp` | — | Temp object | | — | `daily.temp.morn` | — | Morning temp | | — | `daily.temp.day` | — | Day temp | | — | `daily.temp.eve` | — | Evening temp | | — | `daily.temp.night` | — | Night temp | | — | `daily.temp.min` | — | Min temp | | — | `daily.temp.max` | — | Max temp | | — | `daily.feels_like` | — | Feels like object | | — | `daily.feels_like.morn` | — | Morning feels like | | — | `daily.feels_like.day` | — | Day feels like | | — | `daily.feels_like.eve` | — | Evening feels like | | — | `daily.feels_like.night` | — | Night feels like | | — | `daily.pressure` | `list.main.pressure` | Pressure | | — | `daily.humidity` | `list.main.humidity` | Humidity | | — | `daily.dew_point` | — | Dew point | | — | `daily.wind_speed` | `list.wind.speed` | Wind speed | | — | `daily.wind_gust` | `list.wind.gust` | Wind gust | | — | `daily.wind_deg` | `list.wind.deg` | Wind direction | | — | `daily.clouds` | `list.clouds.all` | Cloudiness | | — | `daily.uvi` | — | Max UV index | | — | `daily.pop` | `list.pop` | Precip probability | | — | `daily.rain` | `list.rain.3h` | Rain volume | | — | `daily.snow` | `list.snow.3h` | Snow volume | | — | `daily.weather` | `list.weather` | Weather object | | — | `daily.weather.id` | `list.weather.id` | Condition id | | — | `daily.weather.main` | `list.weather.main` | Condition group | | — | `daily.weather.description` | `list.weather.description` | Condition text | | — | — | `list.weather.icon` | Icon code | | — | — | `cod` | Internal | | — | — | `message` | Internal | | — | — | `cnt` | Timestep count | | — | — | `list` | Forecast list | | — | — | `list.sys.pod` | Part of day | | — | — | `city` | City block | | — | — | `city.id` | City id | | — | — | `city.name` | City name | | — | — | `city.country` | Country code | | — | — | `city.population` | Population | | — | — | `list.main.grnd_level` | Ground pressure | | — | — | `list.main.humidity` | Humidity | | — | — | `list.main.temp_kf` | Internal | | — | — | `list.weather` | Weather block | | — | — | `list.weather.id` | Condition id | | — | — | `list.weather.main` | Condition group | | — | — | `list.weather.description` | Condition text | | — | — | `list.weather.icon` | Icon code | | — | — | `list.clouds` | Clouds block | | — | — | `list.visibility` | Visibility | | — | — | `list.rain` | Rain block | | — | — | `list.snow` | Snow block | | — | — | `list.sys` | Sys block | | — | — | `list.sys.pod` | Part of day | | — | — | `city` | City block | | — | — | `city.id` | City id | | — | — | `city.name` | City name | | — | — | `city.country` | Country code | | — | — | `city.population` | Population | ## 5. Hourly Forecast (12 Hours) Upgrade your 12-hour forecast to our **48-hour hourly forecast**, available in the [One Call API 3.0](/api/one-call-3.md). This gives you four times the forecast coverage. - **AccuWeather URL:** `http://dataservice.accuweather.com/forecasts/v1/hourly/12hour/{locationKey}` - **OpenWeather URL:** - **48-Hour Forecast: ** `https://api.openweathermap.org/data/3.0/onecall?lat={lat}&lon={lon}&exclude=current,minutely,daily&appid={API key}` Units of measurement: standard, metric and imperial units are available. If you do not use the units parameter, standard units will be applied by default. [Units documentation](/weather-data.md) | AccuWeather Hourly | OpenWeather One Call 3.0 | Meaning | | --- | --- | --- | | DateTime | `hourly.dt` | Forecast time | | EpochTime | `hourly.dt` | Unix time | | WeatherIcon | `hourly.weather.icon` | Icon code | | IconPhrase | `hourly.weather.description` | Weather description | | HasPrecipitation | — | Precip present | | PrecipitationType | `hourly.weather.main` | Precip type | | PrecipitationIntensity | — | Precip intensity | | IsDaylight | — | Daylight flag | | Temperature.Value | `hourly.temp` | Air temperature | | Temperature.Unit | — | Unit label | | Temperature.UnitType | — | Unit type | | RealFeelTemperature.Value | `hourly.feels_like` | Feels like | | RealFeelTemperature.Unit | — | Unit label | | RealFeelTemperature.UnitType | — | Unit type | | RealFeelTemperatureShade.Value | — | Feels like shade | | RealFeelTemperatureShade.Unit | — | Unit label | | RealFeelTemperatureShade.UnitType | — | Unit type | | WetBulbTemperature.Value | — | Wet bulb | | WetBulbTemperature.Unit | — | Unit label | | WetBulbTemperature.UnitType | — | Unit type | | WetBulbGlobeTemperature.Value | — | WBGT | | WetBublGlobeTemperature.Unit | — | Unit label | | WetBulbGlobeTemperature.UnitType | — | Unit type | | DewPoint.Value | `hourly.dew_point` | Dew point | | DewPoint.Unit | — | Unit label | | DewPoint.UnitType | — | Unit type | | Wind.Speed.Value | `hourly.wind_speed` | Wind speed | | Wind.Speed.Unit | — | Unit label | | Wind.Speed.UnitType | — | Unit type | | Wind.Direction.Degrees | `hourly.wind_deg` | Wind direction | | Wind.Direction.Localized | — | Direction text local | | Wind.Direction.English | — | Direction text en | | WindGust.Speed.Value | `hourly.wind_gust` | Wind gust | | WindGust.Speed.Unit | — | Unit label | | WindGust.Speed.UnitType | — | Unit type | | RelativeHumidity | `hourly.humidity` | Humidity | | Visibility.Value | `hourly.visibility` | Visibility | | Visibility.Unit | — | Unit label | | Visibility.UnitType | — | Unit type | | Ceiling.Value | — | Cloud ceiling | | Ceiling.Unit | — | Unit label | | Ceiling.UnitType | — | Unit type | | UVIndex | `hourly.uvi` | UV index | | UVIndexText | — | UV label | | PrecipitationProbability | `hourly.pop` | Precip probability | | RainProbability | — | Rain probability | | SnowProbability | — | Snow probability | | IceProbability | — | Ice probability | | TotalLiquid.Value | — | Total liquid | | TotalLiquid.Unit | — | Unit label | | TotalLiquid.UnitType | — | Unit type | | Rain.Value | `hourly.rain.1h` | Rain last hour | | Rain.Unit | — | Unit label | | Rain.UnitType | — | Unit type | | Snow.Value | `hourly.snow.1h` | Snow last hour | | Snow.Unit | — | Unit label | | Snow.UnitType | — | Unit type | | Ice.Value | — | Ice amount | | Ice.Unit | — | Unit label | | Ice.UnitType | — | Unit type | | CloudCover | `hourly.clouds` | Cloudiness | | Evapotranspiration.Value | — | Evapotranspiration | | Evapotranspiration.Unit | — | Unit label | | Evapotranspiration.UnitType | — | Unit type | | SolarIrradiance.Value | — | Solar irradiance | | SolarIrradiance.Unit | — | Unit label | | SolarIrradiance.UnitType | — | Unit type | | MobileLink | — | Mobile link | | Link | — | Web link | | — | `lat` | Latitude | | — | `lon` | Longitude | | — | `timezone` | Timezone | | — | `timezone_offset` | UTC offset | | — | `hourly` | Hourly block | | — | `hourly.rain` | Rain object | | — | `hourly.snow` | Snow object | | — | `hourly.weather` | Weather object | ## 6. Indices AccuWeather's 5-Day Indices can be migrated to OpenWeather by using the [One Call API 3.0](/api/one-call-3.md) for UV Index data and the [Air Pollution API](/api/air-pollution.md) for air quality information. - **AccuWeather URL:** `http://dataservice.accuweather.com/indices/v1/daily/5day/{locationKey}` - **OpenWeather URLs:** - **UV Index (via One Call API):** `https://api.openweathermap.org/data/3.0/onecall?lat={lat}&lon={lon}&appid={API key}` - **Air Pollution:** `http://api.openweathermap.org/data/2.5/air_pollution?lat={lat}&lon={lon}&appid={API key}` | AccuWeather Indices | OpenWeather One Call 3.0 UV | OpenWeather Air Pollution | Meaning | | --- | --- | --- | --- | | Name | — | — | Index name | | ID | — | — | Index ID | | Ascending | — | — | Scale direction | | LocalDateTime | — | `list.dt` | Time | | EpochDateTime | — | — | Unix time | | Value | — | — | Index value | | Category | — | — | Category text | | CategoryValue | — | — | Category level | | Text | — | — | Summary text | | MobileLink | — | — | Mobile link | | Link | — | — | Web link | | — | — | `coord` | Coordinates | | — | — | `list` | Air data list | | — | — | `main.aqi` | Air quality level | | — | — | `components` | Pollutants object | | — | — | `components.co` | CO µg/m³ | | — | — | `components.no` | NO µg/m³ | | — | — | `components.no2` | NO₂ µg/m³ | | — | — | `components.o3` | O₃ µg/m³ | | — | — | `components.so2` | SO₂ µg/m³ | | — | — | `components.pm2_5` | PM2.5 µg/m³ | | — | — | `components.pm10` | PM10 µg/m³ | | — | — | `components.nh3` | NH₃ µg/m³ | | — | `current.uvi` | — | UV index current | | — | `hourly.uvi` | — | UV index hourly | | — | `daily.uvi` | — | UV index daily | --- ## Air Pollution API concept Air Pollution API provides current, forecast and historical air pollution data for any coordinates on the globe. Besides basic Air Quality Index, the API returns data about polluting gases, such as Carbon monoxide (CO), Nitrogen monoxide (NO), Nitrogen dioxide (NO2), Ozone (O3), Sulphur dioxide (SO2), Ammonia (NH3), and particulates (PM2.5 and PM10). Air pollution forecast is available for 4 days with hourly granularity. Historical data is accessible from 27th November 2020. Here is a description of OpenWeather scale for Air Quality Index levels: | Qualitative name | Index | Pollutant concentration in μg/m3 | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | | | | SO2 | NO2 | PM10 | PM2.5 | O3 | CO | | Good | 1 | [0; 20) | [0; 40) | [0; 20) | [0; 10) | [0; 60) | [0; 4400) | | Fair | 2 | [20; 80) | [40; 70) | [20; 50) | [10; 25) | [60; 100) | [4400; 9400) | | Moderate | 3 | [80; 250) | [70; 150) | [50; 100) | [25; 50) | [100; 140) | [9400-12400) | | Poor | 4 | [250; 350) | [150; 200) | [100; 200) | [50; 75) | [140; 180) | [12400; 15400) | | Very Poor | 5 | ⩾350 | ⩾200 | ⩾200 | ⩾75 | ⩾180 | ⩾15400 | Other parameters that do not affect the AQI calculation: - NH3: min value 0.1 - max value 200 - NO: min value 0.1 - max value 100 Please find Air Quality Index levels scales used in UK, Europe, USA and Mainland China in the ["Air Pollution Index levels scale"](/air-pollution-index-levels.md) page. ### Current air pollution data ### API call ```text http://api.openweathermap.org/data/2.5/air_pollution?lat={lat}&lon={lon}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `lon` | Yes | Longitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### Example of API request ```json { "coord": [ 50.0, 50.0 ], "list": [ { "dt": 1606147200, "main": { "aqi": 4.0 }, "components": { "co": 203.609, "no": 0.0, "no2": 0.396, "o3": 75.102, "so2": 0.648, "pm2_5": 23.253, "pm10": 92.214, "nh3": 0.117 } } ] } ``` ### Forecast air pollution data ### API call ```text http://api.openweathermap.org/data/2.5/air_pollution/forecast?lat={lat}&lon={lon}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `lon` | Yes | Longitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### Example of API request ```json { "coord": [ 50.0, 50.0 ], "list": [ { "dt": 1605916800, "main": { "aqi": 1.0 }, "components": { "co": 211.954, "no": 0.0, "no2": 0.217, "o3": 72.956, "so2": 0.514, "pm2_5": 2.563, "pm10": 5.757, "nh3": 0.216 } }, { "dt": 1605920400, "main": { "aqi": 1.0 }, "components": { "co": 211.954, "no": 0.0, "no2": 0.201, "o3": 72.241, "so2": 0.469, "pm2_5": 2.662, "pm10": 5.622, "nh3": 0.224 } }, { "dt": 1605924000, "main": { "aqi": 1.0 }, "components": { "co": 213.623, "no": 0.0, "no2": 0.185, "o3": 71.526, "so2": 0.443, "pm2_5": 2.724, "pm10": 5.51, "nh3": 0.23 } }, { "dt": 1605927600, "main": { "aqi": 1.0 }, "components": { "co": 213.623, "no": 0.0, "no2": 0.17, "o3": 72.241, "so2": 0.432, "pm2_5": 2.812, "pm10": 5.687, "nh3": 0.234 } }, ..... ``` ### Historical air pollution data ### API call ```text http://api.openweathermap.org/data/2.5/air_pollution/history?lat={lat}&lon={lon}&start={start}&end={end}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `lon` | Yes | Longitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `start` | Yes | Start date (unix time, UTC time zone), e.g. start=1606488670 | | `end` | Yes | End date (unix time, UTC time zone), e.g. end=1606747870 | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### Example of API request ```json { "coord": [ 50.0, 50.0 ], "list": [ { "main": { "aqi": 2 }, "components": { "co": 270.367, "no": 5.867, "no2": 43.184, "o3": 4.783, "so2": 14.544, "pm2_5": 13.448, "pm10": 15.524, "nh3": 0.289 }, "dt": 1606482000 }, { "main": { "aqi": 2 }, "components": { "co": 280.38, "no": 8.605, "no2": 42.155, "o3": 2.459, "so2": 14.901, "pm2_5": 15.103, "pm10": 17.249, "nh3": 0.162 }, "dt": 1606478400 }, { "main": { "aqi": 2 }, "components": { "co": 293.732, "no": 13.523, "no2": 41.47, "o3": 1.173, "so2": 15.14, "pm2_5": 17.727, "pm10": 19.929, "nh3": 0.072 }, "dt": 1606474800 }, ..... ``` ### Air Pollution API response ### Example of the API response ```json { "coord":[ 50, 50 ], "list":[ { "dt":1605182400, "main":{ "aqi":1 }, "components":{ "co":201.94053649902344, "no":0.01877197064459324, "no2":0.7711350917816162, "o3":68.66455078125, "so2":0.6407499313354492, "pm2_5":0.5, "pm10":0.540438711643219, "nh3":0.12369127571582794 } } ] } ``` ### Fields in API response #### coord Coordinates from the specified location (latitude, longitude) #### list - `dt` Date and time, Unix, UTC - `main` - - `main.aqi` Air Quality Index. Possible values: 1, 2, 3, 4, 5. Where 1 = Good, 2 = Fair, 3 = Moderate, 4 = Poor, 5 = Very Poor. If you want to recalculate Air Quality indexes according UK, Europe, USA and Mainland China scales please use ["Air Pollution Index levels scale"](/air-pollution-index-levels.md) page - `components` - - `components.co` Сoncentration of CO ([Carbon monoxide](https://en.wikipedia.org/wiki/Carbon_monoxide)), μg/m3 - `components.no` Сoncentration of NO ([Nitrogen monoxide](https://en.wikipedia.org/wiki/Nitric_oxide)), μg/m3 - `components.no2` Сoncentration of NO2 ([Nitrogen dioxide](https://en.wikipedia.org/wiki/Nitrogen_dioxide)), μg/m3 - `components.o3` Сoncentration of O3 ([Ozone](https://en.wikipedia.org/wiki/Ozone)), μg/m3 - `components.so2` Сoncentration of SO2 ([Sulphur dioxide](https://en.wikipedia.org/wiki/Sulfur_dioxide)), μg/m3 - `components.pm2_5` Сoncentration of PM2.5 ([Fine particles matter](https://en.wikipedia.org/wiki/Particulates)), μg/m3 - `components.pm10` Сoncentration of PM10 ([Coarse particulate matter](https://en.wikipedia.org/wiki/Particulates#Size,_shape,_and_solubility_matter)), μg/m3 - `components.nh3` Сoncentration of NH3 ([Ammonia](https://en.wikipedia.org/wiki/Ammonia)), μg/m3 --- ## Air Pollution Index levels scale ### Overview Different countries have their own air quality indices, corresponding to different national air quality standards. Please find air quality index levels scales used in [UK,](#uk) [Europe,](#europe) [USA](#usa) and [Mainland China](#china) in the sections below. You can get air pollution data for any coordinates on the globe using [Air Pollution API](/api/air-pollution.md). ## Air quality index levels scale in UK Below is a description of UK Air Quality Index levels: | Qualitative name | Index | Pollutant concentration in μg/m3 | | | | | | --- | --- | --- | --- | --- | --- | --- | | | | SO2 | NO2 | PM2.5 | PM10 | O3 | | Low | 1 | 0-88 | 0-67 | 0-11 | 0-16 | 0-33 | | Low | 2 | 89-177 | 68-134 | 12-23 | 17-33 | 34-66 | | Low | 3 | 178-266 | 135-200 | 24-35 | 34-50 | 67-100 | | Moderate | 4 | 267-354 | 201-267 | 36-41 | 52-58 | 101-120 | | Moderate | 5 | 355-443 | 268-334 | 42-47 | 59-66 | 121-140 | | Moderate | 6 | 444-532 | 335-400 | 48-53 | 67-75 | 141-160 | | High | 7 | 533-710 | 401-467 | 54-58 | 76-83 | 161-187 | | High | 8 | 711-887 | 468-534 | 59-64 | 84-91 | 188-213 | | High | 9 | 888-1064 | 535-600 | 65-70 | 92-100 | 214-240 | | Very High | 10 | ⩾1065 | ⩾601 | ⩾71 | ⩾101 | ⩾241 | ## Air quality index levels scale in Europe Below is a description of Europe Air Quality Index levels: | Qualitative name | Index or sub-index | Pollutant (hourly) concentration in μg/m3 | | | | | --- | --- | --- | --- | --- | --- | | | | NO2 | PM10 | O3 | PM2.5 | | Very Low | 0-25 | 0-50 | 0-25 | 0-60 | 0-15 | | Low | 25-50 | 50-100 | 25-50 | 60-120 | 15-30 | | Medium | 50-75 | 100-200 | 50-90 | 120-180 | 30-55 | | High | 75-100 | 200-400 | 90-180 | 180-240 | 55-110 | | Very high | >100 | >400 | >180 | >240 | >110 | ## Air quality index levels scale in USA Below is a description of USA Air Quality Index levels: | AQI | Level of health concern | Color | | --- | --- | --- | | 0 to 50 | Good | Green | | 51 to 100 | Moderate | Yellow | | 101 to 150 | Unhealthy for sensitive groups | Orange | | 151 - 200 | Unhealthy | Red | | 201-300 | Very unhealthy | Purple | | 301-500 | Hazardous | Maroon | | 501-1000 | Very Hazardous | Brown | For pollutants concentration recalculation into AQI equation and table below is used: ![computingaqi](/payload/api/media/file/computingaqi-1.png) where: I = the Air Quality index, C = the pollutant concentration, Clow= the concentration breakpoint that is ≤C, Chigh= the concentration breakpoint that is ≥C, Ilow= the index breakpoint corresponding to Clow, Ihigh= the index breakpoint corresponding to Chigh. | Ilow-Ihigh | O3, ppb (8-hr) | O3, ppb (1-hr) | PM2.5, μg/m3 (24-hr) | PM10, μg/m3 (24-hr) | CO, ppm (8-hr) | SO2, ppb | NO2, ppb (1-hr) | | --- | --- | --- | --- | --- | --- | --- | --- | | Сlow-Chigh(avg) | | | | | | | | | 0-50 | 0-54 | - | 0.0-12.0 | 0-54 | 0.0-4.4 | 0-35 (1-hr) | 0-53 | | 51-100 | 55-70 | - | 12.1-35.4 | 55-154 | 4.5-9.4 | 36-75 (1-hr) | 54-100 | | 101-150 | 71-85 | 125-164 | 35.5-55.4 | 155-254 | 9.5-12.4 | 76-185 (1-hr) | 101-360 | | 151-200 | 86-105 | 165-204 | 55.5-150.4 | 255-354 | 12.5-15.4 | 186-304 (1-hr) | 361-649 | | 201-300 | 106-200 | 205-404 | 150.5-250.4 | 355-424 | 15.5-30.4 | 305-604 (24-hr) | 650-1249 | | 301-400 | - | 405-504 | 250.5-350.4 | 425-504 | 30.5-40.4 | 605-804 (24-hr) | 1250-1649 | | 401-500 | - | 505-604 | 350.5-500.4 | 505-604 | 40.5-50.4 | 805-1004 (24-hr) | 1650-2049 | ## Air quality index levels scale in Mainland China Below is a description of Mainland China Air Quality Index levels: | AQI | Air pollution level | Air pollution category | | --- | --- | --- | | 0-50 | Level 1 | Excellent | | 51-100 | Level 2 | Good | | 101-150 | Level 3 | Lightly polluted | | 151-200 | Level 4 | Moderatory polluted | | 201-300 | Level 5 | Heavily polluted | | >300 | Level 6 | Severely polluted | An individual score (Individual Air Quality Index, IAQI) is calculated using formula and table with breakpoint concentrations below: ![computingaqi](/payload/api/media/file/computingaqi-1.png) where: I = the Individual Air Quality index, C = the pollutant concentration, Clow= the concentration breakpoint that is ≤C, Chigh= the concentration breakpoint that is ≥C, Ilow= the index breakpoint corresponding to Clow, Ihigh= the index breakpoint corresponding to Chigh. | Individual index | Units are in μg/m3 except CO, which is in mg/m3 | | | | | | | | | | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | IAQI | SO2, 24 hour | SO2,1 hour (1) | NO2, 24 hour | NO2, 1 hour (1) | PM10, 24 hour | CO, 24 hour | CO, 1 hour (1) | O3, 1 hour | O3, 8 hour | PM2.5, 24 hour | | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | | 50 | 50 | 150 | 40 | 100 | 50 | 2 | 5 | 160 | 100 | 35 | | 100 | 150 | 500 | 80 | 200 | 150 | 4 | 10 | 200 | 160 | 75 | | 150 | 475 | 650 | 180 | 700 | 250 | 14 | 35 | 300 | 215 | 115 | | 200 | 800 | 800 | 280 | 1200 | 350 | 24 | 60 | 400 | 265 | 150 | | 300 | 1600 | (2) | 565 | 2340 | 420 | 36 | 90 | 800 | 800 | 250 | | 400 | 2100 | (2) | 750 | 3090 | 500 | 48 | 120 | 1000 | (3) | 350 | | 500 | 2620 | (2) | 940 | 3840 | 600 | 60 | 150 | 1200 | (3) | 500 | | Notes | (1) SO2, NO2, CO 1 hour average concentrations are only for real time reporting. For daily reports use 24 hour average concentration. (2) If the SO2 concentration exceeds 800 μg/m3 use the index from the 24 hour concentration instead. (3) If the O3 concentration exceeds 800 μg/m3 use the index from the 1 hour concentration instead. | | | | | | | | | | --- ## How to transfer from BBOX and Group By endpoints to alternatives The deprecation is part of a broader effort to improve service accuracy, data quality, and system performance. We strongly encourage all users to begin transitioning to our modern, production-grade APIs — [One Call 3.0](/api/one-call-3.md), [Current Weather Data](/current.md), and [Geocoding API](/api/geocoding-api.md#description) — and to use [Bulk Download](/bulk.md) for efficiently retrieving large-scale data to ensure uninterrupted access to accurate, scalable, and continuously supported weather services. Please note that support for the deprecated products will end **on July 31, 2025. After this date, these products will no longer be available.** ## One Call 3.0 **One Call 3.0** provides comprehensive weather data for any location, supporting highly precise location targeting and time-specific queries. With a single API call, you can retrieve current weather, multiple forecast types, weather alerts, and access historical data by timestamp. The service also offers daily aggregation for over 40 years of archived weather and up to 1.5 years ahead in forecasts. **Key features include:** - Retrieve current weather, minutely forecast for 1 hour, hourly forecast for 48 hours, daily forecast for 8 days, and government weather alerts in a single response - Access to 40+ years of historical weather data for any timestamp and 4 days ahead forecast - Daily aggregation of weather data for 40+ years archive and 1.5 years ahead forecast - Precise location targeting by latitude and longitude - Modular data requests using the exclude parameter to optimize response size and usage **Rate limits:** You can make up to **1,000 API calls per day** to One Call 3.0 at no cost. This free quota is available to all users, regardless of subscription. **One Call 3.0 requires a separate subscription** for usage beyond the free limit and is not included in the standard Free plan. Additional usage is billed automatically based on actual API consumption at the end of each billing period. ### How to make an API call to One Call 3.0 ** If you want to get current weather and set of forecast and alerts in one response please use API call below. ** ### API ```text https://api.openweathermap.org/data/3.0/onecall?lat={lat}&lon={lon}&exclude={part}&appid={API key} ``` Please find more about [One Call 3.0 at the documentation page](/api/one-call-3.md) and [FAQ](/faq.md) ### API call example: ```text https://api.openweathermap.org/data/3.0/onecall?lat=33.44&lon=-94.04&appid={API key} ``` If you want to get only current weather you can exclude the forecast part, use the exclude parameter as shown below. ### API call ```text https://api.openweathermap.org/data/3.0/onecall?lat=33.44&lon=-94.04&exclude=minutely,hourly,daily,alerts&appid={API key} ``` Please find more about [One Call API 3.0 at the documentation page](/api/one-call-3.md) and [FAQ](/faq.md) ## Current Weather Data The Current Weather Data provides instant access to real-time weather conditions for any location around the globe. It is designed to deliver essential weather parameters in a fast and lightweight format, making it ideal for use cases that require up-to-date observations without additional forecast or historical layers. **Key features include:** - Real-time weather data, including temperature, pressure, humidity, wind, cloudiness, visibility, and weather conditions - Global coverage with support for city name, city ID, geographic coordinates, or ZIP/postal code queries - Multiple unit formats (metric, imperial, standard) - Optimized for high-frequency and performance-sensitive applications (e.g. dashboards, widgets, mobile apps) - Fast response time with low payload size **Rate limits**: The Current Weather Data API is included in the **Free plan**, which allows up to **60 calls per minute** and **1,000,000 calls per month**. Higher limits are available in paid plans. ### How to make an API call to Current Weather Data ```text https://api.openweathermap.org/data/2.5/weather?lat={lat}&lon={lon}&appid={API key} ``` ### API call example ```text https://api.openweathermap.org/data/2.5/weather?lat=44.34&lon=10.99&appid={API key} ``` Please find more about [Current Weather Data at the documentation page](/api/geocoding-api.md#description) and [FAQ](/faq.md) We recommend using the Geocoding product to convert desired locations into geographic coordinates when needed, enabling seamless integration with One Call and Current Weather API requests. ## Bulk Download The OpenWeather Bulk Download service provides large-scale precompiled weather data files for efficient access to current conditions, forecasts, or extensive historical archives. Unlike real-time API calls, Bulk Download supplies ready-made datasets, significantly simplifying data management and reducing operational overhead. **Key features include:** - **Large-scale data delivery**: Access weather data for tens of thousands of locations simultaneously (e.g., 22,600+ global cities or 41,000+ ZIP codes in the US). - **Comprehensive datasets**: Includes current weather conditions, forecasts (hourly or daily), and extensive historical records—available in structured JSON or CSV files. - **Scheduled updates**: Data files updated hourly or daily, delivered reliably through direct download, FTP, AWS S3 buckets, or other custom delivery options. - **Reduced complexity**: Eliminates the need for extensive API management, error handling, and aggregation logic. - **Custom datasets available**: Tailor-made bulk data files created according to your specific list of locations and data parameters. Bulk Download is ideal for applications requiring extensive, consistent datasets—such as analytics platforms, large-scale monitoring systems, research projects, or historical data archives. The Bulk Download service is offered under OpenWeather’s Professional, Expert and Enterprise subscription plans. Custom bulk datasets and enterprise-grade support options are available upon request. Please [contact us](mailto:info@openweathermap.org) to discuss your bulk data requirements. **Example datasets include:** - Current weather data for ~22,635 global cities, updated hourly. - 16-day daily forecasts for 209,000+ locations worldwide. - Historical hourly weather data for selected regions, spanning multiple years. **Rate limits:** Bulk Download does not use traditional API calls; therefore, standard API rate limits do not apply. Data is provided as downloadable files, simplifying consumption at any scale. ### How to get data from Bulk Download ```text https://bulk.openweathermap.org/snapshot/{BULK_FILE_NAME}?appid={API key} ``` ### URL example ```text https://bulk.openweathermap.org/archive/weather_zip_uk_011020_2000.csv.gz?appid={API key} ``` Please find more about [Bulk Download at the documentation page](/bulk.md) and [FAQ](/faq.md) ## Geocoding API The OpenWeather Geocoding API provides robust location-based services through two main endpoints: - **Direct Geocoding**: Convert city names, ZIP/postal codes, and other location identifiers into geographic coordinates (latitude and longitude). - **Reverse Geocoding**: Retrieve location names from geographic coordinates. **Key features include:** - Support for partial names, multiple languages, and country filtering - Ability to fetch up to 5 location results per query, ranked by importance or population - Worldwide coverage, including small towns and rural locations - Fast and reliable performance for real-time applications **Rate limits:** The Geocoding API is included in the Free plan, which allows up to **60 calls per minute** and **1,000,000 calls per month**. Higher limits are available in paid plans. ### How to make an API call to Geocoding API ```text http://api.openweathermap.org/geo/1.0/direct?q={city name},{state code},{country code}&limit={limit}&appid={API key} ``` ### API call example (Direct Geocoding): ```text http://api.openweathermap.org/geo/1.0/reverse?lat=51.5098&lon=-0.1180&limit=5&appid={API key} ``` Please find more about [Geocoding API at the documentation page](/api/geocoding-api.md#description) and [FAQ](/faq.md) ## Action Plan for Migration If you’ve reviewed the material above but are still unsure how to proceed, this section outlines a structured, step-by-step approach to help you move forward with clarity. ### Step 1: Manage my location Prepare a list of locations you’re interested in: You can organize your locations as follows: - For **Group By**, list city names or precise geographical points (e.g., cities, towns, neighborhoods). - For **BBOX**, clearly define a bounding box area. Identify its four coordinate points (latitude and longitude for the top-left and bottom-right corners). This bounding box represents the geographical area for which you need weather data. ### Step 2: Convert in coordinates **Convert locations into geographical coordinates using the **[**Geocoding API**](/api/geocoding-api.md#description) - **Group By**: Use Direct Geocoding to retrieve latitude and longitude for each specific location. - **BBOX**: Typically, you already have the required coordinates for your bounding box. ### Step 3: Choose your service **Choose your OpenWeather alternative service:** - [One Call 3.0](/api/one-call-3.md): For detailed forecasts, historical weather data, aggregated weather information, and more extensive datasets. - [Current Weather Data](/current.md): For instant access to current weather conditions only. - [Bulk Download](/bulk.md): For retrieving large-scale precompiled weather datasets, particularly suitable for extensive location lists or reducing high-volume API calls. ### Step 4: Make API calls **Make API calls to your selected service:** - Use your API key to access [Current Weather Data](/current.md) or [One Call 3.0](/api/one-call-3.md). Please note that an active subscription is required to use [One Call 3.0](/api/one-call-3.md). [Bulk Download](/bulk.md) is available as part of a subscription plan. Customized Bulk Downloads can be purchased separately upon request. - Use the coordinates obtained earlier from [Geocoding API](/geocoding-api.md#descriptio). - Check API response and integrate results into your application or workflow. ### Step 5: Verify and complete migration **Verify and complete migration before July 31, 2025** Make sure your application fully utilizes the new endpoints before the legacy endpoints (BBOX, Group By) are deprecated. --- ## Bulk Download The service allows you to regularly download current weather, weather forecasts and their 7-day archives in JSON or CSV format. Weather bulks are grouped by [types of weather data](/bulk.md#types) and [location lists](/bulk.md#list), such as a variety of city lists or ZIP code lists of EU, UK, and US. ### About Current, forecast and historical weather data is available via regulary updated JSON or CSV files. In order to receive this data, you will need to download an archive via provided link. Each archive will contain selected weather data by chosen locations lists. This product has access to all types of weather data (current weather, forecasts, bulk archives) and data formats. The weather data can be downloaded by list of major cities (22,635 cities across the globe), extended cities list (209,579 cities across the globe) and variety of city lists or ZIP code lists of EU, UK, and US. > Please note, that we can develop a custom regularly updated current, forecast and historical bulks. Please [contact us](mailto:info@openweathermap.org) to learn more about it. ### How to use the service #### Use links of the following types in order to access bulks files: - To get [Current](/bulk.md#bulk_current) and [Forecast](/bulk.md#forecasts) bulks files: ```text https://bulk.openweathermap.org/snapshot/{BULK_FILE_NAME}?appid={API key} ``` - To get access to [7-days archive](/bulk.md#bulk_archive) of current and forecasts bulk files: ```text https://bulk.openweathermap.org/archive/{BULK_FILE_NAME}?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `{BULK_FILE_NAME}` | Yes | Specified in the **"File name"** table column in the ["Types of bulk files"](/bulk.md#types) section | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](/api_keys.md)) | > All bulk files available both in JSON and CSV formats. File names provided in the [tables below](/bulk.md#bulk_current) are relevant for JSON format. If you want to upload data in the CSV formate, please change `json` on `csv` in the file name. > > Examples: > > JSON file name: `weather_16.json.gz` > CSV file name: `weather_16.csv.gz` #### Unpack the downloaded file Unpack the downloaded file by using any suitable archiver software. After this is done, you will have a JSON or CSV format file that is ready to use. The file implies line-by-line processing. Examples of bulk files can be found here: [bulk samples](/bulk.md#examples). #### Download updated weather data To download updated weather data, please also use the same link. Data in the files get updated in accordance with the schedule found in the **"Updated"** column of the downloaded file. Please note that weather data in the fill is rewritten regularly. ### Types of bulk files There are 3 types of bulk files: [Current bulk](/bulk.md#bulk_current), [Forecasts bulks](/bulk.md#forecasts) and [7-days archive](/bulk.md#bulk_archive) weather bulks. Please note that scheduled update times are specified in UTC. ### Current weather bulks With Current weather bulk you can upload bulk file of current weather for chosen [city lists and ZIP codes locations lists](bulk#list). Examples of bulk files can be found here: [bulk samples](http://bulk.openweathermap.org/sample/). Please pay attention that `weather_14.json.gz` and `weather_16.json.gz` files refer for current weather. | File name | Number of locations | Updated, UTC time | | --- | --- | --- | | weather_14.json.gz | 22,635 cities | 1 time/hour (00:10, 01:10, 02:10,...) | | weather_16.json.gz | 209,579 cities | 1 time/hour (00:20, 01:20, 02:20,...) | | weather_zip_eu.json.gz | 153,952 EU ZIP codes | 1 time/hour (00:20, 01:20, 02:20,...) | | weather_zip_us.json.gz | 41,959 US ZIP codes | 1 time/hour (00:20, 01:20, 02:20,...) | | weather_zip_uk.json.gz | 15,225 UK ZIP codes | 1 time/hour (00:20, 01:20, 02:20,...) | ### Example of link to download bulk file in CSV format ```text https://bulk.openweathermap.org/snapshot/weather_zip_us.csv.gz?appid={API key} ``` If you are interested in to get Current bulk files for 7 previous days, please read ["7-day archives of bulk files"](/bulk.md#bulk_archive) section. ### Forecast bulks WIth Forecast bulk you can upload bulk file of Forecast weather with a variable data granulation for chosen cities and ZIP codes locations. Examples of bulk files can be found here: [bulk samples](/sample/.md). Please pay attention that `hourly_14.json.gz`, `hourly_16.json.gz`, `daily_14.json.gz` and `daily_16.json.gz` files refer for forecast weather. ### Hourly forecast for 4 days ahead | File name | Number of locations | Updated, UTC time | | --- | --- | --- | | hourly1h_14.json.gz | 22,635 cities | 4 times/day (03:00, 09:00, 15:00, 21:00) | | hourly1h_16.json.gz | 209,579 cities | 4 times/day (03:00, 09:00, 15:00, 21:00) | | hourly1h_zip_eu.json.gz | 153,952 EU ZIP codes | 2 times/day (08:00, 20:00) | | hourly1h_zip_us.json.gz | 41,959 US ZIP codes | 2 times/day (08:00, 20:00) | | hourly1h_zip_uk.json.gz | 15,225 UK ZIP codes | 2 times/day (08:00, 20:00) | ### Example of link to download bulk file in CSV format ```text https://bulk.openweathermap.org/snapshot/hourly1h_zip_eu.csv.gz?appid={API key} ``` ### Daily forecast for 16 days ahead | File name | Number of locations | Updated, UTC time | | --- | --- | --- | | daily_14.json.gz | 22,635 cities | 2 times/day (07:00, 19:00) | | daily_16.json.gz | 209,579 cities | 2 times/day (07:00, 19:00) | | daily_zip_eu.json.gz | 153,952 EU ZIP codes | 2 times/day (08:00, 20:00) | | daily_zip_us.json.gz | 41,959 US ZIP codes | 2 times/day (08:00, 20:00) | | daily_zip_uk.json.gz | 15,225 UK ZIP codes | 2 times/day (08:00, 20:00) | ### Example of link to download bulk file in CSV format ```text https://bulk.openweathermap.org/snapshot/daily_zip_uk.csv.gz?appid={API key} ``` ### 3-hour step forecast for 5 days ahead | File name | Number of locations | Updated, UTC time | | --- | --- | --- | | hourly_14.json.gz | 22,635 cities | 1 time/hour (00:10, 01:10, 02:10,...) | | hourly_16.json.gz | 209,579 cities | 2 times/day (07:00, 19:00) | | hourly_zip_eu.json.gz | 153,952 EU ZIP codes | 2 times/day (08:00, 20:00) | | hourly_zip_us.json.gz | 41,959 US ZIP codes | 2 times/day (08:00, 20:00) | | hourly_zip_uk.json.gz | 15,225 UK ZIP codes | 2 times/day (08:00, 20:00) | ### Example of link to download bulk file in CSV format ```text https://bulk.openweathermap.org/snapshot/hourly_zip_eu.csv.gz?appid={API key} ``` If you are interested in to get Forecasts bulk files for 7 previous days, please read ["7-day archives of bulk files"](/bulk.md#bulk_archive) section. ### 7-day archive of current and forecast weather bulks files You can get all weather bulks files for the 7 previous days. The structure of data the same as for current and forecasts bulks files. | File name | Number of locations | Available data per day, UTC time | | --- | --- | --- | | **weather_14_mmddyy_hhmm.json.gz** Example of file name: weather_14_011020_0200.json.gz | 22,635 cities | 01:00, 02:00, 03:00, 04:00, 05:00, 06:00, 07:00, 08:00, 09:00, 10:00, 11:00, 12:00, 13:00, 14:00, 15:00, 16:00, 17:00, 18:00, 19:00, 20:00, 21:00, 22:00, 23:00, 00:00 | | **weather_16_mmddyy_hhmm.json.gz** Example of file name: weather_16_011020_0200.json.gz | 209,579 cities | 01:00, 02:00, 03:00, 04:00, 05:00, 06:00, 07:00, 08:00, 09:00, 10:00, 11:00, 12:00, 13:00, 14:00, 15:00, 16:00, 17:00, 18:00, 19:00, 20:00, 21:00, 22:00, 23:00, 00:00 | | **weather_zip_eu_mmddyy_hhmm.json.gz** Example of file name: weather_zip_eu_011020_2000.json.gz | 153,952 EU ZIP codes | 01:00, 02:00, 03:00, 04:00, 05:00, 06:00, 07:00, 08:00, 09:00, 10:00, 11:00, 12:00, 13:00, 14:00, 15:00, 16:00, 17:00, 18:00, 19:00, 20:00, 21:00, 22:00, 23:00, 00:00 | | **weather_zip_us_mmddyy_hhmm.json.gz** Example of file name: weather_zip_us_011020_2000.json.gz | 41,959 US ZIP codes | 01:00, 02:00, 03:00, 04:00, 05:00, 06:00, 07:00, 08:00, 09:00, 10:00, 11:00, 12:00, 13:00, 14:00, 15:00, 16:00, 17:00, 18:00, 19:00, 20:00, 21:00, 22:00, 23:00, 00:00 | | **weather_zip_uk_mmddyy_hhmm.json.gz** Example of file name: weather_zip_uk_011020_2000.json.gz | 15,225 UK ZIP codes | 01:00, 02:00, 03:00, 04:00, 05:00, 06:00, 07:00, 08:00, 09:00, 10:00, 11:00, 12:00, 13:00, 14:00, 15:00, 16:00, 17:00, 18:00, 19:00, 20:00, 21:00, 22:00, 23:00, 00:00 | ### Example of link to download bulk file in CSV format ```text https://bulk.openweathermap.org/archive/weather_zip_uk_011020_2000.csv.gz?appid={API key} ``` ### 7-day archive of hourly forecast for 4 days ahead | File name | Number of locations | Available data per day, UTC time | | --- | --- | --- | | **hourly1h_14_mmddyy_hhmm.json.gz** Example of file name: hourly1h_14_011020_0200.json.gz | 22,635 cities | 02:00, 08:00, 14:00, 20:00 | | **hourly1h_16_mmddyy_hhmm.json.gz** Example of file name: hourly1h_16_011020_0200.json.gz | 209,579 cities | 02:00, 08:00, 14:00, 20:00 | | **hourly1h_zip_eu_mmddyy_hhmm.json.gz** Example of file name: hourly1h_zip_eu_011020_2000.json.gz | 153,952 EU ZIP codes | 07:00, 19:00 | | **hourly1h_zip_us_mmddyy_hhmm.json.gz** Example of file name: hourly1h_zip_us_011020_2000.json.gz | 41,959 US ZIP codes | 07:00, 19:00 | | **hourly1h_zip_uk_mmddyy_hhmm.json.gz** Example of file name: hourly1h_zip_uk_011020_2000.json.gz | 15,225 UK ZIP codes | 07:00, 19:00 | ### 7-day archive of daily forecast for 16 days ahead | File name | Number of locations | Available data per day, UTC time | | --- | --- | --- | | **daily_14_mmddyy_hhmm.json.gz** Example of file name: daily_14_011020_0200.json.gz | 22,635 cities | 06:00, 18:00 | | **daily_16_mmddyy_hhmm.json.gz** Example of file name: daily_16_011020_0200.json.gz | 209,579 cities | 06:00, 18:00 | | **daily_zip_eu_mmddyy_hhmm.json.gz** Example of file name: daily_zip_eu_011020_2000.json.gz | 153,952 EU ZIP codes | 07:00, 19:00 | | **daily_zip_us_mmddyy_hhmm.json.gz** Example of file name: daily_zip_us_011020_2000.json.gz | 41,959 US ZIP codes | 07:00, 19:00 | | **daily_zip_uk_mmddyy_hhmm.json.gz** Example of file name: daily_uk_011020_2000.json.gz | 15,225 UK ZIP codes | 07:00, 19:00 | ### 7-day archive of 3-hour step forecast for 5 days ahead | File name | Number of locations | Available data per day, UTC time | | --- | --- | --- | | **hourly_14_mmddyy_hhmm.json.gz** Example of file name: hourly_14_011020_0200.json.gz | 22,635 cities | 01:00, 02:00, 03:00, 04:00, 05:00, 06:00, 07:00, 08:00, 09:00, 10:00, 11:00, 12:00, 13:00, 14:00, 15:00, 16:00, 17:00, 18:00, 19:00, 20:00, 21:00, 22:00, 23:00, 00:00 | | **hourly_16_mmddyy_hhmm.json.gz** Example of file name: hourly_16_011020_0200.json.gz | 209,579 cities | 06:00, 18:00 | | **hourly_zip_eu_mmddyy_hhmm.json.gz** Example of file name: hourly_zip_eu_011020_2000.json.gz | 153,952 EU ZIP codes | 07:00, 19:00 | | **hourly_zip_us_mmddyy_hhmm.json.gz** Example of file name: hourly_zip_us_011020_2000.json.gz | 41,959 US ZIP codes | 07:00, 19:00 | | **hourly_zip_uk_mmddyy_hhmm.json.gz** Example of file name: hourly_uk_011020_2000.json.gz | 15,225 UK ZIP codes | 07:00, 19:00 | ### Location lists There are 5 lists of locations for each type of weather data: - List of major cities across the globe - 22,635 cities. You can download the full list of cities [here](https://bulk.openweathermap.org/sample/current.city.list.json.gz) - Extended cities list across the globe - 209,579 cities. You can download the full list of cities [here](https://bulk.openweathermap.org/sample/city.list.json.gz) - Full list of the US ZIP codes - Full list of the UK ZIP codes - Full list of the all Europe ZIP codes ### Bulk file samples Samples of bulk files can be downloaded here: [bulk samples](http://bulk.openweathermap.org/sample/). Please pay attention that: - `weather_14.json.gz` and `weather_16.json.gz` files refer for current weather - `hourly_14.json.gz`, `hourly_16.json.gz`, `daily_14.json.gz` and `daily_16.json.gz` files refer for forecast weather --- ## How to improve OpenWeather API's performance and reliability for users in China ### Regional endpoints for improved performance and reliability To reduce latency and improve reliability for users connecting from China, we recommend using regional endpoints by adding the `cn-` prefix to the standard hostname. You can also continue using the standard endpoints if they already meet your needs. When working with regional endpoints for China, the primary difference is the addition of the `cn-` prefix to the standard hostname. The request structure, parameters, authentication, and response formats remain unchanged, and your existing API keys continue to work without extra costs or subscriptions. All calls to regional endpoints are counted in your overall API usage statistics. | Endpoint mapping | | | | --- | --- | --- | | User group / plan | Global | Recommended in China | | Standard API (Free, Startup plans) | [api.openweathermap.org](/api.md) | [cn-api.openweathermap.org](/api.md) | | Professional (Developer and above plans) | [pro.openweathermap.org](/api.md) | [cn-pro.openweathermap.org](/api.md) | > **Recommendation:** just add `cn-` before the hostname. Global: ### Standard Example: ```text https://api.openweathermap.org/data/2.5/weather?lat={lat}&lon={lon}&appid={API key} ``` Recommended in China: ### API call ```text https://cn-api.openweathermap.org/data/2.5/weather?lat={lat}&lon={lon}&appid={API key} ``` Global: ### Professional Example: ```text https://pro.openweathermap.org/data/2.5/forecast/hourly?lat={lat}&lon={lon}&appid={API key} ``` Recommended in China: ### API call ```text https://cn-pro.openweathermap.org/data/2.5/forecast/hourly?lat={lat}&lon={lon}&appid={API key} ``` ## Notes for Users - **No extra costs** Using the China endpoints does not require any additional payment. Your existing subscription plan and pricing remain exactly the same. - **No changes to limits or quotas** All request limits, quotas, and rate restrictions defined by your current plan continue to apply without modification. - **Fully compatible** The China endpoints are fully compatible with the global ones. Request structure, parameters, authentication, and response formats remain unchanged. - **Same API key** You don’t need to get new API keys, your current API keys work with API endpoints dedicated for users from China. - **Who can use** While anyone can technically use the China endpoints, they are designed to improve performance and reliability primarily for users connecting from China. --- ## Current weather data ### Product concept Access current weather data for any location on Earth! We collect and process weather data from different sources such as global and local weather models, satellites, radars and a vast network of weather stations. Data is available in JSON, XML, or HTML format. ## Call current weather data ### How to make an API call ```text https://api.openweathermap.org/data/2.5/weather?lat={lat}&lon={lon}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `lon` | Yes | Longitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `mode` | optional | Response format. Possible values are `xml` and `html`. If you don't use the `mode` parameter format is JSON by default. [Learn more](#format) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | You can use this parameter to get the output in your language. [Learn more](#multi) | > Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around. > > Please note that [built-in geocoder](#geocoding) has been deprecated. Although it is still available for use, bug fixing and updates are no longer available for this functionality. ### Examples of API calls ```text https://api.openweathermap.org/data/2.5/weather?lat=44.34&lon=10.99&appid={API key} ``` ```json { "coord": { "lon": 10.99, "lat": 44.34 }, "weather": [ { "id": 501, "main": "Rain", "description": "moderate rain", "icon": "10d" } ], "base": "stations", "main": { "temp": 298.48, "feels_like": 298.74, "temp_min": 297.56, "temp_max": 300.05, "pressure": 1015, "humidity": 64, "sea_level": 1015, "grnd_level": 933 }, "visibility": 10000, "wind": { "speed": 0.62, "deg": 349, "gust": 1.18 }, "rain": { "1h": 3.16 }, "clouds": { "all": 100 }, "dt": 1661870592, "sys": { "type": 2, "id": 2075663, "country": "IT", "sunrise": 1661834187, "sunset": 1661882248 }, "timezone": 7200, "id": 3163858, "name": "Zocca", "cod": 200 } ``` ## API response > If you do not see some of the parameters in your API response it means that these weather phenomena are just not happened for the time of measurement for the city or location chosen. Only really measured or calculated data is displayed in API response. ### JSON ```json { "coord": { "lon": 7.367, "lat": 45.133 }, "weather": [ { "id": 501, "main": "Rain", "description": "moderate rain", "icon": "10d" } ], "base": "stations", "main": { "temp": 284.2, "feels_like": 282.93, "temp_min": 283.06, "temp_max": 286.82, "pressure": 1021, "humidity": 60, "sea_level": 1021, "grnd_level": 910 }, "visibility": 10000, "wind": { "speed": 4.09, "deg": 121, "gust": 3.47 }, "rain": { "1h": 2.73 }, "clouds": { "all": 83 }, "dt": 1726660758, "sys": { "type": 1, "id": 6736, "country": "IT", "sunrise": 1726636384, "sunset": 1726680975 }, "timezone": 7200, "id": 3165523, "name": "Province of Turin", "cod": 200 } ``` ### JSON format API response fields - `coord` - - `coord.lon` Longitude of the location - `coord.lat` Latitude of the location - `weather` (more info [Weather condition codes](/weather-conditions.md)) - - `weather.id` Weather condition id - `weather.main` Group of weather parameters (Rain, Snow, Clouds etc.) - `weather.description` Weather condition within the group. Please find more [here.](/current.md#list) You can get the output in your language. [Learn more](/current.md#multi) - `weather.icon` Weather icon id - `base` Internal parameter - `main` - - `main.temp` Temperature. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `main.feels_like` Temperature. This temperature parameter accounts for the human perception of weather. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `main.pressure` Atmospheric pressure on the sea level, hPa - `main.humidity` Humidity, % - `main.temp_min` Minimum temperature at the moment. This is minimal currently observed temperature (within large megalopolises and urban areas). Please find more info [here.](/current.md#min) Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `main.temp_max` Maximum temperature at the moment. This is maximal currently observed temperature (within large megalopolises and urban areas). Please find more info [here.](/current.md#min) Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `main.sea_level` Atmospheric pressure on the sea level, hPa - `main.grnd_level` Atmospheric pressure on the ground level, hPa - `visibility` Visibility, meter. The maximum value of the visibility is 10 km - `wind` - - `wind.speed` Wind speed. Unit Default: meter/sec, Metric: meter/sec, Imperial: miles/hour - `wind.deg` Wind direction, degrees (meteorological) - `wind.gust` Wind gust. Unit Default: meter/sec, Metric: meter/sec, Imperial: miles/hour - `clouds` - - `clouds.all` Cloudiness, % - `rain` - - `1h`(where available)Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter - `snow` - - `1h`(where available) Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter - `dt` Time of data calculation, unix, UTC - `sys` - - `sys.type` Internal parameter - `sys.id` Internal parameter - `sys.message` Internal parameter - `sys.country` Country code (GB, JP etc.) - `sys.sunrise` Sunrise time, unix, UTC - `sys.sunset` Sunset time, unix, UTC - `timezone` Shift in seconds from UTC - `id` City ID. Please note that built-in geocoder functionality has been deprecated. Learn more [here](/current.md#builtin) - `name` City name. Please note that built-in geocoder functionality has been deprecated. Learn more [here](/current.md#builtin) - `cod` Internal parameter ## XML ### Example of API response ```text IT 7200 ``` ### XML format API response fields - `city` - - `city.id `City ID. Please note that built-in geocoder functionality has been deprecated. Learn more [here](/current.md#builtin) - `city.name` City name. Please note that built-in geocoder functionality has been deprecated. Learn more [here](/current.md#builtin) - `city.coord` - - `city.coord.lon`Geo location, longitude - `city.coord.lat` Geo location, latitude - `city.country` Country code (GB, JP etc.). Please note that built-in geocoder functionality has been deprecated. Learn more [here](/current.md#builtin) - `timezone`Shift in seconds from UTC - `city.sun` - - `city.sun.rise` Sunrise time - `city.sun.set` Sunset time - `temperature` - - `temperature.value` Temperature - `temperature.min` Minimum temperature at the moment of calculation. This is minimal currently observed temperature (within large megalopolises and urban areas), use this parameter optionally. Please find more info [here](/current.md#min) - `temperature.max` Maximum temperature at the moment of calculation. This is maximal currently observed temperature (within large megalopolises and urban areas), use this parameter optionally. Please find more info [here](/current.md#min) - `temperature.unit` Unit of measurements. Possible value is Celsius, Kelvin, Fahrenheit - `feels_like` - - `feels_like.value `Temperature. This temperature parameter accounts for the human perception of weather - `feels_like.unit` Unit of measurements. Possible value is Celsius, Kelvin, Fahrenheit. Unit Default: Kelvin - `humidity` - - `humidity.value `Humidity value - `humidity.unit` Humidity units, % - `pressure` - - `pressure.value `Pressure value - `pressure.unit` Pressure units, hPa - `wind` - - `wind.speed` - - `wind.speed.value `Wind speed - `wind.speed.unit `Wind speed units, m/s - `wind.speed.name` Type of the wind - `wind.direction` - - `wind.direction.value `Wind direction, degrees (meteorological) - `wind.direction.code` Code of the wind direction. Possible value is WSW, N, S etc. - `wind.direction.name` Full name of the wind direction - `clouds` - - `clouds.value `Cloudiness - `clouds.name` Name of the cloudiness - `visibility` - - `visibility.value `Visibility, meter. The maximum value of the visibility is 10 km - `precipitation` - - `precipitation.value` Precipitation, mm. Please note that only mm as units of measurement are available for this parameter. - `precipitation.mode` Possible values are 'no", name of weather phenomena as 'rain', 'snow' - `weather` - - `weather.number` Weather condition id - `weather.value` Weather condition name - `weather.icon` Weather icon id - `lastupdate` - - `lastupdate.value` Last time when data was updated > We provide a broad variety of products such as [One Call API 4.0,](/api/one-call-4.md) [Solar Irradiance & Energy Prediction service,](/api.md#solar) [Road Risk API,](/api/road-risk.md) [Air Pollution API](/api/air-pollution.md) and solutions for advanced weather parameters like solar irradiance data, UVI, dew point, government weather alerts, etc. Please review our [product list](/api.md) page and find more info in the product documentation and [pricing](/price.md) pages. ## List of weather condition codes List of [weather condition codes](/weather-conditions.md) with icons (range of thunderstorm, drizzle, rain, snow, clouds, atmosphere etc.) ## Min/max temperature in current weather API and forecast API Please do not confuse min/max parameters in our weather APIs. - In **Current weather API**, [Hourly forecast API](/api/hourly-forecast.md) and [5 day / 3 hour forecast API](/forecast5.md) - **temp_min** and **temp_max** are optional parameters mean min / max temperature in the city at the current moment just for your reference. For large cities and megalopolises geographically expanded it might be applicable. In most cases both **temp_min** and **temp_max** parameters have the same volume as 'temp'. Please use **temp_min** and **temp_max** parameters in current weather API optionally. - In [16 Day forecast](/forecast16.md) - **min** and **max** mean maximum and minimum temperature in the day. ### Example of current weather API response ```text "main":{ "temp":306.15, //current temperature "pressure":1013, "humidity":44, "temp_min":306.15, //min current temperature in the city "temp_max":306.15 //max current temperature in the city } ``` ### Example of daily forecast weather API response ```text "dt":1406080800, "temp":{ "day":297.77, //daily averaged temperature "min":293.52, //daily min temperature "max":297.77, //daily max temperature "night":293.52, //night temperature "eve":297.77, //evening temperature "morn":297.77}, //morning temperature ``` ## Bulk downloading We provide number of bulk files with current weather and forecasts. The service allows you to regularly download current weather and forecast data in JSON format. There is no need to call an API to do this. More information is on the [Bulk page](/bulk.md). ### Examples of bulk files [http://bulk.openweathermap.org/sample/](http://bulk.openweathermap.org/sample/) ## Other features ### Geocoding API Requesting API calls by geographical coordinates is the most accurate way to specify any location. If you need to convert city names and zip-codes to geo coordinates and the other way around automatically, please use our [Geocoding API](/api/geocoding-api.md). ### Built-in geocoding > Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around. > > **Please note that API requests by city name, zip-codes and city id have been deprecated. Although they are still available for use, bug fixing and updates are no longer available for this functionality.** ### Built-in API request by city name You can call by city name or city name, state code and country code. Please note that searching by states available only for the USA locations. ### API call ```text https://api.openweathermap.org/data/2.5/weather?q={city name}&appid={API key} ``` ### API call ```text https://api.openweathermap.org/data/2.5/weather?q={city name},{country code}&appid={API key} ``` ### API call ```text https://api.openweathermap.org/data/2.5/weather?q={city name},{state code},{country code}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `q` | Yes | City name, state code and country code divided by comma, Please refer to [ISO 3166](https://www.iso.org/obp/ui/#search) for the state codes or country codes. You can specify the parameter not only in English. In this case, the API response should be returned in the same language as the language of requested location name if the location is in our predefined list of more than 200,000 locations. | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `mode` | optional | Response format. Possible values are `xml` and `html`. If you don't use the `mode` parameter format is JSON by default. [Learn more](#format) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | You can use this parameter to get the output in your language. [Learn more](#multi) | ### Examples of API calls: ```json { "coord": { "lon": -0.13, "lat": 51.51 }, "weather": [ { "id": 300, "main": "Drizzle", "description": "light intensity drizzle", "icon": "09d" } ], "base": "stations", "main": { "temp": 280.32, "pressure": 1012, "humidity": 81, "temp_min": 279.15, "temp_max": 281.15 }, "visibility": 10000, "wind": { "speed": 4.1, "deg": 80 }, "clouds": { "all": 90 }, "dt": 1485789600, "sys": { "type": 1, "id": 5091, "message": 0.0103, "country": "GB", "sunrise": 1485762037, "sunset": 1485794875 }, "id": 2643743, "name": "London", "cod": 200 } ``` ### Example of API response ```json { "coord": { "lon": -0.13, "lat": 51.51 }, "weather": [ { "id": 300, "main": "Drizzle", "description": "light intensity drizzle", "icon": "09d" } ], "base": "stations", "main": { "temp": 280.32, "pressure": 1012, "humidity": 81, "temp_min": 279.15, "temp_max": 281.15 }, "visibility": 10000, "wind": { "speed": 4.1, "deg": 80 }, "clouds": { "all": 90 }, "dt": 1485789600, "sys": { "type": 1, "id": 5091, "message": 0.0103, "country": "GB", "sunrise": 1485762037, "sunset": 1485794875 }, "id": 2643743, "name": "London", "cod": 200 } ``` > There is a possibility to receive a central district of the city/town with its own parameters (geographic coordinates/id/name) in API response. [Example](http://samples.openweathermap.org/data/2.5/forecast?q=München,DE&appid=439d4b804bc8187953eb36d2a8c26a02) ### Built-in API request by city ID You can make an API call by city ID. List of city ID 'city.list.json.gz' can be downloaded [here](http://bulk.openweathermap.org/sample/). We recommend to call API by city ID to get unambiguous result for your city. ### API call ```text https://api.openweathermap.org/data/2.5/weather?id={city id}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `id` | Yes | City ID. List of city ID 'city.list.json.gz' can be downloaded [here](http://bulk.openweathermap.org/sample/). | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `mode` | optional | Response format. Possible values are `xml` and `html`. If you don't use the `mode` parameter format is JSON by default. [Learn more](#format) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | You can use this parameter to get the output in your language. [Learn more](#multi) | ### Examples of API calls ```json { "coord": { "lon": 145.77, "lat": -16.92 }, "weather": [ { "id": 802, "main": "Clouds", "description": "scattered clouds", "icon": "03n" } ], "base": "stations", "main": { "temp": 300.15, "pressure": 1007, "humidity": 74, "temp_min": 300.15, "temp_max": 300.15 }, "visibility": 10000, "wind": { "speed": 3.6, "deg": 160 }, "clouds": { "all": 40 }, "dt": 1485790200, "sys": { "type": 1, "id": 8166, "message": 0.2064, "country": "AU", "sunrise": 1485720272, "sunset": 1485766550 }, "id": 2172797, "name": "Cairns", "cod": 200 } ``` ### Built-in API request by ZIP code Please note if country is not specified then the search works for USA as a default. ### API call ```text https://api.openweathermap.org/data/2.5/weather?zip={zip code},{country code}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `zip` | Yes | Zip code | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `mode` | optional | Response format. Possible values are `xml` and `html`. If you don't use the `mode` parameter format is JSON by default. [Learn more](#format) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | You can use this parameter to get the output in your language. [Learn more](#multi) | ### Examples of API calls ```json { "coord": {"lon": -122.08,"lat": 37.39}, "weather": [ { "id": 800, "main": "Clear", "description": "clear sky", "icon": "01d" } ], "base": "stations", "main": { "temp": 282.55, "feels_like": 281.86, "temp_min": 280.37, "temp_max": 284.26, "pressure": 1023, "humidity": 100 }, "visibility": 10000, "wind": { "speed": 1.5, "deg": 350 }, "clouds": { "all": 1 }, "dt": 1560350645, "sys": { "type": 1, "id": 5122, "message": 0.0139, "country": "US", "sunrise": 1560343627, "sunset": 1560396563 }, "timezone": -25200, "id": 420006353, "name": "Mountain View", "cod": 200 } ``` ## Format Response format. JSON format is used by default. To get data in XML format just set up mode = xml. | Parameters | | | | --- | --- | --- | | `mode` | optional | Response format. Possible values are `xml` and `html`. If you don't use the `mode` parameter format is JSON by default. | JSON ### Example of API calls ```json { "coord":{ "lon":-0.13, "lat":51.51 }, "weather":[ { "id":300, "main":"Drizzle", "description":"light intensity drizzle", "icon":"09d" } ], "base":"stations", "main":{ "temp":280.32, "pressure":1012, "humidity":81, "temp_min":279.15, "temp_max":281.15 }, "visibility":10000, "wind":{ "speed":4.1, "deg":80 }, "clouds":{ "all":90 }, "dt":1485789600, "sys":{ "type":1, "id":5091, "message":0.0103, "country":"GB", "sunrise":1485762037, "sunset":1485794875 }, "id":2643743, "name":"London", "cod":200 } ``` XML ### Example of API response ```text London GB 0.0117 ## Units of measurement `standard`, `metric`, and `imperial` units are available. [List of all API parameters with available units](/weather-data.md). | Parameters | | | | --- | --- | --- | | `units` | optional | `standard`, `metric`, `imperial`. When you do not use the `units` parameter, format is `standard` by default. | > Temperature is available in Fahrenheit, Celsius and Kelvin units. > > List of all API parameters with units [openweathermap.org/weather-data](/weather-data.md) Standard ### Examples of API calls: ```json { "coord": { "lon": -2.15, "lat": 57 }, "weather": [ { "id": 804, "main": "Clouds", "description": "overcast clouds", "icon": "04d" } ], "base": "stations", "main": { "temp": 281.63, "feels_like": 278.05, "temp_min": 281.33, "temp_max": 282.41, "pressure": 1016, "humidity": 79, "sea_level": 1016, "grnd_level": 1016 }, "visibility": 10000, "wind": { "speed": 7.3, "deg": 189, "gust": 13.48 }, "clouds": { "all": 100 }, "dt": 1647347424, "sys": { "type": 2, "id": 2031790, "country": "GB", "sunrise": 1647325488, "sunset": 1647367827 }, "timezone": 0, "id": 2641549, "name": "Newtonhill", "cod": 200 } ``` metric ### Example of API response ```json { "coord": { "lon": -2.15, "lat": 57 }, "weather": [ { "id": 804, "main": "Clouds", "description": "overcast clouds", "icon": "04d" } ], "base": "stations", "main": { "temp": 8.48, "feels_like": 4.9, "temp_min": 8.18, "temp_max": 9.26, "pressure": 1016, "humidity": 79, "sea_level": 1016, "grnd_level": 1016 }, "visibility": 10000, "wind": { "speed": 7.3, "deg": 189, "gust": 13.48 }, "clouds": { "all": 100 }, "dt": 1647347424, "sys": { "type": 2, "id": 2031790, "country": "GB", "sunrise": 1647325488, "sunset": 1647367827 }, "timezone": 0, "id": 2641549, "name": "Newtonhill", "cod": 200 } ``` imperial ### Example of API response ```json { "coord": { "lon": -2.15, "lat": 57 }, "weather": [ { "id": 804, "main": "Clouds", "description": "overcast clouds", "icon": "04d" } ], "base": "stations", "main": { "temp": 47.26, "feels_like": 40.82, "temp_min": 46.72, "temp_max": 48.67, "pressure": 1016, "humidity": 79, "sea_level": 1016, "grnd_level": 1016 }, "visibility": 10000, "wind": { "speed": 16.33, "deg": 189, "gust": 30.15 }, "clouds": { "all": 100 }, "dt": 1647347504, "sys": { "type": 2, "id": 2031790, "country": "GB", "sunrise": 1647325488, "sunset": 1647367827 }, "timezone": 0, "id": 2641549, "name": "Newtonhill", "cod": 200 } ``` ## Multilingual support ### Multilingual support You can use the `lang` parameter to get the output in your language. Translation is applied for the `city name` and `description` fields. ### API call ```text https://api.openweathermap.org/data/2.5/weather?lat={lat}&lon={lon}&appid={API key}&lang={lang} ``` | Parameters | | | | --- | --- | --- | | `lang` | optional | Language code | ### Examples of API calls ```json { "coord": { "lon": 37.62, "lat": 55.75 }, "weather": [ { "id": 501, "main": "Rain", "description": "pluie modérée", "icon": "10d" } ], "base": "stations", "main": { "temp": 295.48, "feels_like": 295.41, "temp_min": 295.15, "temp_max": 296.15, "pressure": 1018, "humidity": 60 }, "visibility": 10000, "wind": { "speed": 2, "deg": 260 }, "rain": { "1h": 1.23 }, "clouds": { "all": 100 }, "dt": 1599492273, "sys": { "type": 1, "id": 9029, "country": "RU", "sunrise": 1599446791, "sunset": 1599494929 }, "timezone": 10800, "id": 524901, "name": "Moscou", "cod": 200 } ``` We support the following languages that you can use with the corresponded lang values: - `sq` Albanian - `af` Afrikaans - `ar` Arabic - `az` Azerbaijani - `eu` Basque - `be` Belarusian - `bg` Bulgarian - `ca` Catalan - `zh_cn` Chinese Simplified - `zh_tw` Chinese Traditional - `hr` Croatian - `cz` Czech - `da` Danish - `nl` Dutch - `en` English - `fi` Finnish - `fr` French - `gl` Galician - `de` German - `el` Greek - `he` Hebrew - `hi` Hindi - `hu` Hungarian - `is` Icelandic - `id` Indonesian - `it` Italian - `ja` Japanese - `kr` Korean - `ku` Kurmanji (Kurdish) - `la` Latvian - `lt` Lithuanian - `mk` Macedonian - `no` Norwegian - `fa` Persian (Farsi) - `pl` Polish - `pt` Portuguese - `pt_br` Português Brasil - `ro` Romanian - `ru` Russian - `sr` Serbian - `sk` Slovak - `sl` Slovenian - `sp, es` Spanish - `sv, se` Swedish - `th` Thai - `tr` Turkish - `ua, uk` Ukrainian - `vi` Vietnamese - `zu` Zulu ## Call back function for JavaScript code ### Call back function for JavaScript code To use JavaScript code you can transfer `callback` functionName to JSONP callback. ### Example of API call ```text test( { "coord":{ "lon":-0.13, "lat":51.51 }, "weather":[ { "id":300, "main":"Drizzle", "description":"light intensity drizzle", "icon":"09d" } ], "base":"stations", "main":{ "temp":280.32, "pressure":1012, "humidity":81, "temp_min":279.15, "temp_max":281.15 }, "visibility":10000, "wind":{ "speed":4.1, "deg":80 }, "clouds":{ "all":90 }, "dt":1485789600, "sys":{ "type":1, "id":5091, "message":0.0103, "country":"GB", "sunrise":1485762037, "sunset":1485794875 }, "id":2643743, "name":"London", "cod":200 } ) ``` --- ## How to migrate from Dark Sky API to OpenWeather One Call API 3.0 With our [**One Call API 3.0**](/api/one-call-3.md) you can easily migrate from the Dark Sky API and get [free access](/full-price.md) to main weather data such as current weather, forecast and historical weather with only one call to the API. ## Features of OpenWeather [One Call API 3.0](/api/one-call-3.md) 1. [Free access and pay-as-you-call subscription](/full-price.md) One Call API 3.0 has its own, separate subscription that has a variable cost, in proportion to your actual use of the API. **1,000 API calls per day is included for free**. Users can configure and limit their usage to ensure that they don’t make more request than expected. Read more on the [pricing page](/price.md) and in the [FAQ](/faq.md). 2. One Call API 3.0 contains 4 endpoints and provides access to various data: 3. - [**Current weather and forecasts:**](/api/one-call-3.md#current) and government weather alerts - - minute forecast for 1 hour - hourly forecast for 48 hours - daily forecast for 8 days - [**Weather data for any timestamp**](/api/one-call-3.md#history) for 47+ years historical archive and 4 days ahead forecast - [**Daily aggregation**](/api/one-call-3.md#history_daily_aggregation) of weather data for 47+ years archive and 1.5 years ahead forecast - [**Weather overview**](/api/one-call-3.md#weather_overview) with a human-readable weather summary for today and tomorrow's forecast - [**AI Weather Assistant**](/api/one-call-3.md#ai_weather_assistant) for retrieving weather data and weather-related advice in a human-readable and friendly format 4. Matching parameters of Dark Sky API and OpenWeather One Call API 3.0 To match Dark Sky API parameters to the equivalent OpenWeather One Call API 3.0 parameters, please use [**this table**](/darksky-openweather-3.md#match). - [Subscribe for free](/home/sign_up.md) ## How to start using One Call API 3.0 There are 3 simple steps: 1. [Sign up](/home/sign_up.md) You will receive a welcome email that contains endpoints and instructions. 2. Get API key On the account page find the ["API key" tab](https://home.openweathermap.org/api_keys) and get the API key. Please use your API key in each API call. 3. Call API 4. - Getting current, minute, hourly and daily forecasts weather data `https://api.openweathermap.org/data/3.0/onecall?lat={lat}&lon={lon}&exclude={part}&appid=`[`{API key}`](https://home.openweathermap.org/api_keys) - Getting weather data by specified timestamp from 1st January 1979 till 4 days ahead forecast `https://api.openweathermap.org/data/3.0/onecall/timemachine?lat={lat}&lon={lon}&dt={time}&appid=`[`{API key}`](https://home.openweathermap.org/api_keys) - Getting daily aggregation weather data by specified timestamp from 2st January 1979 till 1.5 years ahead forecast `https://api.openweathermap.org/data/3.0/onecall/day_summary?lat={lat}&lon={lon}&date={date}&appid=`[`{API key}`](https://home.openweathermap.org/api_keys) - Getting weather overview with a human-readable weather summary for today and tomorrow's forecast, utilizing OpenWeather AI technologies `https://api.openweathermap.org/data/3.0/onecall/overview?lat={lat}&lon={lon}&appid=`[`{API key}`](https://home.openweathermap.org/api_keys) - Read [**AI Weather Assistant documentation**](/api/one-call-3.md#ai_weather_assistant) to get weather data and weather-related advice in a human-readable and friendly format | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude of coordinates | | `lon` | Yes | Longitude of coordinates | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `dt` | Yes | Timestamp (Unix time, UTC time zone), e.g. dt=1586468027. Data is available from January 1st, 1979 till 4 days ahead | | `date` | Yes | Date in the `YYYY-MM-DD` format for which data is requested. Date is available for 447+ years archive (starting from 1979-01-02) up to the 1,5 years ahead forecast to the current date | | `exclude` | optional | By using this parameter you can exclude some parts of the weather data from the API response. It should be a comma-delimited list (without spaces). Available values: `current` `minutely` `hourly` `daily` `alerts` | [One Call API 3.0](/api/one-call-3.md) documentation (complete description of API calls and parameters in API response, with examples). - [One Call API documentation](/api/one-call-3.md) ## Matching parameters | One Call API | Dark Sky API | Description | | --- | --- | --- | | `timezone` | `timezone` | Time zone name of the requested location | | **Current weather** (parameters of current weather and weather data by timestamp are the same) | | | | `dt` | `time` | UTC time zone | | `sunrise` | `sunriseTime` | Sunrise time, unix, UTC | | `sunset` | `sunsetTime` | Sunset time, unix, UTC | | `temp` | `temperature` | Temperature. Unit Default: Kelvin. [How to change units format](/api/one-call-3.md#data) | | `feels_like` | `apparentTemperature` | Feels like. Unit Default: Kelvin. [How to change units format](/api/one-call-3.md#data) | | `pressure` | `pressure` | Atmospheric pressure on the sea level, hPa | | `humidity` | `humidity` | Humidity, % | | `dew_point` | `dewPoint` | Dew point. Unit Default: Kelvin. [How to change units format](/api/one-call-3.md#data) | | `clouds` | `cloudCover` | Cloudiness, % | | `wind_speed` | `windSpeed` | Wind speed. Unit Default: meter/sec. [How to change units format](/api/one-call-3.md#data) | | `wind_gust` | `windGust` | Wind gust. Unit Default: meter/sec. [How to change units format](/api/one-call-3.md#data) | | `wind_deg` | `windBearing` | Wind direction, degrees (meteorological) | | `weather.description` | `summary` | Weather condition within the group. [Full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2) You can get the output in your language. [Learn more](/api/one-call-3.md#multi) | | `weather.icon` | `icon` | Weather icon id. [How to get icons](/weather-conditions.md#How-to-get-icon-URL) | | `rain` | `precipIntensity` | Precipitation volume, mm | | `snow` | `precipIntensity` | Snow volume, mm | | `uvi` | `uvIndex` | UV index | | `visibility` | `visibility` | Average visibility, meters | | **Minute forecast for 1 hour** | | | | `dt` | `time` | Time of forecasted data, unix, UTC | | `precipitation` | `precipIntensity` | Precipitation volume, mm | | **Hourly forecast for 48 hours** (parameters of hourly forecast and weather data by timestamp are the same) | | | | `dt` | `time` | Time of forecasted data, unix, UTC | | `temp` | `temperature` | Temperature. Unit Default: Kelvin. [How to change units format](/api/one-call-3.md#data) | | `feels_like` | `apparentTemperature` | Feels like. Unit Default: Kelvin. [How to change units format](/api/one-call-3.md#data) | | `pressure` | `pressure` | Atmospheric pressure on the sea level, hPa | | `humidity` | `humidity` | Humidity, % | | `dew_point` | `dewPoint` | Dew point. Unit Default: Kelvin. [How to change units format](/api/one-call-3.md#data) | | `clouds` | `cloudCover` | Cloudiness, % | | `wind_speed` | `windSpeed` | Wind speed. Unit Default: meter/sec. [How to change units format](/api/one-call-3.md#data) | | `wind_gust` | `windGust` | Wind gust. Unit Default: meter/sec. [How to change units format](/api/one-call-3.md#data) | | `wind_deg` | `windBearing` | Wind direction, degrees (meteorological) | | `weather.description` | `summary` | Weather condition within the group. [Full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2) You can get the output in your language. [Learn more](/api/one-call-3.md#multi) | | `weather.icon` | `icon` | Weather icon id. [How to get icons](/weather-conditions.md#How-to-get-icon-URL) | | `rain` | `precipIntensity` | Precipitation volume, mm | | `snow` | `precipIntensity` | Snow volume, mm | | `visibility` | `visibility` | Average visibility, meters | | **Daily forecast for 8 days** | | | | `dt` | `time` | Time of data forecasted, unix, UTC | | `sunrise` | `sunriseTime` | Sunrise time, unix, UTC | | `sunset` | `sunsetTime` | Sunset time, unix, UTC | | `summary` | `data.summary` | Human-readable description of the weather conditions for the day | | `temp.day` | `temperatureHigh` | Day temperature. Unit Default: Kelvin. [How to change units format](/api/one-call-3.md#data) | | `temp.night` | `temperatureLow` | Night temperature. Unit Default: Kelvin. [How to change units format](/api/one-call-3.md#data) | | `temp.morn` | - | Morning temperature. Unit Default: Kelvin. [How to change units format](/api/one-call-3.md#data) | | `temp.eve` | - | Evening temperature. Unit Default: Kelvin. [How to change units format](/api/one-call-3.md#data) | | `temp.min` | `temperatureMin` | Unit Default: Kelvin. [How to change units format](/api/one-call-3.md#data) | | `temp.max` | `temperatureMax` | Unit Default: Kelvin. [How to change units format](/api/one-call-3.md#data) | | `feels_like.day` | `apparentTemperatureHigh` | Unit Default: Kelvin. [How to change units format](/api/one-call-3.md#data) | | `feels_like.night` | `apparentTemperatureLow` | Unit Default: Kelvin. [How to change units format](/api/one-call-3.md#data) | | `feels_like.morn` | - | Unit Default: Kelvin. [How to change units format](/api/one-call-3.md#data) | | `feels_like.eve` | - | Unit Default: Kelvin. [How to change units format](/api/one-call-3.md#data) | | `pressure` | `pressure` | Atmospheric pressure on the sea level, hPa | | `humidity` | `humidity` | Humidity, % | | `dew_point` | `dewPoint` | Unit Default: Kelvin. [How to change units format](/api/one-call-3.md#data) | | `clouds` | `cloudCover` | Cloudiness, % | | `wind_speed` | `windSpeed` | Wind speed. Unit Default: meter/sec. [How to change units format](/api/one-call-3.md#data) | | `wind_gust` | `windGust` | Wind gust. Unit Default: meter/sec. [How to change units format](/api/one-call-3.md#data) | | `wind_deg` | `windBearing` | Wind direction, degrees (meteorological) | | `weather.description` | `summary` | Weather condition within the group. [Full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2) You can get the output in your language. [Learn more](/api/one-call-3.md#multi) | | `weather.icon` | `icon` | Weather icon id. [How to get icons](/weather-conditions.md#How-to-get-icon-URL) | | `rain` | `precipIntensity` | Precipitation volume, mm | | `snow` | `precipIntensity` | Snow volume, mm | | `uvi` | `uvIndex` | UV index | | `visibility` | `visibility` | Average visibility, meters | --- ## Fire Weather Index API ### Fire Weather Index API concept This product provides users with [current](#current) and [forecast](#forecast) Fire Weather Index data for any coordinates on the globe. Data is available in the JSON format. Fire Weather Index forecast is available for 5 days ahead with a daily step. You could obtain current and forecast fire weather index data as map product. Read more about Fire Weather Map [here](/api/fire-index-map.md). Fire Weather Index API is designed to help users to estimate current and forecast fire danger. Predictions of fire danger conditions based on the Canadian Forest Service Fire Weather Index Rating System (FWI). Fire Weather Index (FWI) is a numerical rating of the potential frontal fire intensity and indicates fire intensity by combining the rate of fire spread with the amount of fuel being consumed. ### Fire Weather Index range values FWI is classified in 6 classes of danger (very low, low, medium, high, very high and extreme). The fire danger classes are the same for all countries and show a harmonized picture of the spatial distribution of fire danger level. The following are the FWI values used as thresholds of the fire danger classes: | Fire danger class number | Fire danger class name | FWI ranges (upper bound excluded) | | --- | --- | --- | | 0 | Very low | <5.2 | | 1 | Low | 5.2-11.2 | | 2 | Moderate | 11.2-21.3 | | 3 | High | 21.3-38.0 | | 4 | Very high | 38.0-50.0 | | 5 | Extreme | ≥50 | ## How to get access to Fire Weather Index data 1. [Sign up](https://home.openweathermap.org/users/sign_up) to OpenWeather service in case you haven't got your API key yet. 2. [Contact us](mailto:info@openweathermap.org) via email to get access to our Fire Weather Index API. 3. Just make an API call according to the tech documentation for [Current](#current) and [Forecast](#forecast) Fire Weather Index API below, remembering to add your key to each call. To learn more about Fire Weather Index API (how to make an API call, samples, parameters), please read the next sections of the documentation. ## Call Current Fire Weather Index data To get access to current Fire Weather Index data, please use this section of the documentation. Please read the [Call Forecast Fire Weather Index data](#forecast) section in case you are looking for forecast of fire weather index dataset. ### How to make an API call ```text https://api.openweathermap.org/data/2.5/fwi?lat={lat}&lon={lon}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `lon` | Yes | Longitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### Example of API call ```text https://api.openweathermap.org/data/2.5/fwi?lat=24&lon=-103&appid={API key} ``` ### Example of API response ```json { "coord": { "lon":-103, "lat": 24 }, "list": [ { "main": { "fwi":70.53 }, "danger_rating:{ "description:"Extreme", "value": "5" }, "dt": "1677142800", } ] } ``` - `lat` Latitude of the location, decimal (-90; 90) - `lon` Longitude of the location, decimal (-180; 180) - `list` - `main` - `fwi`[Fire Weather Index range value](#fwi-range) - `danger_rating` - `description` Fire danger class name - `value` Fire danger class number - `dt`Time of current data, Unix, UTC. Please pay attention that time in the API responce equvalent midday local time is showing ## Call Forecast Fire Weather Index data To get access to the forecast with daily step for 5 next days for Fire Weather Index data, please use this section of the documentation. Please read the [Call current Fire Weather Index data](#current) section in case you are looking for current fire weather index dataset. ### How to make an API call ### API call ```text https://api.openweathermap.org/data/2.5/fwi/forecast?lat={lat}&lon={lon}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `lon` | Yes | Longitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### Example of API call ```text https://api.openweathermap.org/data/2.5/fwi/forecast?lat=35&lon=-102&appid={API key} ``` ### Example of API response ```json { "coord": { "lon":-102, "lat": 35 }, "list": [ { "main": { "fwi": 21.23 }, "danger_rating:{ "description:"Moderate", "value": "2" }, "dt": "1677142800" }, { "main": { "fwi": 11.61 }, "danger_rating:{ "description:"Moderate", "value": "2" }, "dt": "1677229200" }, { "main": { "fwi": 39.04 }, "danger_rating:{ "description:"Very high", "value": "4" }, "dt": "1677315600" }, { "main": { "fwi": 23.76 }, "danger_rating:{ "description:"High", "value": "3" }, "dt": "1677402000" }, { "main": { "fwi": 46.33 }, "danger_rating:{ "description:"Very high", "value": "4" }, "dt": "1677488400" }, { "main": { "fwi": 61.57 }, "danger_rating:{ "description:"Extreme", "value": "5" }, "dt": "1677574800" } ] } ``` ### Fields in API response - `lat` Latitude of the location,decimal (-90; 90) - `lon` Longitude of the location,decimal (-180; 180) - `list` - `main` - `fwi`[Fire Weather Index range value](#fwi-range) - `danger_rating` - `description` Fire danger class name - `value` Fire danger class number - `dt`Time of current data, Unix, UTC. Please pay attention that time in the API responce equvalent midday local time is showing ### API errors You could find information about some popular errors [here](/faq.md#api-errors). --- ## Fire Weather Index map ### Fire Weather Index map concept Using simple URL you can get the following Fire Weather Index maps: - Current Fire Weather index maps - Forecast Fire Weather index maps: The forecast for 5 days with a daily step To recieve infromation about current and forecast fire weather index data in JSON format please read [here](/api/fire-index-api.md). Fire Weather Index map is designed to help users to estimate current and forecast fire danger. Predictions of fire danger conditions based on the Canadian Forest Service Fire Weather Index Rating System (FWI). Fire Weather Index (FWI) is a numerical rating of the potential frontal fire intensity and indicates fire intensity by combining the rate of fire spread with the amount of fuel being consumed. ### Fire Weather Index range values FWI is classified in 6 classes of danger (very low, low, medium, high, very high and extreme). The fire danger classes are the same for all countries and maps show a harmonized picture of the spatial distribution of fire danger level. The following are the FWI values used as thresholds of the fire danger classes: | Fire danger class number | Fire danger class name | FWI ranges (upper bound excluded) | | --- | --- | --- | | 0 | Very low | <5.2 | | 1 | Low | 5.2-11.2 | | 2 | Moderate | 11.2-21.3 | | 3 | High | 21.3-38.0 | | 4 | Very high | 38.0-50.0 | | 5 | Extreme | ≥50 | ## URL format and parameters Use the following URL format and parameters to get Fire weather Index maps. Please pay attention to the URL example. ### API call ```text https://maps.openweathermap.org/maps/2.0/fwi/{z}/{x}/{y}?appid={API key}&date={date} ``` | Parameters | | | | --- | --- | --- | | `{z}` | Yes | Number of zoom level. You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `{x}` | Yes | Number of x tile coordinate. You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `{y}` | Yes | Number of y tile coordinate. You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](/api_keys.md)) | | `date` | optional | Date and time of (Unix time, UTC), e.g. date=1527811200. If you do not specify any date and time, you will get Current Fire Weather Index map. More information about how to get Current, and Forecast fire weather index maps you can find [here](/api/fire-index-map.md#data). | ### URL example ```text https://maps.openweathermap.org/maps/2.0/fwi/4/1/6?appid={API key}&date=1600780200 ``` > You need to insert the generated URL into special plugins. > > For example, Leaflet, OpenLayers. You can also use any other apps that support the display of layers. [Learn more](/api/fire-index-map.md#library). ## How to get Current and Forecast Fire Weather Index maps using only 'date' parameter? To get Current and Forecast Fire Weather Index maps you just need to change only `date` parameter in the URL request: **1. Current Fire Weather Index maps. **Specify the current date and time to get Current Fire Weather Index map. The date and time specified in the request will be rounded to the midday local time of the current day. If you do not specify any date and time, you will get Current Fire Weather Index map. **2. Forecast Fire Weather Index maps.** You can specify any date and time within the next 5 days to get the Forecast Fire Weather Index maps for the specified time. The date and time specified in the request will be rounded to the midday local time of the forecasted day. If you do not specify any date and time, you will get Current Fire Weather Index map. ## Example of Fire Index maps Please pay attention that for geographical coordinates with zero probobility of Fire Weather Index filling is absent. ### Fire Weather Index map ![fire_Index_map_africa](/payload/api/media/file/fire_Index_map_africa.jpg) ## Fire Weather Index map default palette By default in Fire Weather Index maps used the palette below: 0:126E00;35:FFEB3B;75:ED8E3E;150:FF0000;200:890000;300:FF00FB ## Libraries to connect weather layers ### Open Layers The following functions are available for the OpenLayers library: - Classes of weather layer and weather stations layer - Possibility to set your own style - Classes with clustered markers - Support of marker server clustering ### Leaflet The OpenWeatherMap javascript library is designed to work with the Leaflet mapping service. The current version of the library allows the following: - Embedding of layer with current weather in cities - Embedding of layer with weather stations - The library supports customer clustering ### Leaflet library Another implementation of map based on Leaflet technology supports OWM's TileLayers and current city/station data. It is configurable with many options. For current city/station data the library supports refreshing the data in intervals, some types of client-side clustering (show only the station/city with the highest rank for a defined pixel square), custom image set (if you provide one), different languages (`en`, `de`, `ru`, `fr`, but translation is incomplete), `minZoom` and others. Source and documentation (README.md) is available on GitHub [https://github.com/buche/leaflet-openweathermap](https://github.com/buche/leaflet-openweathermap) Example of weather map: [https://github.com/owm-inc/VANE-intro/tree/master/apps](https://github.com/owm-inc/VANE-intro/tree/master/apps) Using OpenWeatherMap weather tiles with leaflet: PDF --- ## Daily Forecast 16 Days ### Product concept Daily Forecast 16 Days is available at any location on the globe. The forecast includes daily weather data and the response data is available in JSON or XML format. ## Call 16 day / daily forecast data You can seach 16 day weather forecast with daily average parameters by geographic coordinates. All weather data can be obtained in JSON and XML formats. ### API call ```text api.openweathermap.org/data/2.5/forecast/daily?lat={lat}&lon={lon}&cnt={cnt}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `lon` | Yes | Longitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `cnt` | optional | A number of days, which will be returned in the API response (from `1` to `16`). [Learn more](#limit) | | `mode` | optional | Data format. Possible values are: `json`, `xml`. If the `mode` parameter is empty the format is JSON by default. [Learn more](#format) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | Language code. [Learn more](#multi) | > Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around. > > Please note that [built-in geocoder](#geocoding) has been deprecated. Although it is still available for use, bug fixing and updates are no longer available for this functionality. Call 7 days forecast by geographic coordinates ## API response > If you do not see some of the parameters in your API response it means that these weather phenomena are just not happened for the time of measurement for the city or location chosen. Only really measured or calculated data is displayed in API response. - `city` - `city.id` City ID. Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin) - `city.name` City name. Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin) - `city.coord` - `city.coord.lat` Geo location, latitude - `city.coord.lon` Geo location, longitude - `country` Country code (GB, JP etc.). Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin) - `population` Internal parameter - `timezone` Shift in seconds from UTC - `cod` Internal parameter - `message` Internal parameter - `cnt` A number of days returned in the API response - `list` - `list.dt ` Time of data forecasted - `list.temp` - `list.temp.day` Temperature at 12:00 local time. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.temp.min` Min daily temperature. Please find more info [here.](#min) Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.temp.max` Max daily temperature. Please find more info [here.](#min) Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.temp.night` Temperature at 00:00 local time. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.temp.eve` Temperature at 18:00 local time. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.temp.morn` Ttemperature at 06:00 local time. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.feels_like` - `list.feels_like.day` Temperature at 12:00 local time.This temperature parameter accounts for the human perception of weather. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.feels_like.night` Temperature at 00:00 local time.This temperature parameter accounts for the human perception of weather. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.feels_like.eve` Temperature at 18:00 local time.This temperature parameter accounts for the human perception of weather. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.feels_like.morn` Temperature at 06:00 local time. This temperature parameter accounts for the human perception of weather. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.pressure` Atmospheric pressure on the sea level, hPa - `list.humidity` Humidity, % - `list.weather` (more info [Weather condition codes](/weather-conditions.md)) - `list.weather.id` Weather condition id - `list.weather.main` Group of weather parameters (Rain, Snow, Clouds etc.) - `list.weather.description` Weather condition within the group. Please find more [here.](#list) You can get the output in your language. [Learn more](#multi) - `list.weather.icon` Weather icon id - `list.speed` Maximum wind speed for the day. Unit Default: meter/sec, Metric: meter/sec, Imperial: miles/hour. - `list.deg` Wind direction relevant to the maximum wind speed, degrees (meteorological) - `list.gust` Wind gust. Unit Default: meter/sec, Metric: meter/sec, Imperial: miles/hour. - `list.clouds` Cloudiness, % - `list.rain` Precipitation volume, mm. Please note that only mm as units of measurement are available for this parameter - `list.snow` Snow volume, mm. Please note that only mm as units of measurement are available for this parameter - `list.pop` Probability of precipitation. The values of the parameter vary between 0 and 1, where 0 is equal to 0%, 1 is equal to 100% ### XML ```text Zocca IT 7200 0 ... ``` - `location` - `location.name` City name. Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin) - `location.type` Prototype parameter - `location.country` Country code (GB, JP etc.). Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin) - `location.timezone` Shift in seconds from UTC - `location.location` - `location.location.altitude` Geo location, altitude above the sea level - `location.location.latitude` Geo location, latitude - `location.location.longitude` Geo location, longitude - `location.location.geobase` Internal parameter - `location.location.geobaseid` Internal parameter - `meta` - `meta.lastupdate` Internal parameter - `meta.calctime` Speed of data calculation - `meta.nextupdate` Internal parameter - `sun` - `sun.rise` Sunrise time - `sun.set` Sunset time - `forecast` - `forecast.time` - `forecast.time.day` Date of weather data forecasted - `forecast.symbol` - `forecast.symbol.number` Weather condition id - `forecast.symbol.name` Weather condition - `forecast.symbol.var` Weather icon id - `forecast.precipitation` - `forecast.precipitation.value` Precipitation volume for the last day, mm. Please note that only mm as units of measurement are available for this parameter - `forecast.precipitation.type` Type of precipitation. Possible value is rain, snow - `forecast.precipitation.probability` Probability of precipitation. The values of the parameter vary between 0 and 1, where 0 is equal to 0%, 1 is equal to 100% - `forecast.windDirection` - `forecast.windDirection.deg` Wind direction relevant to the maximum wind speed, degrees (meteorological) - `forecast.windDirection.code` Code of the wind direction relevant to the maximum wind speed. Possible value is WSW, N, S etc. - `forecast.windDirection.name` Full name of the wind direction relevant to the maximum wind speed - `forecast.windSpeed` - `forecast.windSpeed.mps` Maximum wind speed for the day, meters per second - `forecast.windSpeed.unit` Maximum wind speed units, m/s - `forecast.windSpeed.name`Type of wind relevant to the maximum wind speed - `forecast.windGust` - `forecast.windGust.gust` Wind gust, meters per second - `forecast.windGust.unit` Wind gust units, m/s - `forecast.temperature` - `forecast.temperature.day` Temperature at 12:00 local time for forecasted day. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `forecast.temperature.min` Min daily temperature. Please find more info [here.](#min) Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `forecast.temperature.max` Max daily temperature. Please find more info [here.](#min) Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `forecast.temperature.night` Temperature at 00:00 local time for forecasted day. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `forecast.temperature.eve` Temperature at 18:00 local time for forecasted day. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `forecast.temperature.morn` Temperature at 06:00 local time for forecasted day. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `forecast.temperature.unit` Unit of measurements. Possible values are Celsius, Kelvin, Fahrenheit - `forecast.feels_like` - `forecast.feels_like.day` Temperature at 12:00 local time for forecasted day. This temperature parameter accounts for the human perception of weather. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenhei. - `forecast.feels_like.night` Temperature at 00:00 local time for forecasted day. This temperature parameter accounts for the human perception of weather. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `forecast.feels_like.eve` Temperature at 18:00 local time for forecasted day. This temperature parameter accounts for the human perception of weather. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `forecast.feels_like.morn` Temperature at 06:00 local time for forecasted day. This temperature parameter accounts for the human perception of weather. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `forecast.feels_like.unit` Unit of measurements. Possible values are Celsius, Kelvin, Fahrenheit. Unit Default: Kelvin - `forecast.pressure` - `forecast.pressure.unit` hPa - `forecast.pressure.value` Pressure value - `forecast.humidity` - `forecast.humidity.unit` % - `forecast.humidity.value` Humidity value - `forecast.clouds` - `forecast.pressure.value` Name of the cloudiness - `forecast.pressure.all` Cloudiness - `forecast.pressure.unit` % > We provide a broad variety of products such as [One Call API 4.0,](/api/one-call-4.md) [Solar Irradiance & Energy Prediction service,](/api.md#solar) [Road Risk API,](/api/road-risk.md) [Air Pollution API](/api/air-pollution.md) and solutions for advanced weather parameters like solar irradiance data, UVI, dew point, government weather alerts, etc. Please review our [product list](/api.md) page and find more info in the product documentation and [pricing](/price.md) pages. ### List of condition codes List of [weather condition codes](/weather-conditions.md) with icons (range of thunderstorm, drizzle, rain, snow, clouds, atmosphere etc.) ### Min/max temperature in current weather API and forecast API - In **16 Day forecast** - **min** and **max** mean maximum and minimum temperature in the day. - In [Current weather API](/current.md), [Hourly forecast API](/api/hourly-forecast.md) and [5 day / 3 hour forecast API](/forecast5.md) - **temp_min** and **temp_max** are optional parameters mean min / max temperature in the city at the current moment to see deviation from current temp just for your reference. For large cities and megalopolises geographically expanded it might be applicable. In most cases both **temp_min** and **temp_max** parameters have the same volume as 'temp'. Please use **temp_min** and **temp_max** parameters in current weather API optionally. ### Min/max temperature in current weather API and forecast API ```text "main":{ "temp":306.15, //current temperature "pressure":1013, "humidity":44, "temp_min":306.15, //min current temperature in the city "temp_max":306.15 //max current temperature in the city }, ``` For comparison, take a look at the example of daily forecast weather API response: ## Bulk downloading We provide number of bulk files with current weather and forecasts. More information is on the [Bulk page](/bulk.md). > Bulk downloading is available not for all accounts. To get more information please refer to the [Price page.](/price.md) [http://bulk.openweathermap.org/sample/](http://bulk.openweathermap.org/sample/) ## Other features ### Geocoding API Requesting API calls by geographical coordinates is the most accurate way to specify any location. If you need to convert city names and zip-codes to geo coordinates and the other way around automatically, please use our [Geocoding API](/api/geocoding-api.md). ### Built-in geocoding > Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around. > > **Please note that API requests by city name, zip-codes and city id have been deprecated. Although they are still available for use, bug fixing and updates are no longer available for this functionality.** ### Built-in API request by city name You can search 16 day weather forecast with daily average parameters by city name. All weather data can be obtained in JSON and XML formats. ### API calls ```text api.openweathermap.org/data/2.5/forecast/daily?q={city name}&cnt={cnt}&appid={API key} ``` ### API call ```text api.openweathermap.org/data/2.5/forecast/daily?q={city name},{country code}&cnt={cnt}&appid={API key} ``` ### API call ```text api.openweathermap.org/data/2.5/forecast/daily?q={city name},{state code},{country code}&cnt={cnt}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `q` | Yes | City name, state code and country code divided by comma, use ISO 3166 country codes. You can specify the parameter not only in English. In this case, the API response should be returned in the same language as the language of requested location name if the location is in our predefined list of more than 200,000 locations. | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `cnt` | optional | A number of days, which will be returned in the API response (from `1` to `16`). [Learn more](#limit) | | `mode` | optional | Data format. Possible values are: `json`, `xml`. If the `mode` parameter is empty the format is JSON by default. [Learn more](#format) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | Language code. [Learn more](#multi) | ### Examples of API calls Call 7 days forecast by city name in metric units > There is a possibility to receive a central district of the city/town with its own parameters (geographic coordinates/id/name) in API response. Please see the example below Call 16 days forecast by geographic coordinates ### Built-in API request by city ID You can seach 16 day weather forecast with daily average parameters by city ID. All weather data can be obtained in JSON and XML format. List of city ID 'city.list.json.gz' can be downloaded [here.](http://bulk.openweathermap.org/sample/) We recommend to call API by city ID to get unambiguous result for your city. ### API call ```text api.openweathermap.org/data/2.5/forecast/daily?id={city ID}&cnt={cnt}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `id` | Yes | city ID | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `cnt` | optional | A number of days, which will be returned in the API response (from `1` to `16`). [Learn more](#limit) | | `mode` | optional | Data format. Possible values are: `json`, `xml`. If the `mode` parameter is empty the format is JSON by default. [Learn more](#format) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | Language code. [Learn more](#multi) | ### Built-in API request by ZIP code Please note if country is not specified then the search works for USA as a default. ### API call ```text api.openweathermap.org/data/2.5/forecast/daily?zip={zip code},{country code}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `zip` | Yes | Zip code | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `cnt` | optional | A number of days, which will be returned in the API response (from `1` to `16`). [Learn more](#limit) | | `mode` | optional | Data format. Possible values are: `json`, `xml`. If the `mode` parameter is empty the format is JSON by default. [Learn more](#format) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | Language code. [Learn more](#multi) | ### Format Data format. JSON format is used by default. To get data in XML format use `mode=xml`. | Parameters | | | | --- | --- | --- | | `mode` | optional | Data format. Possible values are: `json`, `xml`. If the `mode` parameter is empty the format is JSON by default. | JSON XML ### Example of API response ```text London GB 0.0117 ### Limitation of result To limit the number of returned days please use `cnt` parameter. | Parameters | | | | --- | --- | --- | | `cnt` | | A number of days, which will be returned in the API response | ### Units of measurement `standard`, `metric`, and `imperial` units are available. [List of all API parameters with available units](/weather-data.md). | Parameters | | | | --- | --- | --- | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. | > Maximum wind speed is available in miles/hour and meter/sec. Standard metric imperial ### Multilingual support You can use `lang` parameter to get the output in your language. Translation is applied for the `city name` and `description` fields. ### API call ```text https://api.openweathermap.org/data/2.5/forecast/daily?id=524901&lang={lang} ``` | Parameters | | | | --- | --- | --- | | `lang` | optional | Language code | We support the following languages that you can use with the corresponded lang values: - `sq` Albanian - `af` Afrikaans - `ar` Arabic - `az` Azerbaijani - `eu` Basque - `be` Belarusian - `bg` Bulgarian - `ca` Catalan - `zh_cn` Chinese Simplified - `zh_tw` Chinese Traditional - `hr` Croatian - `cz` Czech - `da` Danish - `nl` Dutch - `en` English - `fi` Finnish - `fr` French - `gl` Galician - `de` German - `el` Greek - `he` Hebrew - `hi` Hindi - `hu` Hungarian - `is` Icelandic - `id` Indonesian - `it` Italian - `ja` Japanese - `kr` Korean - `ku` Kurmanji (Kurdish) - `la` Latvian - `lt` Lithuanian - `mk` Macedonian - `no` Norwegian - `fa` Persian (Farsi) - `pl` Polish - `pt` Portuguese - `pt_br` Português Brasil - `ro` Romanian - `ru` Russian - `sr` Serbian - `sk` Slovak - `sl` Slovenian - `sp, es` Spanish - `sv, se` Swedish - `th` Thai - `tr` Turkish - `ua, uk` Ukrainian - `vi` Vietnamese - `zu` Zulu ### Call back function for JavaScript code To use JavaScript code you can transfer `callback` functionName to JSONP callback. ### Example of API call ```text test( { "coord":{ "lon":-0.13, "lat":51.51 }, "weather":[ { "id":300, "main":"Drizzle", "description":"light intensity drizzle", "icon":"09d" } ], "base":"stations", "main":{ "temp":280.32, "pressure":1012, "humidity":81, "temp_min":279.15, "temp_max":281.15 }, "visibility":10000, "wind":{ "speed":4.1, "deg":80, "gust":6.1 }, "clouds":{ "all":90 }, "dt":1485789600, "sys":{ "type":1, "id":5091, "message":0.0103, "country":"GB", "sunrise":1485762037, "sunset":1485794875 }, "id":2643743, "name":"London", "cod":200 } ) ``` --- ## Climatic forecast for 30 days ### Product concept Climatic forecast 30 Days allows you to request daily weather data for the next 30 days. Data is available in JSON and XML formats. ## Call weather forecast for 30 days ### How to make an API call ### API call ```text https://pro.openweathermap.org/data/2.5/forecast/climate?lat={lat}&lon={lon}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `lon` | Yes | Longitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `cnt` | optional | A number of days, which will be returned in the API response (from `1` to `30`). [Learn more](#limit) | | `mode` | optional | Data format. Possible values are: `json`, `xml`. If the `mode` parameter is empty the format is JSON by default. [Learn more](#format) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | Language code. [Learn more](#multi) | > Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around. > > Please note that [built-in geocoder](#geocoding) has been deprecated. Although it is still available for use, bug fixing and updates are no longer available for this functionality. ### Example of API call ```text https://pro.openweathermap.org/data/2.5/forecast/climate?lat=35&lon=139&appid={API key} ``` ### Fields in API response - `city` - - `city.id` City ID. Please note that built-in geocoder functionality has been deprecated. Learn more [here](/api/forecast30.md#builtin) - `city.name` City name. Please note that built-in geocoder functionality has been deprecated. Learn more [here](/api/forecast30.md#builtin) - `city.coord` - - `city.coord.lat` Geo location, latitude - `city.coord.lon` Geo location, longitude - `country` Country code (GB, JP etc.). Please note that built-in geocoder functionality has been deprecated. Learn more [here](/api/forecast30.md#builtin) - `population` City population - `timezone` Shift in seconds from UTC - `cod` Internal parameter - `message` Internal parameter - `list` - - `list.dt `Time of data forecasted - `list.sunrise` Sunrise time, Unix, UTC - `list.sunset` Sunset time, Unix, UTC - `list.temp` - - `list.temp.day` Day temperature. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.temp.min` Min daily temperature. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.temp.max` Max daily temperature. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.temp.night` Night temperature. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.temp.eve` Evening temperature. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.temp.morn` Morning temperature. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.feels_like` - - `list.feels_like.day` Day temperature.This temperature parameter accounts for the human perception of weather. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.feels_like.night` Night temperature.This temperature parameter accounts for the human perception of weather. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.feels_like.eve` Evening temperature.This temperature parameter accounts for the human perception of weather. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.feels_like.morn` Morning temperature. This temperature parameter accounts for the human perception of weather. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.pressure` Atmospheric pressure on the sea level, hPa - `list.humidity` Humidity, % - `list.weather` (more info [Weather condition codes](/weather-conditions.md)) - - `list.weather.id` Weather condition id - `list.weather.main` Group of weather parameters (Rain, Snow, Clouds etc.) - `list.weather.description` Weather condition within the group. Please find more [here.](/api/forecast30.md#list) You can get the output in your language. [Learn more](/api/forecast30.md#multi) - `list.weather.icon` Weather icon id - `list.speed` Wind speed. Unit Default: meter/sec, Metric: meter/sec, Imperial: miles/hour - `list.deg` Wind direction, degrees (meteorological) - `list.clouds` Cloudiness, % - `list.rain` Precipitation volume, mm. Please note that only mm as units of measurement are available for this parameter - `list.snow` Snow volume, mm. Please note that only mm as units of measurement are available for this parameter - `list.cnt` Number of lines returned by this API call > We provide a broad variety of products such as [One Call API 4.0,](/api/one-call-4.md) [Solar Irradiance & Energy Prediction service,](/api.md#solar) [Road Risk API,](/api/road-risk.md) [Air Pollution API](/api/air-pollution.md) and solutions for advanced weather parameters like solar irradiance data, UVI, dew point, government weather alerts, etc. Please review our [product list](/api.md) page and find more info in the product documentation and [pricing](/price.md) pages. ### List of weather condition codes List of [weather condition codes](/weather-conditions.md) with icons (range of thunderstorm, drizzle, rain, snow, clouds, atmosphere etc.) ## Other features ### Geocoding API Requesting API calls by geographical coordinates is the most accurate way to specify any location. If you need to convert city names and zip-codes to geo coordinates and the other way around automatically, please use our [Geocoding API](/api/geocoding-api.md). ### Built-in geocoding > Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around. > > **Please note that API requests by city name, zip-codes and city id have been deprecated. Although they are still available for use, bug fixing and updates are no longer available for this functionality.** ### Built-in API request by city name ### API call ```text https://pro.openweathermap.org/data/2.5/forecast/climate?q={city name},{country code}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `q` | Yes | city name and country code divided by comma (please use ISO 3166 country codes) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `cnt` | optional | A number of days, which will be returned in the API response (from `1` to `30`). [Learn more](#limit) | | `mode` | optional | Data format. Possible values are: `json`, `xml`. If the `mode` parameter is empty the format is JSON by default. [Learn more](#format) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | Language code. [Learn more](#multi) | ### Example of API call ```text https://pro.openweathermap.org/data/2.5/forecast/climate?q=London&appid={API key} ``` > When requesting API by city name, there is a possibility to receive a central district of the city/town with its own parameters (geographic coordinates/id/name) in API response. ### Built-in API request by city ID List of city IDs can be downloaded [here](http://bulk.openweathermap.org/sample/city.list.json.gz). We recommend to call API by city ID to get unambiguous result for your city. ### API call ```text https://pro.openweathermap.org/data/2.5/forecast/climate?id={city ID}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `id` | Yes | city ID | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `cnt` | optional | A number of days, which will be returned in the API response (from `1` to `30`). [Learn more](#limit) | | `mode` | optional | Data format. Possible values are: `json`, `xml`. If the `mode` parameter is empty the format is JSON by default. [Learn more](#format) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | Language code. [Learn more](#multi) | ### Example of API call ```text https://pro.openweathermap.org/data/2.5/forecast/climate?id=2643743&appid={API key} ``` ### Built-in API request by ZIP code Please note that, if the country code is not specified, then the search function will use `usa` by default. ### API call ```text https://pro.openweathermap.org/data/2.5/forecast/climate?zip={zip code},{country code}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `zip` | Yes | Zip code | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `cnt` | optional | A number of days, which will be returned in the API response (from `1` to `30`). [Learn more](#limit) | | `mode` | optional | Data format. Possible values are: `json`, `xml`. If the `mode` parameter is empty the format is JSON by default. [Learn more](#format) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | Language code. [Learn more](#multi) | ### Example of API call ```text https://pro.openweathermap.org/data/2.5/forecast/climate?zip=94040,us&appid={API key} ``` ### Format Data format. JSON format is used by default. To get data in XML format use `mode=xml`. | Parameters | | | | --- | --- | --- | | `mode` | optional | Data format. Possible values are: `json`, `xml`. If the `mode` parameter is empty the format is JSON by default. | JSON XML ### Limitation of result To limit the number of returned days please use `cnt` parameter. | Parameters | | | | --- | --- | --- | | `cnt` | | A number of days, which will be returned in the API response | ### Units of measurement `standard`, `metric`, and `imperial` units are available. [List of all API parameters with available units](/weather-data.md). | Parameters | | | | --- | --- | --- | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. | > Temperature is available in Fahrenheit, Celsius and Kelvin units. > > Wind speed is available in miles/hour and meter/sec. > > - For temperature in Fahrenheit and wind speed in miles/hour, use `units=imperial` > - For temperature in Celsius and wind speed in meter/sec, use `units=metric` > - Temperature in Kelvin and wind speed in meter/sec is used by default, so there is no need to use the units parameter in the API call if you want this ### Standard ### Metric ### Imperial ### Multilingual support You can use `lang` parameter to get the output in your language. Translation is applied for the `city name` and `description` fields. ### API call ```text http://api.openweathermap.org/data/2.5/forecast/climate?id=524901&lang={lang} ``` | Parameters | | | | --- | --- | --- | | `lang` | optional | Language code | We support the following languages that you can use with the corresponded lang values: - `sq` Albanian - `af` Afrikaans - `ar` Arabic - `az` Azerbaijani - `eu` Basque - `be` Belarusian - `bg` Bulgarian - `ca` Catalan - `zh_cn` Chinese Simplified - `zh_tw` Chinese Traditional - `hr` Croatian - `cz` Czech - `da` Danish - `nl` Dutch - `en` English - `fi` Finnish - `fr` French - `gl` Galician - `de` German - `el` Greek - `he` Hebrew - `hi` Hindi - `hu` Hungarian - `is` Icelandic - `id` Indonesian - `it` Italian - `ja` Japanese - `kr` Korean - `ku` Kurmanji (Kurdish) - `la` Latvian - `lt` Lithuanian - `mk` Macedonian - `no` Norwegian - `fa` Persian (Farsi) - `pl` Polish - `pt` Portuguese - `pt_br` Português Brasil - `ro` Romanian - `ru` Russian - `sr` Serbian - `sk` Slovak - `sl` Slovenian - `sp, es` Spanish - `sv, se` Swedish - `th` Thai - `tr` Turkish - `ua, uk` Ukrainian - `vi` Vietnamese - `zu` Zulu ### Call back function for JavaScript code To use JavaScript code you can transfer `callback` functionName to JSONP callback. ### Example of API call ```text test( { "coord":{ "lon":-0.13, "lat":51.51 }, "weather":[ { "id":300, "main":"Drizzle", "description":"light intensity drizzle", "icon":"09d" } ], "base":"stations", "main":{ "temp":280.32, "pressure":1012, "humidity":81, "temp_min":279.15, "temp_max":281.15 }, "visibility":10000, "wind":{ "speed":4.1, "deg":80 }, "clouds":{ "all":90 }, "dt":1485789600, "sys":{ "type":1, "id":5091, "message":0.0103, "country":"GB", "sunrise":1485762037, "sunset":1485794875 }, "id":2643743, "name":"London", "cod":200 } ) ``` --- ## 5 day weather forecast ### Product concept 5 day forecast is available at any location on the globe. It includes weather forecast data with 3-hour step. Forecast is available in JSON or XML format. ## Call 5 day / 3 hour forecast data ### How to make an API call You can search weather forecast for 5 days with data every 3 hours by geographic coordinates. All weather data can be obtained in JSON and XML formats. ### API call ```text api.openweathermap.org/data/2.5/forecast?lat={lat}&lon={lon}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `lon` | Yes | Longitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `mode` | optional | Response format. JSON format is used by default. To get data in XML format use `mode=xml`. [Learn more](#format) | | `cnt` | optional | A number of timestamps, which will be returned in the API response. [Learn more](#limit) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | You can use the `lang` parameter to get the output in your language. [Learn more](#multi) | > Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around. > > Please note that [built-in geocoder](#geocoding) has been deprecated. Although it is still available for use, bug fixing and updates are no longer available for this functionality. ## API response > If you do not see some of the parameters in your API response it means that these weather phenomena are just not happened for the time of measurement for the city or location chosen. Only really measured or calculated data is displayed in API response. ## JSON format API response fields - `cod` Internal parameter - `message` Internal parameter - `cnt`A number of timestamps returned in the API response - `list` - `list.dt ` Time of data forecasted, unix, UTC - `list.main` - `list.main.temp` Temperature. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.main.feels_like` This temperature parameter accounts for the human perception of weather. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.main.temp_min` Minimum temperature at the moment of calculation. This is minimal forecasted temperature (within large megalopolises and urban areas), use this parameter optionally. Please find more info [here](#min). Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.main.temp_max` Maximum temperature at the moment of calculation. This is maximal forecasted temperature (within large megalopolises and urban areas), use this parameter optionally. Please find more info [here](#min). Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.main.pressure` Atmospheric pressure on the sea level by default, hPa - `list.main.sea_level` Atmospheric pressure on the sea level, hPa - `list.main.grnd_level` Atmospheric pressure on the ground level, hPa - `list.main.humidity` Humidity, % - `list.main.temp_kf` Internal parameter - `list.weather` - `list.weather.id` Weather condition id - `list.weather.main` Group of weather parameters (Rain, Snow, Clouds etc.) - `list.weather.description` Weather condition within the group. Please find more [here.](#list) You can get the output in your language. [Learn more](#multi) - `list.weather.icon` Weather icon id - `list.clouds` - `list.clouds.all` Cloudiness, % - `list.wind` - `list.wind.speed` Wind speed. Unit Default: meter/sec, Metric: meter/sec, Imperial: miles/hour - `list.wind.deg` Wind direction, degrees (meteorological) - `list.wind.gust` Wind gust. Unit Default: meter/sec, Metric: meter/sec, Imperial: miles/hour - `list.visibility` Average visibility, metres. The maximum value of the visibility is 10km - `list.pop` Probability of precipitation. The values of the parameter vary between 0 and 1, where 0 is equal to 0%, 1 is equal to 100% - `list.rain` - `list.rain.3h` Rain volume for last 3 hours, mm. Please note that only mm as units of measurement are available for this parameter - `list.snow` - `list.snow.3h` Snow volume for last 3 hours. Please note that only mm as units of measurement are available for this parameter - `list.sys` - `list.sys.pod` Part of the day (n - night, d - day) - `list.dt_txt` Time of data forecasted, ISO, UTC - `city` - `city.id` City ID. Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin) - `city.name` City name. Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin) - `city.coord` - `city.coord.lat ` Geo location, latitude - `city.coord.lon` Geo location, longitude - `city.country` Country code (GB, JP etc.). Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin) - `city.population` City population - `city.timezone` Shift in seconds from UTC - `city.sunrise` Sunrise time, Unix, UTC - `city.sunset` Sunset time, Unix, UTC ## XML - `location` - `location.name ` City name. Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin) - `location.type` Internal parameter - `location.country` Country code (GB, JP etc.). Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin) - `location.timezone` Shift in seconds from UTC - `location.location` - `location.location.altitude` Geo location, altitude above the sea level - `location.location.latitude` Geo location, latitude - `location.location.longitude` Geo location, longitude - `location.location.geobase` Internal parameter - `location.location.geobaseid` Internal parameter - `meta` - `meta.lastupdate` Prototype parameter - `meta.calctime` Speed of data calculation - `meta.nextupdate` Prototype parameter - `sun` - `sun.rise` Sunrise time - `sun.set` Sunset time - `forecast` - `forecast.time` - `forecast.time.from` Beginning of the period of data forecasted - `forecast.time.to` End of the period of data forecasted - `forecast.symbol` - `forecast.symbol.number` Weather condition id - `forecast.symbol.name` Weather condition - `forecast.symbol.var` Weather icon id - `forecast.precipitation` - `forecast.precipitation.probability` Probability of precipitation. The values of the parameter vary between 0 and 1, where 0 is equal to 0%, 1 is equal to 100% - `forecast.precipitation.unit` Period of measurements. Possible value is 1 hour, 3 hours - `forecast.precipitation.value` Precipitation volume for the last 3 hours, mm. Please note that only mm as units of measurement are available for this parameter - `forecast.precipitation.type` Type of precipitation. Possible value is rain, snow - `forecast.windDirection` - `forecast.windDirection.deg` Wind direction, degrees (meteorological) - `forecast.windDirection.code` Code of the wind direction. Possible value is WSW, N, S etc. - `forecast.windDirection.name` Full name of the wind direction - `forecast.windSpeed` - `forecast.windSpeed.mps` Wind speed, meters per second - `forecast.windSpeed.unit` Wind speed units, m/s - `forecast.windSpeed.name`Type of wind - `forecast.windGust` - `forecast.windGust.gust` Wind gust, meters per second - `forecast.windGust.unit` Wind gust units, m/s - `forecast.temperature` - `forecast.temperature.unit` Unit of measurements. Possible value is Celsius, Kelvin, Fahrenhei. - `forecast.temperature.value` Temperature - `forecast.temperature.min` Minimum temperature at the moment of calculation. This is minimal forecasted temperature (within large megalopolises and urban areas), use this parameter optionally. Please find more info [here](#min) - `forecast.temperature.max` Maximum temperature at the moment of calculation. This is maximal forecasted temperature (within large megalopolises and urban areas), use this parameter optionally. Please find more info [here](#min) - `forecast.feels_like` - `forecast.feels_like.unit` Unit of measurements. Possible value is Celsius, Kelvin, Fahrenheit. Unit Default: Kelvin - `forecast.feels_like.value` Temperature. This temperature parameter accounts for the human perception of weather - `forecast.pressure` - `forecast.pressure.unit` hPa - `forecast.pressure.value` Pressure value - `forecast.humidity` - `forecast.humidity.unit` % - `forecast.humidity.value` Humidity value - `forecast.clouds` - `forecast.pressure.value` Name of the cloudiness - `forecast.pressure.all` Cloudiness - `forecast.pressure.unit` % - `forecast.visibility` - `forecast.visibility.value` Average visibility, metres. The maximum value of the visibility is 10km > We provide a broad variety of products such as [One Call API 4.0,](/api/one-call-4.md) [Solar Irradiance & Energy Prediction service,](/api.md#solar) [Road Risk API,](/api/road-risk.md) [Air Pollution API](/api/air-pollution.md) and solutions for advanced weather parameters like solar irradiance data, UVI, dew point, government weather alerts, etc. Please review our [product list](/api.md) page and find more info in the product documentation and [pricing](/price.md) pages. ### List of weather condition codes List of [weather condition codes](/weather-conditions.md) with icons (range of thunderstorm, drizzle, rain, snow, clouds, atmosphere etc.) ### Min/max temperature in current weather API and forecast API - In **5 day / 3 hour forecast API**, [Hourly forecast API](/api/hourly-forecast.md) and [Current weather API](/current.md) - **temp_min** and **temp_max** are optional parameters mean min / max temperature in the city at the current moment just for your reference. For large cities and megalopolises geographically expanded it might be applicable. In most cases both **temp_min** and **temp_max** parameters have the same volume as 'temp'. Please use **temp_min** and **temp_max** parameters in current weather API optionally. - In [16 Day forecast](/forecast16.md) - **min** and **max** mean maximum and minimum temperature in the day. ### Example of Current Weather API response ```text "main":{ "temp":306.15, //current temperature "pressure":1013, "humidity":44, "temp_min":30.15, //min current temperature in the city "temp_max":306.15 //max current temperature in the city }, ``` For comparison take a look at example of Daily Forecast Weather API response: ### Example of API response ```text "dt":1406080800, "temp":{ "day":297.77, //daily averaged temperature "min":293.52, //daily min temperature "max":297.77, //daily max temperature "night":293.52, //night temperature "eve":297.77, //evening temperature "morn":297.77}, //morning temperature ``` ## Bulk downloading We provide number of bulk files with current weather and forecasts. More information is on the [Bulk page](/bulk.md). > Bulk downloading is available not for all accounts. To get more information please refer to the [Price page.](/price.md) [http://bulk.openweathermap.org/sample/](http://bulk.openweathermap.org/sample/) ## Other features ### Geocoding API Requesting API calls by geographical coordinates is the most accurate way to specify any location. If you need to convert city names and zip-codes to geo coordinates and the other way around automatically, please use our [Geocoding API](/api/geocoding-api.md). ### Built-in geocoding > Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around. > > **Please note that API requests by city name, zip-codes and city id have been deprecated. Although they are still available for use, bug fixing and updates are no longer available for this functionality.** ### Built-in API request by city name You can search weather forecast for 5 days with data every 3 hours by city name. All weather data can be obtained in JSON and XML formats. ### API call ```text api.openweathermap.org/data/2.5/forecast?q={city name}&appid={API key} ``` ### API call ```text api.openweathermap.org/data/2.5/forecast?q={city name},{country code}&appid={API key} ``` ### API call ```text api.openweathermap.org/data/2.5/forecast?q={city name},{state code},{country code}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `q` | Yes | City name, state code and country code divided by comma, use ISO 3166 country codes. You can specify the parameter not only in English. In this case, the API response should be returned in the same language as the language of requested location name if the location is in our predefined list of more than 200,000 locations. | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `mode` | optional | Response format. JSON format is used by default. To get data in XML format use `mode=xml`. [Learn more](#format) | | `cnt` | optional | A number of timestamps, which will be returned in the API response. [Learn more](#limit) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | You can use the `lang` parameter to get the output in your language. [Learn more](#multi) | > There is a possibility to receive a central district of the city/town with its own parameters (geographic coordinates/id/name) in API response. Please see the example below. ### Built-in API request by city ID You can search weather forecast for 5 days with data every 3 hours by city ID. All weather data can be obtained in JSON and XML formats. List of city ID "city.list.json.gz" can be downloaded [here](http://bulk.openweathermap.org/sample/). We recommend to call API by city ID to get unambiguous result for your city. ### API call ```text api.openweathermap.org/data/2.5/forecast?id={city ID}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `id` | Yes | City ID. The list of city IDs 'city.list.json.gz' can be downloaded [here](http://bulk.openweathermap.org/sample/). | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `mode` | optional | Response format. JSON format is used by default. To get data in XML format use `mode=xml`. [Learn more](#format) | | `cnt` | optional | A number of timestamps, which will be returned in the API response. [Learn more](#limit) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | You can use the `lang` parameter to get the output in your language. [Learn more](multi) | ### Built-in API request by ZIP code Please note if country is not specified then the search works for USA as a default. ### API call ```text api.openweathermap.org/data/2.5/forecast?zip={zip code},{country code}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `zip` | Yes | Zip code | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `mode` | optional | Response format. JSON format is used by default. To get data in XML format use `mode=xml`. [Learn more](#format) | | `cnt` | optional | A number of timestamps, which will be returned in the API response. [Learn more](#limit) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | You can use the `lang` parameter to get the output in your language. [Learn more](multi) | ### Format Response format. JSON format is used by default. To get data in XML format use `mode=xml`. | Parameters | | | | --- | --- | --- | | `mode` | optional | Response format. JSON format is used by default. To get data in XML format use `mode=xml`. | JSON XML ### Limitation of result To limit number of timestamps in the API response please setup `cnt`. | Parameters | | | | --- | --- | --- | | `cnt` | optional | A number of timestamps, which will be returned in the API response. | ### Units of measurement `standard`, `metric`, and `imperial` units are available. | Parameters | | | | --- | --- | --- | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default | > List of all API parameters with units [openweathermap.org/weather-data](/weather-data.md) Standard Metric Imperial ### Multilingual support You can use the `lang` parameter to get the output in your language. Translation is applied to the `city name` and `description` fields. ### API call ```text http://api.openweathermap.org/data/2.5/forecast?id=524901&lang={lang} ``` | Parameters | | | | --- | --- | --- | | `lang` | optional | You can use the `lang` parameter to get the output in your language. | We support the following languages that you can use with the corresponded lang values: - `sq` Albanian - `af` Afrikaans - `ar` Arabic - `az` Azerbaijani - `eu` Basque - `be` Belarusian - `bg` Bulgarian - `ca` Catalan - `zh_cn` Chinese Simplified - `zh_tw` Chinese Traditional - `hr` Croatian - `cz` Czech - `da` Danish - `nl` Dutch - `en` English - `fi` Finnish - `fr` French - `gl` Galician - `de` German - `el` Greek - `he` Hebrew - `hi` Hindi - `hu` Hungarian - `is` Icelandic - `id` Indonesian - `it` Italian - `ja` Japanese - `kr` Korean - `ku` Kurmanji (Kurdish) - `la` Latvian - `lt` Lithuanian - `mk` Macedonian - `no` Norwegian - `fa` Persian (Farsi) - `pl` Polish - `pt` Portuguese - `pt_br` Português Brasil - `ro` Romanian - `ru` Russian - `sr` Serbian - `sk` Slovak - `sl` Slovenian - `sp, es` Spanish - `sv, se` Swedish - `th` Thai - `tr` Turkish - `ua, uk` Ukrainian - `vi` Vietnamese - `zu` Zulu ### Call back function for JavaScript code To use JavaScript code you can transfer `callback` functionName to JSONP callback. --- ## Geocoding API Geocoding API is a simple tool that we have developed to ease the search for locations while working with geographic names and coordinates. Supporting API calls by geographical coordinates is the most accurate way to specify any location, that is why this method is integrated in all OpenWeather APIs. However, this way is not always suitable for all users. Geocoding is the process of transformation of any location name into geographical coordinates, and the other way around (reverse geocoding). OpenWeather’s Geocoding API supports both the direct and reverse methods, working at the level of city names, areas and districts, countries and states: - [Direct geocoding](#direct) converts the specified name of a location or zip/post code into the exact geographical coordinates; - [Reverse geocoding](#reverse) converts the geographical coordinates into the names of the nearby locations. ## Direct geocoding Direct geocoding allows to get geographical coordinates (lat, lon) by using name of the location (city name or area name). If you use the `limit` parameter in the API call, you can cap how many locations with the same name will be seen in the API response (for instance, London in the UK and London in the US). ### Coordinates by location name ### How to make an API call ### API call ```text http://api.openweathermap.org/geo/1.0/direct?q={city name},{state code},{country code}&limit={limit}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `q` | Yes | City name, state code (only for the US) and country code divided by comma. Please use ISO 3166 country codes. | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `limit` | optional | Number of the locations in the API response (up to 5 results can be returned in the API response) | ### Example of API call ```text http://api.openweathermap.org/geo/1.0/direct?q=London&limit=5&appid={API key} ``` > Please note that the fields present will vary based on a country to which a location belongs as well as a specific location. - `name` Name of the found location - `local_names` - `local_names.[language code]` Name of the found location in different languages. The list of names can be different for different locations - `local_names.ascii` Internal field - `local_names.feature_name` Internal field - `lat` Geographical coordinates of the found location (latitude) - `lon` Geographical coordinates of the found location (longitude) - `country` Country of the found location - `state` (where available) State of the found location ### Coordinates by zip/post code ### How to make an API call ```text http://api.openweathermap.org/geo/1.0/zip?zip={zip code},{country code}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `zip code` | Yes | Zip/post code and country code divided by comma. Please use ISO 3166 country codes. | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### Example of API call ```text http://api.openweathermap.org/geo/1.0/zip?zip=E14,GB&appid={API key} ``` ### Example of API response ```json { "zip": "90210", "name": "Beverly Hills", "lat": 34.0901, "lon": -118.4065, "country": "US" } ``` ### Fields in API response - `zip` Specified zip/post code in the API request - `name` Name of the found area - `lat` Geographical coordinates of the centroid of found zip/post code (latitude) - `lon` Geographical coordinates of the centroid of found zip/post code (longitude) - `country` Country of the found zip/post code ## Reverse geocoding Reverse geocoding allows to get name of the location (city name or area name) by using geografical coordinates (lat, lon). The `limit` parameter in the API call allows you to cap how many location names you will see in the API response. ### API call ```text http://api.openweathermap.org/geo/1.0/reverse?lat={lat}&lon={lon}&limit={limit}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat, lon` | Yes | Geographical coordinates (latitude, longitude) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `limit` | optional | Number of the location names in the API response (several results can be returned in the API response) | ### Example of API call ```text http://api.openweathermap.org/geo/1.0/reverse?lat=51.5098&lon=-0.1180&limit=5&appid={API key} ``` > Please note that the fields present will vary based on a country to which a location belongs as well as a specific location. - `name` Name of the found location - `local_names` - `local_names.[language code]` Name of the found location in different languages. The list of names can be different for different locations. - `local_names.ascii` Internal field - `local_names.feature_name` Internal field - `lat` Geographical coordinates of the found location (latitude) - `lon` Geographical coordinates of the found location (longitude) - `country` Country of the found location - `state` (where available) State of the found location --- ## Global Precipitation Maps Get current and historical global precipitation weather maps via the easy-to-work API. ## Features of Global Precipitation Map 1. Current and historical weather maps The historical weather map for the previous 2 days with a 10 minutes-step. 2. Resolution less than 1 km 3. Weather map layers: Precipitation layer 4. Weather sources Global Precipitatoin Map is based on global weather models, satellites, radars and our OWM NWP-ML technology. 5. There is the [OpenWeather Interactive Weather Maps](/weathermap.md?basemap=map&cities=true&layer=radar&lat=56.9510&lon=24.1064&zoom=5) with Global Precipitation layer, which provide users with free access to visual data. ## URL format and parameters Use the following URL format and parameters to get weather maps. Please pay attention to the URL example. ### API call ```text https://maps.openweathermap.org/maps/2.0/radar/{z}/{x}/{y}?appid={API key}&tm={date} ``` | Parameters | | | | --- | --- | --- | | `{z}` | Yes | Number of zoom level. The minimum value is **3**, and the maximum value is **7**. You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `{x}` | Yes | Number of x tile coordinate. You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `{y}` | Yes | Number of y tile coordinate. You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `tm` | Yes | Date and time of (Unix time, UTC), e.g. 1600782000. To get historical data, please specify the date in the past in your API request. The date must be no earlier than 2 days ago from the current moment. To get current data, please specify the the nearest time in the past rounded up to 10 minutes | > Please pay attention to the poins bellow to avoid possible errors: > > - Please specify dates in all API requests. > - Please specify dates with 10 minutes steps. For example, 1600780200, 1600780800, 1600781400, etc. ### URL example ```text https://maps.openweathermap.org/maps/2.0/radar/6/13/24?&appid={API key}&tm=1600781400 ``` > You need to insert the generated URL into special plugins. > > For example, Leaflet, OpenLayers. You can also use any other apps that support the display of layers. [Learn more](#library). ## Example of Global Precipitation Map layer Please find below Global Precipitation Map layer example. ### URL example ```text https://maps.openweathermap.org/maps/2.0/radar/7/4/2?&appid={API key}&tm=1703171400 ``` ![precipitation current](/payload/api/media/file/precipitation_current.jpg) - [Preview weathermap](/weathermap.md?basemap=map&cities=false&layer=precipitation&lat=30&lon=-20&zoom=3) ## Libraries to connect weather layers **Open Layers** The following functions are available for the OpenLayers library: - Classes of weather layer and weather stations layer - Possibility to set your own style - Classes with clustered markers - Support of marker server clustering **Leaflet** The OpenWeatherMap javascript library is designed to work with the Leaflet mapping service. The current version of the library allows the following: - Embedding of layer with current weather in cities - Embedding of layer with weather stations - The library supports customer clustering Using OpenWeatherMap weather tiles with leaflet: [PDF](https://) --- ## Global Precipitation Maps History&Forecast Get current, forecast and historical global precipitation weather maps with a 10 minutes-step via the easy-to-work API. ## Features of Global Precipitation Map 1. This product includes two types of forecasts: 2. - Forecast for the next **6 hours** for the US territory - Forecast for the next **2 hours** for other global areas 3. Historical weather map for the previous 2 days 4. Update period: every 10 minutes 5. Resolution: less than 1 km 6. Global coverage 7. Weather map layers: Precipitation layer 8. Weather sources: Global Precipitatoin Map is based on global weather models, satellites, radars and our OWM NWP-ML technology. 9. There is the [OpenWeather Interactive Weather Maps](/weathermap.md?basemap=map&cities=true&layer=radar&lat=56.9510&lon=24.1064&zoom=5) with Global Precipitation layer, which provide users with free access to visual data. ## URL format and parameters Use the following URL format and parameters to get weather maps. Please pay attention to the URL example. ### API call ```text https://maps.openweathermap.org/maps/2.0/radar/forecast/{z}/{x}/{y}?appid={API key}&tm={date} ``` | Parameters | | | | --- | --- | --- | | `{z}` | Yes | Number of zoom level The minimum value is **3**, and the maximum value is **7**.You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `{x}` | Yes | Number of x tile coordinate. You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `{y}` | Yes | Number of y tile coordinate. You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `tm` | Yes | Date and time of (Unix time, UTC), e.g. 1600782000. To get historical or forecast data, please specify the date in your API request. To get current data, please specify the the nearest time in the past rounded up to 10 minutes | > Please pay attention to the points below to avoid possible errors: > > - Please specify dates in all API requests. > - Please specify dates with **10 minutes steps**. For example, 1600780200, 1600780800, 1600781400, etc. > - Please specify dates not earlier than 2 days from the current time and not later than 6 hours from the current time. ### URL example ```text https://maps.openweathermap.org/maps/2.0/radar/forecast/6/13/24?&appid={API key}&tm=1600781400 ``` > You need to insert the generated URL into special plugins. > > For example, Leaflet, OpenLayers. You can also use any other apps that support the display of layers. [Learn more](#library). ## Example of Global Precipitation Map layer Please find below Global Precipitation Map layer example. ### URL example to the timestamp in the past ```text https://maps.openweathermap.org/maps/2.0/radar/forecast/7/4/2?&appid={API key}&tm=1703235600 ``` ### URL example to the timestamp in the future ```text https://maps.openweathermap.org/maps/2.0/radar/forecast/7/4/2?&appid={API key}&tm=1703241000 ``` ![precipitation forecast](/payload/api/media/file/precipitation_forecast.jpg) - [Preview weathermap](/weathermap.md?basemap=map&cities=false&layer=precipitation&lat=30&lon=-20&zoom=3) ## Default palette ranges | Range (dBZ) | Colour | Hex | RGB | | --- | --- | --- | --- | | 0 to < 7.01 | ![0 to <7.01](/payload/api/media/file/color_%2300000000.png) | `#000000` | `0, 0, 0` | | 7.01 to < 9.83 | ![7.01 to <9.83](/payload/api/media/file/color_%2300B2FFFF.png) | `#00B2FF` | `0, 178, 255` | | 9.83 to < 12.17 | ![9.83 to <12.17](/payload/api/media/file/color_%2300A7FFFF.png) | `#00A7FF` | `0, 167, 255` | | 12.17 to < 15.91 | ![12.17 to <15.91](/payload/api/media/file/color_%2300FA96FF.png) | `#00FA96` | `0, 250, 150` | | 15.91 to < 20.02 | ![15.91 to <20.02](/payload/api/media/file/color_%2300FA64FF.png) | `#00FA64` | `0, 250, 100` | | 20.02 to < 21.96 | ![20.02 to <21.96](/payload/api/media/file/color_%2300E600FF.png) | `#00E600` | `0, 230, 0` | | 21.96 to < 23.98 | ![21.96 to <23.98](/payload/api/media/file/color_%2300D300FF.png) | `#00D300` | `0, 211, 0` | | 23.98 to < 26.01 | ![23.98 to <26.01](/payload/api/media/file/color_%2300BA00FF.png) | `#00BA00` | `0, 186, 0` | | 26.01 to < 28 | ![26.01 to <28](/payload/api/media/file/color_%2300A000FF.png) | `#00A000` | `0, 160, 0` | | 28 to < 29.99 | ![28 to <29.99](/payload/api/media/file/color_%23008C00FF.png) | `#008C00` | `0, 140, 0` | | 29.99 to < 31.01 | ![29.99 to <31.01](/payload/api/media/file/color_%23007800FF.png) | `#007800` | `0, 120, 0` | | 31.01 to < 32.01 | ![31.01 to <32.01](/payload/api/media/file/color_%23006400FF.png) | `#006400` | `0, 100, 0` | | 32.01 to < 33 | ![32.01 to <33](/payload/api/media/file/color_%23005A00FF.png) | `#005A00` | `0, 90, 0` | | 33 to < 34 | ![33 to <34](/payload/api/media/file/color_%23005000FF.png) | `#005000` | `0, 80, 0` | | 34 to < 35.01 | ![34 to <35.01](/payload/api/media/file/color_%23004600FF.png) | `#004600` | `0, 70, 0` | | 35.01 to < 36 | ![35.01 to <36](/payload/api/media/file/color_%23EFF800FF.png) | `#EFF800` | `239, 248, 0` | | 36 to < 37 | ![36 to <37](/payload/api/media/file/color_%23F3EB00FF.png) | `#F3EB00` | `243, 235, 0` | | 37 to < 39 | ![37 to <39](/payload/api/media/file/color_%23FADC00FF.png) | `#FADC00` | `250, 220, 0` | | 39 to < 40 | ![39 to <40](/payload/api/media/file/color_%23FFCD00FF.png) | `#FFCD00` | `255, 205, 0` | | 40 to < 41 | ![40 to <41](/payload/api/media/file/color_%23FF9600FF.png) | `#FF9600` | `255, 150, 0` | | 41 to < 42 | ![41 to <42](/payload/api/media/file/color_%23FF5B00FF.png) | `#FF5B00` | `255, 91, 0` | | 42 to < 45.09 | ![42 to <45.09](/payload/api/media/file/color_%23FF0000FF.png) | `#FF0000` | `255, 0, 0` | | 45.09 to < 47.91 | ![45.09 to <47.91](/payload/api/media/file/color_%23FF0064FF.png) | `#FF0064` | `255, 0, 100` | | 47.91 to < 53.01 | ![47.91 to <53.01](/payload/api/media/file/color_%23FF0092FF.png) | `#FF0092` | `255, 0, 146` | | 53.01 to < 59.83 | ![53.01 to <59.83](/payload/api/media/file/color_%23AA2BC3FF.png) | `#AA2BC3` | `170, 43, 195` | | 59.83 to < 70 | ![59.83 to <70](/payload/api/media/file/color_%237609A4FF.png) | `#7609A4` | `118, 9, 164` | | 70 and above | ![70 and above](/payload/api/media/file/color_%233D015EFF.png) | `#3D015E` | `61, 1, 94` | ## Libraries to connect weather layers **Open Layers** The following functions are available for the OpenLayers library: - Classes of weather layer and weather stations layer - Possibility to set your own style - Classes with clustered markers - Support of marker server clustering **Leaflet** The OpenWeatherMap javascript library is designed to work with the Leaflet mapping service. The current version of the library allows the following: - Embedding of layer with current weather in cities - Embedding of layer with weather stations - The library supports customer clustering Using OpenWeatherMap weather tiles with leaflet: [PDF](https://) --- ## Weather History API ### Product concept We provide hourly historical weather data for any location on the globe via Weather History API. Availability of hourly historical data depends on a type of your [subscription](/price.md#current). You can also download this data in JSON or CSV format - please read [History Bulk](/history-bulk.md) and [History Forecast Bulk](/api/history-forecast-bulk.md). ## Call hourly historical data ### How to make an API call ```text https://history.openweathermap.org/data/2.5/history/city?lat={lat}&lon={lon}&type=hour&start={start}&end={end}&appid={API key} ``` ### API call ```text https://history.openweathermap.org/data/2.5/history/city?lat={lat}&lon={lon}&type=hour&start={start}&cnt={cnt}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `lon` | Yes | Longitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `type` | Yes | Type of the call, keep this parameter in the API call as `hour` | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `start` | optional | Start date (unix time, UTC time zone), e.g. start=1369728000 | | `end` | optional | End date (unix time, UTC time zone), e.g. end=1369789200 | | `cnt` | optional | A number of timestamps in response (one per hour, can be used instead of the parameter `end`) | > Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around. > > Please note that [built-in geocoder](#geocoding) has been deprecated. Although it is still available for use, bug fixing and updates are no longer available for this functionality. ### Example of API call ```text https://history.openweathermap.org/data/2.5/history/city?lat=41.85&lon=-87.65&appid={API key} ``` > If you do not see some of the parameters in your API response it means that these weather phenomena are just not happened for the time of measurement for the city or location chosen. Only really measured or calculated data is displayed in API response. > > List of all API parameters with units [openweathermap.org/weather-data](/weather-data.md). ## JSON ### Fields in API Response - `message` Internal parameter - `cod` Internal parameter - `city_id` City ID. Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin) - `calctime` Internal parameter - `list` - `dt` Time of data calculation, unix, UTC - `main` - `main.temp` Temperature. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit. [Learn more](#data) - `main.feels_like` This temperature parameter accounts for the human perception of weather. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit. [Learn more](#data) - `main.pressure` Atmospheric pressure on the sea level, hPa - `main.humidity` Humidity, % - `main.temp_min` Minimum temperature within a large city or a megalopolis (optional parameter). Please find more [here](#min). Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit. [Learn more](#data) - `main.temp_max` Maximum temperature within a large city or a megalopolis (optional parameter). Please find more [here](#min). Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit. [Learn more](#data) - `main.sea_level` Atmospheric pressure on the sea level, hPa - `main.grnd_level` Atmospheric pressure on the ground level, hPa - `wind` - `wind.speed` Wind speed. Unit Default: meter/sec, Metric: meter/sec, Imperial: miles/hour. [Learn more](#data) - `wind.deg` Wind direction, degrees (meteorological) - `clouds` - `clouds.all` Cloudiness, % - `rain` - `rain.1h` Rain volume for the last 1 hour, mm. Please note that only mm as units of measurement are available for this parameter - `rain.3h` Rain volume for the last 3 hours, mm. Please note that only mm as units of measurement are available for this parameter - `snow` - `snow.1h` Snow volume for the last 1 hour, mm. Please note that only mm as units of measurement are available for this parameter - `snow.3h` Snow volume for the last 3 hours, mm. Please note that only mm as units of measurement are available for this parameter - `weather` (more info [Weather condition codes](/weather-conditions.md)) - `weather.id` Weather condition id - `weather.main` Group of weather parameters (Rain, Snow, Clouds etc.) - `weather.description` Weather condition within the group. Please find more [here](#list) - `weather.icon` Weather icon id > We provide a broad variety of products such as [One Call API 4.0,](/api/one-call-4.md) [Solar Irradiance & Energy Prediction service,](/api.md#solar) [Road Risk API,](/api/road-risk.md) [Air Pollution API](/api/air-pollution.md) and solutions for advanced weather parameters like solar irradiance data, UVI, dew point, government weather alerts, etc. Please review our [product list](/api.md) page and find more info in the product documentation and [pricing](/price.md) pages. ## List of weather condition codes List of [weather condition codes](/weather-conditions.md) with icons (range of thunderstorm, drizzle, rain, snow, clouds, atmosphere etc.) ## Min/max temperature in historical weather API and forecast API Please, do not confuse min/max parameters in hourly historical weather API and forecast API. In hourly historical weather API **temp_min** and **temp_max** are optional parameters mean min / max temperature in the city at the moment of calculation to show deviation from the average temperature just for your reference. For large cities and megalopolises geographically expanded it might be applicable. In most cases both **temp_min** and **temp_max** parameters have the same volume as 'temp'. Please, use **temp_min** and **temp_max** parameters optionally. ### Example of historical weather for cities API response ```text "main":{ "temp":306.15, // temperature at the moment of calculation "pressure":1013, "humidity":44, "temp_min":306.15, //min temperature in the city at the moment of calculation "temp_max":306.15 //max temperature in the city at the moment of calculation }, ``` For comparison look at example of daily forecast weather API response ### Example of daily forecast weather API response ```text "dt":1406080800, "temp":{ "day":297.77, //daily averaged temperature "min":293.52, //daily min temperature "max":297.77, //daily max temperature "night":293.52, //night temperature "eve":297.77, //evening temperature "morn":297.77, //morning temperature } ``` ## How to get History Bulk functionality We have recently announced the History Bulk functionality that allows to extract historical data for any location for **47+ years** in the past. For accessing this feature please click the next [link](https://home.openweathermap.org/history_bulks/new). The detailed documentation can be found [here.](/history-bulk.md) ## Other features ### Geocoding API Requesting API calls by geographical coordinates is the most accurate way to specify any location. If you need to convert city names and zip-codes to geo coordinates and the other way around automatically, please use our [Geocoding API](/api/geocoding-api.md). ### Built-in geocoding > Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around. > > **Please note that API requests by city name and city id have been deprecated. Although they are still available for use, bug fixing and updates are no longer available for this functionality.** ### Built-in API request by city name Call historical data by city name. ### API call ```text https://history.openweathermap.org/data/2.5/history/city?q={city name},{country code}&type=hour&start={start}&end={end}&appid={API key} ``` ### API call ```text https://history.openweathermap.org/data/2.5/history/city?q={city name},{country code}&type=hour&start={start}&cnt={cnt}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `q` | Yes | City name, state code and country code divided by comma, please refer to [ISO 3166](https://www.iso.org/obp/ui/) for the state codes or country codes. You can specify the parameter not only in English. In this case, the API response should be returned in the same language as the language of requested location name if the location is in our predefined list of more than 200,000 locations. | | `type` | Yes | type of the call, keep this parameter in the API call as `hour` | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `start` | optional | Start date (unix time, UTC time zone), e.g. start=1369728000 | | `end` | optional | End date (unix time, UTC time zone), e.g. end=1369789200 | | `cnt` | optional | A number of timestamps in response (one per hour, can be used instead of `end`) | ### Example of API call ```text https://history.openweathermap.org/data/2.5/history/city?q=London,UK&appid={API key} ``` > There is a possibility to receive a central district of the city/town with its own parameters (geographic coordinates/id/name) in API response. Please see the example below. ### Example of API response ```text https://history.openweathermap.org/data/2.5/history/city?q=Munchen,DE&appid={API key} ``` ### Built-in API request by city ID Call historical data by city ID. The list of city IDs can be downloaded [here](https://bulk.openweathermap.org/sample/history.city.list.json.gz). ### API calls ```text https://history.openweathermap.org/data/2.5/history/city?id={id}&type=hour&start={start}&end={end}&appid={API key} ``` ### API call ```text https://history.openweathermap.org/data/2.5/history/city?id={id}&type=hour&start={start}&cnt={cnt}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `id` | Yes | City ID. The list of city IDs 'city.list.json.gz' can be downloaded [here](https://bulk.openweathermap.org/sample/). | | `type` | Yes | Type of the call, keep this parameter in the API call as `hour` | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `start` | optional | Start date (unix time, UTC time zone), e.g. start=1369728000 | | `end` | optional | End date (unix time, UTC time zone), e.g. end=1369789200 | | `cnt` | optional | Amount of returned data (one per hour, can be used instead of `end`) | ### Example of API call ```text https://history.openweathermap.org/data/2.5/history/city?id=2885679&type=hour&appid={API key} ``` > **Only for Professional and Expert plans: The maximum historical data depth in one API response is one week.** > > If you specify a historical data depth more than one week in the request, you will receive a historical data only for first week from start date in one API response. > > If you want to get the historical data depth more than one week, then please use several queries. ### Units of measurement `standard`, `metric`, and `imperial` units are available. [List of all API parameters with available units](/weather-data.md). | Parameters | | | | --- | --- | --- | | `units` | optional | `standard`, `metric`, `imperial`. When you do not use the `units` parameter, format is `standard` by default. | Standard (by default): temperature in Kelvin, wind speed in meter/sec ### Examples of API calls: ```text https://history.openweathermap.org/data/2.5/history/city?lat=41.85&lon=-87&type=hour&start=1643720400&end=1643806800&appid={API key} ``` Metric: temperature in Celsius, wind speed in meter/sec ### Example of API response ```text https://history.openweathermap.org/data/2.5/history/city?lat=41.85&lon=-87&type=hour&start=1643720400&end=1643806800&units=metric&appid={API key} ``` Imperial: temperature in Fahrenheit, wind speed in miles/hour ### Example of API response ```text https://history.openweathermap.org/data/2.5/history/city?lat=41.85&lon=-87&type=hour&start=1643720400&end=1643806800&units=imperial&appid={API key} ``` --- ## History API Full archive This product provides the full archive of historical weather data by chosen location from 1 January 1979 till now. Weather data are available with 1-hour step. There are 3 simple steps to get the historical archive for your location: 1. Create a unique location via API call - [section 1](#addlocation). Once you create your location, its historical weather data start preparing automatically. 2. Check your location list to make sure that weather data for your new location has been prepared - [section 2](#getlist). 3. As soon as the weather data for your new location has been prepared, then you can start requesting historical data for it - [section 3](#data). ## 1. How to add a location to download list To activate loading your data you should add your location to the download list by making an API call according to the following rules. ### API call ```text http://history.openweathermap.org/data/3.0/history/locations/create?lat={lat}&lon={lon}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude. If you need a geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `lon` | Yes | Longitude. If you need a geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### Example of API call ```text http://history.openweathermap.org/data/3.0/history/locations/create?lat=51.8080&lon=-0.1257&appid={API key} ``` ```json { "id": "53506193580c9bda6c38a1c6a67f5599", //location id "lat": 52.808, "lon": -0.1257, "start": 283996800, "end": 1597104000, "created_at": "2020-08-11T15:51:23.377Z", "status": "calculating" }, ``` | Errors | | | --- | --- | | `422000` | An incorrect lat, lon or an already existing location was entered | > Please note: > > - When creating unique locations, coordinates are rounded to 4 decimal places. > - You cannot add the same location twice. > - When you add a new location, our system starts to prepare historical weather data. Due to the volume of this archive, preparing weather data archive by your location can be relatively time-consuming. It can take up to 30-40 min before data becomes available. > - To check the status of the newly added location, please see [section #2](/api/history-api-full-archive.md#getlist) below. > - Historical data will not be recalculated after the first calculation. ## 2. How to get a list of all added locations and status of new locations Before trying to get historical weather data by your created location (read the [section 1](#addlocation)), please make sure that weather data has been successfully downloaded for your location. To check the statuses of your locations please use this section. ### API call ```text http://history.openweathermap.org/data/3.0/history/locations?appid={API key} ``` | Location statuses | | | --- | --- | | `calculating` | Data for the new location is processing. Please wait. | | `done` | Calculation for the new location has been successful. You can request historical weather data. Please read [section 3](#data) of the current document to learn more. | | `failed` | Internal error. Please contact our [support team](mailto:info@openweathermap.org). | ## 3. How to get historical data for added location ### API call ```text http://history.openweathermap.org/data/3.0/history/result?id={location_id}&start={start_date}&end={end_date}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `location_id` | Yes | Location ID, which you received when adding your unique location (please see [section 1](#addlocation) of this documentation) | | `start_date` | Yes | Any date from 1 January 1979 till 23:59 of the previous day, Unix, UTC | | `end_date` | Yes | Any date from 1 January 1979 till 23:59 of the previous day, Unix, UTC | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | > To avoid receiving errors in the API response, please specify a time period of requested historical data less than 1 year in one API call. ### Example of API response ```json { "id": "7466e40670b7eccdd6c27cf9a78ea286", "cnt": 278, "list": [ { "dt": 283996800, "main": { "temp": 268.6, "feels_like": 261.48, "pressure": 1010, "humidity": 85, "temp_min": 268.15, "temp_max": 269.121 }, "wind": { "speed": 6.2, "deg": 350 }, "clouds": { "all": 20 }, "weather": [ { "id": 801, "main": "Clouds", "description": "few clouds", "icon": "02n" } ] }, … ] } ``` | Errors | | | --- | --- | | `404000` | You have specified an ID of non-existent location | | `404001` | Calculation process has not yet ended, please see paragraph #2 of the current document) | ## Historical data in the API response > If you do not see some of the parameters in your API response it means that these weather phenomena are just not happened for the time of measurement for the city or location chosen. Only really measured or calculated data is displayed in API response. - `id` Location ID - `cnt` Technical field - `list` - `dt` Time of data calculation, unix, UTC - `main` - `main.temp` Temperature, Kelvins - `main.feels_like` Temperature, Kelvins. This temperature parameter accounts for the human perception of weather - `main.pressure` Atmospheric pressure, hPa - `main.humidity` Humidity, % - `main.temp_min` Minimum temperature within a large city or a megalopolis (optional parameter), Kelvin - `main.temp_max` Maximum temperature within a large city or a megalopolis (optional parameter), Kelvins - `wind` - `wind.speed` Wind speed. Unit: meter/sec. - `wind.deg` Wind direction, degrees (meteorological) - `clouds` - `clouds.all` Cloudiness, % - `rain` - `rain.1h` Rain volume for the last 1 hour - `snow` - `snow.1h` Snow volume for the last 1 hour - `weather` ([Full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2)) - `weather.id` Weather condition id - `weather.main` Group of weather parameters (Rain, Snow, Clouds etc.) - `weather.description` Weather condition within the group. Please find more [here](#list) - `weather.icon` Weather icon id > We provide a broad variety of products such as [One Call API 4.0,](/api/one-call-4.md) [Solar Irradiance & Energy Prediction service,](/api.md#solar) [Road Risk API,](/api/road-risk.md) [Air Pollution API](/api/air-pollution.md) and solutions for advanced weather parameters like solar irradiance data, UVI, dew point, government weather alerts, etc. Please review our [product list](/api.md) page and find more info in the product documentation and [pricing](/price.md) pages. ## List of weather condition codes List of [weather condition codes](/weather-conditions.md) with icons (range of thunderstorm, drizzle, rain, snow, clouds, atmosphere etc.) --- ## History API for Timestamp ### Product concept This product provides historical weather data for any timestamp from 1st January 1979 till now. Data are available for any coordinate on the globe. Specify any coordinates and points in time up to 47+ years back, and get historical weather data by all necessary weather [parameters](#fields). ## How to request historical data Call historical data by geographic coordinates. ### API call ```text https://history.openweathermap.org/data/3.0/history/timemachine?lat={lat}&lon={lon}&dt={dt}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude. If you need a geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md). | | `lon` | Yes | Longitude. If you need a geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md). | | `dt` | Yes | Timestamp (unix time, UTC time zone), e.g. dt=1369728000 Data available from 1st January 1979 till now | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### Example of API call ```text https://history.openweathermap.org/data/3.0/history/timemachine?lat=51.51&lon=-0.13&dt=606348800&appid={API key} ``` ## History API response > If you do not see some of the parameters in your API response it means that these weather phenomena are just not happened for the time of measurement for the city or location chosen. Only really measured or calculated data is displayed in API response. ### Example of API response ```json { "coord": { "lon": -0.13, "lat": 51.51 }, "sys": { "type": 1, "id": 300001635, "message": 0 }, "weather": [ { "id": 300, "main": "Drizzle", "description": "light intensity drizzle", "icon": "09n" } ], "base": "stations", "visibility": 10000, "main": { "temp": 282.91, "feels_like": 277.13, "pressure": 1007, "humidity": 82, "temp_min": 281.648, "temp_max": 283.55 }, "wind": { "speed": 7.2, "deg": 190 }, "clouds": { "all": 90 }, "rain": { "1h": 0.28 }, "dt": 606348800 } ``` ### Fields in API response - `coord` Internal parameter - `sys` - `type` Internal field - `id` Internal field - `message` Internal field - `weather` ([Full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2)) - `weather.id` Weather condition id - `weather.main` Group of weather parameters (Rain, Snow, Clouds etc.) - `weather.description` Weather condition within the group - `weather.icon` Weather icon id - `base` Internal field - `visibility` (where available) Average visibility, metres. The maximum value of the visibility is 10km - `main` - `main.temp` Temperature, Kelvins - `main.feels_like` Temperature, Kelvins. This temperature parameter accounts for the human perception of weather - `main.pressure` Atmospheric pressure on the sea level, hPa - `main.humidity` Humidity, % - `main.temp_min` Minimum temperature within a large city or a megalopolis (optional parameter), Kelvin - `main.temp_max` Maximum temperature within a large city or a megalopolis (optional parameter), Kelvins - `wind` - `wind.speed` Wind speed. Unit: meter/sec. - `wind.deg` Wind direction, degrees (meteorological) - `clouds` - `clouds.all` Cloudiness, % - `rain` - `rain.1h` Rain volume for the last 1 hour - `snow` - `snow.1h` Snow volume for the last 1 hour - `dt` Time of data calculation, unix, UTC > We provide a broad variety of products such as [One Call API 4.0,](/api/one-call-4.md) [Solar Irradiance & Energy Prediction service,](/api.md#solar) [Road Risk API,](/api/road-risk.md) [Air Pollution API](/api/air-pollution.md) and solutions for advanced weather parameters like solar irradiance data, UVI, dew point, government weather alerts, etc. Please review our [product list](/api.md) page and find more info in the product documentation and [pricing](/price.md) pages. ### List of weather condition codes List of [weather condition codes](/weather-conditions.md) with icons (range of thunderstorm, drizzle, rain, snow, clouds, atmosphere etc.) --- ## History Bulk This product enables you to extract hourly historical weather data for over **47+ years deep** for any chosen location or coordinate. It includes 15 weather [parameters](/history-bulk.md#parameter). You can find more info on how to access the historical data on our [pricing page](/price.md#history). - [Buy History Bulk](https://home.openweathermap.org/history_bulks/new) ## Features of History Bulk 1. Historical weather data available from 1st January 1979 with 1-hour step. 2. The weather data archive that includes 15 weather parameters such as temperature, feels like, precipitation, wind and [many more](/history-bulk.md#parameter). You can also select which weather parameters you want to get. 3. You can set up your location in 4 different ways: 4. - Choose a location on the map - Input a location name - Input coordinates - Import a list of coordinates via CSV file 5. The measurement units and the output file format (CSV or JSON) can be configured in accordance to your preferences. 6. You can choose to obtain the data for multiple locations in one file or in an archive with separate files for each location. - [Buy History Bulk](https://home.openweathermap.org/history_bulks/new) The examples of data can be found in the ["Sample data"](/history-bulk.md#examples) section. > Please [contact us](mailto:info@openweathermap.org) when requesting data for a large number of locations. We’ll be happy to prepare and export the data for you. ## How to get historical weather data To request History Bulk for your locations, please follow these steps: 1. Go to the [OpenWeatherMap Marketplace](https://home.openweathermap.org/marketplace) and choose["History Bulk"](https://home.openweathermap.org/history_bulks/new) product. 2. Select locations. There are 4 ways to set your locations: 3. - **Click on the map.** Click on the map and the pin will be set on the chosen location. Click on the "Add location" to add this location into your order or click on another place on the map. - **Input a location name.** Click on the search line, input location name and choose it from the dropdown list. The chosen location will be displayed on the map, click on the "Add location" tab to add this location into your order. - **Input coordinates.** Click on the search line, choose "By coordinate" option, enter latitude and longitude to the form and push the "Enter" button on your keyboard. The chosen location will be displayed on the map, click on the "Add location" tab to add this location into your order. - **Import a list of coordinates via CSV file.** Click on the search line, choose "Import" option and follow the detail instruction on the form to download your CSV file with a list of coordinations. 4. Set the time period for the uploaded weather archive. 5. Configure list of weather parameters, measurement units and the format of the downloadable output file per your preferences. 6. Click on the "Place order" button and check your order details. 7. To complete the checkout process, please click on the "Checkout" button and proceed to payment. - [Buy History Bulk](https://home.openweathermap.org/history_bulks/new) After the successful payment you will be able to find your order in two ways: 1. You will receive a letter to your email with the link to download your current order. 2. All purchases can be also found in your personal account, in the ["Order"](https://home.openweathermap.org/history_bulks) section. ![history bulk](/payload/api/media/file/history_bulk.jpg) > Please see the following tips if you have any troubles to open weather archives of your orders: > > - If you are using the Windows operating system, please use 7zip or WinRAR to unpack the archive. > - In case you are using a Linux family operating system, the archive should be opened by standard means. ## Sample data There are two formats of files History Bulk can be provided in. Please find the examples below: [JSON](https://) [CSV](https://) ## Weather fields in History Bulk > If you do not see some of the parameters in your bulk, it means that these weather phenomena just have not happened in the chosen time period at the chosen location. Only really measured or calculated data is displayed in your bulk. ### Parameters - `city_name` City name - `lat` Geographical coordinates of the location (latitude) - `lon` Geographical coordinates of the location (longitude) - `main` - - `main.temp` Temperature - `main.temp_min` Minimum temperature at the moment. This is deviation from temperature that is possible for large cities and megalopolises geographically expanded (use these parameter optionally). - `main.temp_max` Maximum temperature at the moment. This is deviation from temperature that is possible for large cities and megalopolises geographically expanded (use these parameter optionally). - `main.feels_like` This temperature parameter accounts for the human perception of weather - `main.pressure` Atmospheric pressure (on the sea level), hPa - `main.humidity` Humidity, % - `main.dew_point` Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form. Units – default: kelvin - `wind` - - `wind.speed` Wind speed. Units – default: meter/sec - `wind.deg` Wind direction, degrees (meteorological) - `wind.gust` Wind gust. Units – default: meter/sec - `clouds` - - `clouds.all` Cloudiness, % - `rain` - - `rain.1h` Rain volume for the last hour, mm - `rain.3h` Rain volume for the last 3 hours, mm - `snow` - - `snow.1h` Snow volume for the last hour, mm (in liquid state) - `snow.3h` Snow volume for the last 3 hours, mm (in liquid state) - `weather` (more info [Weather condition codes](/weather-conditions.md)) - - `weather.id` Weather condition id - `weather.main` Group of weather parameters (Rain, Snow, Extreme etc.) - `weather.description` Weather condition within the group. Please find more [here](/history-bulk.md#list) - `weather.icon` Weather [icon id](/history-bulk.md#list) - `visibility` Average visibility, metres. The maximum value of the visibility is 10km - `dt` Time of data calculation, unix, UTC - `dt_iso`Date and time in UTC format - `timezone` Shift in seconds from UTC ## Example ### JSON Example ```json [{ "city_name":"Custom location", "lat":51.485927, "lon":0.24995, "main":{ "temp":277.72, "temp_min":275.632, "temp_max":279.15, "feels_like":273.99, "pressure":1029, "humidity":75, "dew_point" : 280.33 }, "wind":{ "speed":2.6, "deg":10, "gust": 5.8 }, "rain":{ "3h":1 }, "clouds":{ "all":75 }, "weather":[{ "id":500, "main":"Rain", "description":"light rain", "icon":"10n" }], "visibility":10000, "dt":1585612800, "dt_iso":"2020-03-31 00:00:00 +0000 UTC", "timezone":3600 }, ``` > We provide a broad variety of products such as [One Call API 4.0](/api/one-call-4.md), [Solar Irradiance & Energy Prediction service,](/products/solar-energy-prediction.md) [Road Risk API,](/api/road-risk.md) [Road Risk API,](/api/road-risk.md) [Air Pollution API](/api/air-pollution.md). Please review our [product list](/api.md) page and find more info in the product documentation and [pricing](/price.md) pages. ## List of weather condition codes List of [weather condition codes](/weather-conditions.md) with icons (range of thunderstorm, drizzle, rain, snow, clouds, atmosphere etc.) --- ## Historical Weather Data by State These archives contain historical weather data for all ZIP codes in the US. ZIP codes in the weather data are grouped by states. ## About This product allows you to download archives of historical weather data by state for all ZIP codes in the USA. Each archive includes weather data: - for all ZIP codes within the state that you have chosen - for one chosen year (Currently available for 2018 and 2019. Other years are coming soon.) The downloaded weather archive will contain a set of files. Each of these files contains historical data for one ZIP code. Weather data archive includes 15 weather parameters, such as temperature, precipitation, wind and many more. Data is provided with **hourly step** in CSV format. Price varies by state, since each state has a different number of ZIP codes. Price per state can be found [here](#zip). - [Buy historical data](https://home.openweathermap.org/zip_code_data/new) You can find more about ways to access our historical data on our [price page](/price.md#history). ## How to get historical weather data by state To request historical data, please follow these steps: 1. Go to the [OpenWeatherMap Marketplace](https://home.openweathermap.org/marketplace) and choose the ["Historical Weather Data by State for all ZIP codes, USA"](https://home.openweathermap.org/zip_code_data/new) product. 2. Select the state you are interested in. 3. Select the year from the archive. 4. Click on the "Place order" button and check your order details. 5. To complete the checkout process, please click on the "Checkout" button and proceed to payment. - [Buy historical data](https://home.openweathermap.org/zip_code_data/new) After the successful payment you will be able to find your order in two ways: 1. You will also receive an email with the link to download your current order. 2. All purchases can be found in your personal account, in the ["Order"](https://home.openweathermap.org/marketplace/my_orders) section. ![How to get historical weather data by state instruction](/payload/api/media/file/zipcodemarketplace.png) ## Weather parameters > If you do not see some of the parameters in downloaded archive, it means that these weather phenomena just have not happened in the chosen time period at the chosen location. Only really measured or calculated data is displayed in data archive. - `dt` Time of data calculation, unix, UTC - `dt_iso`Date and time in UTC format - `timezone` Shift in seconds from UTC - `city_id` ZIP code - `city_name` City name - `lat` Geographical coordinates of the location (latitude) - `lon` Geographical coordinates of the location (longitude) - `temp` Temperature, Kelvin - `feels_like` This temperature parameter accounts for the human perception of weather, Kelvin - `temp_min` Minimum temperature at the moment. This is deviation from temperature that is possible for large cities and megalopolises geographically expanded (use these parameter optionally), Kelvin - `temp_max` Maximum temperature at the moment. This is deviation from temperature that is possible for large cities and megalopolises geographically expanded (use these parameter optionally), Kelvin - `pressure` Atmospheric pressure (on the sea level), hPa - `sea_level` Sea level pressure, hPa - `grnd_level` Ground level pressure, hPa - `humidity` Humidity, % - `wind_speed` Wind speed, meter/sec - `wind_deg` Wind direction, degrees (meteorological) - `rain_1h` Rain volume for the last hour, mm - `rain_3h` Rain volume for the last 3 hours, mm - `snow_1h` Snow volume for the last hour, mm (in liquid state) - `snow_3h` Snow volume for the last 3 hours, mm (in liquid state) - `clouds_all` Cloudiness, % - `weather_id` Weather condition id (more info [Weather condition codes](/weather-conditions.md#Weather-Condition-Codes-2)) - `weather_main` Group of weather parameters (Rain, Snow, Extreme etc.) - `weather_description` Weather condition within the group. Please find more [here](#list) - `weather_icon` Weather icon id (more info [Weather icon](/weather-conditions.md#Icon-list)) ### List of states, ZIP codes and price ### List of states, ZIP codes and price | State name | Number of ZIP codes | Price | | --- | --- | --- | | Alabama | 811 | 1,000 USD | | Alaska | 273 | 400 USD | | Arizona | 528 | 700 USD | | Arkansas | 705 | 1,000 USD | | California | 2591 | 1,500 USD | | Colorado | 645 | 700 USD | | Connecticut | 429 | 700 USD | | Delaware | 96 | 200 USD | | District of Columbia | 277 | 400 USD | | Florida | 1472 | 1,300 USD | | Georgia | 952 | 1,000 USD | | Hawai`i | 137 | 400 USD | | Idaho | 320 | 400 USD | | Illinois | 1575 | 1,300 USD | | Indiana | 967 | 1,000 USD | | Iowa | 1055 | 1,300 USD | | Kansas | 747 | 1,000 USD | | Kentucky | 946 | 1,000 USD | | Louisiana | 719 | 1,000 USD | | Maine | 485 | 700 USD | | Maryland | 605 | 700 USD | | Massachusetts | 684 | 700 USD | | Michigan | 1159 | 1,300 USD | | Minnesota | 991 | 1,000 USD | | Mississippi | 531 | 700 USD | | Missouri | 1156 | 1,300 USD | | Montana | 404 | 700 USD | | Nebraska | 620 | 700 USD | | Nevada | 253 | 400 USD | | New Hampshire | 281 | 400 USD | | New Jersey | 723 | 1,000 USD | | New Mexico | 427 | 700 USD | | New York | 2153 | 1,500 USD | | North Carolina | 1081 | 1,300 USD | | North Dakota | 407 | 700 USD | | Ohio | 1415 | 1,300 USD | | Oklahoma | 764 | 1,000 USD | | Oregon | 478 | 700 USD | | Pennsylvania | 2176 | 1,500 USD | | Rhode Island | 90 | 200 USD | | South Carolina | 534 | 700 USD | | South Dakota | 385 | 400 USD | | Tennessee | 785 | 1,000 USD | | Texas | 2598 | 1,500 USD | | Utah | 346 | 400 USD | | Vermont | 308 | 400 USD | | Virginia | 1214 | 1,300 USD | | Washington | 716 | 1,000 USD | | West Virginia | 851 | 1,000 USD | | Wisconsin | 896 | 1,000 USD | | Wyoming | 195 | 400 USD | ### Example ![zipcode example](/payload/api/media/file/zipcodeexample.jpg) ### List of the weather condition codes List of the [weather condition codes](/weather-conditions.md) with icons (range of thunderstorm, drizzle, rain, snow, clouds, atmosphere etc.) can be found [here](/weather-conditions.md). --- ## History Forecast Bulk This service allows to extract historical forecast weather data from October 7, 2017 for any location on the globe. We provide historical 16-day forecasts with 1-hour step, please find detailed description in the ["Product structure"](#structure) and ["Fields in History Forecast Bulk"](#parameter) sections. ## About History Forecast Bulk History Forecast Bulk provides an archive of previous forecasts starting from October 7, 2017. By using this service, you can receive data on previously made 16-day forecasts for any coordinates on the globe. There are two formats this can be provided in: CSV and JSON. The examples of data can be found in the ["Sample data and examples"](#sample_and_response) section. Please [contact us](mailto:info@openweathermap.org) when requesting data for a large number of locations. We’ll prepare and export the data for you. - [Buy History Forecast Bulk](https://home.openweathermap.org/history_forecast_bulks/new) ## Product structure Historical forecast data is available from 7 October 2017. A 16-day forecast is a set of values for weather parameters for each of the 16 days ahead. There are 4 model recalculation cycles available for each day. Each time when recalculation happens, the new forecast is generated (it updates values of weather parameters in the forecast). It means that for each day, starting from 7 October 2017, you will have four 16-day forecasts. Forecasts are updated at these times: 00:00 UTC, 06:00 UTC, 12:00 UTC, 18:00 UTC. To learn what weather data are included, please click [here](#parameter). A 16-day forecast is a set of values for weather parameters that are available in 1-hour steps for 16 days ahead. Thus, each day will have the following structure: ### Example of API response ```text 00:00 UTC {forecast weather data for 1st day - 16th day} 06:00 UTC {forecast weather data for 1st day - 16th day} 12:00 UTC {forecast weather data for 1st day - 16th day} 18:00 UTC {forecast weather data for 1st day - 16th day} ``` Please be aware that older historical forecasts will have different time steps: > **{1st day - 10th day with 1-hour steps, 11th day - 16th day with 12-hour steps}** > > On 15th of June 2019 we have upgraded the service and forecast step became 1-hour for the whole period of the forecast: > > **{1st day - 16th day with 1-hour steps}** History Forecast Bulk are available in CSV and JSON. ## How to get History Forecast Bulk To request History Forecast Bulk for your locations, please follow these steps: 1. Go to the [OpenWeatherMap Marketplace](https://home.openweathermap.org/marketplace) and choose ["New History Forecast Bulk"](https://home.openweathermap.org/history_forecast_bulks/new) product. 2. Select locations. There are 4 ways to set your locations: 3. - **Click on the map.** Click on the map and the pin will be set on the chosen location. Click on the "Add location" to add this location into your order or click on another place on the map. - **Input location name.** Click on the search line, input location name and choose it from the dropdown list. The chosen location will be displayed on the map, click on the "Add location" tab to add this location into your order. - **Input coordinates.** Click on the search line, choose "By coordinate" option, enter latitude and longitude to the form and push the "Enter" button on your keyboard. The chosen location will be displayed on the map, click on the "Add location" tab to add this location into your order. - **Import coordinates via CSV file.** Click on the search line, choose "Import" option and follow the detail instruction on the form to download your CSV file with a list of coordinations. 4. Weather parameters, measurement units and the format of the downloadable output file can be also configurable per your preferences. 5. Click on the "Confirm order" button and check your oreder details. 6. To complete the checkout process, please click on the "Checkout" button and proceed to payment. - [Buy History Forecast Bulk](https://home.openweathermap.org/history_forecast_bulks/new) After the successful payment you will be able to find your order in two ways: 1. You will also receive a letter to your email with the link to download your current order. 2. All purchases can be found in your personal account, in the ["Order"](https://home.openweathermap.org/history_bulks) section. ![History forecast bulk](/payload/api/media/file/History_forecast_bulk.jpg) ## Fields in History Forecast Bulk ### JSON format - `lat`Latitude of the location, decimal (−90; 90) - `lon`lon Longitude of the location, decimal (-180; 180) - `forecast`Forecast related information - `forecast_dt`Forecast calculation time in unix timestamp - `list` - `dt`Time for which the corresponding forecast part was calculated in unix timestamp - `main` - `temp`Temperature, Celsius - `pressure`Atmospheric pressure (on the sea level), hPa - `humidity`Humidity, % - `dew_point`Temperature of the dew point, Celsius - `grnd_pressure`Atmospheric pressure (on the surface), hPa - `wind` - `speed`Wind speed, metre/sec - `deg`Wind direction, degrees (meteorological) - `clouds` - `all`Cloudiness, % - `precipitation` - `hours`number of hours for which precipitation values are calculated - `rain`Rain, mm - `snow`Snow water equivalent, mm - `rate`Intensity, mm/s - `convective`Convective precipitation, mm - `ice`Ice pellets, mm - `fr_rain`Freezing rain, mm - `snow_depth`Depth of snow, m - `probability`Probability of precipitation, % - `accumulated`Accumulated volume of precipitation, mm ### CSV format - `forecast dt unixtime` Forecast calculation time in unix timestamp - `forecast dt iso` Forecast calculation time in ISO format - `slice dt unixtime` Time for which the corresponding forecast part was calculated in unix timestamp - `slice dt iso` Time for which the corresponding forecast part was calculated in ISO format - `lat` Latitude of the location, decimal (−90; 90) - `lon` Longitude of the location, decimal (-180; 180) - `temperature` Temperature, Celsius - `dew_point` Temperature of the dew point, Celsius - `pressure` Atmospheric pressure (on the sea level), hPa - `ground_pressure` Atmospheric pressure (on the surface), hPa - `humidity` Humidity, % - `clouds` Cloudiness, % - `wind_speed` Wind speed, metre/sec - `wind_deg` Wind direction, degrees (meteorological) - `rain` Rain, mm - `snow` Snow water equivalent, mm - `ice` Ice pellets, mm - `fr_rain` Freezing rain volume, mm - `convective` Convective precipitation, mm - `snow_depth` Depth of snow, m - `accumulated` Accumulated volume of precipitation, mm - `hours` Number of hours for which precipitation values are calculated - `rate` Precipitation intensity, mm/s - `probability` Probability of precipitation, % ## Sample data and examples Here you can find and download examples of History Forecast bulk files in [JSON](#json_example) and [CSV](#csv_example) formats. In this section you can find and download example of History Forecast bulk files in JSON format. You can download sample of files History Forecast bulk in JSON format using link below: [JSON](https://) Please find below an example of data in JSON format for one measurement. ### CSV sample data and example In this section you can find and download example of History Forecast bulk files in CSV format. You can download sample of files History Forecast bulk in CSV format using link below: [CSV](https://) Please find below an example of data in CSV format in tabular format. ![Table view History bulk CSV](/payload/api/media/file/Table_view_History_bulk_CSV.jpg) --- ## Hourly forecast ### Product concept Hourly forecast for 4 days (96 timestamps). Weather data is available in JSON and XML formats. ## Call hourly forecast data ### How to make an API call You can search weather forecast for 4 days with data every hour by geographic coordinates. All weather data can be obtained in JSON and XML formats. ### API call ```text https://pro.openweathermap.org/data/2.5/forecast/hourly?lat={lat}&lon={lon}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `lon` | Yes | Longitude. If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `mode` | optional | Data format. Possible values are `json` and `xml`. If the `mode` parameter is empty the format is JSON by default. [Learn more](#format) | | `cnt` | optional | A number of timestamps in response. [Learn more](#limit) | | `lang` | optional | Language code. [Learn more](#multi) | > Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around. > > Please note that [built-in geocoder](#geocoding) has been deprecated. Although it is still available for use, bug fixing and updates are no longer available for this functionality. ### API call example ```text https://pro.openweathermap.org/data/2.5/forecast/hourly?lat=44.34&lon=10.99&appid={API key} ``` ## API response > If you do not see some of the parameters in your API response it means that these weather phenomena are just not happened for the time of measurement for the city or location chosen. **Only really measured or calculated data is displayed in API response.** ### JSON format API response fields - `cod` Internal parameter - `message` Internal parameter - `cnt` Number of timestamps returned by this API call - - `list.dt ` Time of data forecasted, Unix, UTC - - `list.main.temp` Temperature. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.main.feels_like` This temperature parameter accounts for the human perception of weather. Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.main.temp_min` Minimum temperature at the moment of calculation. This is minimal forecasted temperature (within large megalopolises and urban areas), use this parameter optionally. Please find more info [here.](#min) Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.main.temp_max` Maximum temperature at the moment of calculation. This is maximal forecasted temperature (within large megalopolises and urban areas), use these parameter optionally. Please find more info [here.](#min) Unit Default: Kelvin, Metric: Celsius, Imperial: Fahrenheit - `list.main.pressure` Atmospheric pressure on the sea level by default, hPa - `list.main.sea_level` Atmospheric pressure on the sea level, hPa - `list.main.grnd_level` Atmospheric pressure on the ground level, hPa - `list.main.humidity` Humidity, % - `list.main.temp_kf` Internal parameter - `list.main.dew_point` Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit - `list.weather` - `list.weather.id` Weather condition id - `list.weather.main` Group of weather parameters (Rain, Snow, Clouds etc.) - `list.weather.description` Weather condition within the group. Please find more [here.](#list) You can get the output in your language. [Learn more](#multi) - `list.weather.icon` Weather icon id - `list.clouds` - `list.clouds.all` Cloudiness, % - `list.wind` - `list.wind.speed` Wind speed. Unit Default: meter/sec, Metric: meter/sec, Imperial: miles/hour - `list.wind.deg` Wind direction, degrees (meteorological) - `list.wind.gust` Wind gust. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour - `list.rain` - `list.rain.1h` Rain volume for last hour, mm. Please note that only mm as units of measurement are available for this parameter - `list.snow` - `list.snow.1h`Snow volume for last hour, mm. Please note that only mm as units of measurement are available for this parameter - `list.visibility` Average visibility, metres. The maximum value of the visibility is 10km - `list.pop` Probability of precipitation. The values of the parameter vary between 0 and 1, where 0 is equal to 0%, 1 is equal to 100% - `list.sys` - `list.sys.pod` Part of the day (n - night, d - day) - `list.dt_txt` Time of data forecasted, ISO, UTC - `city` - `city.id` City ID. Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin) - `city.name` City name. Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin) - `city.coord` - `city.coord.lat ` Geo location, latitude - `city.coord.lon` Geo location, longitude - `country`Country code (GB, JP etc.). Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin) - `timezone` Shift in seconds from UTC - `sunrise` Sunrise time, Unix, UTC - `sunset` Sunset time, Unix, UTC ### XML format API response fields - `location` - `location.name ` City name. Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin) - `location.type` Internal parameter - `location.country` Country code (GB, JP etc.). Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin) - `location.timezone` Shift in seconds from UTC - `location.location` - `location.location.altitude` Geo location, altitude above the sea level - `location.location.latitude` Geo location, latitude - `location.location.longitude` Geo location, longitude - `location.location.geobase` Internal parameter - `location.location.geobaseid` Internal parameter - `credit` Internal parameter - `meta` - `meta.lastupdate` Internal parameter - `meta.calctime` Speed of data calculation - `meta.nextupdate` Internal parameter - `sun` - `sun.rise` Sunrise time - `sun.set` Sunset time - `forecast` - `forecast.time` - `forecast.time.from` Beginning of the period of data forecasted - `forecast.time.to` End of the period of data forecasted - `forecast.symbol` - `forecast.symbol.number` Weather condition id - `forecast.symbol.name` Weather condition - `forecast.symbol.var` Weather icon id - `forecast.precipitation` - `forecast.precipitation.value` Precipitation volume for the last hour, mm. Please note that only mm as units of measurement are available for this parameter - `forecast.precipitation.unit` Period of measurements. Possible value is 1 hour - `forecast.precipitation.type` Type of precipitation. Possible value is rain, snow - `forecast.precipitation.probability` Probability of precipitation. The values of the parameter vary between 0 and 1, where 0 is equal to 0%, 1 is equal to 100% - `forecast.windDirection` - `forecast.windDirection.deg` Wind direction, degrees (meteorological) - `forecast.windDirection.code` Code of the wind direction. Possible value is WSW, N, S etc. - `forecast.windDirection.name` Full name of the wind direction - `forecast.windSpeed` - `forecast.windSpeed.mps` Wind speed, meters per second - `forecast.windSpeed.unit` Unit of measurements - `forecast.windSpeed.name` Type of the wind - `forecast.windGust` - `forecast.windGust.gust` Wind gust, meters per second - `forecast.windGust.unit` Unit of measurements - `forecast.temperature` - `forecast.temperature.unit` Unit of measurements. Possible value is Celsius, Kelvin, Fahrenheit. - `forecast.temperature.value` Temperature - `forecast.temperature.min` Minimum temperature at the moment of calculation. This is minimal forecasted temperature (within large megalopolises and urban areas), use this parameter optionally. Please find more info [here.](#min) - `forecast.temperature.max` Maximum temperature at the moment of calculation. This is maximal forecasted temperature (within large megalopolises and urban areas), use this parameter optionally. Please find more info [here](#min) - `forecast.feels_like` - `forecast.feels_like.unit` Unit of measurements. Possible value is Celsius, Kelvin, Fahrenheit. Unit Default: Kelvin - `forecast.feels_like.value` Temperature. This temperature parameter accounts for the human perception of weather - `forecast.pressure` - `forecast.pressure.unit` hPa - `forecast.pressure.value` Pressure value - `forecast.humidity` - `forecast.humidity.unit` % - `forecast.humidity.value` Humidity value - `forecast.clouds` - `forecast.clouds.value` Name of the cloudiness - `forecast.clouds.all` Cloudiness - `forecast.clouds.unit` % - `forecast.visibility` - `forecast.visibility.value` Average visibility, metres. The maximum value of the visibility is 10km > We provide a broad variety of products such as [One Call API 4.0,](/api/one-call-4.md) [Solar Irradiance & Energy Prediction service,](/api.md#solar) [Road Risk API,](/api/road-risk.md) [Air Pollution API](/api/air-pollution.md) and solutions for advanced weather parameters like solar irradiance data, UVI, dew point, government weather alerts, etc. Please review our [product list](/api.md) page and find more info in the product documentation and [pricing](/price.md) pages. ### List of weather condition codes List of [weather condition codes](/weather-conditions.md) with icons (range of thunderstorm, drizzle, rain, snow, clouds, atmosphere etc.) ### Min/max temperature in our weather API Please do not confuse min/max parameters in our weather APIs. - In **Hourly forecast API**, [Current weather API](/current.md) and [5 day / 3 hour forecast API](/forecast5.md) - **temp_min** and **temp_max** are optional parameters mean min / max temperature in the city at the current moment just for your reference. For large cities and megalopolises geographically expanded it might be applicable. In most cases both **temp_min** and **temp_max** parameters have the same volume as 'temp'. Please use **temp_min** and **temp_max** parameters in current weather API optionally. - In [16 Day forecast](/forecast16.md) - **min** and **max** mean maximum and minimum temperature in the day. ### Example of current weather API response ```text "main":{ "temp":306.15, //current temperature "pressure":1013, "humidity":44, "temp_min":306.15, //min current temperature in the city "temp_max":306.15 //max current temperature in the city }, ``` For comparison look at example of daily forecast weather API response: ### Example of daily forecast weather API response ```text "dt":1406080800, "temp":{ "day":297.77, //daily averaged temperature "min":293.52, //daily min temperature "max":297.77, //daily max temperature "night":293.52, //night temperature "eve":297.77, //evening temperature "morn":297.77}, //morning temperature ``` ## Other features ### Geocoding AP Requesting API calls by geographical coordinates is the most accurate way to specify any location. If you need to convert city names and zip-codes to geo coordinates and the other way around automatically, please use our [Geocoding API](/api/geocoding-api.md). ### Built-in geocoding > Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around. > > **Please note that API requests by city name, zip-codes and city id have been deprecated. Although they are still available for use, bug fixing and updates are no longer available for this functionality.** ### Built-in API request by city name You can search weather forecast for 4 days (96 hours) with data every hour by city name. All weather data can be obtained in JSON and XML formats. ### API call ```text https://pro.openweathermap.org/data/2.5/forecast/hourly?q={city name}&appid={API key} ``` ### API call ```text https://pro.openweathermap.org/data/2.5/forecast/hourly?q={city name},{country code}&appid={API key} ``` ### API call ```text https://pro.openweathermap.org/data/2.5/forecast/hourly?q={city name},{state code},{country code}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `q` | Yes | city name, state code and country code divided by comma, use ISO 3166 country codes. You can specify the parameter not only in English. In this case, the API response should be returned in the same language as the language of requested location name if the location is in our predefined list of more than 200,000 locations. | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `mode` | optional | Data format. Possible values are `json` and `xml`. If the `mode` parameter is empty the format is JSON by default. [Learn more](#format) | | `cnt` | optional | A number of timestamps in response. [Learn more](#limit) | | `lang` | optional | Language code. [Learn more](#multi) | ### API call examples ```text https://pro.openweathermap.org/data/2.5/forecast/hourly?q=London,us&mode=xml&appid={API key} ``` > There is a possibility to receive a central district of the city/town with its own parameters (geographic coordinates/id/name) in API response. Please see the example below. ### Example of API response ```text https://pro.openweathermap.org/data/2.5/forecast/hourly?q=München,DE&appid={API key} ``` ### Built-in API request by city ID You can search weather forecast for 4 days with data every hour by city ID. List of city ID city.list.json.gz can be downloaded here [http://bulk.openweathermap.org/sample/](http://bulk.openweathermap.org/sample/) We recommend to call API by city ID to get unambiguous result for your city. ### API call ```text https://pro.openweathermap.org/data/2.5/forecast/hourly?id={city ID}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `id` | Yes | city ID | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `mode` | optional | Data format. Possible values are `json` and `xml`. If the `mode` parameter is empty the format is JSON by default. [Learn more](#format) | | `cnt` | optional | A number of timestamps in response. [Learn more](#limit) | | `lang` | optional | Language code. [Learn more](#multi) | ### API call example ```text https://pro.openweathermap.org/data/2.5/forecast/hourly?id=524901&appid={API key} ``` ### Built-in API request by ZIP code Please note if country is not specified then the search works for USA as a default. ### API call ```text https://pro.openweathermap.org/data/2.5/forecast/hourly?zip={zip code},{country code}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `zip` | Yes | Zip code | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `mode` | optional | Data format. Possible values are `json` and `xml`. If the `mode` parameter is empty the format is JSON by default. [Learn more](#format) | | `cnt` | optional | A number of timestamps in response. [Learn more](#limit) | | `lang` | optional | Language code | ### API call example ```text https://pro.openweathermap.org/data/2.5/forecast/hourly?zip=94040,us&appid={API key} ``` ### Format JSON format is used by default. To get data in XML format just set up mode = xml. | Parameters | | | | --- | --- | --- | | `mode` | optional | Data format. Possible values are `json` and `xml`. If the `mode` parameter is empty the format is JSON by default. | JSON ### API call examples ```text api.openweathermap.org/data/2.5/weather?q=London&appid={API key} ``` XML ### Example of API response ```text api.openweathermap.org/data/2.5/weather?q=London&mode=xml ``` ### Limitation of result To limit number of listed cities please setup `cnt` parameter that specifies the number of timestamps returned. | Parameters | | | | --- | --- | --- | | `cnt` | optional | A number of timestamps in response | cnt=3 ### API call example ```text https://pro.openweathermap.org/data/2.5/forecast/hourly?lat=57&lon=-2.15{API key}&cnt=3 ``` ### API call example ```json { "cod": "200", "message": 0, "cnt": 3, "list": [ { "dt": 1647356400, "main": { "temp": 281.98, "feels_like": 278.65, "temp_min": 280.57, "temp_max": 281.98, "pressure": 1014, "sea_level": 1014, "grnd_level": 1014, "humidity": 81, "temp_kf": 1.41, "dew_point": 279.01 }, "weather": [ { "id": 804, "main": "Clouds", "description": "overcast clouds", "icon": "04d" } ], "clouds": { "all": 100 }, "wind": { "speed": 6.78, "deg": 184, "gust": 12.14 }, "visibility": 10000, "pop": 0.34, "sys": { "pod": "d" }, "dt_txt": "2022-03-15 15:00:00" }, { "dt": 1647360000, "main": { "temp": 281.8, "feels_like": 278.45, "temp_min": 281.06, "temp_max": 281.8, "pressure": 1014, "sea_level": 1014, "grnd_level": 1014, "humidity": 79, "temp_kf": 0.74, "dew_point": 278.36 }, "weather": [ { "id": 804, "main": "Clouds", "description": "overcast clouds", "icon": "04d" } ], "clouds": { "all": 100 }, "wind": { "speed": 6.68, "deg": 186, "gust": 11.8 }, "visibility": 10000, "pop": 0.28, "sys": { "pod": "d" }, "dt_txt": "2022-03-15 16:00:00" }, { "dt": 1647363600, "main": { "temp": 281.58, "feels_like": 278.29, "temp_min": 280.99, "temp_max": 281.58, "pressure": 1014, "sea_level": 1014, "grnd_level": 1014, "humidity": 79, "temp_kf": 0.59, "dew_point": 278.22 }, "weather": [ { "id": 804, "main": "Clouds", "description": "overcast clouds", "icon": "04d" } ], "clouds": { "all": 100 }, "wind": { "speed": 6.33, "deg": 181, "gust": 11.26 }, "visibility": 10000, "pop": 0.24, "sys": { "pod": "d" }, "dt_txt": "2022-03-15 17:00:00" } ], "city": { "id": 2641549, "name": "Newtonhill", "coord": { "lat": 57, "lon": -2.15 }, "country": "GB", "population": 3284, "timezone": 0, "sunrise": 1647325488, "sunset": 1647367827 } } ``` ### Units of measurement `standard`, `metric`, and `imperial` units are available. [List of all API parameters with available units](/weather-data.md). | Parameters | | | | --- | --- | --- | | `units` | optional | Units of measurement. `metric`, `imperial`. When you do not use units parameter, format is Standard by default | > Temperature is available in Fahrenheit, Celsius and Kelvin units. > > List of all API parameters with units [openweathermap.org/weather-data](/weather-data.md) Standard ### API call examples ```text https://pro.openweathermap.org/data/2.5/forecast/hourly?lat=57&lon=-2.15&appid={API key} ``` ### Example of API response ```text https://pro.openweathermap.org/data/2.5/forecast/hourly?lat=57&lon=-2.15&appid={API key}&units=metric ``` ### Example of API response ```text https://pro.openweathermap.org/data/2.5/forecast/hourly?lat=57&lon=-2.15&appid={API key}&units=imperial ``` ### Multilingual support You can use `lang` parameter to get the output in your language. Translation is applied for the `city name` and `description` fields. ### API call ```text https://pro.openweathermap.org/data/2.5/forecast/hourly?lat=57&lon=-2.15&appid={API key}&lang={lang} ``` | Parameters | | | | --- | --- | --- | | `lang` | optional | Language code | ### API call example ```text https://pro.openweathermap.org/data/2.5/forecast/hourly?lat=57&lon=-2.15&lang=zh_cn&appid={API key} ``` We support the following languages that you can use with the corresponded lang values: - `sq` Albanian - `af` Afrikaans - `ar` Arabic - `az` Azerbaijani - `eu` Basque - `be` Belarusian - `bg` Bulgarian - `ca` Catalan - `zh_cn` Chinese Simplified - `zh_tw` Chinese Traditional - `hr` Croatian - `cz` Czech - `da` Danish - `nl` Dutch - `en` English - `fi` Finnish - `fr` French - `gl` Galician - `de` German - `el` Greek - `he` Hebrew - `hi` Hindi - `hu` Hungarian - `is` Icelandic - `id` Indonesian - `it` Italian - `ja` Japanese - `kr` Korean - `ku` Kurmanji (Kurdish) - `la` Latvian - `lt` Lithuanian - `mk` Macedonian - `no` Norwegian - `fa` Persian (Farsi) - `pl` Polish - `pt` Portuguese - `pt_br` Português Brasil - `ro` Romanian - `ru` Russian - `sr` Serbian - `sk` Slovak - `sl` Slovenian - `sp, es` Spanish - `sv, se` Swedish - `th` Thai - `tr` Turkish - `ua, uk` Ukrainian - `vi` Vietnamese - `zu` Zulu ### Call back function for JavaScript code To use JavaScript code you can transfer `callback` functionName to JSONP callback. ### API call example ```text https://pro.openweathermap.org/data/2.5/forecast/hourly?lat=57&lon=-2.15&callback=test&appid={API key} ``` --- ## Historical Lightning Data The **OpenWeather Historical Lightning Data API** provides observed lightning events detected by a global sensor network. The data is derived from the ERA5 reanalysis model, offering **global coverage** and a historical archive starting from 2023-06-26. Each record represents an individual lightning discharge with geographic coordinates, timestamp, and an estimated positional uncertainty. - **Data type:** Observed lightning strikes (cloud-to-ground and intra- cloud, where available). - **Spatial input:** Point (lat/lon) + search radius ≤ 50 km. All parameters are required. - **Temporal input:** start_date, end_date (UTC, ISO-8601) — **maximum 7-day** window. - **Output:** List of lightning events, each with: - - datetime — timestamp of detection - lat, lon — strike location - quality — detection confidence - error — horizontal location error - **Update frequency:** Near-real-time, available within minutes of occurrence. - **Historical range:** Historical lightning data available from 2023-06-26 to present ### Authentication > Every request requires an **API key**. ### Endpoints **HTTP** ### GET ```text https://demo.openweathermap.org/lightning/1.0/data?lat={LATITUDE}&lon={LONGITUDE}&radius={RADIUS}&start_date={START_DATE}&end_date={END_DATE} &apikey={YOUR_API_KEY} ``` ### Query Parameters > Please note that all parameters are required. | **Name** | **Type** | **Description** | | --- | --- | --- | | lat | number | Latitude in decimal degrees (−90…90). Global coverage (±90). | | lon | number | Longitude in decimal degrees (−180…180). Global coverage (±180). | | radius | number | Search radius in kilometres (0–50, decimal values allowed). | | start_date | string (ISO-8601 UTC or with timezone offset) | Start of the requested time window. | | end_date | string (ISO-8601 UTC or with timezone offset) | End of the requested time window (maximum 7 days 23:59:59 after start_date). | | apikey | string | OpenWeather API key. | **Date & Time Rules** - `start_date` must be less than or equal to `end_date` - Maximum allowed range between dates: **7 days 23 hours 59 minutes 59 seconds** - Earliest available date: **2023-06-26T09:56:38.000Z** Supported formats: - ISO-8601 with UTC (`Z`), e.g. `2023-09-08T21:00:00Z` - ISO-8601 with timezone offset, e.g. `2023-09-08T21:00:00+02:00` > **Important:** > > - Both dates must use the same format > - Mixing formats is not allowed (e.g. `Z` and `+02:00`) ### URL Example ```text https://demo.openweathermap.org/lightning/1.0/data?lat=34.360371&lon=22.617449&radius=20&start_date=2023-09-08T21:00:00Z&end_date=2023-09-08T21:10:00Z&apik ey={YOUR_API_KEY} ``` ### JSON response (200) ```json { "lat": 34.360371, "lon": 22.617449, "radius": 20.0, "start_date": "2023-09-08T21:00:00Z", "end_date": "2023-09-08T21:10:00Z", "lightnings": [ { "id": "9db73abd-a064-4cd5-8086-ba1053e49e6b", "datetime": "2023-09-08T21:03:54+00:00", "lat": 34.362811, "lon": 22.614233, "quality": "good", "error": 4.5 }, { "id": "91b5581a-4005-44a9-9d01-0c6daf2567f9", "datetime": "2023-09-08T21:07:21+00:00", "lat": 34.359114, "lon": 22.619822, "quality": "medium", "error": 12.5 } ] } ``` ### Field Descriptions - `id`  Unique record identifier - `date` Detection time of lightning strike (always returned in UTC, ISO-8601) - `lon` Longitude of the location - `lat` Latitude of the location - `quality` Quality level of detection (good, medium, bad, undefined) - `error` Estimated horizontal location uncertainty, km ### Error Handling | **HTTP** | **Meaning ** | **Example Payload** | | --- | --- | --- | | 400 | Validation error (missing/invalid parameters) | {"code":"400","message": "Invalid parameter format","parameters":["lat"]} | | 401 | Unauthorized (invalid API key) | {"code":"401","message": Unauthorized"} | | 403 | Forbidden | {"code":"403","message":"Forbidden"} | | 404 | Not found | {"code":"404","message":"Not Found"} | | 429 | Rate limited | {"code":"429","message":"Too many requests"} | | 500 | Internal server error | {"code":"500","message":"Internal server error"} | --- ## OpenWeather Lightning real-time data API The **OpenWeather Lightning real-time data API** provides access to lightning strike data in real time. Our streaming service continuously collects lightning records from our data hub and broadcasts them the moment they are processed. - **Data type:** As soon as a new strike is detected, it is pushed over a persistent WebSocket connection. Each message is delivered in JSON format. - **Update frequency:** This is a real-time live stream - **Historical range:** Historical lightning data are not available via WebSocket API. For accessing historical lightning data, use the **OpenWeather Lightning API** . ## Connection flow To start receiving lightning data, follow these three steps: 1. **Connect** to the WebSocket endpoint using your API key as the `apikey` query parameter. 2. **Send** the stream-type message `all_lightnings` within 60 seconds of connecting. 3. **Receive** - you're now subscribed and will start getting live lightning records as they're detected. To stop receiving data, simply close the connection. ## Subscribe to a stream type First, connect to the WebSocket endpoint using your API key: `wss:///?apikey=YOUR_OWM_API_KEY` Once the connection is established, send a message specifying the stream type. You must send this message within 60 seconds of connecting. > Please note: if you do not send this message, you will receive a timeout error after 60 seconds of waiting and the connection will be closed. Supported value: `all_lightnings` - enables you to receive the full stream of lightning strikes as they happen in real time. > Please note that this stream does not support any filtering: you receive every detected strike. > > Any other value is rejected with *"Not supported streaming type"*. ### Python example ```text import asyncio import json import websockets API_KEY = "YOUR_OWM_API_KEY" #locally, port 8004 (docker-compose); in prod, your WSS host behind the gateway URI = f"wss:///?apikey={API_KEY}" async def stream_lightnings(): async with websockets.connect(URI, ping_interval=20, ping_timeout=20) as ws: # the mandatory first step is to select the stream type await ws.send("all_lightnings") async for raw in ws: # endless stream rec = json.loads(raw) print(rec["date"], rec["lat"], rec["lon"], rec["quality"], rec["error"]) asyncio.run(stream_lightnings()) ``` ### JS example ```text const API_KEY = "YOUR_OWM_API_KEY"; const ws = new WebSocket(`wss:///?apikey=${API_KEY}`); ws.onopen = () => ws.send("all_lightnings"); // select a stream ws.onmessage = (e) => { const rec = JSON.parse(e.data); console.log(rec.date, rec.lat, rec.lon, rec.quality, rec.error); }; ws.onclose = (e) => console.log("closed", e.code, e.reason); ``` ## Query Parameters ### Connection endpoint > `wss:///?apikey={API_KEY}` ### Field Descriptions | **Name** | **Type** | **Description** | | --- | --- | --- | | apikey | string | OpenWeather API key | ### Stream response > Each message pushed is a single lightning record (LightningRecordMessage) in JSON format. ```json { "id": "7829b824-880f-5354-badc-7705ab7a0395", "date": "07/08/2026 13:50:47", "lat": 50.89287, "lon": 35.231313, "quality": "good", "error": 5.0 } ``` ### JSON format API response fields - `id`  Unique record identifier - `date` Detection time of lightning strike (always returned in UTC, ISO-8601) - `lon` Longitude of the location - `lat` Latitude of the location - `quality` Quality level of detection (good, medium, bad, undefined) - `error` Estimated horizontal location uncertainty, km ### Error Handling `APIKeyValidationError` — the apikey parameter is missing or invalid. `ExceededConnectionsLimitError` — too many concurrent connections for the key. `Not supported streaming type` — an unsupported stream type was requested. --- ## Map legend ### Map styles legend Default legend for weather maps colors. ### Classic rain (mm) ```json { raster-opacity: 0.6; raster-scaling: lanczos; raster-colorizer-default-mode: linear; raster-colorizer-default-color: transparent; raster-colorizer-stops: stop(0, rgba(225, 200, 100, 0)) stop(0.1, rgba(200, 150, 150, 0)) stop(0.2, rgba(150, 150, 170, 0)) stop(0.5, rgba(120, 120, 190, 0)) stop(1, rgba(110, 110, 205, 0.3)) stop(10, rgba(80,80, 225, 0.7)) stop(140, rgba(20, 20, 255, 0.9)); } ``` ### Snow (mm) ```json { stop(0, transparent) stop(5, #00d8ff) stop(10, #00b6ff) stop(25.076, #9549ff); } ``` ### Classic clouds (0-100%) ```json { stop(0, rgba(255, 255, 255, 0.0)) stop(10, rgba(253, 253, 255, 0.1)) stop(20, rgba(252, 251, 255, 0.2)) stop(30, rgba(250, 250, 255, 0.3)) stop(40, rgba(249, 248, 255, 0.4)) stop(50, rgba(247, 247, 255, 0.5)) stop(60, rgba(246, 245, 255, 0.75)) stop(70, rgba(244, 244, 255, 1)) stop(80, rgba(243, 242, 255, 1)) stop(90, rgba(242, 241, 255, 1)) stop(100, rgba(240, 240, 255, 1)); } ``` ### Temperature (°C) ```json { stop(-65, rgba(130, 22, 146, 1)) stop(-55, rgba(130, 22, 146, 1)) stop(-45, rgba(130, 22, 146, 1)) stop(-40, rgba(130, 22, 146, 1)) stop(-30, rgba(130, 87, 219, 1)) stop(-20, rgba(32, 140, 236, 1)) stop(-10, rgba(32, 196, 232, 1)) stop(0, rgba(35, 221, 221, 1)) stop(10, rgba(194, 255, 40, 1)) stop(20, rgba(255, 240, 40, 1)) stop(25, rgba(255, 194, 40,1)) stop(30, rgba(252, 128, 20, 1)); } ``` ### Pressure (Pa) ```json { stop(94000, rgba(0,115,255,1)) stop(96000, rgba(0,170,255,1)) stop(98000, rgba(75,208,214,1)) stop(100000, rgba(141,231,199,1)) stop(101000, rgba(176,247,32,1)) stop(102000, rgba(240,184,0,1)) stop(104000, rgba(251,85,21,1)) stop(106000, rgba(243,54,59,1)) stop(108000, rgba(198,0,0,1)); } ``` ### Wind (m/s) ```json { stop(1, rgba(255,255,255, 0)) stop(5, rgba(238,206,206, 0.4)) stop(15, rgba(179,100,188, 0.7)) stop(15, rgba(179,100,188, 0.7)) stop(25,rgba(63,33,59, 0.8)) stop(50, rgba(116,76,172, 0.9)) stop(100, rgba(70,0,175,1)) stop(200, rgba(13,17,38,1)); } ``` --- ## Ultraviolet index (beta) Access UV index (Clear Sky) for any location on Earth! Data is available in JSON. NOTE: Documentation for older version is available [here](/api_uv.md). NOTE: The tool that we provide for accessing the API is new and has not seen much testing from users or developers. We are using the Beta phase to collect feedback on this tool and make changes to make it as intuitive and easy to use as we can. If you try out the tool, please leave your feedback [here](https://home.openweathermap.org/questions) – it is very important to help us remove the 'Beta' label from these features. NOTE: This service is only available to subscribers. API key usage is mandatory. Please register [here](https://home.openweathermap.org) in order to receive an API key. ## URL format ```text http://api.openweathermap.org/v3/uvi/{location}/{datetime}.json?appid={api_key} ``` `location` Location coordinates `datetime` ISO 8601 date or alias `api_key` Your API key ## Location format - Location format is `{lat},{lon}`. - Accuracy of coordinates affects maximum distance for search among available data entries around specified location. More digits beyond decimal point means shorter search distance. > Please note that currently geocoordinates should be specified with the following digits(2,7,25,75) after decimal point in any order.The data is not obtained, if other digits are specified. See examples below: > > `api.openweathermap.org/v3/uvi/40.7,-74.2/2017Z.json?appid={your-api-key}` > > `api.openweathermap.org/v3/uvi/40.25,-74.75/2017Z.json?appid={your-api-key}` ### Digits beyond decimal point to search radius **No decimal part** - ~78km **1 digit** - 7862 m **2 digits** - 786 m **3 digits** - 78 m **4 digits** - 8 m **5 digits** - 1 m Examples: [`http://api.openweathermap.org/v3/uvi/40.7,-74.2/2016-03-01Z.json?appid={your-api-key}`](http://samples.openweathermap.org/v3/uvi/40.7,-74.2/2016-12-31T12:00:00Z.json?appid=b1b15e88fa797225412429c1c50c122a1) 1 digit (~78km) [`http://api.openweathermap.org/v3/uvi/40.700,-74.2/2016-03-01Z.json?appid={your-api-key}`](http://samples.openweathermap.org/v3/uvi/40.7,-74.2/2016-12-31T12:00:00Z.json?appid=b1b15e88fa797225412429c1c50c122a1) 3 digits (78m) ## Date format Date can be specified using either of two specifications. ### ISO 8601 - Searches for the latest available point within specified date (see examples below). All dates are UTC-only. Using local time zones is not supported at the moment. **Date values** `2016-01-02T15:04:05Z` searches between `2016-01-02T15:04:05Z` and `2016-01-02T15:04:05.9999Z` `2016-01-02T15:04Z` searches between `2016-01-02T15:04:00Z` and `2016-01-02T15:04:59.9999Z` `2016-01-02T15Z` searches between `2016-01-02T15:00:00Z` and `2016-01-02T15:59:59.9999Z` `2016-01-02Z` searches between `2016-01-02T00:00:00Z` and `2016-01-02T23:59:59.9999Z` `2016-01Z` searches between `2016-01-01T00:00:00Z` and `2016-12-31T23:59:59.9999Z` `2016Z` searches between `2016-01-01T00:00:00Z` and `2016-12-31T23:59:99.9999Z` **NOTE:** currently, the data is only provided provided for 12:00:00 a.m. So, please specify time values as following format: `2017-01-02T12:00:00Z` `2017-01-02T12:00Z` `2017-01-02T12Z` ### Examples - [http://api.openweathermap.org/v3/uvi/40.7,-74.2/2016-01-02T15:04:05Z.json?appid={your-api-key}](http://samples.openweathermap.org/v3/uvi/40.7,-74.2/2016-12-31T12:00:00Z.json?appid=b1b15e88fa797225412429c1c50c122a1) - [http://api.openweathermap.org/v3/uvi/40.7,-74.2/2016Z.json?appid={your-api-key}](http://samples.openweathermap.org/v3/uvi/40.7,-74.2/2016Z.json?appid=b1b15e88fa797225412429c1c50c122a1) **NOTE:** data is not cut off at the current date and time. If search request falls into the future, furthermost forecast data available will be displayed. ### Alias - A keyword bound to a certain date. ### Available aliases **current** Searches for the latest available data point up until now [http://api.openweathermap.org/v3/uvi/40.7,-74.2/current.json?appid={your-api-key}](http://samples.openweathermap.org/v3/uvi/40.7,-74.2/current.json?appid=b1b15e88fa797225412429c1c50c122a1) ## Server response format `time`  **ISO 8601 timestamp** - date and time corresponding to returned data `location`  **object** - location for which data is provided `latitude` **float** - latitude for returned data `longitude` **float** - longitude for returned data `data` **float** - [ultraviolet index](https://en.wikipedia.org/wiki/Ultraviolet_index) ### Example of API response ```json { "time": "2016-03-03T12:00:00Z", "location": { "latitude": 40.75, "longitude": -74.25 }, "data": 3.11 } ``` --- ### Explore One Call API 4.0 We recommend using [**One Call API 4.0**](/api/one-call-4.md) for all new integrations. It provides access to our latest weather data, enhanced functionality, and new features such as high-resolution 15-minute forecasts, extended weather timelines, and a unified API structure for historical and forecast data. Learn more about One Call API 4.0 and discover what's new. Please check [One Call 4.0 API documentation](/api/one-call-4.md) and our [Migration guide](/api/one-call-3-migration.md). - [One Call 4.0 documentation](/api/one-call-4.md) ## One Call API 3.0 ### Product concept Get essential weather data, short-term and long-term forecasts and aggregated weather data is easy with our OpenWeather **One Call API 3.0**. One Call API 3.0 contains 5 endpoints and provides access to various data: - [**Current weather and forecasts:**](/api/one-call-3.md#current) and government weather alerts - - 1-minute forecast for 1 hour - hourly forecast for 48 hours - daily forecast for 8 days - [**Weather data for any timestamp**](/api/one-call-3.md#history) for 47+ years historical archive and 4 days ahead forecast - [**Daily aggregation**](/api/one-call-3.md#history_daily_aggregation) of weather data for 47+ years archive and 1.5 years ahead forecast - [**Weather overview**](/api/one-call-3.md#weather_overview) with a human-readable weather summary for today and tomorrow's forecast, utilizing OpenWeather AI technologies - [**AI Weather Assistant**](/api/one-call-3.md#ai_weather_assistant) for retrieving weather data and weather-related advice in a human-readable and friendly format. One Call API 3.0 is based on the proprietary [OpenWeather Model](https://openweather.co.uk/technology) and is updated every 10 minutes. Thus, in order to receive the most accurate and up-to-date weather data, we recommend you request One Call API 3.0 every 10 minutes. Please note, that One Call API 3.0 is included in the "One Call by Call" subscription only. This separate subscription includes 1,000 calls/day for free and allows you to pay only for the number of API calls made to this product. ## Current and forecasts weather data To get access to current weather, minute forecast for 1 hour, hourly forecast for 48 hours, daily forecast for 8 days and government weather alerts, please use this section of the documentation. If you are interested in other functionality on One Call API 3.0, please check [Product concept](/api/one-call-3.md#concept) to follow the right section. ### How to make an API call ### API call ```text https://api.openweathermap.org/data/3.0/onecall?lat={lat}&lon={lon}&exclude={part}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude, decimal (-90; 90). If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `lon` | Yes | Longitude, decimal (-180; 180). If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `exclude` | optional | By using this parameter you can exclude some parts of the weather data from the API response. It should be a comma-delimited list (without spaces). Available values: `current` `minutely` `hourly` `daily` `alerts` | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | You can use the `lang` parameter to get the output in your language. [Learn more](#multi) | ### Example of API call Before making an API call, please note, that One Call 3.0 is included in the "One Call by Call" subscription **only**. [Learn more](/price.md) If you you want to exclude some parts of the weather data from the API response please add `exclude` parameter to the API call like in the example below: ### Example of API call ```text https://api.openweathermap.org/data/3.0/onecall?lat=33.44&lon=-94.04&exclude=hourly,daily&appid={API key} ``` If you do not need to exclude any of the weather data from the API response please use API call like in the example below: ### Example of API call ```text https://api.openweathermap.org/data/3.0/onecall?lat=33.44&lon=-94.04&appid={API key} ``` ### Fields in API response > If you do not see some of the parameters in your API response it means that these weather phenomena are just not happened for the time of measurement for the city or location chosen. Only really measured or calculated data is displayed in API response. - `lat` Latitude of the location, decimal (−90; 90) - `lon` Longitude of the location, decimal (-180; 180) - `timezone` Timezone name for the requested location - `timezone_offset` Shift in seconds from UTC - `current` **Current weather data API response** - `current.dt` Current time, Unix, UTC - `current.sunrise` Sunrise time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `current.sunset` Sunset time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `current.temp` Temperature. Units - default: kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](#data) - `current.feels_like` Temperature. This temperature parameter accounts for the human perception of weather. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. - `current.pressure` Atmospheric pressure on the sea level, hPa - `current.humidity` Humidity, % - `current.dew_point` Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit - `current.clouds` Cloudiness, % - `current.uvi` Current UV index. - `current.visibility` Average visibility, metres. The maximum value of the visibility is 10 km - `current.wind_speed` Wind speed. Wind speed. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](#data) - `current.wind_gust` (where available) Wind gust. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](#data) - `current.wind_deg` Wind direction, degrees (meteorological) - `current.rain` - `current.rain.1h` (where available) Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter - `current.snow` - `current.snow.1h` (where available) Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter - `current.weather` - `current.weather.id` [Weather condition id](/weather-conditions.md#Weather-Condition-Codes-2) - `current.weather.main` Group of weather parameters (Rain, Snow etc.) - `current.weather.description` Weather condition within the group ([full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2)). Get the output in [your language](#multi) - `current.weather.icon` Weather icon id. [How to get icons](/weather-conditions.md#How-to-get-icon-URL) - `minutely` **Minute forecast weather data API response** - `minutely.dt` Time of the forecasted data, unix, UTC - `minutely.precipitation` Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter - `hourly` **Hourly forecast weather data API response** - `hourly.dt` Time of the forecasted data, Unix, UTC - `hourly.temp` Temperature. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](#data) - `hourly.feels_like` Temperature. This accounts for the human perception of weather. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. - `hourly.pressure` Atmospheric pressure on the sea level, hPa - `hourly.humidity` Humidity, % - `hourly.dew_point` Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. - `hourly.uvi` UV index - `hourly.clouds` Cloudiness, % - `hourly.visibility` Average visibility, metres. The maximum value of the visibility is 10 km - `hourly.wind_speed` Wind speed. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour.[How to change units used](#data) - `hourly.wind_gust` (where available) Wind gust. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](#data) - `hourly.wind_deg` Wind direction, degrees (meteorological) - `hourly.pop` Probability of precipitation. The values of the parameter vary between 0 and 1, where 0 is equal to 0%, 1 is equal to 100% - `hourly.rain` - `hourly.rain.1h` (where available) Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter - `hourly.snow` - `hourly.snow.1h` (where available) Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter - `hourly.weather` - `hourly.weather.id` [Weather condition id](/weather-conditions.md#Weather-Condition-Codes-2) - `hourly.weather.main` Group of weather parameters (Rain, Snow etc.) - `hourly.weather.description` Weather condition within the group ([full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2)). Get the output in [your language](#multi) - `hourly.weather.icon` Weather icon id. [How to get icons](/weather-conditions.md#How-to-get-icon-URL) - `daily` **Daily forecast weather data API response** - `daily.dt` Time of the forecasted data, Unix, UTC - `daily.sunrise` Sunrise time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `daily.sunset` Sunset time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `daily.moonrise` The time of when the moon rises for this day, Unix, UTC - `daily.moonset` The time of when the moon sets for this day, Unix, UTC - `daily.moon_phase` Moon phase. `0` and `1` are 'new moon', `0.25` is 'first quarter moon', `0.5` is 'full moon' and `0.75` is 'last quarter moon'. The periods in between are called 'waxing crescent', 'waxing gibbous', 'waning gibbous', and 'waning crescent', respectively. Moon phase calculation algorithm: if the moon phase values between the start of the day and the end of the day have a round value (0, 0.25, 0.5, 0.75, 1.0), then this round value is taken, otherwise the average of moon phases for the start of the day and the end of the day is taken - `summary`Human-readable description of the weather conditions for the day - `daily.temp` Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](#data) - `daily.temp.morn` Morning temperature. - `daily.temp.day` Day temperature. - `daily.temp.eve` Evening temperature. - `daily.temp.night` Night temperature. - `daily.temp.min` Min daily temperature. - `daily.temp.max` Max daily temperature. - `daily.feels_like` This accounts for the human perception of weather. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](#data) - `daily.feels_like.morn` Morning temperature. - `daily.feels_like.day` Day temperature. - `daily.feels_like.eve` Evening temperature. - `daily.feels_like.night` Night temperature. - `daily.pressure` Atmospheric pressure on the sea level, hPa - `daily.humidity` Humidity, % - `daily.dew_point` Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. - `daily.wind_speed` Wind speed. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](#data) - `daily.wind_gust` (where available) Wind gust. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](#data) - `daily.wind_deg` Wind direction, degrees (meteorological) - `daily.clouds` Cloudiness, % - `daily.uvi` The maximum value of UV index for the day - `daily.pop` Probability of precipitation. The values of the parameter vary between 0 and 1, where 0 is equal to 0%, 1 is equal to 100% - `daily.rain` (where available) Precipitation volume, mm. Please note that only mm as units of measurement are available for this parameter - `daily.snow` (where available) Snow volume, mm. Please note that only mm as units of measurement are available for this parameter - `daily.weather` - `daily.weather.id` [Weather condition id](/weather-conditions.md#Weather-Condition-Codes-2) - `daily.weather.main` Group of weather parameters (Rain, Snow etc.) - `daily.weather.description` Weather condition within the group ([full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2)). Get the output in [your language](#multi) - `daily.weather.icon` Weather icon id. [How to get icons](/weather-conditions.md#How-to-get-icon-URL) - `alerts` **National weather alerts data from major national weather warning systems** - `alerts.sender_name` Name of the alert source. Please read here the [full list of alert sources](#listsource) - `alerts.event` Alert event name - `alerts.start` Date and time of the start of the alert, Unix, UTC - `alerts.end` Date and time of the end of the alert, Unix, UTC - `alerts.description` Description of the alert - `alerts.tags` Type of severe weather > National weather alerts are provided in English by default. Please note that some agencies provide the alert’s description only in a local language. ### How to get government weather alerts only for location To get access to government weather alerts relevant to a selected location only, please use this section of the documentation. If you are interested in other functionality on One Call API 3.0, please check [Product concept](/api/one-call-3.md#concept) to follow the right section. ### How to make an API call ### API call ```text https://api.openweathermap.org/data/3.0/onecall?lat={lat}&lon={lon}&exclude=current,minutely,hourly,daily&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | required | Latitude, decimal (-90; 90). If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `lon` | required | Longitude, decimal (-180; 180). If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `appid` | required | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `exclude` | optional | This parameter is pre-filled to keep only the alerts section for the selected location and exclude other parts of the API response. If you need the complete API response or other weather data components, please return to section [How to make an API call](/api/one-call-3.md?collection=one_call_api_3.0#how) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](/api/one-call-3.md?collection=one_call_api_3.0#data) | | `lang` | optional | You can use the `lang` parameter to get the output in your language. [Learn more](/api/one-call-3.md?collection=one_call_api_3.0#multi) | ### Example of API call Before making an API call, please note, that One Call 3.0 is included in the "One Call by Call" subscription **only**. [Learn more](/price.md) ### Example of API call ```text https://api.openweathermap.org/data/3.0/onecall?lat=33.44&lon=-94.04&exclude=current,minutely,hourly,daily&appid={API key} ``` ### Example of API response ```json { "lat":33.44, "lon":-94.04, "timezone":"America/Chicago", "timezone_offset":-18000, "alerts": [ { "sender_name": "NWS Philadelphia - Mount Holly (New Jersey, Delaware, Southeastern Pennsylvania)", "event": "Small Craft Advisory", "start": 1684952747, "end": 1684988747, "description": "...SMALL CRAFT ADVISORY REMAINS IN EFFECT FROM 5 PM THIS\nAFTERNOON TO 3 AM EST FRIDAY...\n* WHAT...North winds 15 to 20 kt with gusts up to 25 kt and seas\n3 to 5 ft expected.\n* WHERE...Coastal waters from Little Egg Inlet to Great Egg\nInlet NJ out 20 nm, Coastal waters from Great Egg Inlet to\nCape May NJ out 20 nm and Coastal waters from Manasquan Inlet\nto Little Egg Inlet NJ out 20 nm.\n* WHEN...From 5 PM this afternoon to 3 AM EST Friday.\n* IMPACTS...Conditions will be hazardous to small craft.", "tags": [ ] }, ... ] } ``` > If you do not see some of the parameters in your API response it means that these weather phenomena are just not happened for the time of measurement for the city or location chosen. Only really measured or calculated data is displayed in API response ### Fields in API response - `lat` Latitude of the location, decimal (−90; 90) - `lon` Longitude of the location, decimal (-180; 180) - `timezone` Timezone name for the requested location - `timezone_offset` Shift in seconds from UTC - `alerts` **National weather alerts data from major national weather warning systems** - - `alerts.sender_name` Name of the alert source. Please read here the [full list of alert sources](https://openweathermap.org/api/one-call-3?collection=one_call_api_3.0&collection=one_call_api_3.0&collection=one_call_api_3.0#listsource) - `alerts.event` Alert event name - `alerts.start` Date and time of the start of the alert, Unix, UTC - `alerts.end` Date and time of the end of the alert, Unix, UTC - `alerts.description` Description of the alert - `alerts.tags` Type of severe weather > National weather alerts are provided in English by default. Please note that some agencies provide the alert’s description only in a local language. ## Weather data for timestamp To learn about how get access to weather data for any timestamp from 1st January 1979 till 4 days ahead forecast, please use this section of the documentation. If you are interested in other functionality on One Call API 3.0, please check [Product concept](/api/one-call-3.md#concept) to follow the right section. ### How to make an API call ### API call ```text https://api.openweathermap.org/data/3.0/onecall/timemachine?lat={lat}&lon={lon}&dt={time}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude, decimal (-90; 90). If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `lon` | Yes | Longitude, decimal (-180; 180). If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md) | | `dt` | Yes | Timestamp (Unix time, UTC time zone), e.g. dt=1586468027. Data is available **from January 1st, 1979 till 4 days ahead ** | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | You can use the `lang` parameter to get the output in your language. [Learn more](#multi) | > Please note that the one API response contains weather data for only one specified timestamp. Before making an API call, please note, that One Call 3.0 is included in the "One Call by Call" subscription **only**. [Learn more](/price.md) ### Example of API call ```text https://api.openweathermap.org/data/3.0/onecall/timemachine?lat=39.099724&lon=-94.578331&dt=1643803200&appid={API key} ``` ### Example of API response ```json { "lat": 52.2297, "lon": 21.0122, "timezone": "Europe/Warsaw", "timezone_offset": 3600, "data": [ { "dt": 1645888976, "sunrise": 1645853361, "sunset": 1645891727, "temp": 279.13, "feels_like": 276.44, "pressure": 1029, "humidity": 64, "dew_point": 272.88, "uvi": 0.06, "clouds": 0, "visibility": 10000, "wind_speed": 3.6, "wind_deg": 340, "weather": [ { "id": 800, "main": "Clear", "description": "clear sky", "icon": "01d" } ] } ] } ``` ### Fields in API response > If you do not see some of the parameters in your API response it means that these weather phenomena are just not happened for the time of measurement for the city or location chosen. Only really measured or calculated data is displayed in API response. - `lat` Latitude of the location, decimal (−90; 90) - `lon` Longitude of the location, decimal (-180; 180) - `timezone` Timezone name for the requested location - `timezone_offset` Shift in seconds from UTC - `data` - `data.dt` Requested time, Unix, UTC - `data.sunrise` Sunrise time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `data.sunset` Sunset time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `data.temp` Temperature. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](#data) - `data.feels_like` Temperature. This accounts for the human perception of weather. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. - `data.pressure` Atmospheric pressure on the sea level, hPa - `data.humidity` Humidity, % - `data.dew_point` Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. - `data.clouds` Cloudiness, % - `data.uvi` UV index. Please pay attention that historical UV index data available only for 5 days back. If you would like to get historical UVI index data starting from 20th September 2020 please [contact us](mailto:info@openweathermap.org) - `data.visibility` Average visibility, metres. The maximum value of the visibility is 10 km - `data.wind_speed` Wind speed. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](#data) - `data.wind_gust` (where available) Wind gust. Wind speed. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](#data) - `data.wind_deg` Wind direction, degrees (meteorological) - `data.weather` - `data.weather.id` [Weather condition id](/weather-conditions.md#Weather-Condition-Codes-2) - `data.weather.main` Group of weather parameters (Rain, Snow etc.) - `data.weather.description` Weather condition within the group ([full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2)). Get the output in [your language](#multi) - `data.weather.icon` Weather icon id. [How to get icons](/weather-conditions.md#How-to-get-icon-URL) - `data.rain` (where available) - `1h` Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter - `data.snow`(where available) - `1h` Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter ## Daily Aggregation To learn about how get access to aggregated weather data for a particular date from 2nd January 1979 till long-term forecast for 1,5 years ahead, please use this section of the documentation. If you are interested in other functionality on One Call API 3.0, please check [Product concept](/api/one-call-3.md#concept) to follow the right section. ### How to make an API call ### API call ```text https://api.openweathermap.org/data/3.0/onecall/day_summary?lat={lat}&lon={lon}&date={date}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude, decimal (-90; 90) | | `lon` | Yes | Longitude, decimal (-180; 180) | | `date` | Yes | Date in the `YYYY-MM-DD` format for which data is requested. Date is available for 447+ years archive (starting from 1979-01-02) up to the 1,5 years ahead forecast to the current date | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | You can use the `lang` parameter to get the output in your language. [Learn more](#multi) | > If the service detected timezone for your location incorrectly you can specify correct timezone manually by adding `tz` parameter in the ±XX:XX format to API call. > > API call > > `https://api.openweathermap.org/data/3.0/onecall/day_summary?lat={lat}&lon={lon}&date={date}&tz={tz}&appid=`[`{API key}`](https://home.openweathermap.org/api_keys) > > Example of API call > > `https://api.openweathermap.org/data/3.0/onecall/day_summary?lat=60.45&lon=-38.67&date=2023-03-30&tz=+03:00&appid=`[`{API key}`](https://home.openweathermap.org/api_keys) > > Please pay attention that in case timezone is specified time of afternoon, night, evening, morning temperatures, pressure, humidity will be returned in accordance with this specified timezone. ### Example of API call Before making an API call, please note, that One Call 3.0 is included in the "One Call by Call" subscription **only**. [Learn more](/price.md) ### Example of API call ```text https://api.openweathermap.org/data/3.0/onecall/day_summary?lat=39.099724&lon=-94.578331&date=2020-03-04&appid={API key} ``` ### Example of API response ```json { "lat":33, "lon":35, "tz":"+02:00", "date":"2020-03-04", "units":"standard", "cloud_cover":{ "afternoon":0 }, "humidity":{ "afternoon":33 }, "precipitation":{ "total":0 }, "temperature":{ "min":286.48, "max":299.24, "afternoon":296.15, "night":289.56, "evening":295.93, "morning":287.59 }, "pressure":{ "afternoon":1015 }, "wind":{ "max":{ "speed":8.7, "direction":120 } } } ``` ### Fields in API response - `lat` Latitude of the location, decimal (−90; 90) - `lon` Longitude of the location, decimal (-180; 180) - `tz` Timezone in the ±XX:XX format - `date` Date specified in the API request in the `YYYY-MM-DD` format (from 1979-01-02 up to the 1,5 years ahead forecast) - `units` Units of measurement specified in the request. [Learn more](#data) - `cloud_cover` Cloud related information - `afternoon` Cloud cover at 12:00 for the date specified in the request, % - `humidity` Humidity related information - `afternoon` Relative humidity at 12:00 for the date specified in the request, % - `precipitation` Precipitation related information - `total` Total amount of liquid water equivalent of precipitation for the date specified in the request, mm - `pressure` Atmospheric pressure related information - `afternoon` Atmospheric pressure at 12:00 for the date specified in the request, hPa - `temperature` Temperature related information - `min` Minimum temperature for the date specified in the request. Units - default: kelvin, metric: Celsius, imperial: Fahrenheit.[How to change units used](#data) - `max` Maximum temperature for the date specified in the request. Units - default: kelvin, metric: Celsius, imperial: Fahrenheit.[How to change units used](#data) - `afternoon` Temperature at 12:00 for the date specified in the request. Units - default: kelvin, metric: Celsius, imperial: Fahrenheit.[How to change units used](#data) - `night` Temperature at 00:00 for the date specified in the request. Units - default: kelvin, metric: Celsius, imperial: Fahrenheit.[How to change units used](#data) - `evening` Temperature at 18:00 for the date specified in the request. Units - default: kelvin, metric: Celsius, imperial: Fahrenheit.[How to change units used](#data) - `morning` Temperature at 06:00 for the date specified in the request. Units - default: kelvin, metric: Celsius, imperial: Fahrenheit.[How to change units used](#data) - `wind` Wind speed related information - `max` Maximum wind speed related information - `speed` Maximum wind speed for the date specified in the request. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](#data) - `direction` Wind cardinal direction relevant to the maximum wind speed, degrees (meteorological) ## Weather overview This section describes how to get weather overview with a human-readable weather summary for today and tomorrow's forecast, utilizing OpenWeather AI technologies. If you are interested in other functionality on One Call API 3.0, please check [Product concept](/api/one-call-3.md#concept) to follow the right section. ### How to make an API call ### API call ```text https://api.openweathermap.org/data/3.0/onecall/overview?lat={lat}&lon={lon}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude, decimal (-90; 90) | | `lon` | Yes | Longitude, decimal (-180; 180) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `date` | optional | The date the user wants to get a weather summary in the YYYY-MM-DD format. Data is available for today and tomorrow. If not specified, the current date will be used by default. Please note that the date is determined by the timezone relevant to the coordinates specified in the API request | | `units` | optional | Units of measurement. Standard, metric and imperial units are available. If you do not use the units parameter, standard units will be applied by default. [Learn more](#data) | ### Example of API call ```text https://api.openweathermap.org/data/3.0/onecall/overview?lon=-11.8092&lat=51.509865&appid={API key} ``` ### Example of API response ```json { "lat": 51.509865, "lon": -0.118092, "tz": "+01:00", "date": "2024-05-13", "units": "metric", "weather_overview": "The current weather is overcast with a temperature of 16°C and a feels-like temperature of 16°C. The wind speed is 4 meter/sec with gusts up to 6 meter/sec coming from the west-southwest direction. The air pressure is at 1007 hPa with a humidity level of 79%. The dew point is at 12°C and the visibility is 10000 meters. The UV index is at 4, indicating moderate risk from the sun's UV rays. The sky is covered with overcast clouds, and there is no precipitation expected at the moment. Overall, it is a moderately cool and cloudy day with light to moderate winds from the west-southwest." } ``` ### Fields in API response - `lat` Latitude of the location, decimal (−90; 90) - `lon` Longitude of the location, decimal (-180; 180) - `tz`Timezone in the ±XX:XX format - `date` Date for which summary is generated in the format YYYY-MM-DD - `units` Units of measurement specified in the request - `weather_overview`AI generated weather overview for the requested date ## AI Weather Assistant To learn how to access weather and weather-related advice in a human-readable format, please use this section of the documentation. If you are interested in other functionality in One Call API 3.0, please refer to the [Product concept](#concept) to follow the appropriate section. The AI Weather Assistant is available via [API](#access_api), allowing you to integrate it directly into your applications and workflows. For your convenience, you can also explore the service in a chatbot-like format using the [web interface](#access_web) to familiarize yourself with the service's functionality, test various use cases, and understand how the AI Weather Assistant responds to different queries before implementing it in your projects. Please note that all interactions with the AI Assistant endpoint are free of charge. However, the AI Weather Assistant retrieves weather information for requested locations from the Current & Forecast endpoint of the One Call API 3.0, and these requests are counting toward your One Call API 3.0 usage statistics. At the moment, the AI Weather Assistant considers current weather, minutely forecast, hourly forecast and daily forecast for the next 7 days for any location around the globe. The product offers global coverage and accepts cities, provinces or countries as valid locations. The AI weather assistant will remember the location you are inquiring about and use it for all future inquiries until a new location is specified. Questions examples: - What's the weather in London like? - Is it a good idea to go for a swim? - Will it rain tomorrow in Paris? - What should my 8-year-old child wear? - Where is it better to go on holiday next weekend: in London or Paris? The AI Weather Assistant understands over 50 languages, including English, French, Italian, German, Chinese, Arabic and Hindi. The AI Weather Assistant is a work in progress. Its knowledge of the world and weather is being continuously enhanced. ### How to make a call with web interface Here you will find how to explore the service in a chatbot-like format with the web interface to familiarize yourself with the service's functionality, test various use cases, and understand how the AI Weather Assistant responds to different queries before implementing it in your projects. The address of the web page with the web interface is: ### How to make a call with web interface ```text https://openweathermap.org/weather-assistant?apikey={API key} ``` Ensure that you use your valid OpenWeather API key in place of *api key*. | Parameters | | | | --- | --- | --- | | `api_key` | Yes | Your unique API key (you can always find it on your account page under the ["API key"](https://home.openweathermap.org/api_keys) tab) | Upon successful validation of the API key, you will be directed to the default chat page. This page serves as the primary interface for interacting with the AI Weather Assistant, allowing to initiate conversations and request weather information seamlessly. ![wa docs1](/payload/api/media/file/wa-docs1.png) Enter your prompt to communicate with the AI Weather Assistant. The AI Weather Assistant will remember the location you are inquiring about and will use it for all future inquiries until a new location is specified. The topic can include queries about the weather or activities based on weather data. ![wa-docs2](/payload/api/media/file/wa-docs2.jpg) ## How to make a call with API Endpoints ### Step 1: Session start This HTTP method is used to start a session and ask questions about the weather and weather related advice.To interact with the AI Weather Assistant, please enter your prompt following the guidelines outlined below. In case of successful creation, the method returns an HTTP code 200. Method: `POST` Header: `Content-Type: application/json` X-Api-Key: `[your OpenWeather API key]` ### URL ```text https://api.openweathermap.org/assistant/session ``` ### Example of the request body ```text json = { "prompt": "What’s weather like in London?", } ``` | Parameters | | | | --- | --- | --- | | `prompt` | Yes | Query about the weather or activities based on weather data the user is asking for. If a location is not provided in the request, the AI Weather Assistant will ask to specify the location. | ### Example of the API response ```json { "answer": "Hello! Right now in London, it's quite cloudy with overcast skies. The temperature is around 9.5°C, but it feels a little cooler at 9.2°C. The humidity is at 91%, so it might feel a bit damp. Winds are light at 1.54 m/s coming from the southwest. With these conditions, it's a cozy day to perhaps enjoy indoor activities or a calm walk with a warm jacket. If you're heading out, there's no rain reported at the moment, but it's a good idea to keep an umbrella handy just in case. Stay cozy and enjoy your day in London!", "data": { "London": { "Current UTC Time": "15 January 2025, 14:25", "Current Week Day UTC": "Wednesday", "clouds": 100, "dew_point": 281.26, "dt": 1736951146, "feels_like": 282.19, "humidity": 91, "pressure": 1034, "sunrise": 1736927957, "sunset": 1736958011, "temp": 282.65, "uvi": 0.43, "visibility": 10000, "weather": [ { "description": "overcast clouds", "icon": "04d", "id": 804, "main": "Clouds" } ], "wind_deg": 240, "wind_speed": 1.54 } }, "session_id": "d47d2211-f1cf-409c-8297-617d74945571" } ``` ### Fields in API response - `answer` LLM-generated answer to the prompt - `data` Data that was used as the data source for generating the 'answer' part. Please note that only sections relevant to the time period mentioned in the "prompt" are included in the API response. If the user doesn’t mention a location or continues to inquire about the same location, the 'data' field will remain empty. The “data” field will contain new weather data automatically upon receiving a query related to a different location or forecast type. - - `loc1`Location 1 name from inquiry - - `current UTC Time` Current time, UTC - `current Week Day UTC`Day of the week, UTC - `lat`Latitude of the location, decimal (−90; 90) - `lon`Longitude of the location, decimal (-180; 180) - `timezone` Timezone name for the requested location - `timezone_offset`Shift in seconds from UTC - `current`**Current weather data API response** - - `current.dt`Current time, Unix, UTC - `current.sunrise`Sunrise time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `current.sunset`Sunset time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `current.temp`Temperature, kelvin - `current.feels_like`Temperature. This temperature parameter accounts for the human perception of weather, kelvin. - `current.pressure`Atmospheric pressure on the sea level, hPa - `current.humidity`Humidity, % - `current.dew_point`Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form. Units: kelvin - `current.clouds`Cloudiness, % - `current.uvi`Current UV index - `current.visibility`Average visibility, metres. The maximum value of the visibility is 10 km - `current.wind_speed` Wind speed. Wind speed. Units: metre/sec - `current.wind_gust`(where available) Wind gust, metre/sec - `current.wind_deg`Wind direction, degrees (meteorological) - `current.wind_speed` Wind speed. Wind speed. Units: metre/sec - `current.rain` - - `current.rain.1h`(where available) Precipitation, mm/h - `current.snow` - - `current.snow.1h`(where available)Precipitation, mm/h - `current.weather` - - `current.weather.id`[Weather condition id](/weather-conditions.md#Weather-Condition-Codes-2) - `current.weather.main`Group of weather parameters (Rain, Snow etc.) - `current.weather.description` Weather condition within the group ([full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2)) - `current.weather.icon` Weather icon id. [How to get icons](/weather-conditions.md#How-to-get-icon-URL) - `minutely`**Minute forecast weather data API response** - - `minutely.dt`Time of the forecasted data, unix, UTC - `minutely.precipitation`Precipitation, mm/h. - `hourly` **Hourly forecast weather data API response** - - `hourly.dt`Time of the forecasted data, Unix, UTC - `hourly.temp`Temperature, kelvin - `hourly.feels_like`Temperature. This accounts for the human perception of weather, kelvin - `hourly.pressure` Atmospheric pressure on the sea level, hPa - `hourly.humidity`Humidity, % - `hourly.dew_point`Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form, kelvin - `hourly.uvi`UV index - `hourly.clouds`Cloudiness, % - `hourly.visibility`Average visibility, metres. The maximum value of the visibility is 10 km - `hourly.wind_speed` - Wind speed, metre/sec - `hourly.wind_gust`(where available)Wind gust, metre/sec - `hourly.wind_deg`Wind direction, degrees (meteorological) - `hourly.pop `Probability of precipitation. The values of the parameter vary between 0 and 1, where 0 is equal to 0%, 1 is equal to 100% - `hourly.rain` - - `hourly.rain.1h `(where available) Precipitation, mm/h - `hourly.snow` - - `hourly.snow.1h`(where available)Precipitation, mm/h - `hourly.weather` - - `current.weather.id`[Weather condition id](/weather-conditions.md#Weather-Condition-Codes-2) - `current.weather.main`Group of weather parameters (Rain, Snow etc.) - `current.weather.description` Weather condition within the group ([full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2)) - `current.weather.icon` Weather icon id. [How to get icons](/weather-conditions.md#How-to-get-icon-URL) - `daily`**Daily forecast weather data API response** - - `daily.dt`Time of the forecasted data, Unix, UTC - `daily.sunrise`SSunrise time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `daily.sunset`Sunset time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `daily.moonrise`The time of when the moon rises for this day, Unix, UTC - `daily.moonset`The time of when the moon sets for this day, Unix, UTC - `daily.moon_phase`Moon phase. 0 and 1 are 'new moon', 0.25 is 'first quarter moon', 0.5 is 'full moon' and 0.75 is 'last quarter moon'. The periods in between are called 'waxing crescent', 'waxing gibbous', 'waning gibbous', and 'waning crescent', respectively. Moon phase calculation algorithm: if the moon phase values between the start of the day and the end of the day have a round value (0, 0.25, 0.5, 0.75, 1.0), then this round value is taken, otherwise the average of moon phases for the start of the day and the end of the day is taken - `summary`Human-readable description of the weather conditions for the day - `Daily.temp`kelvin - - `daily.temp.morn` Morning temperature - `daily.temp.day` Day temperature - `daily.temp.eve` Evening temperature - `daily.temp.night` Night temperature - `daily.temp.min` Min daily temperature - `daily.temp.max` Max daily temperature - `daily.feels_like`This accounts for the human perception of weather, kelvin - - `daily.feels_like.morn` Morning temperature - `daily.feels_like.day` Day temperature - `daily.feels_like.eve` Evening temperature - `daily.feels_like.night` Night temperature - `daily.pressure`Atmospheric pressure on the sea level, hPa - `daily.humidity`Humidity, % - `daily.dew_point`Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form, kelvin - `daily.wind_speed`Wind speed, metre/sec - `daily.wind_gust`(where available) Wind gust, metre/sec - `daily.wind_deg`Wind direction, degrees (meteorological) - `daily.clouds `Cloudiness, % - `daily.uvi`The maximum value of UV index for the day - `daily.pop`Probability of precipitation. The values of the parameter vary between 0 and 1, where 0 is equal to 0%, 1 is equal to 100% - `daily.rain`(where available)Precipitation volume, mm - `daily.snow`(where available)Snow volume, mm - `daily.weather` - - `daily.weather.id`[Weather condition id](/weather-conditions.md#Weather-Condition-Codes-2) - `daily.weather.main`Group of weather parameters (Rain, Snow etc.) - `daily.weather.description` Weather condition within the group ([full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2)) - `daily.weather.icon` Weather icon id. [How to get icons](/weather-conditions.md#How-to-get-icon-URL) - `alerts`**National weather alerts data from major national weather warning systems** - - `alerts.sender_name`Name of the alert source. Please read here the [full list of alert sources](/api/one-call-3.md#listsource) - `alerts.event`Alert event name - `alerts.start`Date and time of the start of the alert, Unix, UTC - `alerts.end`Date and time of the end of the alert, Unix, UTC - `alerts.description`Description of the alert - `alerts.tags` Type of severe weather - `session_id`id of a conversation session To continue the session, please see Step 2. If you want the chatbot to disregard previous messages, return to Step 1 and begin a new session. ### Step 2: Resume a session This HTTP method is used to resume a conversation session with the chatbot. The AI Weather Assistant will remember the previous messages and retain the location you specify. It will use the location for all following inquiries until a new location is provided. In case of successful creation, the method returns an HTTP code 200. Method: `POST` Header: `Content-Type: application/json` X-Api-Key: `[your OpenWeather API key]` ### URL ```text https://api.openweathermap.org/assistant/session/{session_id} ``` ### Example of the request body ```text json = { "prompt": "Do I need a hat?", } ``` | Parameters | | | | --- | --- | --- | | `prompt` | Yes | Query about the weather or activities based on weather data the user is asking for. If a location is not provided in the initial request, the AI Weather Assistant will ask to specify the location. | ### Example of the API response ```json {'answer': "Given the mild temperature of around 9.76°C in London and the gentle north wind at 2.68 m/s, wearing a hat could be a good idea, especially if you tend to feel a bit chilly or if you're sensitive to cooler weather. Plus, a hat can add a nice style touch to your outfit! Stay cozy and enjoy your day, whatever you choose! 😊", 'data': {}, 'session_id': 'xxxxxxxxx'} ``` ### Fields in API response - `answer` LLM-generated answer to the prompt - `data` Data that was used as the data source for generating the 'answer' part. Please note that only sections relevant to the time period mentioned in the "prompt" are included in the API response. If the user doesn’t mention a location or continues to inquire about the same location, the 'data' field will remain empty. The “data” field will contain new weather data automatically upon receiving a query related to a different location or forecast type. - - `loc1`Location 1 name from inquiry - - `current UTC Time` Current time, UTC - `current Week Day UTC`Day of the week, UTC - `lat`Latitude of the location, decimal (−90; 90) - `lon`Longitude of the location, decimal (-180; 180) - `timezone` Timezone name for the requested location - `timezone_offset`Shift in seconds from UTC - `current`**Current weather data API response** - - `current.dt`Current time, Unix, UTC - `current.sunrise`Sunrise time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `current.sunset`Sunset time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `current.temp`Temperature, kelvin - `current.feels_like`Temperature. This temperature parameter accounts for the human perception of weather, kelvin. - `current.pressure`Atmospheric pressure on the sea level, hPa - `current.humidity`Humidity, % - `current.dew_point`Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form. Units: kelvin - `current.clouds`Cloudiness, % - `current.uvi`Current UV index - `current.visibility`Average visibility, metres. The maximum value of the visibility is 10 km - `current.wind_speed` Wind speed. Wind speed. Units: metre/sec - `current.wind_gust`(where available) Wind gust, metre/sec - `current.wind_deg`Wind direction, degrees (meteorological) - `current.wind_speed` Wind speed. Wind speed. Units: metre/sec - `current.rain` - - `current.rain.1h`(where available) Precipitation, mm/h - `current.snow` - - `current.snow.1h`(where available)Precipitation, mm/h - `current.weather` - - `current.weather.id`[Weather condition id](/weather-conditions.md#Weather-Condition-Codes-2) - `current.weather.main`Group of weather parameters (Rain, Snow etc.) - `current.weather.description` Weather condition within the group ([full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2)) - `current.weather.icon` Weather icon id. [How to get icons](/weather-conditions.md#How-to-get-icon-URL) - `minutely`**Minute forecast weather data API response** - - `minutely.dt`Time of the forecasted data, unix, UTC - `minutely.precipitation`Precipitation, mm/h. - `hourly` **Hourly forecast weather data API response** - - `hourly.dt`Time of the forecasted data, Unix, UTC - `hourly.temp`Temperature, kelvin - `hourly.feels_like`Temperature. This accounts for the human perception of weather, kelvin - `hourly.pressure` Atmospheric pressure on the sea level, hPa - `hourly.humidity`Humidity, % - `hourly.dew_point`Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form, kelvin - `hourly.uvi`UV index - `hourly.clouds`Cloudiness, % - `hourly.visibility`Average visibility, metres. The maximum value of the visibility is 10 km - `hourly.wind_speed` - Wind speed, metre/sec - `hourly.wind_gust`(where available)Wind gust, metre/sec - `hourly.wind_deg`Wind direction, degrees (meteorological) - `hourly.pop `Probability of precipitation. The values of the parameter vary between 0 and 1, where 0 is equal to 0%, 1 is equal to 100% - `hourly.rain` - - `hourly.rain.1h `(where available) Precipitation, mm/h - `hourly.snow` - - `hourly.snow.1h`(where available)Precipitation, mm/h - `hourly.weather` - - `current.weather.id`[Weather condition id](/weather-conditions.md#Weather-Condition-Codes-2) - `current.weather.main`Group of weather parameters (Rain, Snow etc.) - `current.weather.description` Weather condition within the group ([full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2)) - `current.weather.icon` Weather icon id. [How to get icons](/weather-conditions.md#How-to-get-icon-URL) - `daily`**Daily forecast weather data API response** - - `daily.dt`Time of the forecasted data, Unix, UTC - `daily.sunrise`SSunrise time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `daily.sunset`Sunset time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `daily.moonrise`The time of when the moon rises for this day, Unix, UTC - `daily.moonset`The time of when the moon sets for this day, Unix, UTC - `daily.moon_phase`Moon phase. 0 and 1 are 'new moon', 0.25 is 'first quarter moon', 0.5 is 'full moon' and 0.75 is 'last quarter moon'. The periods in between are called 'waxing crescent', 'waxing gibbous', 'waning gibbous', and 'waning crescent', respectively. Moon phase calculation algorithm: if the moon phase values between the start of the day and the end of the day have a round value (0, 0.25, 0.5, 0.75, 1.0), then this round value is taken, otherwise the average of moon phases for the start of the day and the end of the day is taken - `summary`Human-readable description of the weather conditions for the day - `Daily.temp`kelvin - - `daily.temp.morn` Morning temperature - `daily.temp.day` Day temperature - `daily.temp.eve` Evening temperature - `daily.temp.night` Night temperature - `daily.temp.min` Min daily temperature - `daily.temp.max` Max daily temperature - `daily.feels_like`This accounts for the human perception of weather, kelvin - - `daily.feels_like.morn` Morning temperature - `daily.feels_like.day` Day temperature - `daily.feels_like.eve` Evening temperature - `daily.feels_like.night` Night temperature - `daily.pressure`Atmospheric pressure on the sea level, hPa - `daily.humidity`Humidity, % - `daily.dew_point`Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form, kelvin - `daily.wind_speed`Wind speed, metre/sec - `daily.wind_gust`(where available) Wind gust, metre/sec - `daily.wind_deg`Wind direction, degrees (meteorological) - `daily.clouds `Cloudiness, % - `daily.uvi`The maximum value of UV index for the day - `daily.pop`Probability of precipitation. The values of the parameter vary between 0 and 1, where 0 is equal to 0%, 1 is equal to 100% - `daily.rain`(where available)Precipitation volume, mm - `daily.snow`(where available)Snow volume, mm - `daily.weather` - - `daily.weather.id`[Weather condition id](/weather-conditions.md#Weather-Condition-Codes-2) - `daily.weather.main`Group of weather parameters (Rain, Snow etc.) - `daily.weather.description` Weather condition within the group ([full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2)) - `daily.weather.icon` Weather icon id. [How to get icons](/weather-conditions.md#How-to-get-icon-URL) - `alerts`**National weather alerts data from major national weather warning systems** - - `alerts.sender_name`Name of the alert source. Please read here the [full list of alert sources](/api/one-call-3.md#listsource) - `alerts.event`Alert event name - `alerts.start`Date and time of the start of the alert, Unix, UTC - `alerts.end`Date and time of the end of the alert, Unix, UTC - `alerts.description`Description of the alert - `alerts.tags` Type of severe weather - `session_id`id of a conversation session ## Other features ### List of weather condition codes List of [weather condition codes](/weather-conditions.md) with icons (range of thunderstorm, drizzle, rain, snow, clouds, atmosphere etc.) ### Units of measurement `standard`, `metric` and `imperial` units are available. [List of all API parameters with available units.](/weather-data.md) ### API call ```text https://api.openweathermap.org/data/3.0/onecall?lat={lat}&lon={lon}&units={units} ``` | Parameters | | | | --- | --- | --- | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. | > Temperature is available in Fahrenheit, Celsius and Kelvin units. > > Wind speed is available in miles/hour and meter/sec. > > - For temperature in Fahrenheit and wind speed in miles/hour, use `units=imperial` > - For temperature in Celsius and wind speed in meter/sec, use `units=metric` > - Temperature in Kelvin and wind speed in meter/sec is used by default, so there is no need to use the units parameter in the API call if you want this ### Examples of API calls ### Standard (default) ```text api.openweathermap.org/data/3.0/onecall?lat=30.489772&lon=-99.771335 ``` ### Metric ```text api.openweathermap.org/data/3.0/onecall?lat=30.489772&lon=-99.771335&units=metric ``` ### Imperial ```text api.openweathermap.org/data/3.0/onecall?lat=30.489772&lon=-99.771335&units=imperial ``` ### Multilingual support You can use `lang` parameter to get the output in your language. The contents of the `description` field will be translated. ### API call ```text https://api.openweathermap.org/data/3.0/onecall?lat={lat}&lon={lon}&lang={lang} ``` | Parameters | | | | --- | --- | --- | | `lang` | optional | You can use the `lang` parameter to get the output in your language. | ### Example of API call Before making an API call, please note, that One Call 3.0 is included in the "One Call by Call" subscription **only**. [Learn more](/price.md) ```text https://api.openweathermap.org/data/3.0/onecall?lat=30.489772&lon=-99.771335&lang=zh_cn ``` We support the following languages. To select one, you can use the corresponding language code: - `sq` Albanian - `af` Afrikaans - `ar` Arabic - `az` Azerbaijani - `eu` Basque - `be` Belarusian - `bg` Bulgarian - `ca` Catalan - `zh_cn` Chinese Simplified - `zh_tw` Chinese Traditional - `hr` Croatian - `cz` Czech - `da` Danish - `nl` Dutch - `en` English - `fi` Finnish - `fr` French - `gl` Galician - `de` German - `el` Greek - `he` Hebrew - `hi` Hindi - `hu` Hungarian - `is` Icelandic - `id` Indonesian - `it` Italian - `ja` Japanese - `kr` Korean - `ku` Kurmanji (Kurdish) - `la` Latvian - `lt` Lithuanian - `mk` Macedonian - `no` Norwegian - `fa` Persian (Farsi) - `pl` Polish - `pt` Portuguese - `pt_br` Português Brasil - `ro` Romanian - `ru` Russian - `sr` Serbian - `sk` Slovak - `sl` Slovenian - `sp, es` Spanish - `sv, se` Swedish - `th` Thai - `tr` Turkish - `ua, uk` Ukrainian - `vi` Vietnamese - `zu` Zulu ### List of national weather alerts sources | Country | Agency | | --- | --- | | Albania | Institute of GeoSciences, Energy, Water and Environment of Albania | | Algeria | National Meteorological Office | | Argentina | National Weather Service of Argentina | | Australia | Australian Bureau of Meteorology | | Austria | - Central Institute for Meteorology and Geodynamics - Water Balance Department | | Bahrain | Bahrain Meteorological Directorate | | Barbados | Barbados Meteorological Service | | Belarus | State institution "Republican center for hydrometeorology, control of radioactive contamination and environmental monitoring" (Belhydromet) | | Belgium | Royal Meteorological Institute | | Belize | National Meteorological Service of Belize | | Benin | National Meteorological Agency (METEO-BENIN) | | Bosnia and Herzegovina | - Federal Hydrometeorological Institute of BiH - Republic Hydrometeorological Institute | | Botswana | Botswana Meteorological Services | | Brazil | National Meteorological Institute - INMET | | Bulgaria | National Institute of Meteorology and Hydrology - Plovdiv branch | | Cameroon | Cameroon National Meteorological Service | | Canada | - Alberta Emergency Management Agency (Government of Alberta, Ministry of Municipal Affairs) - Meteorological Service of Canada - Quebec Ministry of Public Safety - Yukon Emergency Measures Organization - Manitoba Emergency Management Organization | | Chile | Meteorological Directorate of Chile | | Congo | National Civil Aviation Agency (ANAC Congo) | | Costa Rica | National Meteorological Institute of Costa Rica | | Croatia | State Hydrometeorological Institute (DHMZ) | | Curacao and Sint Maarten | Meteorological Department Curacao | | Cyprus | Republic of Cyprus - Department of Meteorology | | Czech Republic | Czech Hydrometeorological Institute | | Denmark | Danish Meteorological Institute | | Ecuador | Ecuadoran Institute for Meteorology and Hydrology (INAMHI) | | Egypt | Egyptian Meteorological Authority | | Estonia | Estonian Environment Agency | | Eswatini | Eswatini Meteorological Service | | Finland | Finnish Meteorological Institute | | France | Meteo-France | | Gabon | General Directorate of Meteorology of Gabon | | Germany | German Meteorological Office | | Ghana | Ghana Meteorological Agency | | Greece | Hellenic National Meteorological Service | | Guinea | National Meteorological Agency of Guinea | | Guyana | Hydrometeorological Service of Guyana | | Hong Kong China | Hong Kong Observatory | | Hungary | Hungarian Meteorological Service | | Iceland | Icelandic Meteorological Office | | India | India Meteorological Department | | Indonesia | - Agency for Meteorology Climatology and Geophysics of Republic Indonesia (BMKG) - InaTEWS BMKG | | Ireland | Met Eireann - Irish Meteorological Service | | Israel | Israel Meteorological Service | | Italy | Italian Air Force National Meteorological Service | | Ivory Coast | Airport, aeronautical and meteorological operating and development company (SODEXAM) | | Jamaica | Meteorological Service of Jamaica | | Japan | Japan Meteorological Business Support Center | | Jordan | Jordanian Meteorological Department | | Kazakhstan | National Hydrometeorological Service of the Republic of Kazakhstan (Kazhydromet) | | Kenya | Kenya Meteorological Department | | Kuwait | Kuwait Meteorological Department | | Latvia | Latvian Environment, Geology and Meteorology Center | | Lesotho | Lesotho Meteorological Services | | Libya | Libyan National Meteorological Center | | Lithuania | Lithuanian Hydrometeorological Service under the Ministry of Environment of the Republic of Lithuania (LHMS) | | Luxembourg | Luxembourg Airport Administration | | Macao China | Macao Meteorological and Geophysical Bureau | | Madagascar | METEO Madagascar | | Malawi | Malawi Department of Climate Change and Meteorological Services | | Maldives | Maldives Meteorological Service | | Mauritania | National Meteorological Office of Mauritania | | Mauritius | Mauritius Meteorological Services | | Mexico | CONAGUA - National Meteorological Service of Mexico | | Moldova | State Hydrometeorological Service of Moldova | | Mongolia | National Agency Meteorology and the Environmental Monitoring of Mongolia | | Mozambique | National Institute of Meteorology of Mozambique | | Myanmar | Myanmar Department of Meteorology and Hydrology | | Netherlands | Royal Netherlands Meteorological Institute (KNMI) | | New Zealand | - Meteorological Service of New Zealand Limited - National Emergency Management Agency - Fire and Emergency New Zealand - Civil Defence Emergency Management (CDEM) Groups | | New Zealand | New Zealand Emergency Mobile Alert | | Niger | National Meteorological Directorate of Niger | | Nigeria | Nigerian Meteorological Agency (NiMet) | | North Macedonia | National Hydrometeorological Service - Republic of Macedonia | | Norway | - Norwegian Meteorological Institute - Norwegian Water Resources and Energy Directorate | | Paraguay | Directorate of Meteorology and Hydrology | | Philippines | Philippine Atmospheric Geophysical and Astronomical Services Administration | | Poland | Institute of Meteorology and Water Management (IMGW-PIB) | | Portugal | Portuguese Institute of Sea and Atmosphere, I.P. | | Qatar | Qatar Meteorology Department | | Republic of Korea | Korea Meteorological Administration, Weather Information | | Romania | National Meteorological Administration | | Russia | Hydrometcenter of Russia | | Saudi Arabia | National Center for Meteorology - Kingdom of Saudi Arabia | | Serbia | Republic Hydrometeorological Service of Serbia | | Seychelles | Seychelles Meteorological Authority | | Singapore | Meteorological Service Singapore | | Slovakia | Slovak Hydrometeorological Institute | | Slovenia | National Meteorological Service of Slovenia | | Solomon Islands | Solomon Islands Meteorological Services | | South Africa | South African Weather Service (SAWS) | | Spain | State Meteorological Agency (AEMET) | | Sudan | Sudan Meteorological Authority | | Sweden | Swedish Meteorological and Hydrological Institute | | Switzerland | MeteoSwiss | | Tanzania | Tanzania Meteorological Authority | | Thailand | Thai Meteorological Department | | Timor-Leste | National Directorate of Meteorology and Geophysics of Timor-Leste | | Trinidad and Tobago | Trinidad and Tobago Meteorological Service | | Ukraine | Ukrainian Hydrometeorological Center | | United Arab Emirates (UAE) | National Center of Meteorology (NCM), United Arab Emirates | | United Kingdom of Great Britain and Northern Ireland | UK Met Office | | Uruguay | Uruguayan Institute of Meteorology | | USA | - Environmental Protection Agency (EPA), Air Quality Alerts - Integrated Public Alert and Warning System (IPAWS) - National Oceanic and Atmospheric Administration (NOAA), National Tsunami Warning Center - National Oceanic and Atmospheric Administration (NOAA), National Weather Service - National Oceanic and Atmospheric Administration (NOAA), National Weather Service - Marine Zones - U.S. Geological Survey (USGS), Volcano Hazard Program | | Uzbekistan | Uzhydromet | | Yemen | Yemeni Civil Aviation and Meteorology Authority (CAMA) | | Zambia | Meteorological Department Zambia | | Zimbabwe | Meteorological Services Department | Please note that some agencies from the list may cease to provide us the weather alert information. In case you don’t receive alerts from any agency, please [contact us](mailto:info@openweathermap.org). We constantly work on our product’s improvement and keep expanding the list of partner agencies. ### Call back function for JavaScript code To use JavaScript code you can transfer `callback` functionName to JSONP callback. ### API call example ```text test({ "lat": 40.12, "lon": -96.66, "timezone": "America/Chicago", "timezone_offset": -18000, "current": { "dt": 1595243443, "sunrise": 1595243663, "sunset": 1595296278, "temp": 293.28, "feels_like": 293.82, "pressure": 1016, "humidity": 100, "dew_point": 293.28, "uvi": 10.64, "clouds": 90, "visibility": 10000, "wind_speed": 4.6, "wind_deg": 310, "weather": [ { "id": 501, "main": "Rain", "description": "moderate rain", "icon": "10n" }, { "id": 201, "main": "Thunderstorm", "description": "thunderstorm with rain", "icon": "11n" } ], "rain": { "1h": 2.93 } }, "minutely": [ { "dt": 1595243460, "precipitation": 2.928 }, ... }, "hourly": [ { "dt": 1595242800, "temp": 293.28, "feels_like": 293.82, "pressure": 1016, "humidity": 100, "dew_point": 293.28, "clouds": 90, "visibility": 10000, "wind_speed": 4.6, "wind_deg": 123, "weather": [ { "id": 501, "main": "Rain", "description": "moderate rain", "icon": "10n" } ], "pop": 0.99, "rain": { "1h": 2.46 } }, ... } "daily": [ { "dt": 1595268000, "sunrise": 1595243663, "sunset": 1595296278, "temp": { "day": 298.82, "min": 293.25, "max": 301.9, "night": 293.25, "eve": 299.72, "morn": 293.48 }, "feels_like": { "day": 300.06, "night": 292.46, "eve": 300.87, "morn": 293.75 }, "pressure": 1014, "humidity": 82, "dew_point": 295.52, "wind_speed": 5.22, "wind_deg": 146, "weather": [ { "id": 502, "main": "Rain", "description": "heavy intensity rain", "icon": "10d" } ], "clouds": 97, "pop": 1, "rain": 12.57, "uvi": 10.64 }, ... }, "alerts": [ { "sender_name": "NWS Tulsa (Eastern Oklahoma)", "event": "Heat Advisory", "start": 1597341600, "end": 1597366800, "description": "...HEAT ADVISORY REMAINS IN EFFECT FROM 1 PM THIS AFTERNOON TO\n8 PM CDT THIS EVENING...\n* WHAT...Heat index values of 105 to 109 degrees expected.\n* WHERE...Creek, Okfuskee, Okmulgee, McIntosh, Pittsburg,\nLatimer, Pushmataha, and Choctaw Counties.\n* WHEN...From 1 PM to 8 PM CDT Thursday.\n* IMPACTS...The combination of hot temperatures and high\nhumidity will combine to create a dangerous situation in which\nheat illnesses are possible." }, ... ] }) ``` ## API errors ### Structure of API errors In case of incorrected API call you will receive API error response. Error response payload returned for all types of errors with the structure below. ### Example of error response ```json { "cod":400, "message":"Invalid date format", "parameters": [ "date" ] } ``` ### Fields in error response - `cod` Code of error - `message` Description of error - `parameters`(optional) List of request parameters names that are related to this particular error ### Errors list Please find more detailed information about some popular errors below. #### API calls return an error 400 Error 400 - Bad Request. You can get 400 error if either some mandatory parameters in the request are missing or some of request parameters have incorrect format or values out of allowed range. List of all parameters names that are missing or incorrect will be returned in `parameters`attribute of the `ErrorResponse` object. #### API calls return an error 401 Error 401 - Unauthorized. You can get 401 error if API token did not providen in the request or in case API token provided in the request does not grant access to this API. You must add API token with granted access to the product to the request before returning it. #### API calls return an error 404 Error 404 - Not Found. You can get 404 error if data with requested parameters (`lat`, `lon`, `date` etc) does not exist in service database. You must not retry the same request. #### API calls return an error 429 Error 429 - Too Many Requests. You can get 429 error if key quota of requests for provided API to this API was exceeded. You may retry request after some time or after extending your key quota. #### API calls return errors '5xx' Errors 5xx - Unexpected Error. You can get '5xx' error in case of other internal errors. Error Response code will be `5xx`. Please [contact us](https://home.openweathermap.org/questions) and enclose an example of your API request that receives this error into your email to let us analyze it and find a solution for you promptly. You may retry the request which led to this error. --- ## Migrating from One Call API 3.0 to One Call API 4.0 ### Overview Thanks for building with OpenWeather. We've just launched [**One Call API 4.0**](https://openweathermap.org/api/one-call-4), the next generation of our flagship weather product, and we want to make your move from 3.0 as smooth as possible. This guide walks you through what's new, what's changed, how your existing fields map across, and what to expect on billing. If at any point you'd rather just ask us directly, our support team and **Ulla, the OpenWeather AI assistant**, are both available - see the [FAQ](https://openweathermap.org/faq) or [Support Centre](https://openweathermap.org/support-centre). ## What's new in One Call 4.0 One Call 3.0 has served developers well as an all-in-one weather response. With 4.0, we've rebuilt the product around a few things our customers asked for most: - **Finer-grained near-term forecasting.** We've added a brand-new **15-minute timeline**, covering the next 48 hours - a resolution we didn't offer before. - **A single, seamless timeline for historical and forecast weather data.** The hourly endpoint combines hourly forecasts with historical data dating back to 1979. The daily endpoint provides an even broader view, spanning 47 years of history and up to 1.5 years of forecast data - all delivered in a consistent format. - **A modular API.** Instead of one large combined response, you now call focused endpoints for exactly the data you need - current conditions, a specific timeline resolution, or alert detail. - **Built on our proprietary forecasting model.** 4.0 is powered by **OWHL™ - Hyper-Local Forecasting Model** - refreshed every 10 minutes, same as before. One Call 3.0 remains available today and isn't being switched off as part of this release. We recommend 4.0 for all new integrations, and this guide is here to help existing 3.0 customers move over at their own pace. ## At a glance: what changes | Parameters | One Call 3.0 | One Call 4.0 | | --- | --- | --- | | **How you get your data** | One combined response, with an `exclude` parameter to drop sections you don't need | Separate, focused endpoints - call only what you need | | **Endpoints** | 5: current+forecast, timestamp lookup, daily aggregation, weather overview, AI assistant | 6: current, 1-minute, 15-minute, hourly, daily, alert detail | | **Minute-by-minute forecast** | 1-minute steps, next 60 minutes | Same - unchanged | | **15-minute forecast** | Not available | **New** - 15-minute steps, next 48 hours | | **Hourly data** | Forecast only, next 48 hours | Forecast **and** history, one continuous 47-year-back-to-48-hour-ahead timeline | | **Daily data** | Forecast only, next 8 days | Forecast **and** history, one continuous 47-year-back-to-1.5-year-ahead timeline | | **Looking up a specific past date/time** | Dedicated `/timemachine` endpoint | Folded into the hourly/daily timeline - request a `start` time and read off the record | | **Weather alerts** | Full alert text included directly in your response | We return an alert ID first; a quick second call gets you the full detail | | **Large data requests** | Always returned in a single response | We paginate - you'll get `next`/`prev` links when there's more data to fetch | | **Free daily calls** | 1,000/day, with your account defaulting to a 2,000/day cap once you subscribe. You can always change the cap in your [Personal Account](https://home.openweathermap.org/subscriptions) | Same - unchanged | ## Field mapping, endpoint by endpoint Good news: the actual field names, units, and meanings you already know from 3.0 carry over almost entirely unchanged in 4.0. What moves is the **path** the data sits at (most 3.0 sections like `current`, `hourly`, `daily` simply become `data` in 4.0's dedicated endpoints), and — for alerts — the **workflow**. ### Current weather | 3.0 | One Call 4.0 | Notes | | --- | --- | --- | | `current.dt` | `data.dt` | Path only | | `current.sunrise` / `current.sunset` | `data.sunrise` / `data.sunset` | Path only | | `current.temp` | `data.temp` | Path only | | `current.feels_like` | `data.feels_like` | Path only | | `current.pressure` | `data.pressure` | Path only | | `current.humidity` | `data.humidity` | Path only | | `current.dew_point` | `data.dew_point` | Path only | | `current.clouds` | `data.clouds` | Path only | | `current.uvi` | `data.uvi` | Path only | | `current.visibility` | `data.visibility` | Path only | | `current.wind_speed` / `wind_gust` / `wind_deg` | `data.wind_speed` / `wind_gust` / `wind_deg` | Path only | | `current.rain.1h` / `current.snow.1h` | `data.rain.1h` / `data.snow.1h` | Path only | | `current.weather[].id`/`main`/`description`/`icon` | `data.weather[].id`/`main`/`description`/`icon` | Path only | | Full `alerts[]` array alongside `current` | `data.alerts[]` — array of **alert IDs** | You'll now call the alert detail endpoint for full text | ### Minute-by-minute forecast (next 60 minutes) | One Call 3.0 | One Call 4.0 | Notes | | --- | --- | --- | | `minutely.dt` | `data.dt` | Path only | | `minutely.precipitation` | `data.precipitation` | Unchanged | | *Not available in 3.0* | `data.alerts[]` | New addition in 4.0 | ### 15-minute forecast — new in One Call 4.0 There's no One Call 3.0 equivalent to map from here — this is a new capability. If you've been downsampling our hourly data to approximate 15-minute granularity, you can now call this directly: | One Call 4.0 field | Meaning | | --- | --- | | `data.dt` | Forecast time | | `data.temp` / `data.feels_like` | Temperature and Feels like temperature | | `data.pressure`, `data.humidity`, `data.dew_point` | Atmospheric conditions - pressure, humidity level and dew point temperature | | `data.uvi`, `data.clouds`, `data.visibility` | Sky conditions | | `data.wind_speed` / `wind_gust` / `wind_deg` | Wind | | `data.pop` | Probability of precipitation | | `data.rain.1h` / `data.snow.1h` | Precipitation | | `data.weather[].id/main/description/icon` | Condition summary | | `data.alerts[]` | Alert IDs | ### Hourly data (now forecast and history, in one place) | 3.0 | 4.0 | Notes | | --- | --- | --- | | `hourly.dt` | `data.dt` | Path only | | `hourly.temp` / `feels_like` | `data.temp` / `feels_like` | Unchanged | | `hourly.pressure`, `humidity`, `dew_point` | `data.pressure`, `humidity`, `dew_point` | Unchanged | | `hourly.uvi`, `clouds`, `visibility` | `data.uvi`, `clouds`, `visibility` | Unchanged | | `hourly.wind_speed` / `wind_gust` / `wind_deg` | `data.wind_speed` / `wind_gust` / `wind_deg` | Unchanged | | `hourly.pop` | `data.pop` | Unchanged | | `hourly.rain.1h` / `hourly.snow.1h` | `data.rain.1h` / `data.snow.1h` | Unchanged | | `hourly.weather[].id/main/description/icon` | `data.weather[].id/main/description/icon` | Unchanged | | *Not available in 3.0 hourly* | `data.alerts[]` | New addition | | Historical hours required a separate `/timemachine` call | Same endpoint — just request an earlier `start` | One endpoint now covers both | ### Daily data (now forecast and history, in one place) | 3.0 | 4.0 | Notes | | --- | --- | --- | | `daily.dt` | `data.dt` | Path only | | `daily.sunrise` / `sunset` / `moonrise` / `moonset` / `moon_phase` | `data.sunrise` / `sunset` / `moonrise` / `moonset` / `moon_phase` | Path only | | `daily.summary` | Not available in One Call 4.0 | | | `daily.temp.{morn,day,eve,night,min,max}` | `data.temp.{morn,day,eve,night,min,max}` | Path only | | `daily.feels_like.{morn,day,eve,night}` | `data.feels_like.{morn,day,eve,night}` | `data.feels_like.{morn,day,eve,night}` | | `daily.pressure`, `humidity`, `dew_point` | `data.pressure`, `humidity`, `dew_point` | Unchanged | | `daily.wind_speed` / `wind_gust` / `wind_deg` | `data.wind_speed` / `wind_gust` / `wind_deg` | Unchanged | | `daily.clouds`, `uvi`, `pop` | `data.clouds`, `uvi`, `pop` | Unchanged | | `daily.rain` / `daily.snow` (daily total, mm) | `data.rain` / `data.snow` | Unchanged units | | `daily.weather[].id/main/description/icon` | `data.weather[].id/main/description/icon` | Unchanged | | *Not available in 3.0 daily* | `data.alerts[]` | New addition | ### Looking up weather for a specific past date or time For that particular case please use Hourly endpoint in One Call 4.0 (`/timeline/1h`) instead of Time machine endpoint in One Call 3.0 (`/timemachine`). | One Call 3.0 | One Call 4.0 | Notes | | --- | --- | --- | | `data.dt` | `data.dt` | Unchanged | | `data.sunrise` / `sunset` | `data.sunrise` / `sunset` | Unchanged | | `data.temp`, `feels_like`, `pressure`, `humidity`, `dew_point` | Same fields, same path | Unchanged | | `data.uvi` | `data.uvi` | Limited historical UV data to 5 days back. | | `data.visibility`, `wind_speed`, `wind_gust`, `wind_deg` | Same fields, same path | Unchanged | | `data.rain.1h` / `data.snow.1h` | Same fields, same path | Unchanged | | `data.weather[].id/main/description/icon` | Same fields, same path | Unchanged | In practice: rather than calling a dedicated timestamp endpoint, you'll request a timeline window around your target time and pick out the matching record from the page returned. ### Weather alerts - full detail For that particular case please use Weather alerts endpoint in One Call 4.0 (`/onecall/alert/{alert_id}`) instead of Current&Forecasts endpoint in One Call 3.0 (inline `alerts[]`). | One Call 3.0 | One Call 4.0 | Notes | | --- | --- | --- | | *(alerts were identified only by position in the array)* | `id` | Alerts are now individually addressable | | `alerts.sender_name` | `sender_name` | Unchanged | | `alerts.event` | `event` | Unchanged | | `alerts.start` / `alerts.end` | `start` / `end` | Unchanged | | `alerts.description` | `description` | Unchanged | | `alerts.tags` | Not available in One Call 4.0 | - | ## Your migration checklist 1. **Subscribe to One Call 4.0.** It's billed under the same "One Call by Call" plan type as 3.0, but as a separate product subscription — your existing 3.0 subscription doesn't automatically extend to 4.0. 2. **Check your daily API calls cap.** Visit your Personal Account to update your daily API limits, the 2,000 API calls/day limit is set by default. 3. **Map your current usage.** Note which 3.0 sections (`current`, `minutely`, `hourly`, `daily`, `alerts`) your integration actually uses today - this tells you exactly which 4.0 endpoints you'll need. 4. **Update your endpoint URLs**, splitting combined One Call 3.0 calls into the specific One Call 4.0 endpoints you need. 5. **Add pagination support** anywhere you're pulling large hourly/daily/15-minute ranges. ## Billing | Parameters | One Call 3.0 | One Call 4.0 | | --- | --- | --- | | Subscription | "One Call by Call" | "One Call by Call" (separate subscription) | | Free calls per day | 1,000 | 1,000 | | Default cap after subscribing | 2,000/day (adjustable in your account) | 2,000/day (adjustable in your account) | | Cost beyond free tier | Pay-as-you-call — see [pricing](https://openweathermap.org/price) | Pay-as-you-call — see [pricing](https://openweathermap.org/price) | | Paginated requests | N/A | Each `next`/`prev` page is billed as its own call | **Worth knowing:** because One Call 4.0 paginates large responses, a query that was one billed call in One Call 3.0 via Current&Forecasts endpoint could become several billed calls in One Call 4.0 if it spans a long timeline. ## We're here to help One Call 4.0 is a young product, and we know migration guides like this one work best when they keep pace with what we ship. If you hit a gap — especially around Daily Aggregation, Weather Overview, or the AI Assistant — please reach out via our [Support Centre](https://openweathermap.org/support-centre) or ask Ulla. We'll keep this guide updated as those areas are documented. Thanks for building with OpenWeather. *Sources:* [*One Call API 4.0 documentation*](https://openweathermap.org/api/one-call-4) [*One Call API 3.0 documentation*](https://openweathermap.org/api/one-call-3) [*Pricing*](https://openweathermap.org/price) [*FAQ*](https://openweathermap.org/faq) --- ## One Call API 4.0 ### Product concept **One Call API 4.0** is a unified weather intelligence API designed to give developers, digital products, and enterprise teams access to current weather, short-term forecasts, long-range daily outlooks, historical weather records, and official weather alerts through a single integration. Instead of combining multiple weather endpoints and datasets, users can request highly relevant weather information for any latitude and longitude from one product family built around a consistent response structure. One Call API 4.0 contains 6 endpoints and provides access to various data: - [**Current** weather conditions](#current) - [**Minute-by-minute forecast** data for the next 60 minutes](#min) - [**15-minute forecast** data for the next 48 hours](#15min) - [**Hourly weather timelines** spanning 47 years of history and 48 hours of forecast](#hourly) - [**Daily weather timelines** spanning 47 years of history and up to 1.5 years ahead](#daily) - [**Detailed weather alert **information from national agencies](#alerts) One Call API 4.0 is based on the proprietary [**OWHL ™ OpenWeather Hyper-Local Forecasting Model**](https://openweather.co.uk/hyper-local-forecasting-model) and is updated every 10 minutes. Thus, in order to receive the most accurate and up-to-date weather data, we recommend you request One Call API 4.0 every 10 minutes. - [Product features](/api/one-call-4-desciption.md) > Please note that One Call API 4.0 is included only in the ["One Call by Call"](/price.md) subscription. This separate subscription includes **1,000 calls/day for free **and allows you to pay only for the number of API calls made to this product above the daily free limit. > > No other OpenWeather subscription plans are required to access One Call API 4.0. For more information, please visit the [pricing page](/price.md) and [FAQ](/faq.md#onecall), or ask [Ulla, OpenWeather AI assistant](/chat.md). ## How to start #### Sign up [Sign up](https://home.openweathermap.org/users/sign_up) for the OpenWeather service if you do not have an [OpenWeather API key](https://home.openweathermap.org/api_keys) yet. #### Follow the pricing page Visit the [pricing page](/price.md#onecall) to learn more about pricing. > One Call API 4.0 is included only in a separate subscription and allows you to pay only for the number of API calls made to this product. Please find more details on the [pricing page](/price.md#onecall). #### 2,000 API calls per day Once you subscribe to One Call API 4.0, 2,000 API calls per day to this product are set up by default. If you want to change this limit, please go to the ["Billing plans" tab](https://home.openweathermap.org/subscriptions)in your Personal account to update standard settings. You can find more information on the [FAQ](/faq.md#onecall) or ask [Ulla, OpenWeather AI assistant](/chat.md). #### Desired type of data Select the desired data type and make an API call according to the relevant technical documentation section, remembering to add your key to each call. ## Pagination & response limits Some One Call API 4.0 endpoints may return large datasets, especially when requesting forecast or historical weather data. To improve API performance and ensure efficient data delivery, responses can be split into multiple pages. When pagination is applied, the API response includes a fully prepared URL for retrieving the next page of data. ### How pagination works 1. Send a request to the API endpoint. 2. Receive a response containing weather data and, if additional data is available, `next` or `prev` fields. 3. Use the URL provided in the `next` or `prev` field to request the next or previous page of results. ### Example of API response ```json { "lat": 51.5, "lon": -0.1, "timezone": "Europe/London", "timezone_offset": 3600, "data": [ { "dt": 1777460400, "sunrise": 1777437375, "sunset": 1777490344, "moonrise": 1777482960, "moonset": 1777433400, "moon_phase": 0.43, ... } ... ], "prev": "https://api.openweathermap.org/data/4.0/onecall/timeline/1day?cnt=10&lat=51.5000&lon=-0.1000&start=1776596400&appid={API key}", "next": "https://api.openweathermap.org/data/4.0/onecall/timeline/1day?cnt=10&lat=51.5000&lon=-0.1000&start=1778324400&appid={API key}" } ``` ### Pagination parameters One Call API 4.0 uses timeline-based pagination to navigate through weather data forward and backward in time. | Parameters | | | --- | --- | | `start` | UTC date and time used as the starting point of the timeline. Records before and after this timestamp can be accessed using pagination links. If `start` is not specified, the current UTC time is used by default. | | `next` | URL for retrieving the next portion of records forward in the timeline. | | `prev` | URL for retrieving the previous portion of records backward in the timeline. | Each endpoint returns a fixed maximum number of records per response. Please refer to the corresponding endpoint documentation for response record limits. ### Response record limits Each One Call API 4.0 endpoint has a maximum number of records that can be returned in a single response. These limits are described in the corresponding endpoint sections of the documentation. If the available dataset exceeds the response limit, the API response includes `next` and/or `prev` URLs that can be used to continue retrieving data across the timeline. > Please note that each paginated request made using the `next` or `prev` URLs is counted as a separate API call according to your subscription plan. ## Current weather data The API endpoint returns current weather conditions for a specific location with core meteorological parameters such as temperature, feels-like temperature, pressure, humidity, dew point, UV index, cloud cover, visibility, wind speed, wind direction, sunrise and sunset times, and weather condition descriptors with icons. This endpoint is useful for apps and services that need an instant snapshot of weather at a location. If you are interested in other functionality on One Call API 4.0, please check [Product concept](/api/one-call-4.md#concept) to follow the right section. ### How to make an API call ### API call ```text https://api.openweathermap.org/data/4.0/onecall/current?lat={lat}&lon={lon}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude, decimal (-90; 90). If you need to automatically convert city names and ZIP codes into geographic coordinates, or vice versa, please use our [Geocoding API](/api/geocoding-api.md) | | `lon` | Yes | Longitude, decimal (-180; 180). If you need to automatically convert city names and ZIP codes into geographic coordinates, or vice versa, please use our [Geocoding API](/api/geocoding-api.md) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | You can use the `lang` parameter to get the output in your language. [Learn more](#multi) | ### Example of API call Before making an API call, please note that One Call 4.0 is included in the "One Call by Call" subscription **only**. [Learn more](/price.md) ### Example of API call ```text https://api.openweathermap.org/data/4.0/onecall/current?lat=52.2297&lon=21.0122&units=metric&lang=en&appid={API key} ``` ### Example of API response ```json { "lat": 51.5, "lon": -0.1, "timezone": "Europe/London", "timezone_offset": 3600, "data": [ { "dt": 1777449371, "sunrise": 1777437375, "sunset": 1777490344, "temp": 286.42, "feels_like": 285.32, "pressure": 1024, "humidity": 58, "dew_point": 278.34, "uvi": 1.55, "clouds": 0, "visibility": 10000, "wind_speed": 8.23, "wind_deg": 70, "weather": [ { "id": 800, "main": "Clear", "description": "sky is clear", "icon": "01d" } ] "alerts": [ "8B46C632-DCA7-44D7-8BDF-02445621BAFF", "29F58A35-BB91-4A73-9F46-9FC64BDF604F", ... ] } ] } ``` ### Fields in API response > If you do not see some of the parameters in your API response, it means these weather phenomena did not occur at the time of measurement for the selected city or location. Only measured or calculated data is displayed in the API response. **Current weather endpoint returns 1 record in the API response.** - `lat` Latitude of the location, decimal (−90; 90) - `lon` Longitude of the location, decimal (-180; 180) - `timezone` Timezone name for the requested location - `timezone_offset` Shift in seconds from UTC - - `data.dt` Current time, Unix, UTC - `data.sunrise` Sunrise time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `data.sunset` Sunset time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `data.temp` Temperature. Units - default: kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](#data) - `data.feels_like` Temperature. This temperature parameter accounts for the human perception of weather. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. - `data.pressure` Atmospheric pressure at sea level, hPa - `data.humidity` Humidity, % - `data.dew_point` Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit - `data.clouds` Cloudiness, % - `data.uvi` Current UV index. - `data.visibility` Average visibility, metres. The maximum value of the visibility is 10 km - `data.wind_speed` Wind speed. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](#data) - `data.wind_gust` (where available) Wind gust. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](#data) - `data.wind_deg` Wind direction, degrees (meteorological) - `data.rain` - `data.rain.1h` (where available) Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter - `data.snow` - `data.snow.1h` (where available) Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter - `data.weather` - `data.weather.id` [Weather condition id](/weather-conditions.md#Weather-Condition-Codes-2) - `data.weather.main` Group of weather parameters (Rain, Snow etc.) - `data.weather.description` Weather condition within the group ([full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2)). Get the output in [your language](#multi) - `data.weather.icon` Weather icon id. [How to get icons](/weather-conditions.md#How-to-get-icon-URL) - `data.alerts` Array of weather alert IDs associated with the requested location and time. Each ID can be used to retrieve detailed information about the corresponding alert via the Weather Alert detailed information endpoint. National weather alerts are provided in English by default. Please note that some agencies provide the alert’s description only in a local language. ## 1 minute step timeline ### How to make an API call ### API call ```text https://api.openweathermap.org/data/4.0/onecall/timeline/1min?lat={lat}&lon={lon}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude, decimal (-90; 90). If you need to automatically convert city names and ZIP codes into geographic coordinates, or vice versa, please use our [Geocoding API](/api/geocoding-api.md) | | `lon` | Yes | Longitude, decimal (-180; 180). If you need to automatically convert city names and ZIP codes into geographic coordinates, or vice versa, please use our [Geocoding API](/api/geocoding-api.md) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | You can use the `lang` parameter to get the output in your language. [Learn more](#multi) | ### Example of API call ### Example of API call ```text https://api.openweathermap.org/data/4.0/onecall/timeline/1min?lat=51.5&lon=-0.1&appid={API key} ``` ### Example of API response ```json { "lat": 51.5, "lon": -0.1, "timezone": "Europe/London", "timezone_offset": 3600, "data": [ { "dt": 1777451940, "precipitation": 0, "alerts": [ "8B46C632-DCA7-44D7-8BDF-02445621BAFF", "29F58A35-BB91-4A73-9F46-9FC64BDF604F", ... ], ... ] } ``` > **The 1-minute timeline returns up to 60 records in the API response.** ### Fields in API response - `lat` Latitude of the location, decimal (−90; 90) - `lon` Longitude of the location, decimal (-180; 180) - `timezone` Timezone name for the requested location - `timezone_offset` Shift in seconds from UTC - `data` - - `data.dt` Time of the forecasted data, unix, UTC - `data.precipitation` Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter - `data.alerts` Array of weather alert IDs associated with the requested location and time. Each ID can be used to retrieve detailed information about the corresponding alert via the Weather Alert detailed information endpoint. National weather alerts are provided in English by default. Please note that some agencies provide the alert’s description only in a local language. ## 15 minutes step timeline ### How to make an API call ### API call ```text https://api.openweathermap.org/data/4.0/onecall/timeline/15min?lat={lat}&lon={lon}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude, decimal (-90; 90). If you need to automatically convert city names and ZIP codes into geographic coordinates, or vice versa, please use our [Geocoding API](/api/geocoding-api.md) | | `lon` | Yes | Longitude, decimal (-180; 180). If you need to automatically convert city names and ZIP codes into geographic coordinates, or vice versa, please use our [Geocoding API](/api/geocoding-api.md) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | You can use the `lang` parameter to get the output in your language. [Learn more](#multi) | ### Example of API call ### Example of API call ```text https://api.openweathermap.org/data/4.0/onecall/timeline/15min?lat=51.5&lon=-0.1&appid={API key} ``` ### Example of API response ```json { "lat": 51.5, "lon": -0.1, "timezone": "Europe/London", "timezone_offset": 3600, "data": [ { "dt": 1777452300, "temp": 287.95, "feels_like": 286.75, "pressure": 1024, "humidity": 48, "dew_point": 277.2, "uvi": 2.36, "clouds": 0, "visibility": 10000, "wind_speed": 7.41, "wind_deg": 70, "pop": 0, "weather": [ { "id": 800, "main": "Clear", "description": "sky is clear", "icon": "01d" } ], "alerts": [ "8B46C632-DCA7-44D7-8BDF-02445621BAFF", "29F58A35-BB91-4A73-9F46-9FC64BDF604F", ... ] }, ... ], "next": "https://api.openweathermap.org/data/4.0/onecall/timeline/15min?lat=51.5000&lon=-0.1000&start=1777497300&appid={API key}" } ``` > **The 15-minute timeline returns up to 50 records in a single API response.** To retrieve the full dataset, please check the `next` parameter in the API response. If present, it contains a fully prepared URL for requesting the next portion of records. If the `next` parameter is not returned, it means the full dataset has already been retrieved. For more details, see the [Pagination & response limits](#pagination) section. ### Fields in API response - `lat` Latitude of the location, decimal (−90; 90) - `lon` Longitude of the location, decimal (-180; 180) - `timezone` Timezone name for the requested location - `timezone_offset` Shift in seconds from UTC - `data` - - `data.dt` Time of the forecasted data, Unix, UTC - `data.temp` Temperature. Units - default: kelvin, metric: Celsius, imperial: Fahrenheit. How to change units used - `data.feels_like` Temperature. This temperature parameter accounts for the human perception of weather. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. - `data.pressure` Atmospheric pressure on the sea level, hPa - `data.humidity` Humidity, % - `data.dew_point` Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit - `data.clouds` Cloudiness, % - `data.uvi` UV index. - `data.visibility` Average visibility, metres. The maximum value of the visibility is 10 km - `data.wind_speed` Wind speed. Wind speed. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. How to change units used - `data.wind_gust` (where available) Wind gust. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. How to change units used - `data.wind_deg` Wind direction, degrees (meteorological) - `data.rain` - - `data.rain.1h` (where available) Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter - `data.snow` - - `data.snow.1h` (where available) Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter - `data.weather` - - `data.weather.id` Weather condition id - `data.weather.main` Group of weather parameters (Rain, Snow etc.) - `data.weather.description` Weather condition within the group (full list of weather conditions). Get the output in your language - `data.weather.icon` Weather icon id. How to get icons - `data.alerts` Array of weather alert IDs associated with the requested location and time. Each ID can be used to retrieve detailed information about the corresponding alert via the Weather Alert detailed information endpoint. National weather alerts are provided in English by default. Please note that some agencies provide the alert’s description only in a local language. - `prev` API-generated request URL that can be used to retrieve the previous portion of data relative to the current time range. This link allows navigation to earlier records using the same query parameters. - `next` API-generated request URL that can be used to retrieve the next portion of data relative to the current time range. This link allows navigation to later records using the same query parameters. ## 1 hour step timeline ### How to make an API call ### API call ```text https://api.openweathermap.org/data/4.0/onecall/timeline/1h?lat={lat}&lon={lon}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude, decimal (-90; 90). If you need to automatically convert city names and ZIP codes into geographic coordinates, or vice versa, please use our [Geocoding API](/api/geocoding-api.md) | | `lon` | Yes | Longitude, decimal (-180; 180). If you need to automatically convert city names and ZIP codes into geographic coordinates, or vice versa, please use our [Geocoding API](/api/geocoding-api.md) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | You can use the `lang` parameter to get the output in your language. [Learn more](#multi) | ### Example of API call ### Example of API call ```text https://api.openweathermap.org/data/4.0/onecall/timeline/1h?lat=51.5&lon=-0.1&appid={API key} ``` > **The 1-hour timeline returns up to 20 records in a single API response. **To retrieve the full dataset, please use the `next` and `prev` parameters returned in the API response. These parameters contain fully prepared URLs for requesting the following or previous portions of records within the timeline. If the `next` or `prev` parameter is not returned, it means there are no additional records available in that direction. For more details, see the [Pagination & response limits](#pagination) section. ### Fields in API response - `lat` Latitude of the location, decimal (−90; 90) - `lon` Longitude of the location, decimal (-180; 180) - `timezone` Timezone name for the requested location - `timezone_offset` Shift in seconds from UTC - `data` - - `data.dt` Time of the forecasted data, Unix, UTC - `data.temp` Temperature. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](https://openweathermap.org/api/one-call-4#data) - `data.feels_like` Temperature. This accounts for the human perception of weather. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. - `data.pressure` Atmospheric pressure on the sea level, hPa - `data.humidity` Humidity, % - `data.dew_point` Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. - `data.uvi` UV index - `data.clouds` Cloudiness, % - `data.visibility` Average visibility, metres. The maximum value of the visibility is 10 km - `data.wind_speed` Wind speed. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour.[How to change units used](https://openweathermap.org/api/one-call-4#data) - `data.wind_gust` (where available) Wind gust. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](https://openweathermap.org/api/one-call-4#data) - `data.wind_deg` Wind direction, degrees (meteorological) - `data.pop` Probability of precipitation. The values of the parameter vary between 0 and 1, where 0 is equal to 0%, 1 is equal to 100% - `data.rain` - - `data.rain.1h` (where available) Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter - `data.snow` - - `data.snow.1h` (where available) Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter - `data.weather` - - `hourly.weather.id` [Weather condition id](https://openweathermap.org/weather-conditions#Weather-Condition-Codes-2) - `hourly.weather.main` Group of weather parameters (Rain, Snow etc.) - `hourly.weather.description` Weather condition within the group ([full list of weather conditions](https://openweathermap.org/weather-conditions#Weather-Condition-Codes-2)). Get the output in [your language](https://openweathermap.org/api/one-call-4#multi) - `hourly.weather.icon` Weather icon id. [How to get icons](https://openweathermap.org/weather-conditions#How-to-get-icon-URL) - `data.alerts` Array of weather alert IDs associated with the requested location and time. Each ID can be used to retrieve detailed information about the corresponding alert via the Weather Alert detailed information endpoint. National weather alerts are provided in English by default. Please note that some agencies provide the alert’s description only in a local language. - `prev` API-generated request URL that can be used to retrieve the previous portion of data relative to the current time range. This link allows navigation to earlier records using the same query parameters. - `next` API-generated request URL that can be used to retrieve the next portion of data relative to the current time range. This link allows navigation to later records using the same query parameters. ## 1 day step timeline ### How to make an API call ### API call ```text https://api.openweathermap.org/data/4.0/onecall/timeline/1day?lat={lat}&lon={lon}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude, decimal (-90; 90). If you need to automatically convert city names and ZIP codes into geographic coordinates, or vice versa, please use our [Geocoding API](/api/geocoding-api.md) | | `lon` | Yes | Longitude, decimal (-180; 180). If you need to automatically convert city names and ZIP codes into geographic coordinates, or vice versa, please use our [Geocoding API](/api/geocoding-api.md) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | You can use the `lang` parameter to get the output in your language. [Learn more](#multi) | ### Example of API call ### Example of API call ```text https://api.openweathermap.org/data/4.0/onecall/timeline/1day?lat=51.5&lon=-0.1&appid={API key} ``` ### Example of API response ```json { "lat": 51.5, "lon": -0.1, "timezone": "Europe/London", "timezone_offset": 3600, "data": [ { "dt": 1777460400, "sunrise": 1777437375, "sunset": 1777490344, "moonrise": 1777482960, "moonset": 1777433400, "moon_phase": 0.43, "temp": { "day": 288.16, "min": 280.7, "max": 290.05, "night": 285.7, "eve": 289.38, "morn": 282.78 }, "feels_like": { "day": 286.89, "night": 284.58, "eve": 288.31, "morn": 279.89 }, "pressure": 1024, "humidity": 45, "dew_point": 276.33, "wind_speed": 8.35, "wind_deg": 76, "wind_gust": 15.34, "weather": [ { "id": 800, "main": "Clear", "description": "sky is clear", "icon": "01d" } ], "clouds": 0, "pop": 0, "uvi": 4.82 }, ... ], "prev": "https://api.openweathermap.org/data/4.0/onecall/timeline/1day?cnt=10&lat=51.5000&lon=-0.1000&start=1776596400&appid={API key}", "next": "https://api.openweathermap.org/data/4.0/onecall/timeline/1day?cnt=10&lat=51.5000&lon=-0.1000&start=1778324400&appid={API key}" } ``` > **The 1-day timeline returns up to 10 records in a single API response. **To retrieve the full dataset, please use the `next` and `prev` parameters returned in the API response. These parameters contain fully prepared URLs for requesting the following or previous portions of records within the timeline. If the `next` or `prev` parameter is not returned, it means there are no additional records available in that direction. For more details, see the [Pagination & response limits](#pagination) section. ### Fields in API response - `lat` Latitude of the location, decimal (−90; 90) - `lon` Longitude of the location, decimal (-180; 180) - `timezone` Timezone name for the requested location - `timezone_offset` Shift in seconds from UTC - `data` - - `data.dt` Time of the forecasted data, Unix, UTC - `data.temp` Temperature. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](https://openweathermap.org/api/one-call-4#data) - `data.feels_like` Temperature. This accounts for the human perception of weather. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. - `data.pressure` Atmospheric pressure on the sea level, hPa - `data.humidity` Humidity, % - `data.dew_point` Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. - `data.uvi` UV index - `data.clouds` Cloudiness, % - `data.visibility` Average visibility, metres. The maximum value of the visibility is 10 km - `data.wind_speed` Wind speed. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour.[How to change units used](https://openweathermap.org/api/one-call-4#data) - `data.wind_gust` (where available) Wind gust. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](https://openweathermap.org/api/one-call-4#data) - `data.wind_deg` Wind direction, degrees (meteorological) - `data.pop` Probability of precipitation. The values of the parameter vary between 0 and 1, where 0 is equal to 0%, 1 is equal to 100% - `data.rain` - - `data.rain.1h` (where available) Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter - `data.snow` - - `data.snow.1h` (where available) Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter - `data.weather` - - `data.weather.id` [Weather condition id](https://openweathermap.org/weather-conditions#Weather-Condition-Codes-2) - `data.weather.main` Group of weather parameters (Rain, Snow etc.) - `data.weather.description` Weather condition within the group ([full list of weather conditions](https://openweathermap.org/weather-conditions#Weather-Condition-Codes-2)). Get the output in [your language](https://openweathermap.org/api/one-call-4#multi) - `data.weather.icon` Weather icon id. [How to get icons](https://openweathermap.org/weather-conditions#How-to-get-icon-URL) - `data.alerts` Array of weather alert IDs associated with the requested location and time. Each ID can be used to retrieve detailed information about the corresponding alert via the Weather Alert detailed information endpoint. National weather alerts are provided in English by default. Please note that some agencies provide the alert’s description only in a local language. - `prev` API-generated request URL that can be used to retrieve the previous portion of data relative to the current time range. This link allows navigation to earlier records using the same query parameters. - `next` API-generated request URL that can be used to retrieve the next portion of data relative to the current time range. This link allows navigation to later records using the same query parameters. ## Weather Alert detailed information The **Weather Alert detailed information** endpoint provides full information about a specific weather alert by its ID. The response includes the alert source, event name, validity period, and a detailed description of the expected weather hazard and its potential impacts. ### How to make an API call ### API call ```text https://api.openweathermap.org/data/4.0/onecall/alert/{alert_id}?appid=KEY ``` | Parameters | | | | --- | --- | --- | | `alert_id` | Yes | Alert ID | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### Example of API call ### Example of API call ```text https://api.openweathermap.org/data/4.0/onecall/alert/8B46C632-DCA7-44D7-8BDF-02445621BAFF?appid={API key} ``` ### Example of API response ```json { "id": "8B46C632-DCA7-44D7-8BDF-02445621BAFF", "sender_name": "NWS Tulsa (Eastern Oklahoma)", "event": "Heat Advisory", "start": 1597341600, "end": 1597366800, "description": "...HEAT ADVISORY REMAINS IN EFFECT FROM 1 PM THIS AFTERNOON TO\n8 PM CDT THIS EVENING...\n* WHAT...Heat index values of 105 to 109 degrees expected.\n* WHERE...Creek, Okfuskee, Okmulgee, McIntosh, Pittsburg,\nLatimer, Pushmataha, and Choctaw Counties.\n* WHEN...From 1 PM to 8 PM CDT Thursday.\n* IMPACTS...The combination of hot temperatures and high\nhumidity will combine to create a dangerous situation in which\nheat illnesses are possible." } ``` ### Fields in the API response **Weather alerts endpoint returns 1 record in the API response.** • `id` Alert ID • `sender_name` Name of the alert source. Please see the full list of alert sources here. • `event` Alert event name • `start` Date and time of the start of the alert, Unix, UTC • `end` Date and time of the end of the alert, Unix, UTC • `description` Description of the alert ## Other features ### List of weather condition codes A list of [weather condition codes](/weather-conditions.md) with icons, including thunderstorm, drizzle, rain, snow, clouds, atmosphere, etc. ### Units of measurement `standard`, `metric` and `imperial` units are available. [List of all API parameters with available units.](/weather-data.md) ### API call ```text https://api.openweathermap.org/data/4.0/onecall/current?lat={lat}&lon={lon}&units={units}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. | > Temperature is available in Fahrenheit, Celsius and Kelvin units. > > Wind speed is available in miles/hour and meter/sec. > > - For temperature in Fahrenheit and wind speed in miles/hour, use `units=imperial` > - For temperature in Celsius and wind speed in meter/sec, use `units=metric` > - Temperature in Kelvin and wind speed in meter/sec is used by default, so there is no need to use the units parameter in the API call if you want this ### Examples of API calls ### Standard (default) ```text https://api.openweathermap.org/data/4.0/onecall/current?lat=30.489772&lon=-99.771335&appid={API key} ``` ### Metric ```text https://api.openweathermap.org/data/4.0/onecall/current?lat=30.489772&lon=-99.771335&units=metric&appid={API key} ``` ### Imperial ```text https://api.openweathermap.org/data/4.0/onecall/current?lat=30.489772&lon=-99.771335&units=imperial&appid={API key} ``` ### Multilingual support You can use `lang` parameter to get the output in your language. The contents of the `description` field will be translated. ### API call ```text https://api.openweathermap.org/data/4.0/onecall/current?lat={lat}&lon={lon}&lang={lang}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lang` | optional | You can use the `lang` parameter to get the output in your language. | ### Example of API call Before making an API call, please note that One Call 4.0 is included in the "One Call by Call" subscription **only**. [Learn more](/price.md) ```text https://api.openweathermap.org/data/4.0/onecall/current?lat=30.489772&lon=-99.771335&lang=zh_cn&appid={API key} ``` We support the following languages. To select one, you can use the corresponding language code: - `sq` Albanian - `af` Afrikaans - `ar` Arabic - `az` Azerbaijani - `eu` Basque - `be` Belarusian - `bg` Bulgarian - `ca` Catalan - `zh_cn` Chinese Simplified - `zh_tw` Chinese Traditional - `hr` Croatian - `cz` Czech - `da` Danish - `nl` Dutch - `en` English - `fi` Finnish - `fr` French - `gl` Galician - `de` German - `el` Greek - `he` Hebrew - `hi` Hindi - `hu` Hungarian - `is` Icelandic - `id` Indonesian - `it` Italian - `ja` Japanese - `kr` Korean - `ku` Kurmanji (Kurdish) - `la` Latvian - `lt` Lithuanian - `mk` Macedonian - `no` Norwegian - `fa` Persian (Farsi) - `pl` Polish - `pt` Portuguese - `pt_br` Português Brasil - `ro` Romanian - `ru` Russian - `sr` Serbian - `sk` Slovak - `sl` Slovenian - `sp, es` Spanish - `sv, se` Swedish - `th` Thai - `tr` Turkish - `ua, uk` Ukrainian - `vi` Vietnamese - `zu` Zulu ### List of national weather alerts sources | Country | Agency | | --- | --- | | Albania | Institute of GeoSciences, Energy, Water and Environment of Albania | | Algeria | National Meteorological Office | | Argentina | National Weather Service of Argentina | | Australia | Australian Bureau of Meteorology | | Austria | Central Institute for Meteorology and Geodynamics Water Balance Department | | Bahrain | Bahrain Meteorological Directorate | | Barbados | Barbados Meteorological Service | | Belarus | State institution "Republican center for hydrometeorology, control of radioactive contamination and environmental monitoring" (Belhydromet) | | Belgium | Royal Meteorological Institute | | Belize | National Meteorological Service of Belize | | Benin | National Meteorological Agency (METEO-BENIN) | | Bosnia and Herzegovina | Federal Hydrometeorological Institute of BiH Republic Hydrometeorological Institute | | Botswana | Botswana Meteorological Services | | Brazil | National Meteorological Institute - INMET | | Bulgaria | National Institute of Meteorology and Hydrology - Plovdiv branch | | Cameroon | Cameroon National Meteorological Service | | Canada | Alberta Emergency Management Agency (Government of Alberta, Ministry of Municipal Affairs) Meteorological Service of Canada Quebec Ministry of Public Safety Yukon Emergency Measures Organization Manitoba Emergency Management Organization | | Chile | Meteorological Directorate of Chile | | Congo | National Civil Aviation Agency (ANAC Congo) | | Costa Rica | National Meteorological Institute of Costa Rica | | Croatia | State Hydrometeorological Institute (DHMZ) | | Curacao and Sint Maarten | Meteorological Department Curacao | | Cyprus | Republic of Cyprus - Department of Meteorology | | Czech Republic | Czech Hydrometeorological Institute | | Denmark | Danish Meteorological Institute | | Ecuador | Ecuadoran Institute for Meteorology and Hydrology (INAMHI) | | Egypt | Egyptian Meteorological Authority | | Estonia | Estonian Environment Agency | | Eswatini | Eswatini Meteorological Service | | Finland | Finnish Meteorological Institute | | France | Meteo-France | | Gabon | General Directorate of Meteorology of Gabon | | Germany | German Meteorological Office | | Ghana | Ghana Meteorological Agency | | Greece | Hellenic National Meteorological Service | | Guinea | National Meteorological Agency of Guinea | | Guyana | Hydrometeorological Service of Guyana | | Hong Kong China | Hong Kong Observatory | | Hungary | Hungarian Meteorological Service | | Iceland | Icelandic Meteorological Office | | India | India Meteorological Department | | Indonesia | Agency for Meteorology Climatology and Geophysics of Republic Indonesia (BMKG) InaTEWS BMKG | | Ireland | Met Eireann - Irish Meteorological Service | | Israel | Israel Meteorological Service | | Italy | Italian Air Force National Meteorological Service | | Ivory Coast | Airport, aeronautical and meteorological operating and development company (SODEXAM) | | Jamaica | Meteorological Service of Jamaica | | Japan | Japan Meteorological Business Support Center | | Jordan | Jordanian Meteorological Department | | Kazakhstan | National Hydrometeorological Service of the Republic of Kazakhstan (Kazhydromet) | | Kenya | Kenya Meteorological Department | | Kuwait | Kuwait Meteorological Department | | Latvia | Latvian Environment, Geology and Meteorology Center | | Lesotho | Lesotho Meteorological Services | | Libya | Libyan National Meteorological Center | | Lithuania | Lithuanian Hydrometeorological Service under the Ministry of Environment of the Republic of Lithuania (LHMS) | | Luxembourg | Luxembourg Airport Administration | | Macao China | Macao Meteorological and Geophysical Bureau | | Madagascar | METEO Madagascar | | Malawi | Malawi Department of Climate Change and Meteorological Services | | Maldives | Maldives Meteorological Service | | Mauritania | National Meteorological Office of Mauritania | | Mauritius | Mauritius Meteorological Services | | Mexico | CONAGUA - National Meteorological Service of Mexico | | Moldova | State Hydrometeorological Service of Moldova | | Mongolia | National Agency Meteorology and the Environmental Monitoring of Mongolia | | Mozambique | National Institute of Meteorology of Mozambique | | Myanmar | Myanmar Department of Meteorology and Hydrology | | Netherlands | Royal Netherlands Meteorological Institute (KNMI) | | New Zealand | Meteorological Service of New Zealand Limited National Emergency Management Agency Fire and Emergency New Zealand Civil Defence Emergency Management (CDEM) Groups | | New Zealand | New Zealand Emergency Mobile Alert | | Niger | National Meteorological Directorate of Niger | | Nigeria | Nigerian Meteorological Agency (NiMet) | | North Macedonia | National Hydrometeorological Service - Republic of Macedonia | | Norway | Norwegian Meteorological Institute Norwegian Water Resources and Energy Directorate | | Paraguay | Directorate of Meteorology and Hydrology | | Philippines | Philippine Atmospheric Geophysical and Astronomical Services Administration | | Poland | Institute of Meteorology and Water Management (IMGW-PIB) | | Portugal | Portuguese Institute of Sea and Atmosphere, I.P. | | Qatar | Qatar Meteorology Department | | Republic of Korea | Korea Meteorological Administration, Weather Information | | Romania | National Meteorological Administration | | Russia | Hydrometcenter of Russia | | Saudi Arabia | National Center for Meteorology - Kingdom of Saudi Arabia | | Serbia | Republic Hydrometeorological Service of Serbia | | Seychelles | Seychelles Meteorological Authority | | Singapore | Meteorological Service Singapore | | Slovakia | Slovak Hydrometeorological Institute | | Slovenia | National Meteorological Service of Slovenia | | Solomon Islands | Solomon Islands Meteorological Services | | South Africa | South African Weather Service (SAWS) | | Spain | State Meteorological Agency (AEMET) | | Sudan | Sudan Meteorological Authority | | Sweden | Swedish Meteorological and Hydrological Institute | | Switzerland | MeteoSwiss | | Tanzania | Tanzania Meteorological Authority | | Thailand | Thai Meteorological Department | | Timor-Leste | National Directorate of Meteorology and Geophysics of Timor-Leste | | Trinidad and Tobago | Trinidad and Tobago Meteorological Service | | Ukraine | Ukrainian Hydrometeorological Center | | United Arab Emirates (UAE) | National Center of Meteorology (NCM), United Arab Emirates | | United Kingdom of Great Britain and Northern Ireland | UK Met Office | | Uruguay | Uruguayan Institute of Meteorology | | USA | Environmental Protection Agency (EPA), Air Quality Alerts Integrated Public Alert and Warning System (IPAWS) National Oceanic and Atmospheric Administration (NOAA), National Tsunami Warning Center National Oceanic and Atmospheric Administration (NOAA), National Weather Service National Oceanic and Atmospheric Administration (NOAA), National Weather Service - Marine Zones U.S. Geological Survey (USGS), Volcano Hazard Program | | Uzbekistan | Uzhydromet | | Yemen | Yemeni Civil Aviation and Meteorology Authority (CAMA) | | Zambia | Meteorological Department Zambia | | Zimbabwe | Meteorological Services Department | Please note that some agencies in the list may stop providing us with weather alert information. In case you don’t receive alerts from any agency, please [contact us](mailto:info@openweathermap.org). We are constantly working to improve our product by expanding the list of partner agencies. ### Callback function for JavaScript code To use JavaScript code, you can pass the `callback` function name to the JSONP callback. ## API errors ### Structure of API errors If an incorrect API call is made, you will receive an API error response. The error response payload is returned for all types of errors using the structure below. ### Example of error response ```json { "cod":400, "message":"Invalid date format", "parameters": [ "date" ] } ``` ### Fields in error response - `cod` Code of error - `message` Description of error - `parameters` (optional) List of request parameters names that are related to this particular error ### Errors list Please find more detailed information about some common errors below. #### API calls return an error 400 Error 400 - Bad Request. You can get 400 error if either some mandatory parameters in the request are missing or some of the request parameters have an incorrect format or values outside the allowed range. A list of all parameter names that are missing or incorrect will be returned in `parameters` attribute of the `ErrorResponse` object. #### API calls return an error 401 Error 401 - Unauthorized. You may receive a 401 error if the API key is missing from the request, or if the API key provided does not grant access to this API. Add an API key with access to the required product before making the request again. #### API calls return an error 404 Error 404 - Not Found. You may receive a 404 error if data for the requested parameters, such as `lat`, `lon`, or `date`, is not available in the service database. Do not retry the same request without changing the parameters. #### API calls return an error 429 Error 429 - Too Many Requests. You may receive a 429 error if the request quota for the provided API key has been exceeded for this API. You may retry the request after some time, or after increasing the quota for your API key. #### API calls return 5xx errors Errors 5xx - Unexpected Error. You may receive a 5xx error if an unexpected internal error occurs. You may retry the request. If the issue continues, please [contact us](https://home.openweathermap.org/questions) and include an example API request that returns this error so we can investigate it. --- # One Call 4.0 Product description ## Product Overview [One Call API 4.0](/api/one-call-4.md) is a unified weather intelligence API designed to give developers, digital products, and enterprise teams access to current weather, short-term forecasts, long-range daily outlooks, historical weather records, and official weather alerts through a single integration. Instead of combining multiple weather endpoints and datasets, users can request highly relevant weather information for any latitude and longitude from one product family built around a consistent response structure. The API is built for applications that need both speed and depth. It supports immediate operational use cases such as current conditions and next-minute precipitation monitoring, while also enabling more advanced analytics with hourly and daily timelines that combine historical data with forecast data. This makes [One Call API 4.0](/api/one-call-4.md) suitable for real-time user experiences, operational planning, data analysis, and weather-driven business decisions. ## Core Value [One Call API 4.0](/api/one-call-4.md) simplifies weather data access by consolidating multiple temporal layers of weather information into one coherent API product. With a single [API key](https://home.openweathermap.org/api_keys) and a standard request model based on geographic coordinates, teams can access: - Current weather conditions - Minute-by-minute forecast data for the next 60 minutes - 15-minute forecast data for the next 48 hours - Hourly weather timelines spanning 47+ years of history and 48 hours of forecast - Daily weather timelines spanning 47+ years of history and up to 1.5 years ahead - Detailed weather alert information from national agencies This combination helps businesses reduce integration complexity, shorten development time, and create richer weather-aware experiences across consumer, commercial, and industrial use cases. ## Key Product Capabilities **1. Current Weather in Real Time** The API returns current weather conditions for a specific location with core meteorological parameters such as temperature, feels-like temperature, pressure, humidity, dew point, UV index, cloud cover, visibility, wind speed, wind direction, sunrise and sunset times, and weather condition descriptors with icons. This endpoint is useful for apps and services that need an instant snapshot of weather at a location. **2. Hyperlocal Next-Minute Forecasting** One Call API 4.0 includes a 1-minute forecast timeline for the next 60 minutes. This is especially valuable for products that need highly responsive precipitation monitoring and short-term decision support, such as mobility services, event platforms, logistics tools, outdoor consumer apps, and smart city solutions. **3. Intra-Day Forecasting in 15-Minute Resolution** For near-term planning, the API provides 15-minute forecast data covering up to 48 hours ahead. This supports operational decisions that need more granularity than hourly updates, including staffing, route planning, outdoor scheduling, field service coordination, and customer-facing forecast visualizations. **4. Unified Hourly Timeline Across Past and Future** One of the strongest differentiators of the product is its hourly weather timeline endpoint, which combines historical weather data going back 47+ years with forecast data extending 48 hours ahead. This allows users to work with one consistent hourly dataset for retrospective analysis, benchmarking, anomaly detection, and forward planning without switching between separate products. **5. Unified Daily Timeline Across Past and Future** The daily timeline endpoint brings together long-range historical weather data and forward-looking daily data in a single structure. It spans 47+ years of history and extends into future daily coverage, including short-range forecast data and long-range daily outlooks up to 1.5 years ahead. This is especially useful for trend analysis, seasonal planning, demand modeling, agriculture, insurance, and climate-sensitive business forecasting. **6. Official Weather Alert Access** The API includes alert references in weather responses and supports a dedicated alert endpoint for retrieving detailed warning information issued by national agencies. Alert payloads include the alert ID, source, event name, start and end timestamps, and full descriptive text. This helps teams enrich their products with actionable warning content and improve user safety and operational awareness. ## Product Structure The main product version includes the following standard endpoints: - [Current weather](/api/one-call-4.md#current) - [1-minute timeline forecast](/api/one-call-4.md#min) - [15-minute timeline forecast](/api/one-call-4.md#15min) - [1-hour weather timeline](/api/one-call-4.md#hourly) combining history and forecast - [1-day weather timeline](/api/one-call-4.md#daily) combining history and forecast - Detailed [weather alert](/api/one-call-4.md#alerts) information In addition, the specification outlines standby endpoints for teams that may need separated forecast-only or history-only access patterns: - 1-hour forecast - 1-day forecast - 1-hour history - 1-day history This structure allows the product to serve both simplified integration needs and more advanced data retrieval strategies. ## Data Access and Request Flexibility [One Call API 4.0](/api/one-call-4.md) uses a straightforward request model centered on geographic coordinates. Core request parameters include: - `lat` and `lon` for location targeting - `units` for selecting measurement systems such as metric or imperial - `lang` for localized human-readable weather descriptions - `appid` for authentication - `start` for defining the starting timestamp - `cnt` for controlling the number of records returned The response format is consistent across endpoints and includes location metadata such as timezone and timezone offset, which makes downstream handling easier for developers building dashboards, apps, automations, and analytics pipelines. ## Designed for Scalable Integration The API is designed to support a broad range of product and platform experiences. Developers can build location-based weather widgets, travel and mobility tools, operational dashboards, enterprise analytics, forecasting engines, and alert-driven workflows on top of a single weather interface. Standardized response patterns and navigation links such as `prev` and `next` also make it easier to page through time-based datasets where applicable. Because the same product covers current, forecast, historical, and alert data, teams can reduce fragmentation in their weather stack and maintain a cleaner architecture across frontend, backend, and data workflows. ## Record Limits and Performance Control To keep responses predictable and efficient, each endpoint has defined limits on the maximum number of records returned per request. For example: - Current weather returns 1 record - 1-minute timeline returns up to 60 records - 15-minute timeline returns up to 50 records - 1-hour timeline and 1-hour history/forecast endpoints return up to 20 records - 1-day timeline and 1-day history/forecast endpoints return up to 10 records - Alert detail returns 1 record This model gives users control over how much data they request while helping ensure manageable payload sizes and consistent API behavior. ## Ideal Use Cases [One Call API 4.0](/api/one-call-4.md) is well suited for: - Consumer weather applications - Travel, mobility, and navigation products - Agriculture and outdoor operations - Logistics and supply chain planning - Energy and utilities forecasting - Insurance and risk assessment - Retail demand planning - Smart home and IoT weather automation - Business intelligence and weather analytics platforms - Safety, alerting, and operational monitoring systems ## Positioning Summary [One Call API 4.0](/api/one-call-4.md) is a comprehensive weather data product that brings together real-time conditions, high-resolution short-term forecasting, historical weather depth, long-range daily coverage, and official alert data in one flexible API. It is built for teams that need more than a simple forecast feed and want a single, scalable interface for weather-aware applications, analytics, and decision support. --- ## One Call API 2.5 > The One Call API 2.5 has been deprecated on June 2024. Please use more advanced [One Call API 4.0](/api/one-call-4.md), which contains the following fetures: > > - Current weather conditions > - Minute-by-minute forecast data for the next 60 minutes > - 15-minute forecast data for the next 48 hours > - Hourly weather timelines spanning 47+ years of history and 48 hours of forecast > - Daily weather timelines spanning 47+ years of history and up to 1.5 years ahead > - Detailed weather alert information from national agencies > > Read more about One Call API 4.0 on the [Product Documentation](/api/one-call-4.md) and the [Detailed Product Description](https://openweathermap.org/api/one-call-4-desciption) pages. Make just one API call and get all your essential weather data for a specific location with our new OpenWeather **One Call API 2.5**. [Easy migration from the Dark Sky API.](/darksky-openweather.md) The One Call API 2.5 provides the following weather data for any geographical coordinates: - Current weather - Minute forecast for 1 hour - Hourly forecast for 48 hours - Daily forecast for 7 days - National weather alerts - Historical weather data for the previous 5 days ## Current and forecast weather data To get access to current weather, minute forecast for 1 hour, hourly forecast for 48 hours, daily forecast for 7 days and government weather alerts, please use this section of the documentation. If you are interested in **historical weather data**, please read the ["Historical weather data" section](#history). ### How to make an API call ### API call ```text https://api.openweathermap.org/data/2.5/onecall?lat={lat}&lon={lon}&exclude={part}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat, lon` | Yes | Geographical coordinates (latitude, longitude) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `exclude` | optional | By using this parameter you can exclude some parts of the weather data from the API response. It should be a comma-delimited list (without spaces). Available values: `current` `minutely` `hourly` `daily` `alerts` | | `units` | optional | Units of measurement. `standard`, `metric` and `imperial` units are available. If you do not use the `units` parameter, `standard` units will be applied by default. [Learn more](#data) | | `lang` | optional | You can use the `lang` parameter to get the output in your language. [Learn more](#multi) | ### Example of API call ```text https://api.openweathermap.org/data/2.5/onecall?lat=33.44&lon=-94.04&exclude=hourly,daily&appid={API key} ``` ### Fields in API response - `lat` Geographical coordinates of the location (latitude) - `lon` Geographical coordinates of the location (longitude) - `timezone` Timezone name for the requested location - `timezone_offset` Shift in seconds from UTC - `current` **Current weather data API response** - `current.dt` Current time, Unix, UTC - `current.sunrise` Sunrise time, Unix, UTC - `current.sunset` Sunset time, Unix, UTC - `current.temp` Temperature. Units - default: kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](#data) - `current.feels_like` Temperature. This temperature parameter accounts for the human perception of weather. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. - `current.pressure` Atmospheric pressure on the sea level, hPa - `current.humidity` Humidity, % - `current.dew_point` Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. - `current.clouds` Cloudiness, % - `current.uvi` Current UV index - `current.visibility` Average visibility, metres. The maximum value of the visibility is 10km - `current.wind_speed` Wind speed. Wind speed. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](#data) - `current.wind_gust` (where available) Wind gust. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](#data) - `current.wind_deg` Wind direction, degrees (meteorological) - `current.rain` - `current.rain.1h` (where available) Rain, mm/h - `current.snow` - `current.snow.1h` (where available) Precipitation, mm/h - `current.weather` - `current.weather.id` [Weather condition id](/weather-conditions.md#Weather-Condition-Codes-2) - `current.weather.main` Group of weather parameters (Rain, Snow, Extreme etc.) - `current.weather.description` Weather condition within the group ([full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2)). Get the output in [your language](/api/one-call-api.md#multi) - `current.weather.icon` Weather icon id. [How to get icons](/weather-conditions.md#How-to-get-icon-URL) - `minutely` **Minute forecast weather data API response** - `minutely.dt` Time of the forecasted data, unix, UTC - `minutely.precipitation` Precipitation, mm/h - `hourly` **Hourly forecast weather data API response** - `hourly.dt` Time of the forecasted data, Unix, UTC - `hourly.temp` Temperature. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](#data) - `hourly.feels_like` Temperature. This accounts for the human perception of weather. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. - `hourly.pressure` Atmospheric pressure on the sea level, hPa - `hourly.humidity` Humidity, % - `hourly.dew_point` Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. - `hourly.uvi` UV index - `hourly.clouds` Cloudiness, % - `hourly.visibility` Average visibility, metres. The maximum value of the visibility is 10km - `hourly.wind_speed` Wind speed. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour.[How to change units used](#data) - `hourly.wind_gust` (where available) Wind gust. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](#data) - `chourly.wind_deg` Wind direction, degrees (meteorological) - `hourly.pop` Probability of precipitation. The values of the parameter vary between 0 and 1, where 0 is equal to 0%, 1 is equal to 100% - `hourly.rain` - `hourly.rain.1h` (where available) Rain, mm/h - `hourly.snow` - `hourly.snow.1h` (where available) Precipitation, mm/h - `hourly.weather` - `hourly.weather.id` [Weather condition id](/weather-conditions.md#Weather-Condition-Codes-2) - `hourly.weather.main` Group of weather parameters (Rain, Snow, Extreme etc.) - `hourly.weather.description` Weather condition within the group ([full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2)). Get the output in [your language](/api/one-call-api.md#multi) - `hourly.weather.icon` Weather icon id. [How to get icons](/weather-conditions.md#How-to-get-icon-URL) - `daily` **Daily forecast weather data API response** - `daily.dt` Time of the forecasted data, Unix, UTC - `daily.sunrise` Sunrise time, Unix, UTC - `daily.sunset` Sunset time, Unix, UTC - `daily.moonrise` The time of when the moon rises for this day, Unix, UTC - `daily.moonset` The time of when the moon sets for this day, Unix, UTC - `daily.moon_phase` Moon phase. `0` and `1` are 'new moon', `0.25` is 'first quarter moon', `0.5` is 'full moon' and `0.75` is 'last quarter moon'. The periods in between are called 'waxing crescent', 'waxing gibous', 'waning gibous', and 'waning crescent', respectively. - `daily.temp` Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](#data) - `daily.temp.morn` Morning temperature. - `daily.temp.day` Day temperature. - `daily.temp.eve` Evening temperature. - `daily.temp.night` Night temperature. - `daily.temp.min` Min daily temperature. - `daily.temp.max` Max daily temperature. - `daily.feels_like` This accounts for the human perception of weather. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](#data) - `daily.feels_like.morn` Morning temperature. - `daily.feels_like.day` Day temperature. - `daily.feels_like.eve` Evening temperature. - `daily.feels_like.night` Night temperature. - `daily.pressure` Atmospheric pressure on the sea level, hPa - `daily.humidity` Humidity, % - `daily.dew_point` Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form. Units – default: kelvin, metric: Celsius, imperial: Fahrenheit. - `daily.wind_speed` Wind speed. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](#data) - `daily.wind_gust` (where available) Wind gust. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](#data) - `daily.wind_deg` Wind direction, degrees (meteorological) - `daily.clouds` Cloudiness, % - `daily.uvi` The maximum value of UV index for the day - `daily.pop` Probability of precipitation. The values of the parameter vary between 0 and 1, where 0 is equal to 0%, 1 is equal to 100% - `daily.rain` (where available) Rain volume, mm - `daily.snow` (where available) Snow volume, mm - `daily.weather` - `daily.weather.id` [Weather condition id](/weather-conditions.md#Weather-Condition-Codes-2) - `daily.weather.main` Group of weather parameters (Rain, Snow, Extreme etc.) - `daily.weather.description` Weather condition within the group ([full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2)). Get the output in [your language](/api/one-call-api.md#multi) - `daily.weather.icon` Weather icon id. [How to get icons](/weather-conditions.md#How-to-get-icon-URL) - `alerts` **National weather alerts data from major national weather warning systems** - `alerts.sender_name` Name of the alert source. Please read here the [full list of alert sources](#listsource) - `alerts.event` Alert event name - `alerts.start` Date and time of the start of the alert, Unix, UTC - `alerts.end` Date and time of the end of the alert, Unix, UTC - `alerts.description` Description of the alert - `alerts.tags` Type of severe weather > National weather alerts are provided in English by default. Please note that some agencies provide the alert’s description only in a local language. --- ## How to transfer from One Call API 2.5 to the One Call API 3.0 In line with our plans to complete the migration from One Call API 2.5 to One Call API 3.0 access to One Call API 2.5 has been finally closed in June 2024. All One Call API 2.5 users are invited to the One Call API 3.0, which replicates the 2.5 version's functionality and includes several useful upgrades. One Call API 3.0 now offers advanced features demanded by businesses, such as minute-by-minute forecast for the next 1 hour, 4-day forecast for any timestamp, 8-day daily forecast, human-readable summaries, historical 47+ years archive (data both for specific timestamp and with daily aggregation), daily long-term forecast for the next 1,5 years, weather overview and others. One Call API 3.0 works in exactly the same way as the One Call API 2.5, but includes several useful upgrades. For seamless transfer from One Call API 2.5 to the One Call API 3.0 please carefully read the following sections: [Dataset comparison](#comparison) [How to start using One Call API 3.0](#how) [Matching parameters](#match) Please note that no other products are affected by this change, including other APIs that have ‘/2.5/’ section in their URL. If you have any questions or need assistance with migrating to One Call API 3.0, please do not hesitate to contact us on [info@openweathermap.org](mailto:info@openweathermap.org) ### About One Call API 3.0 [The One Call API 3.0](/api/one-call-3.md) contains 4 endpoints and provides access to various data: - [Current weather and forecasts:](/api/one-call-3.md#current) - minute forecast for 1 hour - hourly forecast for 48 hours - daily forecast for 8 days - and government weather alerts - [Weather data for any timestamp](/api/one-call-3.md#history) for 47+ years historical archive and 4 days ahead forecast - [Daily aggregation](/api/one-call-3.md#history_daily_aggregation) of weather data for 47+ years archive and 1.5 years ahead forecast - [Weather overview](/api/one-call-3.md#weather_overview) with a human-readable weather summary for today and tomorrow's forecast, utilizing OpenWeather AI technologies. - [AI Weather Assistant](/api/one-call-3.md#ai_weather_assistant) for retrieving weather data and weather-related advice in a human-readable and friendly format One Call API 3.0 offers a separate subscription model that allows you to pay based on the number of API calls you make: **1,000 API calls** per day are for free After exceeding this limit, each additional API call is charged at 0.0012 GBP - [Subscribe](https://home.openweathermap.org/subscriptions/billing_info/onecall_30/base?key=base&service=onecall_30) Please note, the One Call API 3.0 subscription requires credit card details. We use your payment card details only for those calls that go beyond the free limit. If you do not want to exceed a free limit you can always set a daily threshold for your account. For demanding projects, we provide custom One Call API 3.0 packages, tailored to your specific needs. These can include a certain volume of calls per month at a fixed monthly price, an OpenWeather end-user license (as opposed to an open CC license applicable by default), SLAs, and premium support options. If this is something you would like to discuss, please [contact our sales team](mailto:info@openweathermap.org). Please find more about One Call API 3.0 at the [documentation page](/api/one-call-3.md) and [FAQ](/faq.md#onecall). ## Dataset comparison > If you have used historical data from One Call API 2.5, please do take a note on the following changes to correctly estimate the number of requests you will be making to One Call API 3.0: A single request to One Call API 2.5 returned historical data for 1 day at hourly granularity (24 hours). If you would like to do the same via One Call API 3.0, you will need to adapt the way data are requested: > > 1. If you still require historical data for each hour of the day, please make a request to the [Weather data for timestamp](/api/one-call-3.md#history) each hour of the day (24 calls in total). > 2. If you prefer to request historical data with daily granularity, consider making 1 request to [Daily aggregation](/api/one-call-3.md#history_daily_aggregation) feature of One Call API 3.0. | One Call endpoints | One Call API 2.5 | One Call API 3.0 | | --- | --- | --- | | Current and forecast | Current weather Minute forecast for 1 hour Hourly forecast for 48 hours Daily forecast for 8 days National weather alerts | Current weather Minute forecast for 1 hour Hourly forecast for 48 hours Daily forecast for 8 days including human readable daily summary National weather alerts | | Historical weather data (One Call API 2.5) / Weather data for timestamp (One Call API 3.0) | Historical data for 5 days back | Weather data for any timestamp for 47+ years historical archive and 4 days ahead forecast | | Daily aggregation | - | Daily aggregation of weather data for 47+ years archive and 1.5 years long-term forecast | | Weather overview | - | Weather overview with a human-readable weather summary for today and tomorrow's forecast, utilizing OpenWeather AI technologies | | AI Weather Assistant | - | AI Weather Assistant for retrieving weather data and weather-related advice in a human-readable and friendly format | To match One Call API 2.5 parameters to the equivalent OpenWeather One Call API 3.0 parameters, please read ["Matching parameters"](#match) chapter. ## How to start using One Call API 3.0 #### First, subscribe Please subscribe to the One Call API 3.0 clicking 'Subscribe' button in the "One Call API 3.0" section on the [Pricing page.](/full-price.md#onecall) You will get a confirmation email and activation of your API keys can take several minutes. > You don’t need to get new API keys, your current API keys will work with One Call API 3.0 after subscribing finishing #### Second, call API: - Getting current, minute, hourly and daily forecast weather data `https://api.openweathermap.org/data/3.0/onecall?lat={lat}&lon={lon}&exclude={part}&appid=`[`{API key}`](https://home.openweathermap.org/api_keys) - Getting weather data by specified timestamp from 1st January 1979 till 4 days ahead forecast `https://api.openweathermap.org/data/3.0/onecall/timemachine?lat={lat}&lon={lon}&dt={time}&appid=`[`{API key}`](https://home.openweathermap.org/api_keys) - Getting daily aggregation weather data by specified timestamp from 2st January 1979 till 1.5 years ahead forecast `https://api.openweathermap.org/data/3.0/onecall/day_summary?lat={lat}&lon={lon}&date={date}&appid=`[`{API key}`](https://home.openweathermap.org/api_keys) - Getting weather overview with a human-readable weather summary for today and tomorrow's forecast, utilizing OpenWeather AI technologies `https://api.openweathermap.org/data/3.0/onecall/overview?lat={lat}&lon={lon}&appid=`[`{API key}`](https://home.openweathermap.org/api_keys) - Read [**AI Weather Assistant documentation**](/api/one-call-3.md#ai_weather_assistant) to get weather data and weather-related advice in a human-readable and friendly format | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude of coordinates | | `lon` | Yes | Longitude of coordinates | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `dt` | Yes | Timestamp (Unix time, UTC time zone), e.g. dt=1586468027. Data is available from January 1st, 1979 till 4 days ahead forecast | | `date` | Yes | Date in the YYYY-MM-DD format for which data is requested. Date is available for 47+ years archive (starting from 1979-01-02) up to the 1,5 years ahead forecast to the current date | | `exclude` | optional | By using this parameter you can exclude some parts of the weather data from the API response. It should be a comma-delimited list (without spaces). Available values: - `current` - `minutely` - `hourly` - `daily` - `alerts` | [One Call API 3.0](/api/one-call-3.md) documentation (complete description of API calls and parameters in API response, with examples). - [One Call API documentation](/api/one-call-3.md) ## Matching parameters Almost all API response fields in the One Call API 3.0 are the same as in One Call API 2.5. There are few minor differences in the API response fields between One Call API 2.5 and One Call API 3.0: - One Call API 3.0 current and forecast endpoint contain additional field `summary `with human readable daily [summary](#summary) in the daily forecast for 8 days. - One Call API 3.0 included new [Daily aggregation](api/one-call-3#history_daily_aggregation) endpoint that provides historical and forecast data for a particular date, starting from 2nd January 1979 till +1.5 years from today. - One Call API 3.0 also included new [Weather overview](api/one-call-3#weather_overview) and [AI Weather Assistant](/api/one-call-3.md#ai_weather_assistant) endpoints that provides with a human-readable weather summary for today and tomorrow's forecast and weather data and weather-related advice. - API response part containing hourly historical data starting at 00:00 on the requested day and continues until 23:59 on the same day (UTC time) is not included into One Call API 3.0. If you are interested in hourly data for last five days you can specify them using [Weather data for timestamp](/api/one-call-3.md#history) endpoint in the One Call API 3.0. Please use the below comparison [table](#match) to match One Call API 2.5 parameters to equivalent parameters of One Call API 3.0 If you do not see some of the parameters in your API response (e.g., rain), this means that these weather phenomena have not happened at your location at the time of measurement. ### Current and forecast weather data endpoint | One Сall 2.5 | One Сall 3.0 | Description | | --- | --- | --- | | `lat` | `lat` | Latitude of the location, decimal (−90; 90) | | `lon` | `lon` | Longitude of the location, decimal (-180; 180) | | `timezone` | `timezone` | Timezone name for the requested location | | `timezone_offset` | `timezone_offset` | Shift in seconds from UTC | | **Current weather data API response** | | | | `current.dt` | `current.dt` | Current time, Unix, UTC | | `current.sunrise` | `current.sunrise` | Sunrise time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response | | `current.sunset` | `current.sunset` | Sunset time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response | | `current.temp` | `current.temp` | Temperature. Units - default: Kelvin, metric: Celsius, imperial: Fahrenheit | | `current.feels_like` | `current.feels_like` | Temperature. This temperature parameter accounts for the human perception of weather. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. | | `current.pressure` | `current.pressure` | Atmospheric pressure on the sea level, hPa | | `current.humidity` | `current.humidity` | Humidity, % | | `current.dew_point` | `current.dew_point` | Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. | | `current.clouds` | `current.clouds` | Cloudiness, % | | `current.uvi` | `current.uvi` | Current UV index | | `current.visibility` | `current.visibility` | Average visibility, metres. The maximum value of the visibility is 10km | | `current.wind_speed` | `current.wind_speed` | Wind speed. Wind speed. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](/api/one-call-3.md#data) | | `current.wind_gust` (where available) | `current.wind_gust` (where available) | Wind gust. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](/api/one-call-3.md#data) | | `current.wind_deg` | `current.wind_deg` | Wind direction, degrees (meteorological) | | `current.rain.1h` (where available) | `current.rain.1h` (where available) | Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter | | `current.snow.1h` (where available) | `current.snow.1h` (where available) | Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter | | `current.weather.id` | `current.weather.id` | [Weather condition id](/weather-conditions.md#Weather-Condition-Codes-2) | | `current.weather.main` | `current.weather.main` | Group of weather parameters (Rain, Snow etc.) | | `current.weather.` `description` | `current.weather.` `description` | Weather condition within the group([full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2)). Get the output in [your language](/api/one-call-3.md#multi) | | `current.weather.icon` | `current.weather.icon` | Weather icon id. [How to get icons](/weather-conditions.md#How-to-get-icon-URL) | | **Minute forecast weather data API response** | | | | `minutely.dt` | `minutely.dt` | Time of the forecasted data, unix, UTC | | `minutely.` `precipitation` | `minutely.` `precipitation` | Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter | | **Hourly forecast weather data API response** | | | | `hourly.dt` | `hourly.dt` | Time of the forecasted data, Unix, UTC | | `hourly.temp` | `hourly.temp` | Temperature. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](/api/one-call-3.md#data) | | `hourly.feels_like` | `hourly.feels_like` | Temperature. This accounts for the human perception of weather. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. | | `hourly.pressure` | `hourly.pressure` | Atmospheric pressure on the sea level, hPa | | `hourly.humidity` | `hourly.humidity` | Humidity, % | | `hourly.dew_point` | `hourly.dew_point` | Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. | | `hourly.uvi` | `hourly.uvi` | UV index | | `hourly.clouds` | `hourly.clouds` | Cloudiness, % | | `hourly.visibility` | `hourly.visibility` | Average visibility, metres. The maximum value of the visibility is 10km | | `hourly.wind_speed` | `hourly.wind_speed` | Wind speed. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour.[How to change units used](/api/one-call-3.md#data) | | `hourly.wind_gust` (where available) | `hourly.wind_gust` (where available) | Wind gust. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](/api/one-call-3.md#data) | | `hourly.wind_deg` | `hourly.wind_deg` | Wind direction, degrees (meteorological) | | `hourly.pop` | `hourly.pop` | Probability of precipitation. The values of the parameter vary between 0 and 1, where 0 is equal to 0%, 1 is equal to 100% | | `hourly.rain.1h` (where available) | `hourly.rain.1h` (where available) | Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter | | `Hourly.snow.1h` (where available) | `Hourly.snow.1h` (where available) | Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter | | `hourly.weather.id` | `hourly.weather.id` | [Weather condition id](/weather-conditions.md#Weather-Condition-Codes-2) | | `hourly.weather.main` | `hourly.weather.main` | Group of weather parameters (Rain, Snow etc.) | | `hourly.weather.` `description` | `hourly.weather.` `description` | Weather condition within the group ([full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2)). Get the output in [your language](/api/one-call-3.md#multi) | | `hourly.weather.icon` | `hourly.weather.icon` | Weather icon id. [How to get icons](/weather-conditions.md#How-to-get-icon-URL) | | **Daily forecast weather data API response** | | | | `daily.dt` | `daily.dt` | Time of the forecasted data, Unix, UTC | | `daily.sunrise` | `daily.sunrise` | Sunrise time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response | | `daily.sunset` | `daily.sunset` | Sunset time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response | | `daily.moonrise` | `daily.moonrise` | The time of when the moon rises for this day, Unix, UTC | | `daily.moonset` | `daily.moonset` | The time of when the moon sets for this day, Unix, UTC | | `daily.moon_phase` | `daily.moon_phase` | Moon phase. 0 and 1 are 'new moon', 0.25 is 'first quarter moon', 0.5 is 'full moon' and 0.75 is 'last quarter moon'. The periods in between are called 'waxing crescent', 'waxing gibbous', 'waning gibbous', and 'waning crescent', respectively. Moon phase calculation algorithm: if the moon phase values between the start of the day and the end of the day have a round value (0, 0.25, 0.5, 0.75, 1.0), then this round value is taken, otherwise the average of moon phases for the start of the day and the end of the day is taken | | `-` | `summary` | Human-readable description of the weather conditions for the day | | `daily.temp.morn` | `daily.temp.morn` | Morning temperature. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](/api/one-call-3.md#data) | | `daily.temp.day` | `daily.temp.day` | Day temperature. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](/api/one-call-3.md#data) | | `daily.temp.eve` | `daily.temp.eve` | Evening temperature. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](/api/one-call-3.md#data) | | `daily.temp.night` | `daily.temp.night` | Night temperature. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](/api/one-call-3.md#data) | | `daily.temp.min` | `daily.temp.min` | Min daily temperature. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](/api/one-call-3.md#data) | | `daily.temp.max` | `daily.temp.max` | Max daily temperature. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](/api/one-call-3.md#data) | | `daily.feels_like.` `morn` | `daily.feels_like.` `morn` | Morning temperature. This accounts for the human perception of weather. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit.[How to change units used](/api/one-call-3.md#data) | | `daily.feels_like.` `day` | `daily.feels_like.` `day` | Day temperature This accounts for the human perception of weather. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](/api/one-call-3.md#data) | | `daily.feels_like.` `eve` | `daily.feels_like.` `eve` | Evening temperature. This accounts for the human perception of weather. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](/api/one-call-3.md#data) | | `daily.feels_like.` `night` | `daily.feels_like.` `night` | Night temperature. This accounts for the human perception of weather. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. [How to change units used](/api/one-call-3.md#data) | | `daily.pressure` | `daily.pressure` | Atmospheric pressure on the sea level, hPa | | `daily.humidity` | `daily.humidity` | Humidity, % | | `daily.dew_point` | `daily.dew_point` | Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. | | `daily.wind_speed` | `daily.wind_speed` | Wind speed. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](/api/one-call-3.md#data) | | `daily.wind_gust` (where available) | `daily.wind_gust` (where available) | Wind gust. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](/api/one-call-3.md#data) | | `daily.wind_deg` | `daily.wind_deg` | Wind direction, degrees (meteorological) | | `daily.clouds` | `daily.clouds` | Cloudiness, % | | `daily.uvi` | `daily.uvi` | The maximum value of UV index for the day | | `daily.pop` | `daily.pop` | Probability of precipitation. The values of the parameter vary between 0 and 1, where 0 is equal to 0%, 1 is equal to 100% | | `daily.rain` (where available) | `daily.rain` (where available) | Precipitation volume, mm. Please note that only mm as units of measurement are available for this parameter | | `daily.snow` (where available) | `daily.snow` (where available) | Snow volume, mm. Please note that only mm as units of measurement are available for this parameter | | `daily.weather.id` | `daily.weather.id` | [Weather condition id](/weather-conditions.md#Weather-Condition-Codes-2) | | `daily.weather.main` | `daily.weather.main` | Group of weather parameters (Rain, Snow etc.) | | `daily.weather.` `description` | `daily.weather.` `description` | Weather condition within the group ([full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2)). Get the output in [your language](/api/one-call-3.md#multi) | | `daily.weather.icon` | `daily.weather.icon` | Weather icon id. [How to get icons](/weather-conditions.md#How-to-get-icon-URL) | | **National weather alerts data from major national weather warning systems** | | | | `alerts.` `sender_name` | `alerts.` `sender_name` | Name of the alert source. Please read here the [full list of alert sources](/api/one-call-3.md#listsource) | | `alerts.event` | `alerts.event` | Alert event name | | `alerts.start` | `alerts.start` | Date and time of the start of the alert, Unix, UTC | | `alerts.end` | `alerts.end` | Date and time of the end of the alert, Unix, UTC | | `alerts.` `description` | `alerts.` `description` | Description of the alert | | `alerts.tags` | `alerts.tags` | Type of severe weather | ### Historical weather data (One Call 2.5) / Weather data for timestamp (One Call 3.0) | One Сall 2.5 | One Сall 3.0 | Description | | --- | --- | --- | | `lat` | `lat` | Latitude of the location, decimal (−90; 90) | | `lon` | `lon` | Longitude of the location, decimal (-180; 180) | | `timezone` | `timezone` | Timezone name for the requested location | | `timezone_offset` | `timezone_offset` | Shift in seconds from UTC | | **Data point dt refers to the requested time, rather than the current time** | | | | `current.dt` | `data.dt` | Requested time, Unix, UTC | | `current.sunrise` | `data.sunrise` | Sunrise time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response | | `current.sunset` | `data.sunset` | Sunset time, Unix, UTC. For polar areas in midnight sun and polar night periods this parameter is not returned in the response | | `current.temp` | `data.temp` | Temperature. Units - default: Kelvin, metric: Celsius, imperial: Fahrenheit | | `current.feels_like` | `data.feels_like` | Temperature. This temperature parameter accounts for the human perception of weather. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. | | `current.pressure` | `data.pressure` | Atmospheric pressure on the sea level, hPa | | `current.humidity` | `data.humidity` | Humidity, % | | `current.dew_point` | `data.dew_point` | Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. | | `current.clouds` | `data.clouds` | Cloudiness, % | | `current.uvi` | `data.uvi` | UV index. Please pay attention that historical UV index data available only for 5 days back. If you would like to get historical UVI index data starting from 20th September 2020 please [contact us.](mailto:info@openweathermap.org) | | `current.visibility` | `data.visibility` | Average visibility, metres. The maximum value of the visibility is 10km | | `current.wind_speed` | `data.wind_speed` | Wind speed. Wind speed. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](/api/one-call-3.md#data) | | `current.wind_gust` (where available) | `data.wind_gust` (where available) | Wind gust. Units – default: metre/sec, metric: metre/sec, imperial: miles/hour. [How to change units used](/api/one-call-3.md#data) | | `current.wind_deg` | `data.wind_deg` | Wind direction, degrees (meteorological) | | `current.rain.1h` (where available) | `data.rain.1h` (where available) | Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter | | `current.snow.1h` (where available) | `data.snow.1h` (where available) | Precipitation, mm/h. Please note that only mm/h as units of measurement are available for this parameter | | `current.weather.id` | `data.weather.id` | Weather condition id | | `current.weather.main` | `data.weather.main` | Group of weather parameters (Rain, Snow etc.) | | `current.weather.` `description` | `data.weather.` `description` | Weather condition within the group ([full list of weather conditions](/weather-conditions.md#Weather-Condition-Codes-2)). Get the output in [your language](/api/one-call-3.md#multi) | | `current.weather.icon` | `data.weather.icon` | Weather icon id.[How to get icons](/weather-conditions.md#How-to-get-icon-URL) | API response part containing hourly historical data starting at 00:00 on the requested day and continues until 23:59 on the same day (UTC time) is not included into One Call API 3.0. If you are interested in hourly data for last five days you can specify them using [Weather data for timestamp](/api/one-call-3.md#history) endpoint in the One Call API 3.0. --- ## OpenWeather alerts API ### Product concept OpenWeather Alerts service provides users with alerts about the occurrence of certain weather conditions and phenomena on a particular territory. Weather alerts can include both extreme weather events and non-extreme ones. OpenWeather Alerts are based on our unique OpenWeather ML forecasting model which uses a number of data sources - radars, models from global meteorological agencies (e.g., Met Office, NOAA, ECMWF), weather satellites, and a vast network of weather stations. **Alert** is a notification of the occurrence of specified weather conditions or phenomena in an area located or intersecting with the user’s location. The alert is generated based on OpenWeather data or data from the national weather agency. For each forecasted weather condition and phenomenon, the product contents the following information: - Alert description (Hail, Tornado, Extreme low temperature, Air Quality Alert etc.) - Affected area that is presented as exact coordinates of the polygon to which the alert applies - Date and time of the event - Source of data (Source of alert: government, OpenWeather) - Severity (The condition of being severe. There are 5 types of severity: unknown, minor, moderate, severe, extreme. Please find more details in the ["Supporting information"](/openweather-alerts.md#severity) chapter). - Certainty (Alert’s probability level. There are 5 types of certainty: observed, likely, possible, unlikely, unknown. Please find more details in the ["Supporting information"](/openweather-alerts.md#certainty) chapter). - Urgency (The urgency level of taking the alert to actions. There are 4 types of urgency: immediate, expected, future, unknown. Please find more details in the ["Supporting information"](/openweather-alerts.md#urgency) chapter). - Tag (weather phenomena type, the full list of tags is listed below): - - Coastal_event - Extreme_low_temperature - Extreme_high_temperature - Wind - Flood - Sand_dust - Rain - Fire_warning - Marine_event - Avalanches - Fog - Air_quality - Tornado - Cyclone - Snow_ice - Thunderstorm - Hail - Insight (A parameter that describes what decision/action should be taken when the weather conditions specified in the trigger occur. Each insight will correspond to one specific industry and one weather phenomenon. Please find few examples in the "Supporting information" chapter ["Alerts insights and weather conditions"](/openweather-alerts.md#insights) section). OpenWeather provides a pull API method to allow clients to request alerts data as frequently as required. Product update time: hourly Data format: JSON Product has global coverage. The service provide users an opportunity to filter alerts by: - Area of interest - can be specified as a point, or polygon - Weather parameters or specific phenomenon (alerts tag) - Data source - Industry - Urgency - start_date and end_date ## How it works Initially, OpenWeather engineers and meteorologists team select weather parameters and phenomena and their values and establish tailored weather triggers based on critical weather parameters and phenomena relevant to the user's industry and specific circumstances. Subsequently, the system generates prompt and readily accessible alerts containing forecasted weather information spanning up to 5 days in advance. Each forecasted day is segmented into 24 1-hour intervals, enabling the collection of active alert data for each hour. Consequently, this results in the creation of up to 5*24 hourly segments for the forthcoming 5 days. The system undergoes hourly updates to produce a fresh set of hourly segments for the next 5 days. The most recent set of hourly segments is actual. Forecast duration can be extended upon request. The system undergoes hourly updates to produce a fresh set of hourly segments for the next 5 days. The most recent set of hourly segments is actual. Users have the flexibility to customize their received alerts by specifying: - start_date and end_date - A geographical area of interest - Preferred weather conditions - Severity levels - Other relevant parameters If the user's chosen area of interest intersects with the alert zone, they will receive notifications containing relevant geometrical data pertaining to forecasted or observed weather parameters and phenomena. Read chapter [below](/openweather-alerts.md#apicall) to find how to make an API call to get weather alerts. ## How to make an API call In this section you will find detailed information on how to make requests to the OpenWeather Alerts API, examples of API calls and API responses. If you need to make an API call to the location type Point please use the section ["API call to the location type Point"](/openweather-alerts.md#point). If you need to make an API call to the location type Polygon please use the section ["API call to the location type Polygon"](/openweather-alerts.md#polygon). ### API call to the location type Polygon To get access to OpenWeather alerts to the location type Polygon please use this section of documentation. If you are interested in OpenWeather alerts to the location type Point please use the section ["API call to the location type Point"](/openweather-alerts.md#point). In this section you will find detailed information on how to make [request](/openweather-alerts.md#api-polygon) to the OpenWeather Alerts API, [examples](/openweather-alerts.md#api-example) of API call and [API response](/openweather-alerts.md#response-example). ### API call ```text https://api.openweathermap.org/alerts/1.0?location={"type":"Polygon","coordinates":[[[lon,lat]...]]}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | location | Yes | Location of interest with a pair of coordinates: lon - longitude of the coordinates, decimal (-180; 180); lat - latitude of the coordinates, decimal (-90; 90). Location must correspond to the geometry field [geojson](https://geojson.org/) | | source | optional | Source of alert. Available values: owm, government. To choose all possible sources of alerts leave this field empty | | industry | optional | Industry of interest. Please contact us to customize this parameter in accordance with your needs. | | start_date | optional | Date and time starting from which alerts will be returned in the ISO format. Current time is used if the parameter is not specified. Example: 2024-01-01T12:30:00+00:00 | | end_date | optional | Date and time in ISO format up to which need to get alerts. Next hour is used if the parameter is not specified. Example: 2024-01-01T12:30:00+00:00 | | tags | optional | One or more particular types of weather phenomenon to look for. Available values : coastal_event, extreme_low_temperature, extreme_high_temperature, wind, flood, sand_dust, rain, fire_warning, marine_event, avalanches, fog, air_quality, tornado, cyclone, snow_ice, thunderstorm, hail. To choose all possible tags leave this field empty. Weather phenomenon should be listed in the format: tags=parameter1,parameter2,...parameterN Example: tags=snow,ice,thunderstorm | | severity | optional | Severity of the alert. Available values: unknown, minor, moderate, severe, extreme. To choose all possible severity levels leave this field empty | | certainty | optional | Certainty of the alert. Available values: unknown, unlikely, possible, likely, observed. To choose all possible certainty levels leave this field empty | | urgency | optional | Urgency of the alert. Available values: unknown, future, expected, immediate. To choose all possible urgency levels leave this field empty | | show_location | optional | Displaying the location, specified in the API request, in the API response. Available values: false, true. If you do not use the `show_location` parameter, `true` will be applied by default | ### Example of API call ```text https://api.openweathermap.org/alerts/1.0?location={"type":"Polygon","coordinates":[[[109.072266,-9.62148],[108.896484,-44.787594],[157.060547,-44.787594],[157.763672,-9.62148],[109.072266,-9.62148]]]}&appid={API key} ``` ### Fields in API response - `alert_ID` - alert ID - `source` - source of alert - `title`- title of the alert - `industry`- alerts industries - - `industry_name` - name of the industry - - `description` - description of the insight for the industry - `severity` - severity of the alert for the industry - `tag` - One or more particular types of weather phenomenon to look for - `location` - representation of the area, where the alert is forecasted - - `type` - the type of geometry. Possible values: point; polygon - `coordinates` - List of the coordinates of the polygons vertices - `certainty` - Certainty of the alert. May be one of Observed, Likely, Possible, Unlikely, Unknown - `urgency` - urgency of the alert. May be one of Immediate, Expected, Future, Unknown ### API call to the location type Point To get access to OpenWeather alerts to the location type Point please use this section of documentation. If you are interested in OpenWeather alerts to the location type Polygon please use the section ["API call to the location type Polygon"](/openweather-alerts.md#polygon). In this section you will find detailed information on how to make [request](/openweather-alerts.md#api-point) to the OpenWether Alerts API, [examples](/openweather-alerts.md#api-point-example) of API call and [API response](/openweather-alerts.md#response-point-example). ### API call ```text https://api.openweathermap.org/alerts/1.0?location={"type":"Point","coordinates":[lon,lat]}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | location | Yes | Location of interest with a pair of coordinates: lon - longitude of the coordinates, decimal (-180; 180); lat - latitude of the coordinates, decimal (-90; 90). Location must correspond to the geometry field [geojson](https://geojson.org/) | | source | optional | Source of alert. Available values: owm, government. To choose all possible sources of alerts leave this field empty | | industry | optional | Industry of interest. Please contact us to customize this parameter in accordance with your needs. | | start_date | optional | Date and time starting from which alerts will be returned in the ISO format. Current time is used if the parameter is not specified. Example: 2024-01-01T12:30:00+00:00 | | end_date | optional | Date and time in ISO format up to which need to get alerts. Next hour is used if the parameter is not specified. Example: 2024-01-01T12:30:00+00:00 | | tags | optional | One or more particular types of weather phenomenon to look for. Available values : coastal_event, extreme_low_temperature, extreme_high_temperature, wind, flood, sand_dust, rain, fire_warning, marine_event, avalanches, fog, air_quality, tornado, cyclone, snow_ice, thunderstorm, hail. To choose all possible tags leave this field empty. Weather phenomenon should be listed in the format: tags=parameter1,parameter2,...parameterN Example: tags=snow,ice,thunderstorm | | severity | optional | Severity of the alert. Available values: unknown, minor, moderate, severe, extreme. To choose all possible severity levels leave this field empty | | certainty | optional | Certainty of the alert. Available values: unknown, unlikely, possible, likely, observed. To choose all possible certainty levels leave this field empty | | urgency | optional | Urgency of the alert. Available values: unknown, future, expected, immediate. To choose all possible urgency levels leave this field empty | | show_location | optional | Displaying the location, specified in the API request, in the API response. Available values: false, true. If you do not use the `show_location` parameter, `true` will be applied by default | ### Example of API call ```text https://api.openweathermap.org/alerts/1.0?&location={"type":"Point","coordinates":[125.850425,-28.464529]}&appid={API key} ``` ### Fields in API response - `count` - Number of alerts matched with given filters - `items` - - `hour` - number of hour - `date` - date in ISO format - `alerts` - alert related information - - `alert_ID` - alert ID - `source` - source of alert - `title`- title of the alert - `industry`- alerts industries - - `industry_name` - name of the industry - - `description` - description of the insight for the industry - `severity` - severity of the alert for the industry - `tag` - One or more particular types of weather phenomenon to look for - `location` - representation of the area, where the alert is forecasted - - `type` - the type of geometry. Possible values: point; polygon - `coordinates` - List of the coordinates of the polygons vertices - `certainty` - Certainty of the alert. May be one of Observed, Likely, Possible, Unlikely, Unknown - `urgency` - urgency of the alert. May be one of Immediate, Expected, Future, Unknown ## Supporting information This chapter contains information about [Urgency](/openweather-alerts.md#urgency), [Certainty](/openweather-alerts.md#certainty), [Severity](/openweather-alerts.md#severity) content and their usage as well as alerts insights and weather conditions description. ### Urgency content and usage | Type of urgency | General description | | --- | --- | | `immediate` | Is calling for immediate attention means right now of or relating to the here and now occurring, acting, or accomplished without loss or interval of time | | `expected` | There is some time for preparation. is calling for attention to events expected in the nearest days | | `future` | Is calling for future attention | | `unknown` | Used for case where urgency is not specified | ### Certainty content and usage | Type of certainty | General description | | --- | --- | | `observed` | For events which have been started in the past or started and continuing | | `likely` | Show high probability of event occurrence | | `possible` | Show medium probability of event occurrence | | `unlikely` | Show low probability of event occurrence | | `unknown` | Used for case where certainty is not specified | ### Severity content and usage | Type of severiry | General description | | --- | --- | | `unknown` | Used for case where severity is not specified | | `minor` | Probability of serious consequences is small | | `moderate` | Probability of serious consequences is medium | | `severe` | Probability of serious consequences is high | | `extreme` | Probability of serious consequences is very high | ### Alerts insights and weather conditions examples | Name of weather alert | Severity | Weather condition | Industry insight | | --- | --- | --- | --- | | `Extreme high temperature` | Extreme | temp > 39 | Extreme high temperatures can strain power grids as demand peaks for cooling, potentially leading to grid outages due to increased load. | | `Extreme low temperature` | Extreme | temp <= -11 | Extreme low temperatures can significantly elevate heating energy demand, putting additional strain on the power grid and increasing the risk of grid outages. | | `Coastal event` | Variable | YES | Coastal events, including storms and high winds, can lead to power grid outages due to damage to coastal infrastructure and power lines. | ## API errors ### Structure of API errors In case of incorrected API call you will receive an API error response. Error response payload returned for all types of errors with the structure below. ### Example of error response ```json { "code":400, "message":"Invalid parameter format", "parameters": [ "lat" ] } ``` ### Fields in error response - `code` - Code of error - `message` - Description of error - `parameters`(optional) - List of request parameters names that are related to this particular error ### Errors list #### API calls return an error 400 Bad Request. Either some mandatory parameters in the request are missing or some of the request parameters have incorrect format or values out of allowed range. List of all parameters names that are missing or incorrect will be returned in the parameters attribute of the ErrorResponse object. #### API calls return an error 401 Unauthorized. You can get 401 error if API token was not provided in the request or in case API token provided in the request does not grant access to this API. You must add an API token with granted access to the product to the request before returning it. #### API calls return an error 404 Not Found. Returned in case data identified with request parameters does not exist in the service database. You must not retry the same request. #### API calls return an error 500 Internal Server Error. Returned in case of internal service error that prevented processing the request. Please refer to the message text for details. You may retry the request which led to this error. --- ## Global Weather Alerts Receive timely push notifications about severe weather. Our Global Weather alerts lets you set up push notifications for weather alerts in your projects and apps. We collect weather warnings from a vast array of national weather warning systems, and present them in a convenient way. Please note that the dissemination of alerts issued by national weather agencies may experience delays of up to 30 minutes. ## Features of Global Weather Alerts 1. We provide all weather alerts from the entire world. We collect weather alert notifications from majority of national weather warning systems worldwide. As soon as we get a new weather alert, we process it and send to our users via push notifications. If an alert is scheduled to start more than 15 minutes in the future, it is stored and resent 15 minutes before its onset time. If an update to the same alert is received, it is treated as a separate alert for notification purposes. Users get all weather alert notifications sent to their [specified endpoint](#how). 2. All necessary data in the push notification. Each push notification contains the necessary fields, such as the headline of the alert, its start and end dates, and a description. Additionally, each alert has data about urgency, severity, certainty and sender agency, to help users classify alerts according to various criteria. Here is a [full list of the fields in the alert push notification](#fields). ## How to get access to Global Weather Alerts 1. [Sign up](https://home.openweathermap.org/users/sign_up) to OpenWeather service in case you haven't got your API key yet. 2. Follow the [pricing page](/price.md#alerts) to learn details about the API monthly price of Global Weather Alerts subscription. 3. [Contact us](mailto:info@openweathermap.org) via email to process your payment and set up access to our Global Weather Alerts. Please also provide us with the endpoint that all weather alerts should be sent to. Example of the endpoint [`http://test_url.test`](http://test_url.test) Then get all weather alerts to the specified endpoint via POST requests. - [Get access](mailto:info@openweathermap.org) ## Description of alert notifications ### Fields in alert notifications - `alert` - `id` Alert ID - `geometry` GeoJSON representation of the area, where the alert is forecasted - `type` The type of geometry. May be one of `Polygon` or `MultiPolygon` - `coordinates` List of the coordinates of the polygons vertices - `msg_type` Notification type, default value is `warning` - `categories` Category of the alert. Available category is Met - `urgency` Urgency of the alert. May be one of Immediate, Expected, Future, Past, Unknown - `severity` Severity of the alert. May be one of Extreme, Severe, Moderate, Minor, Unknown - `certainty` Certainty of the alert. May be one of Observed, Likely, Possible, Unlikely, Unknown - `start` Date and time of the start of the forecasted event, Unix, UTC - `end` Date and time of the end of the forecasted event, Unix, UTC - `sender` Name of the alert source. Please read here the [full list of alert sources](#listsource) - `description` - `language` Language of the alert's event name, headline, description and instruction. Please note that this field can be empty - `event` Alert event name - `headline` Headline of the alert - `description` Description of the alert - `instruction` Instructions from agency about the alert > Weather alerts are provided in English by default. Please note: > > - Some agencies provide the alert’s event name, headline, description and instruction only in a local language. > - Some agencies provide the alert’s event name, headline, description and instruction in several languages. In this case, all available languages will be listed in the "description" section. ## List of alerts sources | Country | Agency | | --- | --- | | Albania | Institute of GeoSciences, Energy, Water and Environment of Albania | | Algeria | National Meteorological Office | | Argentina | National Weather Service of Argentina | | Australia | Australian Bureau of Meteorology | | Austria | Central Institute for Meteorology and Geodynamics Water Balance Department | | Bahrain | Bahrain Meteorological Directorate | | Barbados | Barbados Meteorological Service | | Belarus | State institution "Republican center for hydrometeorology, control of radioactive contamination and environmental monitoring" (Belhydromet) | | Belgium | Royal Meteorological Institute | | Belize | National Meteorological Service of Belize | | Benin | National Meteorological Agency (METEO-BENIN) | | Bosnia and Herzegovina | Federal Hydrometeorological Institute of BiH Republic Hydrometeorological Institute | | Botswana | Botswana Meteorological Services | | Brazil | National Meteorological Institute - INMET | | Bulgaria | National Institute of Meteorology and Hydrology - Plovdiv branch | | Cameroon | Cameroon National Meteorological Service | | Canada | Alberta Emergency Management Agency (Government of Alberta, Ministry of Municipal Affairs) Meteorological Service of Canada Quebec Ministry of Public Safety Yukon Emergency Measures Organization Manitoba Emergency Management Organization | | Chile | Meteorological Directorate of Chile | | Congo | National Civil Aviation Agency (ANAC Congo) | | Costa Rica | National Meteorological Institute of Costa Rica | | Croatia | State Hydrometeorological Institute (DHMZ) | | Curacao and Sint Maarten | Meteorological Department Curacao | | Cyprus | Republic of Cyprus - Department of Meteorology | | Czech Republic | Czech Hydrometeorological Institute | | Denmark | Danish Meteorological Institute | | Ecuador | Ecuadoran Institute for Meteorology and Hydrology (INAMHI) | | Egypt | Egyptian Meteorological Authority | | Estonia | Estonian Environment Agency | | Eswatini | Eswatini Meteorological Service | | Finland | Finnish Meteorological Institute | | France | Meteo-France | | Gabon | General Directorate of Meteorology of Gabon | | Germany | German Meteorological Office | | Ghana | Ghana Meteorological Agency | | Greece | Hellenic National Meteorological Service | | Guinea | National Meteorological Agency of Guinea | | Guyana | Hydrometeorological Service of Guyana | | Hong Kong China | Hong Kong Observatory | | Hungary | Hungarian Meteorological Service | | Iceland | Icelandic Meteorological Office | | India | India Meteorological Department | | Indonesia | Agency for Meteorology Climatology and Geophysics of Republic Indonesia (BMKG) InaTEWS BMKG | | Ireland | Met Eireann - Irish Meteorological Service | | Israel | Israel Meteorological Service | | Italy | Italian Air Force National Meteorological Service | | Ivory Coast | Airport, aeronautical and meteorological operating and development company (SODEXAM) | | Jamaica | Meteorological Service of Jamaica | | Japan | Japan Meteorological Business Support Center | | Jordan | Jordanian Meteorological Department | | Kazakhstan | National Hydrometeorological Service of the Republic of Kazakhstan (Kazhydromet) | | Kenya | Kenya Meteorological Department | | Kuwait | Kuwait Meteorological Department | | Latvia | Latvian Environment, Geology and Meteorology Center | | Lesotho | Lesotho Meteorological Services | | Libya | Libyan National Meteorological Center | | Lithuania | Lithuanian Hydrometeorological Service under the Ministry of Environment of the Republic of Lithuania (LHMS) | | Luxembourg | Luxembourg Airport Administration | | Macao China | Macao Meteorological and Geophysical Bureau | | Madagascar | METEO Madagascar | | Malawi | Malawi Department of Climate Change and Meteorological Services | | Maldives | Maldives Meteorological Service | | Mauritania | National Meteorological Office of Mauritania | | Mauritius | Mauritius Meteorological Services | | Mexico | CONAGUA - National Meteorological Service of Mexico | | Moldova | State Hydrometeorological Service of Moldova | | Mongolia | National Agency Meteorology and the Environmental Monitoring of Mongolia | | Mozambique | National Institute of Meteorology of Mozambique | | Myanmar | Myanmar Department of Meteorology and Hydrology | | Netherlands | Royal Netherlands Meteorological Institute (KNMI) | | New Zealand | Meteorological Service of New Zealand Limited National Emergency Management Agency Fire and Emergency New Zealand Civil Defence Emergency Management (CDEM) Groups | | New Zealand | New Zealand Emergency Mobile Alert | | Niger | National Meteorological Directorate of Niger | | Nigeria | Nigerian Meteorological Agency (NiMet) | | North Macedonia | National Hydrometeorological Service - Republic of Macedonia | | Norway | Norwegian Meteorological Institute Norwegian Water Resources and Energy Directorate | | Paraguay | Directorate of Meteorology and Hydrology | | Philippines | Philippine Atmospheric Geophysical and Astronomical Services Administration | | Poland | Institute of Meteorology and Water Management (IMGW-PIB) | | Portugal | Portuguese Institute of Sea and Atmosphere, I.P. | | Qatar | Qatar Meteorology Department | | Republic of Korea | Korea Meteorological Administration, Weather Information | | Romania | National Meteorological Administration | | Russia | Hydrometcenter of Russia | | Saudi Arabia | National Center for Meteorology - Kingdom of Saudi Arabia | | Serbia | Republic Hydrometeorological Service of Serbia | | Seychelles | Seychelles Meteorological Authority | | Singapore | Meteorological Service Singapore | | Slovakia | Slovak Hydrometeorological Institute | | Slovenia | National Meteorological Service of Slovenia | | Solomon Islands | Solomon Islands Meteorological Services | | South Africa | South African Weather Service (SAWS) | | Spain | State Meteorological Agency (AEMET) | | Sudan | Sudan Meteorological Authority | | Sweden | Swedish Meteorological and Hydrological Institute | | Switzerland | MeteoSwiss | | Tanzania | Tanzania Meteorological Authority | | Thailand | Thai Meteorological Department | | Timor-Leste | National Directorate of Meteorology and Geophysics of Timor-Leste | | Trinidad and Tobago | Trinidad and Tobago Meteorological Service | | Ukraine | Ukrainian Hydrometeorological Center | | United Arab Emirates (UAE) | National Center of Meteorology (NCM), United Arab Emirates | | United Kingdom of Great Britain and Northern Ireland | UK Met Office | | Uruguay | Uruguayan Institute of Meteorology | | USA | Environmental Protection Agency (EPA), Air Quality Alerts Integrated Public Alert and Warning System (IPAWS) National Oceanic and Atmospheric Administration (NOAA), National Tsunami Warning Center National Oceanic and Atmospheric Administration (NOAA), National Weather Service National Oceanic and Atmospheric Administration (NOAA), National Weather Service - Marine Zones U.S. Geological Survey (USGS), Volcano Hazard Program | | Uzbekistan | Uzhydromet | | Yemen | Yemeni Civil Aviation and Meteorology Authority (CAMA) | | Zambia | Meteorological Department Zambia | | Zimbabwe | Meteorological Services Department | Please note that some agencies from the list may cease to provide us the weather alert information. In case you don’t receive alerts from any agency, please [contact us](mailto:info@openweathermap.org). We constantly work on our product’s improvement and keep expanding the list of partner agencies. --- ## Relief maps This product allows you to get relief maps around the world. Set the position of the sun in parameters and you will receive accurate illumination of the earth’s surface and its relief for these conditions. You can use Relief maps as a base layer in your maps. Also, you can use Relief maps with our [Weather map layers](/api/weather-map-2.md). This product is a combination of a layer tint (colored raster) and a hillshade. ## URL format and Parameters to get Relief maps ### URL format ```text http://maps.openweathermap.org/maps/2.0/relief/{z}/{x}/{y} ``` | Parameters | Parameters | | | --- | --- | --- | | `z` | Yes | Number of zoom level. You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `x` | Yes | Number of x tile coordinate. You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `y` | Yes | Number of y tile coordinate. You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | Optional parameters to configure the layer tint | | | | --- | --- | --- | | `opacity` | optional | Degree of relief maps opacity (layer tint and hillshade). Available value from 0 (transparent) to 1 (nontransparent). Default value - 0.8 | | `palette` | optional | Color palette. You can use custom palettes for each layer. You can also create a palette for yourself and pass it to the URL as follows {value}:{HEX color};..;{value}:{HEX color}. More information about it [here](#palette). | | `fill_bound` | optional | `true` or `false`. If `true`, then all values outside the specified set of palette values will be filled by color corresponding to the nearest specified value. Default value - `false`: all values outside the specified set of palette values are not filled. | | `mk_empty` | optional | `true` or `false`. If `true`, then all areas for which there is no relief data (for example, oceans) will be filled with the default color. If `false`, then all areas for which there is no data will be filled with empty tiles. Default value - true | | Optional parameters to configure the hillshade | | | | --- | --- | --- | | `sun_az` | optional | Azimuth angle of the light source. Degrees, 0° - West, 90° - South, 180° - East, 270° - North. Default value - 315 | | `sun_el` | optional | Altitude angle of the light source above the horizon. Degrees, 90° - Solar zenith. Default value - 45 | | `zfactor` | optional | The ratio of spatial coordinates (x, y) to height units (z). The zfactor allows adjusting the units of measure for the (z) units when they are different from the (x,y) units of the input surface. The z-values of the input surface are multiplied by the zfactor when calculating the final output surface. Default value - 0.025 | | `mix_w` | optional | Degree of layer tint and hillshade opacity. Available value from 0 to 1. If mix_w=0, then layer tint - transparent, hillshade - nontransparent. If mix_w=1, then layer tint - transparent and hillshade - nontransparent. Default value - 0.25 | ### URL example ```text http://maps.openweathermap.org/maps/2.0/relief/{z}/{x}/{y}?appid={API key} ``` > Please note that you need to insert the generated URL into the special plugins. > > For example, Leaflet, OpenLayers. You can also use any other apps that support the display of layers. [Learn more](#library) ## How to pass my palette in Relief maps? We have custom palettes, but you can use your own palette and pass it to the URL as shown `{value}:{HEX color};..;{value}:{HEX color}`. The number of values in the custom palette can be any, but not less than 2. You can set the color for any value with any precision. To pass the code of color, use the HEX format. ### URL example ```text http://maps.openweathermap.org/maps/2.0/relief/{z}/{x}/{y}?palette=0:FF0000;1000:00FF00;3000:0000FF&appid={API key} ``` ## Examples of Relief maps ### Layer tint + Hillshade `mix_w` : **0.25** `fill_bound` : **false** `sun_az` : **315** `sun_el` : **45** Default parameters ![Relief def](/payload/api/media/file/Relief_def.jpg) ### URL example ```text http://maps.openweathermap.org/maps/2.0/relief/{z}/{x}/{y}?appid={API key} ``` ### Layer tint `mix_w` : **0** `fill_bound` : **false** ![Relief tint](/payload/api/media/file/Relief_tint.jpg) ### URL example ```text http://maps.openweathermap.org/maps/2.0/relief/{z}/{x}/{y}?mix_w=0&appid={API key} ``` ### Hillshade `mix_w` : **1** `fill_bound` : **false** ![Relief hillshade](/payload/api/media/file/Relief_hillshade.jpg) ### URL example ```text http://maps.openweathermap.org/maps/2.0/relief/{z}/{x}/{y}?mix_w=1&appid={API key} ``` ### Custom illumination 1 `sun_az` : **180** `sun_el` : **135** `opacity` : **1** `fill_bound` : **false** ![Relief_180_135_op](/payload/api/media/file/Relief_180_135_op.jpg) ### URL example ```text http://maps.openweathermap.org/maps/2.0/relief/{z}/{x}/{y}?sun_az=180&sun_el=135& opacity=1&appid={API key} ``` ### Custom illumination 2 `sun_az` : **0** `sun_el` : **45** `opacity` : **1** `fill_bound` : **false** ![Relief_0_45_op](/payload/api/media/file/Relief_0_45_op.jpg) ### URL example ```text http://maps.openweathermap.org/maps/2.0/relief/{z}/{x}/{y}?sun_az=0&sun_el=45& opacity=1&appid={API key} ``` ## Libraries to connect Relief maps **Open Layers** The following functions are available for the OpenLayers library: - Classes of weather layer and weather stations layer - Possibility to set your own style - Classes with clustered markers - Support of marker server clustering **Leaflet** The OpenWeatherMap javascript library is designed to work with the Leaflet mapping service. The current version of the library allows the following: - Embedding of layer with current weather in cities - Embedding of layer with weather stations - The library supports customer clustering **Leaflet library** Another implementation of map based on Leaflet technology supports OWM's TileLayers and current city/station data. It is configurable with many options. For current city/station data the library supports refreshing the data in intervals, some types of client-side clustering (show only the station/city with the highest rank for a defined pixel square), custom image set (if you provide one), different languages ("en", "de", "ru", "fr", but translation is incomplete), minZoom and others. Source and documentation (README.md) is available on GitHub [https://github.com/buche/leaflet-openweathermap](https://github.com/buche/leaflet-openweathermap) Example of weather map: [https://github.com/owm-inc/VANE-intro/tree/master/apps](https://github.com/owm-inc/VANE-intro/tree/master/apps) Using OpenWeatherMap weather tiles with leaflet: [PDF](https://) --- ## Road Risk API ### Road Risk API concept Road Risk API provides weather data and national alerts at the point of destination and along a route. Road Risk API responds weather data with national alerts along a route that is set up as a massive of points where each point is a pair of latitude, longitude and time. For each point, the API returns air temperature, wind, precipitation, dew point. For the US and EU territories, we also provide road surface temperature and black ice road state. Active national alerts include alert description, national agency name, and the event hazardous level. Weather forecast is available for 5 days with minute granularity for the 2 hours from the current moment and hourly granularity for the rest. Historical data is accessible for 1 previous year. - [Get access](mailto:info@openweathermap.org) ## How to request Road Risk API Method: `POST` Header: `Content-Type: application/json` ### API call ```text https://api.openweathermap.org/data/2.5/roadrisk?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Geographical coordinates (latitude) of the point from the specified track | | `lon` | Yes | Geographical coordinates (longitude) of the point from the specified track | | `dt` | Yes | Date and time for each point of the specified track Unix time | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | > Please note that you can set up the date **not earlier than 1 year** from the current time and **not later than 5 days** from the current time. ### Example of the request body ```json { "track": [ { "lat": 30.680439786468128, "lon": -88.81896972656251, "dt": 1602702000 }, { "lat": 30.56699087315334, "lon": -89.44519042968751, "dt": 1602702000 } ] } ``` ## Road Risk API response ### Example of API response ```json [ { "dt": 1602702000, "coord": [ 7.27, 44.04 ], "weather": { "temp": 278.44, "wind_speed": 2.27, "wind_deg": 7, "precipitation_intensity": 0.38, "dew_point": 276.13 }, "road": { "state": 0, "temp": 293.85 }, "alerts": [ { "sender_name": "METEO-FRANCE", "event": "Moderate thunderstorm warning", "event_level": 2 } ] }, { "dt": 1602702400, "coord": [ 7.37, 45.04 ], "weather": { "temp": 282.44, "wind_speed": 1.84, "wind_deg": 316, "precipitation_intensity": 0, "dew_point": 275.99 }, "road": { "state": 0, "temp": 293.85 }, "alerts": [ ] } ] ``` ### Fields in API response - `dt` Date and time from the specified track - `coord` Coordinates from the specified track - `weather` - `weather.temp` Temperature - `weather.wind_speed` Wind speed. Units - metre/sec - `weather.wind_deg` Wind direction, degrees (meteorological) - `weather.precipitation_intensity` Intensity of precipitation, mm/hour - `weather.dew_point` Atmospheric temperature (varying according to pressure and humidity) below which water droplets begin to condense and dew can form - `road` - `road.state` (only for the US and EU territories) Road conditions. It could be one of the following values: - **0** - No report, - **16** - Black ice warning - `road.temp` (only for the US and EU territories) Road surface temperature - `alerts` - `alerts.sender_name` Name of the alert source - `alerts.event` Alert event name - `alerts.event_level` Level of the alert severity. Available values: - **0** - Unknown - **1** - Green (no awareness required) - **2** - Yellow (potential danger) - **3** - Orange (dangerous weather) - **4** - Red (very dangerous weather) ### List of national weather warning sources | Agency | Country | | --- | --- | | Institute of GeoSciences, Energy, Water and Environment of Albania | Albania | | National Meteorological Office | Algeria | | National Weather Service of Argentina | Argentina | | Australian Bureau of Meteorology | Australia | | Central Institute for Meteorology and Geodynamics Water Balance Department | Austria | | Bahrain Meteorological Directorate | Bahrain | | Barbados Meteorological Service | Barbados | | State institution "Republican center for hydrometeorology, control of radioactive contamination and environmental monitoring" (Belhydromet) | Belarus | | Royal Meteorological Institute | Belgium | | National Meteorological Service of Belize | Belize | | National Meteorological Agency (METEO-BENIN) | Benin | | Federal Hydrometeorological Institute of BiH Republic Hydrometeorological Institute | Bosnia and Herzegovina | | Botswana Meteorological Services | Botswana | | National Meteorological Institute - INMET | Brazil | | National Institute of Meteorology and Hydrology - Plovdiv branch | Bulgaria | | Cameroon National Meteorological Service | Cameroon | | Alberta Emergency Management Agency (Government of Alberta, Ministry of Municipal Affairs) Meteorological Service of Canada Quebec Ministry of Public Safety Yukon Emergency Measures Organization Manitoba Emergency Management Organization | Canada | | Meteorological Directorate of Chile | Chile | | National Civil Aviation Agency (ANAC Congo) | Congo | | National Meteorological Institute of Costa Rica | Costa Rica | | State Hydrometeorological Institute (DHMZ) | Croatia | | Meteorological Department Curacao | Curacao and Sint Maarten | | Republic of Cyprus - Department of Meteorology | Cyprus | | Czech Hydrometeorological Institute | Czech Republic | | Danish Meteorological Institute | Denmark | | Ecuadoran Institute for Meteorology and Hydrology (INAMHI) | Ecuador | | Egyptian Meteorological Authority | Egypt | | Estonian Environment Agency | Estonia | | Eswatini Meteorological Service | Eswatini | | Finnish Meteorological Institute | Finland | | Meteo-France | France | | General Directorate of Meteorology of Gabon | Gabon | | German Meteorological Office | Germany | | Ghana Meteorological Agency | Ghana | | Hellenic National Meteorological Service | Greece | | National Meteorological Agency of Guinea | Guinea | | Hydrometeorological Service of Guyana | Guyana | | Hong Kong Observatory | Hong Kong China | | Hungarian Meteorological Service | Hungary | | Icelandic Meteorological Office | Iceland | | India Meteorological Department | India | | Agency for Meteorology Climatology and Geophysics of Republic Indonesia (BMKG) InaTEWS BMKG | Indonesia | | Ireland: Met Eireann - Irish Meteorological Service | Ireland | | Israel Meteorological Service | Israel | | Italian Air Force National Meteorological Service | Italy | | Airport, aeronautical and meteorological operating and development company (SODEXAM) | Ivory Coast | | Meteorological Service of Jamaica | Jamaica | | Japan Meteorological Business Support Center | Japan | | Jordanian Meteorological Department | Jordan | | National Hydrometeorological Service of the Republic of Kazakhstan (Kazhydromet) | Kazakhstan | | Kenya Meteorological Department | Kenya | | Kuwait Meteorological Department | Kuwait | | Latvian Environment, Geology and Meteorology Center | Latvia | | Lesotho Meteorological Services | Lesotho | | Libyan National Meteorological Center | Libya | | Lithuanian Hydrometeorological Service under the Ministry of Environment of the Republic of Lithuania (LHMS) | Lithuania | | Luxembourg Airport Administration | Luxembourg | | Macao Meteorological and Geophysical Bureau | Macao China | | METEO Madagascar | Madagascar | | Malawi Department of Climate Change and Meteorological Services | Malawi | | Maldives Meteorological Service | Maldives | | National Meteorological Office of Mauritania | Mauritania | | Mauritius Meteorological Services | Mauritius | | CONAGUA - National Meteorological Service of Mexico | Mexico | | State Hydrometeorological Service of Moldova | Moldova | | National Agency Meteorology and the Environmental Monitoring of Mongolia | Mongolia | | National Institute of Meteorology of Mozambique | Mozambique | | Myanmar Department of Meteorology and Hydrology | Myanmar | | Royal Netherlands Meteorological Institute (KNMI) | Netherlands | | Meteorological Service of New Zealand Limited National Emergency Management Agency Fire and Emergency New Zealand Civil Defence Emergency Management (CDEM) Groups | New Zealand | | New Zealand Emergency Mobile Alert | New Zealand | | National Meteorological Directorate of Niger | Niger | | Nigerian Meteorological Agency (NiMet) | Nigeria | | National Hydrometeorological Service - Republic of Macedonia | North Macedonia | | Norwegian Meteorological Institute Norwegian Water Resources and Energy Directorate | Norway | | Directorate of Meteorology and Hydrology | Paraguay | | Philippine Atmospheric Geophysical and Astronomical Services Administration | Philippines | | Institute of Meteorology and Water Management (IMGW-PIB) | Poland | | Portuguese Institute of Sea and Atmosphere, I.P. | Portugal | | Qatar Meteorology Department | Qatar | | Korea Meteorological Administration, Weather Information | Republic of Korea | | National Meteorological Administration | Romania | | Hydrometcenter of Russia | Russia-EN | | Russian Federal Service for Hydrometeorology and Environmental Monitoring | Russia-RU | | National Center for Meteorology - Kingdom of Saudi Arabia | Saudi Arabia | | Republic Hydrometeorological Service of Serbia | Serbia | | Seychelles Meteorological Authority | Seychelles | | Meteorological Service Singapore | Singapore | | Slovak Hydrometeorological Institute | Slovakia | | National Meteorological Service of Slovenia | Slovenia | | Solomon Islands Meteorological Service | Solomon Islands | | South African Weather Service (SAWS) | South Africa | | State Meteorological Agency (AEMET) | Spain | | Sudan Meteorological Authority | Sudan | | Swedish Meteorological and Hydrological Institute | Sweden | | MeteoSwiss | Switzerland | | Tanzania Meteorological Authority | Tanzania | | Thai Meteorological Department | Thailand | | National Directorate of Meteorology and Geophysics of Timor-Leste | Timor-Leste | | Trinidad and Tobago Meteorological Service | Trinidad and Tobago | | Ukrainian Hydrometeorological Center | Ukraine | | UK Met Office | United Kingdom of Great Britain and Northern Ireland | | Uruguayan Institute of Meteorology | Uruguay | | Environmental Protection Agency (EPA), Air Quality Alerts Integrated Public Alerrt and Warning System (IPAWS) National Oceanic and Atmospheric Administration (NOAA), National Tsunami Warning Center National Oceanic and Atmospheric Administration (NOAA), National Weather Service National Oceanic and Atmospheric Administration (NOAA), National Weather Service - Marine Zones U.S. Geological Survey (USGS), Volcano Hazard Program | United States | | National Oceanic and Atmospheric Administration | USA | | Yemeni Civil Aviation and Meteorology Authority (CAMA) | Yemen | | Meteorological Department Zambia | Zambia | | Meteorological Services Department | Zimbabwe | --- ## Solar Irradiance API v1 ⚠️ [You are viewing an outdated version of the API. The current version is available here.](/api/solar-irradiance.md) 🔗 [Transfer guide to v2](https://) ## Product concept **Solar Irradiance & Energy Prediction** service helps to predict the energy generated by a particular solar panel before installation, or check for potential issues with existing panels. Main features of Solar Irradiance API: - Essential solar irradiation data: - [Global Horizontal Irradiation (GHI)](/api/solar-radiation/behind-solar-radiation-api.md#introduction) - [Direct Normal Irradiation (DNI)](/api/solar-radiation/behind-solar-radiation-api.md#introduction) - [Diffuse Horizontal Irradiation (DHI)](/api/solar-radiation/behind-solar-radiation-api.md#introduction) - All indices are available in [Clear Sky](/api/solar-radiation/behind-solar-radiation-api.md#clearsky) and [Cloudy Sky](/api/solar-radiation/behind-solar-radiation-api.md#cloudysky) models - Current data and forecast for 15 days ahead - Historical data is available for 47+ years back (from 1st January 1979) - Data contains daily aggregation for each requested day with hourly detalization or detalization by specified intervals - Global coverage There are two routes to receive solar data: - Get daily aggregation with detalization by 15-minute or 1-hour intervals with [Route 1](#route1) - Get daily aggregation with hourly detalization of solar irradiance data with [Route 2](#route2) Data is available in JSON format. The detailed information about what technologies, algorithms, etc. are behind the Solar Irradiance API can be found [here](/api/solar-radiation/behind-solar-radiation-api.md). ## How to get access 1. [Sign up](https://home.openweathermap.org/users/sign_up) to OpenWeather service in case you haven't got your [OpenWeather API key](https://home.openweathermap.org/api_keys) yet. 2. Follow the [pricing page](/price.md#alerts) to learn details about the price. Solar Irradiance API is included in the separate subscription only and allows you to pay only for the number of API calls made to this product. Please find more details on the [pricing page](/price.md#alerts). > Solar Irradiance API is included in the separate subscription only and allows you to pay only for the number of API calls made to this product. Please find more details on the [pricing page](/price.md#alerts). 1. Just make an API call according to the [tech documentation below](#api), remembering to add your key to each call. ## Route 1: daily aggregation with detalization by intervals In this section you will find how to request historical starting from 1st January 1979, current or forecast for 15 days ahead daily aggregated and accumulated over 1 hour or 15 minutes interval solar radiation data for particular geographical location and for specified date. If you are interested in daily aggregation with hourly detalization for solar irradiation data please use section [Route 2: daily aggregation with hourly detalization](#route2). ### How to make an API call ```text https://api.openweathermap.org/energy/1.0/solar/interval_data?lat={lat}&lon={lon}&date={date}&interval={interval}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude, decimal (−90; 90) | | `lon` | Yes | Longitude, decimal (−180; 180) | | `date` | Yes | Date in the `YYYY-MM-DD` format for which data is requested. Date available from 1979-01-01 up to +15 days to the current date | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `interval` | optional | The time interval during which the energy is summed up, defines the temporary resolution of solar radiation data. If not specified, the default interval of "1h" (1 hour) will be used. Available values for this parameter include: "1h" (1 hour) and "15m" (15 minutes) | > If the service detected timezone for your location incorrectly you can specify correct timezone manually by adding `tz` parameter in the ±XX:XX format to API call. > > API call ```text https://api.openweathermap.org/energy/1.0/solar/interval_data?lat={lat}&lon={lon}&date={date}&interval={interval}&tz={tz}&appid={API key} ``` ```text https://api.openweathermap.org/energy/1.0/solar/interval_data?lat=60.45&lon=-38.67&date=2023-03-30&interval=1h&tz=+03:00&appid={API key} ``` > Please pay attention that in case timezone is specified time of sunset and sunrise will be returned in accordance with this specified timezone. ### Example of API call ```text https://api.openweathermap.org/energy/1.0/solar/interval_data?lat=51.509865&lon=-0.118092&date=2023-10-10&interval=1h&appid={API key} ``` ### Example of API response ```json { "lat":51.509865, "lon":-0.118092, "date":"2023-10-10", "interval":"1h", "tz":"+01:00", "sunrise":"2023-10-10T07:15:03", "sunset":"2023-10-10T18:19:05", "irradiance":{ "daily":[ { "clear_sky":{ "ghi":3341.99, "dni":6736.42, "dhi":796.63 }, "cloudy_sky":{ "ghi":1321.03, "dni":189.2, "dhi":1224.62 } } ], "intervals":[ { "start":"00:00", "end":"01:00", "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "start":"01:00", "end":"02:00", "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "start":"02:00", "end":"03:00", "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "start":"03:00", "end":"04:00", "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "start":"04:00", "end":"05:00", "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "start":"05:00", "end":"06:00", "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "start":"06:00", "end":"07:00", "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "start":"07:00", "end":"08:00", "clear_sky":{ "ghi":17.5, "dni":114.15, "dhi":15.71 }, "cloudy_sky":{ "ghi":4.52, "dni":0, "dhi":4.52 } }, { "start":"08:00", "end":"09:00", "clear_sky":{ "ghi":131.24, "dni":474.04, "dhi":53.2 }, "cloudy_sky":{ "ghi":32.81, "dni":0, "dhi":32.81 } }, { "start":"09:00", "end":"10:00", "clear_sky":{ "ghi":268.29, "dni":644.2, "dhi":73.73 }, "cloudy_sky":{ "ghi":69.88, "dni":0, "dhi":69.88 } }, { "start":"10:00", "end":"11:00", "clear_sky":{ "ghi":386.42, "dni":731.64, "dhi":86.27 }, "cloudy_sky":{ "ghi":145.02, "dni":9.14, "dhi":140.94 } }, { "start":"11:00", "end":"12:00", "clear_sky":{ "ghi":469.28, "dni":777.74, "dhi":93.58 }, "cloudy_sky":{ "ghi":248.06, "dni":65.63, "dhi":215.63 } }, { "start":"12:00", "end":"13:00", "clear_sky":{ "ghi":507.51, "dni":796.21, "dhi":96.65 }, "cloudy_sky":{ "ghi":276.15, "dni":79.43, "dhi":234.49 } }, { "start":"13:00", "end":"14:00", "clear_sky":{ "ghi":497.05, "dni":791.36, "dhi":95.81 }, "cloudy_sky":{ "ghi":228.56, "dni":34.99, "dhi":210.34 } }, { "start":"14:00", "end":"15:00", "clear_sky":{ "ghi":439.01, "dni":762.13, "dhi":90.99 }, "cloudy_sky":{ "ghi":138.36, "dni":0, "dhi":138.36 } }, { "start":"15:00", "end":"16:00", "clear_sky":{ "ghi":339.55, "dni":700.92, "dhi":81.62 }, "cloudy_sky":{ "ghi":98.9, "dni":0, "dhi":98.9 } }, { "start":"16:00", "end":"17:00", "clear_sky":{ "ghi":210.63, "dni":586.34, "dhi":66.18 }, "cloudy_sky":{ "ghi":57.97, "dni":0, "dhi":57.97 } }, { "start":"17:00", "end":"18:00", "clear_sky":{ "ghi":74.12, "dni":344.83, "dhi":39.94 }, "cloudy_sky":{ "ghi":20.4, "dni":0, "dhi":20.4 } }, { "start":"18:00", "end":"19:00", "clear_sky":{ "ghi":1.38, "dni":12.85, "dhi":2.94 }, "cloudy_sky":{ "ghi":0.38, "dni":0, "dhi":0.38 } }, { "start":"19:00", "end":"20:00", "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "start":"20:00", "end":"21:00", "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "start":"21:00", "end":"22:00", "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "start":"22:00", "end":"23:00", "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "start":"23:00", "end":"00:00", "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } } ] } } ``` ### Fields in API response - `lat` Latitude of the location,decimal (−90; 90) - `lon` Longitude of the location,decimal (-180; 180) - `date` Date specified in the API request in the `YYYY-MM-DD` format (from 1979-01-01 up to +15 days to the current date) - `interval` Time interval during which the energy is summed up. Determines temporary resolution of solar radiation data. If not specified "1h" interval will be used. Available values : 1h, 15m - `tz` Timezone in the ±XX:XX format - `sunrise` Date and time of sunrise based on date specified in the API request and timezone authomatically determinated by on latitude and longitute of requested location. If you added timezone parameter into API request, then time of sunrise will be recalculated in accordance with this timezone. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `sunset`Date and time of sunset based on date specified in the API request and timezone authomatically determinated by on latitude and longitute of requested location. If you added timezone parameter into API request, then time of sunset will be recalculated in accordance with this timezone. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `irradiance`Irradiance related information - - `daily` Daily aggregated irradiation data for the requested date - - `clear sky`clear sky model - - `ghi` Clear sky GHI - [Global Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dni` Clear sky DNI - [Direct Normal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dhi` Clear sky DHI - [Diffuse Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `cloud sky`cloudy sky model - - `ghi` Cloudy sky GHI - [Global Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dni` Cloudy sky DNI - [Direct Normal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dhi` Cloudy sky DHI - [Diffuse Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - - `interval` Interval detalization of daily aggregated irradiation data for the requested date - - `start` Start of the time interval for which the energy is summed up. Time interval displays hour and minutes of the day for which indexes were aggregated in "hh:mm" format - `end` End of the time interval for which the energy is summed up. Time interval displays hour and minutes of the day for which indexes were aggregated in "hh:mm" format - `clear sky`clear sky model - - `ghi` Clear sky GHI - [Global Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dni` Clear sky DNI - [Direct Normal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dhi` Clear sky DHI - [Diffuse Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `cloudy sky`cloudy sky model - - `ghi` Cloudy sky GHI - [Global Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dni` Cloudy sky DNI - [Direct Normal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dhi` Cloudy sky DHI - [Diffuse Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 ## Route 2: daily aggregation with hourly detalization In this section you will find how to request historical starting from 1st January 1979, current or forecast for 15 days ahead daily aggregated and accumulated hourly detalization solar radiation data for particular geographical location and for specified date. If you are interested in daily aggregation with detalization by intervals for solar irradiation data please use section [Route 1: daily aggregation with detalization by intervals](#route1). ### API call ```text https://api.openweathermap.org/energy/1.0/solar/data?lat={lat}&lon={lon}&date={date}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude, decimal (−90; 90) | | `lon` | Yes | Longitude, decimal (−180; 180) | | `date` | Yes | Date in the `YYYY-MM-DD` format for which data is requested. Date available from 1979-01-01 up to +15 days to the current date | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | > If the service detected timezone for your location incorrectly you can specify correct timezone manually by adding `tz` parameter in the ±XX:XX format to API call. > > API call ### Example of API call ```text https://api.openweathermap.org/energy/1.0/solar/data?lat={lat}&lon={lon}&date={date}&tz={tz}&appid={API key} ``` ### Example of API call ```text https://api.openweathermap.org/energy/1.0/solar/data?lat=60.45&lon=-38.67&date=2023-03-30&tz=+03:00&appid={API key} ``` > Please pay attention that in case timezone is specified time of sunset and sunrise will be returned in accordance with this specified timezone. ### Example of API call ```text https://api.openweathermap.org/energy/1.0/solar/data?lat=34&lon=34&date=2023-03-28&appid={API key} ``` ### Example of API response ```json { "lat":34, "lon":34, "date":"2023-03-28", "tz":"+02:00", "sunrise":"2023-03-28T05:37:14", "sunset":"2023-03-28T18:01:37", "irradiance":{ "daily":[ { "clear_sky":{ "ghi":6383.04, "dni":8319.8, "dhi":1201.07 }, "cloudy_sky":{ "ghi":5836.23, "dni":6776.87, "dhi":1584.37 } } ], "hourly":[ { "hour":0, "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "hour":1, "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "hour":2, "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "hour":3, "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "hour":4, "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "hour":5, "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "hour":6, "clear_sky":{ "ghi":4.25, "dni":0.73, "dhi":3.52 }, "cloudy_sky":{ "ghi":3.43, "dni":0.41, "dhi":3.02 } }, { "hour":7, "clear_sky":{ "ghi":115.4, "dni":378.23, "dhi":48.82 }, "cloudy_sky":{ "ghi":90.79, "dni":247.14, "dhi":47.29 } }, { "hour":8, "clear_sky":{ "ghi":319.36, "dni":610.29, "dhi":86.67 }, "cloudy_sky":{ "ghi":261.01, "dni":369.79, "dhi":120.02 } }, { "hour":9, "clear_sky":{ "ghi":524.55, "dni":740.47, "dhi":107.61 }, "cloudy_sky":{ "ghi":398.92, "dni":360.05, "dhi":196.18 } }, { "hour":10, "clear_sky":{ "ghi":693.76, "dni":807.95, "dhi":121.26 }, "cloudy_sky":{ "ghi":520.28, "dni":378.22, "dhi":252.28 } }, { "hour":11, "clear_sky":{ "ghi":813.42, "dni":847.94, "dhi":128.46 }, "cloudy_sky":{ "ghi":730.2, "dni":667.45, "dhi":191.04 } }, { "hour":12, "clear_sky":{ "ghi":870.88, "dni":865.74, "dhi":131.59 }, "cloudy_sky":{ "ghi":829.87, "dni":787.48, "dhi":157.4 } }, { "hour":13, "clear_sky":{ "ghi":859.56, "dni":863.79, "dhi":130.63 }, "cloudy_sky":{ "ghi":826.31, "dni":784.68, "dhi":164.14 } }, { "hour":14, "clear_sky":{ "ghi":780.46, "dni":842.11, "dhi":125.07 }, "cloudy_sky":{ "ghi":775.24, "dni":825.45, "dhi":132.8 } }, { "hour":15, "clear_sky":{ "ghi":641.16, "dni":794.85, "dhi":115.22 }, "cloudy_sky":{ "ghi":639.98, "dni":789.39, "dhi":117.65 } }, { "hour":16, "clear_sky":{ "ghi":455.48, "dni":708.64, "dhi":99.7 }, "cloudy_sky":{ "ghi":455.36, "dni":708, "dhi":99.89 } }, { "hour":17, "clear_sky":{ "ghi":246.01, "dni":551.11, "dhi":74.9 }, "cloudy_sky":{ "ghi":246.08, "dni":550.99, "dhi":75 } }, { "hour":18, "clear_sky":{ "ghi":58.76, "dni":307.97, "dhi":27.63 }, "cloudy_sky":{ "ghi":58.76, "dni":307.8, "dhi":27.64 } }, { "hour":19, "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "hour":20, "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "hour":21, "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "hour":22, "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "hour":23, "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } } ] } } ``` ### Fields in API response - `lat` Latitude of the location,decimal (−90; 90) - `lon` Longitude of the location,decimal (-180; 180) - `date` Date specified in the API request in the `YYYY-MM-DD` format (from 1979-01-01 up to +15 days to the current date) - `tz` Timezone in the ±XX:XX format - `sunrise` Date and time of sunrise based on date specified in the API request and timezone authomatically determinated by on latitude and longitute of requested location. If you added timezone parameter into API request, then time of sunrise will be recalculated in accordance with this timezone. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `sunset`Date and time of sunset based on date specified in the API request and timezone authomatically determinated by on latitude and longitute of requested location. If you added timezone parameter into API request, then time of sunset will be recalculated in accordance with this timezone. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `irradiance`Irradiance related information - - `daily` Daily aggregated irradiation data for the requested date - - `clear sky`clear sky model - - `ghi` Clear sky GHI - [Global Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dni` Clear sky DNI - [Direct Normal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dhi` Clear sky DHI - [Diffuse Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `cloud sky`cloudy sky model - - `ghi` Cloudy sky GHI - [Global Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dni` Cloudy sky DNI - [Direct Normal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dhi` Cloudy sky DHI - [Diffuse Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - - `hourly` Hourly detalization of daily aggregated irradiation data for the requested date - - `hour` the ordinal number of the hour of start for which the energy is summed up. The parameter can take integer values from 0 to 23 - `clear sky`clear sky model - - `ghi` Clear sky GHI - [Global Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dni` Clear sky DNI - [Direct Normal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dhi` Clear sky DHI - [Diffuse Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `cloudy sky`cloudy sky model - - `ghi` Cloudy sky GHI - [Global Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dni` Cloudy sky DNI - [Direct Normal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dhi` Cloudy sky DHI - [Diffuse Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 ## Bulk downloading You can get the entire available historical solar irradiance archive in CSV and JSON formats: - [Solar Irradiance History Bulk](/api/solar-irradiance-history-bulks.md) - archive for 47+ years with 15-minutes and 1-hour steps, available from January 1979. - [Solar Irradiance History Forecast Bulk](/api/solar-irradiance-history-forecast-bulks.md) - archive of previously made 16 days ahead forecasts on solar irradiance data with 1-hour step (15-minutes step by request), available from April, 2017. You can find prices on the [corresponding page](/price.md#solar_energy). ## API errors In case of incorrected API call you will receive API error response. Error response payload returned for all types of errors with the structure below. ### Example of error response ```json { "code": "400", "message": "Invalid date format", "parameters": [ "date" ] } ``` - `code` Code of error - `message` Description of error - `parameters`(optional) List of request parameters names that are related to this particular error ### Errors list Please find more detailed information about some popular errors below. #### API calls return an error 400 Error 400 - Bad Request. You can get error 400 error if either some mandatory parameters in the request are missing or some of request parameters have incorrect format or values out of allowed range. List of all parameters names that are missing or incorrect will be returned in `parameters`attribute of the `ErrorResponse` object. #### API calls return an error 401 Error 401 - Unauthorized. You can get 401 error if API token did not providen in the request or in case API token provided in the request does not grant access to this API. You must add API token with granted access to the product to the request before returing it. #### API calls return an error 404 Error 404 - Not Found. You can get 404 error if data with requested parameters (`lat`, `lon` and `date`) does not exist in service database. You must not retry the same request. #### API calls return an error 429 Error 429 - Too Many Requests. You can get 429 error if key quata of requests for provided API to this API was exceeded. You may retry request after some time or after extending your key quota. #### API calls return errors '5xx' Errors 5xx - Unexpected Error. You can get '5xx' error in case of other internal errors. Error Response code will be `5xx`. Please [contact us](https://home.openweathermap.org/questions) and enclose an example of your API request that receives this error into your email to let us analyze it and find a solution for you promptly. You may retry the request which led to this error. ## Pay as you call There are no limits on the number of API calls, users pay for a subscription according to the actual use of the product. ### per API call Any location | No API call limits | Pay-as-you-call - [Subscribe](https://home.openweathermap.org/subscriptions/unauth_subscribe/energy/base) For large-scale projects, we provide a variety of custom packages. Please [get in touch](mailto:info@openweathermap.org) with us with your requirements to learn more. --- ## Solar Irradiance API ✔** This is the latest version of the API (v2).** [Looking for the previous version? You can find the v1 documentation here.](/api/solar-energy-prediction.md) ## Product concept **Solar Irradiance** service supplies accurate solar irradiance data for any location on the globe. Main features of Solar Irradiance API: - Essential solar irradiation data: - [Global Horizontal Irradiation (GHI)](/api/solar-radiation/behind-solar-radiation-api.md#introduction) - [Direct Normal Irradiation (DNI)](/api/solar-radiation/behind-solar-radiation-api.md#introduction) - [Diffuse Horizontal Irradiation (DHI)](/api/solar-radiation/behind-solar-radiation-api.md#introduction) - All indices are available in [Clear Sky](/api/solar-radiation/behind-solar-radiation-api.md#clearsky) and [Cloudy Sky](/api/solar-radiation/behind-solar-radiation-api.md#cloudysky) models - Current data and forecast for 15 days ahead - Historical data is available for 47+ years back (from 1st January 1979) - Data contains daily aggregation for each requested day with hourly detalization or detalization by specified intervals - Global coverage [You can find the previous documentation v1 here](/api/solar-energy-prediction.md#concept) Data is available in JSON format. The detailed information about what technologies, algorithms, etc. are behind the Solar Irradiance API can be found [here](/api/solar-radiation/behind-solar-radiation-api.md). ## How to get access #### Sign up [Sign up](https://home.openweathermap.org/users/sign_up) to OpenWeather service in case you haven't got your [OpenWeather API key](https://home.openweathermap.org/api_keys) yet. #### Follow the pricing page Follow the [pricing page](/price.md#alerts) to learn details about the price. > Solar Irradiance API is included in the separate subscription only and allows you to pay only for the number of API calls made to this product. Please find more details on the [pricing page](/price.md#alerts). #### Make an API call Just make an API call according to the [tech documentation below](/api/solar-irradiance.md#api), remembering to add your key to each call. ## Call Solar Irradiance data In this section you will find how to request historical starting from 1st January 1979, current or forecast for 15 days ahead daily aggregated and accumulated over 1 hour, 15 minutes or 1 day interval solar radiation data for particular geographical location and for specified date. ### How to make an API call ```text https://api.openweathermap.org/energy/2.0/solar/interval_data?lat={lat}&lon={lon}&date={date}&interval={interval}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat` | Yes | Latitude, decimal (−90; 90) | | `lon` | Yes | Longitude, decimal (−180; 180) | | `date` | Yes | Date in the `YYYY-MM-DD` format for which data is requested. Date available from 1979-01-01 up to +15 days to the current date | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `interval` | optional | The time interval during which the energy is summed up, defines the temporary resolution of solar radiation data. If not specified, the default interval of "1h" (1 hour) will be used. Available values for this parameter include: "15m" (15 minutes), "1h" (1 hour) and "1d" (1 day) | > If the service detected timezone for your location incorrectly you can specify correct timezone manually by adding `tz` parameter in the ±XX:XX format to API call. > > **API call** > > `https://api.openweathermap.org/energy/2.0/solar/interval_data?lat={lat}&lon={lon}&date={date}&interval={interval}&tz={tz}&appid=`[`{API key}`](https://home.openweathermap.org/api_keys) > > **Example of API call** > > `https://api.openweathermap.org/energy/2.0/solar/interval_data?lat=60.45&lon=-38.67&date=2023-03-30&interval=1h&tz=+03:00&appid=`[`{API key}`](https://home.openweathermap.org/api_keys) > > Please pay attention that in case timezone is specified time of sunset and sunrise will be returned in accordance with this specified timezone. ### Example of API call ```text https://api.openweathermap.org/energy/2.0/solar/interval_data?lat=51.509865&lon=-0.118092&date=2023-10-10&interval=1h&appid={API key} ``` ### Fields in API response - `lat` Latitude of the location,decimal (−90; 90) - `lon` Longitude of the location,decimal (-180; 180) - `date` Date specified in the API request in the `YYYY-MM-DD` format (from 1979-01-01 up to +15 days to the current date) - `interval` Time interval during which the energy is summed up. Determines temporary resolution of solar radiation data. If not specified "1h" interval will be used. Available values : 15m, 1h and 1d. - `tz` Timezone in the ±XX:XX format - `sunrise` Date and time of sunrise based on date specified in the API request and timezone authomatically determinated by on latitude and longitute of requested location. If you added timezone parameter into API request, then time of sunrise will be recalculated in accordance with this timezone. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `sunset` Date and time of sunset based on date specified in the API request and timezone authomatically determinated by on latitude and longitute of requested location. If you added timezone parameter into API request, then time of sunset will be recalculated in accordance with this timezone. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `intervals` Interval detalization of daily aggregated irradiation data for the requested date - `start` Start of the time interval for which the energy is summed up. Time interval displays hour and minutes of the day for which indexes were aggregated in "hh:mm" format - `end` End of the time interval for which the energy is summed up. Time interval displays hour and minutes of the day for which indexes were aggregated in "hh:mm" format - `avg_irradiance` Average irradiance per period - `clear_sky` clear sky model - `ghi` Clear sky GHI - [Global Horizontal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `dni` Clear sky DNI - [Direct Normal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `dhi` Clear sky DHI - [Diffuse Horizontal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `cloudy_sky` cloudy sky model - `ghi` Cloudy sky GHI - [Global Horizontal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `dni` Cloudy sky DNI - [Direct Normal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `dhi` Cloudy sky DHI - [Diffuse Horizontal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `max_irradiance` Maximum irradiance per period - `clear_sky` clear sky model - `ghi` Clear sky GHI - [Global Horizontal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `dni` Clear sky DNI - [Direct Normal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `dhi` Clear sky DHI - [Diffuse Horizontal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `cloudy_sky` cloudy sky model - `ghi` Cloudy sky GHI - [Global Horizontal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `dni` Cloudy sky DNI - [Direct Normal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `dhi` Cloudy sky DHI - [Diffuse Horizontal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `irradiation` Irradiation related information - `clear_sky` clear sky model - `ghi` Clear sky GHI - [Global Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dni` Clear sky DNI - [Direct Normal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dhi` Clear sky DHI - [Diffuse Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `cloudy_sky` cloudy sky model - `ghi` Cloudy sky GHI - [Global Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dni` Cloudy sky DNI - [Direct Normal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dhi` Cloudy sky DHI - [Diffuse Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 ## Bulk downloading You can get the entire available historical solar irradiance archive in CSV and JSON formats: - [Solar Irradiance History Bulk](/api/solar-irradiance-history-bulks.md) - archive for 47+ years with 15-minutes and 1-hour steps, available from January 1979. - [Solar Irradiance History Forecast Bulk](/api/solar-irradiance-history-forecast-bulks.md) - archive of previously made 16 days ahead forecasts on solar irradiance data with 1-hour step (15-minutes step by request), available from April, 2017. You can find prices on the [corresponding page](/price.md#solar_energy). ## API errors ### Structure of API errors In case of incorrected API call you will receive API error response. Error response payload returned for all types of errors with the structure below. ### Example of error response ```json { "code": "400", "message": "Invalid date format", "parameters": [ "date" ] } ``` ### Fields in error response - `code` Code of error - `message` Description of error - `parameters`(optional) List of request parameters names that are related to this particular error ### Errors list Please find more detailed information about some popular errors below. #### API calls return an error 400 Error 400 - Bad Request. You can get error 400 error if either some mandatory parameters in the request are missing or some of request parameters have incorrect format or values out of allowed range. List of all parameters names that are missing or incorrect will be returned in `parameters`attribute of the `ErrorResponse` object. #### API calls return an error 401 Error 401 - Unauthorized. You can get 401 error if API token did not providen in the request or in case API token provided in the request does not grant access to this API. You must add API token with granted access to the product to the request before returing it. #### API calls return an error 404 Error 404 - Not Found. You can get 404 error if data with requested parameters (`lat`, `lon` and `date`) does not exist in service database. You must not retry the same request. #### API calls return an error 429 Error 429 - Too Many Requests. You can get 429 error if key quata of requests for provided API to this API was exceeded. You may retry request after some time or after extending your key quota. #### API calls return errors '5xx' Errors 5xx - Unexpected Error. You can get '5xx' error in case of other internal errors. Error Response code will be `5xx`. Please [contact us](https://home.openweathermap.org/questions) and enclose an example of your API request that receives this error into your email to let us analyze it and find a solution for you promptly. You may retry the request which led to this error. ## Pay as you call There are no limits on the number of API calls, users pay for a subscription according to the actual use of the product. ### {{price.energy.base}} per API call Any location | No API call limits | Pay-as-you-call - [Subscribe](https://home.openweathermap.org/subscriptions/unauth_subscribe/energy/base) For large-scale projects, we provide a variety of custom packages. Please [get in touch](mailto:info@openweathermap.org) with us with your requirements to learn more. --- ## Solar Irradiance History Bulk ### Product concept Solar Irradiance History Bulk allows you to retrieve an archive of historical solar radiation data for selected locations in a convenient, downloadable format. - Data archive available for 47+ years (from January 1, 1979) - Includes Global Horizontal Irradiation (GHI), Direct Normal Irradiation (DNI), and Diffuse Horizontal Irradiation (DHI) - Time intervals: 15-minute and 1-hour - Output formats: JSON and CSV Solar data is generated using advanced meteorological models. More details about the underlying technology are available in the [Solar Irradiance technology section](/api/solar-radiation/behind-solar-radiation-api.md). - [Buy Solar Irradiance History Bulk](https://home.openweathermap.org/solar_irradiance_history_bulks/new) > Please contact us when requesting data for a large number of locations. We’ll be happy to prepare and export the data for you. ## How to get Solar Irradiance History Bulk To request History Bulk for your locations, please follow these steps: 1. Go to the OpenWeatherMap Marketplace and choose the ["Solar Irradiance History Bulk"](https://home.openweathermap.org/solar_irradiance_history_bulks/new) product. 2. Select locations. There are 4 ways to set your locations: 3. - **Click on the map**. Click on the map and the pin will be set on the chosen location. Click on the "Add location" to add this location into your order or click on another place on the map. - **Input a location name**.Click on the search line, input location name and choose it from the dropdown list. The chosen location will be displayed on the map, click on the "Add location" tab to add this location into your order. - **Input coordinates**. Click on the search line, choose "By coordinate" option, enter latitude and longitude to the form and push the "Enter" button on your keyboard. The chosen location will be displayed on the map, click on the "Add location" tab to add this location into your order. - **Import a list of coordinates via CSV file**. Click on the search line, choose "Import" option and follow the detailed instruction on the form to download your CSV file with a list of coordinations. 4. Set the time period for the uploaded solar irradiance archive. 5. Configure list of solar irradiance indexes, time interval and the format of the downloadable output file per your preferences. 6. Click on the "Place order" button and check your order details. 7. To complete the checkout process, please click on the "Checkout" button and proceed to payment. - [Buy Solar Irradiance History Bulk](https://home.openweathermap.org/solar_irradiance_history_bulks/new) After the successful payment you will be able to find your order in two ways: 1. You will receive a letter to your email with the link to download your current order. 2. All purchases can be also found in your personal account, in the ["Order"](https://home.openweathermap.org/marketplace/my_orders) section. ## Fields in Solar Irradiance History Bulk The output includes location metadata, timestamps, and solar radiation parameters. [JSON](#json_example) and [CSV](#csv_example) formats contain the same fields. ### Parameter definitions - `dt` Date corresponding to the start of the time interval for which energy is summed up, Unix, UTC - `dt_iso` Date corresponding to the start of the time interval for which energy is summed up, ISO format - `timezone` Shift in seconds from UTC - `lat` Latitude of the location,decimal (−90; 90) - `lon` Longitude of the location,decimal (-180; 180) - `ghi_cloudy_sky` - [Global Horizontal Irradiation](https://openweathermap.org/api/solar-radiation/behind-solar-radiation-api#introduction). Energy (Wh/m²) - `dni_cloudy_sky` - [Direct Normal Irradiation](https://openweathermap.org/api/solar-radiation/behind-solar-radiation-api#introduction). Energy (Wh/m²) - `dhi_cloudy_sky` - [Diffuse Horizontal Irradiation](https://openweathermap.org/api/solar-radiation/behind-solar-radiation-api#introduction). Energy (Wh/m²) - `ghi_clear_sky` - [Global Horizontal Irradiation](https://openweathermap.org/api/solar-radiation/behind-solar-radiation-api#introduction). Energy (Wh/m²) - `dni_clear_sky` - [Direct Normal Irradiation](https://openweathermap.org/api/solar-radiation/behind-solar-radiation-api#introduction). Energy (Wh/m²) - `dhi_clear_sky` - [Diffuse Horizontal Irradiation](https://openweathermap.org/api/solar-radiation/behind-solar-radiation-api#introduction). Energy (Wh/m²) - `ghi_cloudy_sky_avg` - [Global Horizontal Irradiance](https://openweathermap.org/api/solar-radiation/behind-solar-radiation-api#introduction). Avg power (W/m²) - `dni_cloudy_sky_avg` - [Direct Normal Irradiance](https://openweathermap.org/api/solar-radiation/behind-solar-radiation-api#introduction). Avg power (W/m²) - `dhi_cloudy_sky_avg` - [Diffuse Horizontal Irradiance](https://openweathermap.org/api/solar-radiation/behind-solar-radiation-api#introduction). Avg power (W/m²) - `ghi_clear_sky_avg` - [Global Horizontal Irradiance](https://openweathermap.org/api/solar-radiation/behind-solar-radiation-api#introduction). Avg power (W/m²) - `dni_clear_sky_avg` - [Direct Normal Irradiance](https://openweathermap.org/api/solar-radiation/behind-solar-radiation-api#introduction). Avg power (W/m²) - `dhi_clear_sky_avg` - [Diffuse Horizontal Irradiance](https://openweathermap.org/api/solar-radiation/behind-solar-radiation-api#introduction). Avg power (W/m²) - `ghi_cloudy_sky_max` - [Global Horizontal Irradiance](https://openweathermap.org/api/solar-radiation/behind-solar-radiation-api#introduction). Max power (W/m²) - `dni_cloudy_sky_max` - [Direct Normal Irradiance](https://openweathermap.org/api/solar-radiation/behind-solar-radiation-api#introduction). Max power (W/m²) - `dhi_cloudy_sky_max` - [Diffuse Horizontal Irradiance](https://openweathermap.org/api/solar-radiation/behind-solar-radiation-api#introduction). Max power (W/m²) - `ghi_clear_sky_max` - [Global Horizontal Irradiance](https://openweathermap.org/api/solar-radiation/behind-solar-radiation-api#introduction). Max power (W/m²) - `dni_clear_sky_max` - [Direct Normal Irradiance](https://openweathermap.org/api/solar-radiation/behind-solar-radiation-api#introduction). Max power (W/m²) - `dhi_clear_sky_max` - [Diffuse Horizontal Irradiance](https://openweathermap.org/api/solar-radiation/behind-solar-radiation-api#introduction). Max power (W/m²) > For Solar Irradiance bulk we can provide you with a customized set and fields order in the API response. Please [contact us](mailto:info@openweathermap.org) via email and specify your needs. ## Sample data and example Here you can find and download example of Solar Irradiance History bulk file in [JSON](#json_example) and [CSV](#csv_example) format. ### JSON sample and example You can download sample of files History Forecast bulk in JSON format using link below: [JSON](https://) Please find below an example an example of data in JSON format for one measurement. ### CSV sample and example You can download sample of files History Forecast bulk in CSV format using link below: [CSV](https://) Please find below an example of data in CSV format in tabular format. ![Table view Solar History bulk CSV](/payload/api/media/file/Table_view_Solar_History_bulk_CSV.png) --- ## Solar Irradiance History Forecast Bulk ### Product concept Solar Irradiance History Forecast Bulk is an one-off export of previously made solar irradiance forecasts for any coordinates on the globe. The archive contains a 16-day solar irradiance forecast with a 1-hour step for each day starting from April 2017 (a 15-minute forecast step is available by request). Please find detailed description in the ["Product structure"](#structure) and ["Fields in Solar Irradiance History Forecast Bulk"](#fields) sections. ## Product structure Solar Irradiance History Forecast Bulk provides a CSV archive of previously made 16 days ahead forecasts on solar irradiance data. The dataset for each day includes 4 kits of historical solar irradiance forecasts on 16 days ahead both for [clear sky](/api/solar-radiation/behind-solar-radiation-api.md#clearsky) and [cloudy sky](/api/solar-radiation/behind-solar-radiation-api.md#cloudysky) models with 1 hour step made on this specified date. Solar Irradiance forecast is generated 4 time per day at these times: 00:00 UTC, 06:00 UTC, 12:00 UTC, 18:00 UTC. Historical solar irradiance forecasts are avaiable starting from April 2017. It means that for each day, starting from April 2017, you will have four 16-day forecasts. Thus, each day has the following structure: ```text 00:00 UTC {forecast solar irradiance for 1st day - 16th day} 06:00 UTC {forecast solar irradiance for 1st day - 16th day} 12:00 UTC {forecast solar irradiance for 1st day - 16th day} 18:00 UTC {forecast solar irradiance for 1st day - 16th day} ``` The example of data can be found in the ["Sample data and examples"](#sample_and_response) section. The detailed information about what technologies, algorithms, etc. are behind the Solar Irradiance History Forecast Bulk can be founded [here](/api/solar-radiation/behind-solar-radiation-api.md). ## How to get Solar Irradiance History Forecast Bulk To request Solar Irradiance History Forecast Bulk for your locations, please [contact us](mailto:info@openweathermap.org) via email. We’ll prepare and export the data for you. ## Fields in Solar Irradiance History Forecast Bulk - `forecast_dt` Forecast calculation time in Unix timestamp - `forecast_dt_iso` Forecast calculation time in ISO format - `slice_dt` Time for which the corresponding forecast part was calculated in Unix timestamp - `slice_dt_iso` Time for which the corresponding forecast part was calculated in ISO format - `lat` Latitude of the location,decimal (-90; 90) - `lon` Longitude of the location,decimal (-180; 180) - `ghi_cloudy_sky` Cloudy sky GHI - [Global Horizontal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `dni_cloudy_sky` Cloudy sky DNI - [Direct Normal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `dhi_cloudy_sky` Cloudy sky DHI - [Diffuse Horizontal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `ghi_clear_sky` Clear sky GHI - [Global Horizontal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `dni_clear_sky` Clear sky DNI - [Direct Normal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `dhi_clear_sky` Clear sky DHI - [Diffuse Horizontal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 > For Solar Irradiance bulk we can provide you with a customized set and fields order in the API response. Please [contact us](mailto:info@openweathermap.org) via email and specify your needs. ## Sample data and example Here you can find and download example of Solar Irradiance History Forecast bulk file in CSV format. You can download sample of files History Forecast bulk in CSV format using link below: [CSV](https://) Please find below an example of data in CSV format in tabular format. ![solar-irradiance-history-forecast-bulks](/payload/api/media/file/solar-irradiance-history-forecast-bulks.png) --- ## Solar Panel Energy Prediction v1 ⚠️ [You are viewing an outdated version of the API. The current version is available here.](/api/solar-panels-and-energy-prediction-2.md) 🔗[Transfer guide to v2](https://) ## Product concept **Solar Panel Energy Prediction** API allows users to accurately estimate solar power generation and determine the energy output of each PV panel. Main features of Solar Panel Energy Prediction: - API response contains daily solar panel power output data for each solar panel with 1 hour and 15 minutes detalization - Each API response contains also essential solar irradiation data (DNI, GHI and DHI) - Current and 15 days ahead forecast data for solar panel power output - Historical solar panel power output data is available for 47+ years back (from 1st January 1979) - Create an unlimited number of solar panels for a particular location. Users could define solar panel by specifying its type, tilt and azimuth angles - Making API call to particular location get solar panel power output data for all solar panels associated with this location - Global coverage Data is available in JSON format. ## How to use the service 1. [Sign up](https://home.openweathermap.org/users/sign_up) to OpenWeather service in case you haven't got your [OpenWeather API key](https://home.openweathermap.org/api_keys) yet. Do not forget to add your key to the each API call in paragraphs 3, 4 and 5. 2. Follow the [pricing page](/price.md#solar_energy) to learn details about the price. Please note that product is available via the separate subscription only, which allows you to pay only for the created locations. 3. Create a unique location via API call according ["Step 1: Manage my location"](#step1). Create a location where your solar panels are located in accordance with chapter ["How to create a unique location"](#post_location) and receive location ID number. Please pay attention that chapters ["How to get a location"](#get_location), ["How to get a list of created locations"](#get_all_locations) ,["How to delete a location"](#delete_location) described how to manage created locations. 4. Create a solar panels for your location according ["Step 2: Operations with solar panels"](#step2). Create a solar panel for location created at the previous step according to the documentation ["How to create a solar panel"](#post_panel). Please note that you could create unlimited number of panels for one location. 5. Make an API call to get location solar panels power output and location solar irradiation data according [step 3](#step3). > Please note that product is available via the separate subscription only, which allows you to pay only for the created locations. ## Step 1: Manage my location ### How to create a unique location This HTTP method is used to create a new location and receive location ID for it. You need to pass a geographical coordinates of location in parameters. In case of successful creation method returns an HTTP code `201`. Method: `POST` Header: `Content-Type: application/json` ### URL ```text https://api.openweathermap.org/energy/1.0/locations?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### Example of API response ```json { "type": "point", "coordinates": [ { "lat": 51.507222, "lon": -0.1275 } ] } ``` | Parameters | | | | --- | --- | --- | | `type` | Yes | Type of the location. Allowed type - point | | `lat` | Yes | Latitude, decimal (−90; 90) | | `lon` | Yes | Longitude, decimal (−180; 180) | ### Example of API response ```json { "location_id": "F01E165B-22F3-4591-89D4-F238E92F6885", "type": "point", "coordinates": [ { "lat": 51.507222, "lon": -0.1275 } ] } ``` ### Fields in API response - `location_id` Unique identifier of the location assigned at resource creation - `type` Type of the location - `lat` Latitude of the location, decimal (−90; 90) - `lon` Longitude of the location, decimal (-180; 180) > Please note: > > - When creating unique locations, coordinates are rounded to 6 decimal places > - To check geographical coordinates of previously created location, please see section ["How to get location"](/api/solar-panels-and-energy-prediction.md#get_location) ### How to get a location data You could get geographical coordinates for previously created location by its id number following instruction below. In case of success method returns an HTTP code `200`. Method: `GET` ### URL ```text https://api.openweathermap.org/energy/1.0/location/{location_id}?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `location_id` | Yes | Unique identifier of the location assigned at resource creation. You could find all created locations id using instruction [here](#get_all_locations) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### URL example ```text https://api.openweathermap.org/energy/1.0/location/F01E165B-22F3-4591-89D4-F238E92F6885?appid={API key} ``` ### Example of API response ```json { "location_id": "F01E165B-22F3-4591-89D4-F238E92F6885", "type": "point", "coordinates": [ { "lat": 51.507222, "lon": -0.1275 } ] } ``` ### Fields in API response - `location_id` Unique identifier of the location assigned at resource creation - `type` Type of the location - `lat` Latitude of the location, decimal (−90; 90) - `lon` Longitude of the location, decimal (-180; 180) ### How to get a list of created locations You could get a list of all created locations using your [OpenWeather API key](https://home.openweathermap.org/api_keys) and instruction below. In case of success method returns an HTTP code `200`. Method: `GET` ### URL ```text https://api.openweathermap.org/energy/1.0/locations?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### Example of API response ```json { "location_id": "F01E165B-22F3-4591-89D4-F238E92F6885", "type": "point", "coordinates": [ { "lat": 51.5072, "lon": -0.1275 } ] } ] ``` ### Fields in API response - `location_id` Unique identifier of the location assigned at resource creation - `type` Type of the location - `lat` Latitude of the location, decimal (−90; 90) - `lon` Longitude of the location, decimal (-180; 180) ### How to delete a location You could delete created location by its id number using folowing URL. Please pay attention, that all solar panels assosiated with this location will deleted as well. In case of successful removing method returns an HTTP code `204`. Method: `DELETE` ### URL ```text https://api.openweathermap.org/energy/1.0/location/{location_id}?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `location_id` | Yes | Unique identifier of the location assigned at resource creation | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### URL example ```text https://api.openweathermap.org/energy/1.0/location/F01E165B-22F3-4591-89D4-F238E92F6885?appid={API key} ``` ### API response Please pay attention if the delete request is successfully processed, then no response will be returned. ## Step 2: Operations with solar panels ### How to create a solar panel This HTTP method is used to create a new solar panel associated with location and receive solar panel ID for this panel. You need to pass a set of solar panel parameters: tilt, azimuth and peak power. In case of successful creation method returns an HTTP code `201`. Method: `POST` Header: `Content-Type: application/json` ### URL ```text https://api.openweathermap.org/energy/1.0/location/{location_id}/panels?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `location_id` | Yes | Unique identifier of the location assigned at resource creation | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### Example of the request body ```json { "type": "mono-si", "area": 1.5, "tilt": 45, "azimuth": 182, "peak_power": 2.5 } ``` | Parameters | | | | --- | --- | --- | | `type` | Yes | PV technology type used in solar panel. In case not specified `mono-si` will be assumed. Allowed technology types: `mono-si`┃`poly-si`┃`tf-as`┃`cdte` | | `area` | Yes | Area of solar panel in square meters. In case `peak_power` is not specified then in the `POST` request then `area` must be specified instead to be able to estimate panel power output. Solar panel area must not be equal to or less than 0. | | `tilt` | Yes | Panel installation tilt angle in degrees (0; 90) | | `azimuth` | Yes | Panel installation azimuth angle in degrees (0; 360). An azimuth circle consists of 360 degrees. Ninety degrees corresponds to east, 180 degrees is south, 270 degrees is west, and 360 degrees and 0 degrees mark north | | `peak_power` | Yes | Total solar panel installation peak power output in kilowatts. In case `area` is not specified in the `POST` request then `peak_power` must be specified instead. In case both `area` and `peak_power` are specified, `peak_power` will be used. In case only `area` is specified, `peak_power` will be calculated from `area` and `type`. Solar panel peak power must not be equal to or less than 0. | ### Example of API response ```json { "panel_id": "F48BE762-6101-405B-BB72-E0CA9FE1A8FF", "location_id": "F01E165B-22F3-4591-89D4-F238E92F6885", "type": "mono-si", "area": 1.5, "tilt": 45, "azimuth": 182, "peak_power": 2.5 } ``` ### Fields in API response - `panel_id`Unique identifier of the solar panel assigned at resource creation - `location_id`Unique identifier of the location assigned at resource creation - `type`PV technology type used in solar panel - `area` Area of solar panel, m2 - `tilt` Panel installation tilt angle in degrees (0; 90) - `azimuth` Panel installation azimuth angle in degrees (0; 360) - `peak_power` Total solar panel installation peak power output in kilowatts ### How to get a solar panel data You could get information about created solar panel by its id number using API call below. In case of success method returns an HTTP code `200`. Method: `GET` ### URL ```text https://api.openweathermap.org/energy/1.0/panel/{panel_id}?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `panel_id` | Yes | Unique identifier of the solar panel assigned at resource creation | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### URL example ```text https://api.openweathermap.org/energy/1.0/panel/F48BE762-6101-405B-BB72-E0CA9FE1A8FF?appid={API key} ``` ### Example of API response ```json { "panel_id": "F48BE762-6101-405B-BB72-E0CA9FE1A8FF", "location_id": "F01E165B-22F3-4591-89D4-F238E92F6885", "type": "mono-si", "area": 1.5, "tilt": 45, "azimuth": 182, "peak_power": 2.5 } ``` ### Fields in API response - `panel_id` Unique identifier of the solar panel assigned at resource creation - `location_id`Unique identifier of the location assigned at resource creation - `type`PV technology type used in solar panel - `area` Area of solar panel, m2 - `tilt` Panel installation tilt angle in degrees (0; 90) - `azimuth` Panel installation azimuth angle in degrees (0; 360) - `peak_power` Total solar panel installation peak power output in kilowatts (kW) ### How to get a list of created solar panels You could get a list of all created solar panels for particular location using [OpenWeather API key](https://home.openweathermap.org/api_keys). In case of success method returns an HTTP code `200`. Method: `GET` ### URL ```text https://api.openweathermap.org/energy/1.0/location/{location_id}/panels?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `location_id` | Yes | Unique identifier of the location assigned at resource creation | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### URL example ```text https://api.openweathermap.org/energy/1.0/location/F01E165B-22F3-4591-89D4-F238E92F6885/panels?appid={API key} ``` ### Example of API response ```json [ { "panel_id": "F48BE762-6101-405B-BB72-E0CA9FE1A8FF", "location_id": "F01E165B-22F3-4591-89D4-F238E92F6885", "type": "mono-si", "area": 1.5, "tilt": 45, "azimuth": 182, "peak_power": 2.5 } ] ``` ### Fields in API response - `panel_id` Unique identifier of the solar panel assigned at resource creation - `location_id`Unique identifier of the location assigned at resource creation - `type`PV technology type used in solar panel - `area` Area of solar panel, m2 - `tilt` A Panel installation tilt angle in degrees (0; 90) - `azimuth` Panel installation azimuth angle in degrees (0; 360) - `peak_power` Total solar panel installation peak power output in kilowatts ### How to delete a solar panel You could delete created solar panel by its id number using folowing API call. In case of successful removing method returns an HTTP code `204`. Method: `DELETE` ### URL ```text https://api.openweathermap.org/energy/1.0/panel/{panel_id}?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `panel_id` | Yes | Unique identifier of the solar panel assigned at resource creation | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### URL example ```text https://api.openweathermap.org/energy/1.0/panel/F01E165B-22F3-4591-89D4-F238E92F6885?appid={API key} ``` ### API response Please pay attention if the delete request is successfully processed, then no response will be returned. ## Step 3: Get solar panel power output and solar irradiation data by location To get solar panel power output data make an API call according rules below. API response contains not only solar panel power output data for all solar panels associated with particular location but solar irradiation data for this location as well. You could find detailed information about what technologies, algorithms, etc. are behind the solar irradiation calculations[here](/api/solar-radiation/behind-solar-radiation-api.md). In case of success method returns an HTTP code `200`. Please pay attention that solar panel output values are given for averaged efficiency with a performance ratio 0.75. There are two routes to receive solar panel power output data and solar irradiation data for specified location: - Get daily aggregation with hourly detalization with [Route 1](#route1) - Get daily aggregation with detalization by intervals with [Route 2](#route2) Method: `GET` ### Route 1: daily aggregation with hourly detalization of solar panel power output and solar irradiation data In this section you will find how to request historical starting from 1st January 1979, current or forecast for 15 days ahead daily aggregated and accumulated hourly detalization for solar panel power output and solar irradiation data for particular geographical location and for specified date. If you are interested in daily aggregation with detalization by intervals for solar panel power output and solar irradiation data please use section [Route 2: daily aggregation with detalization by intervals](#route2). ### URL ```text https://api.openweathermap.org/energy/1.0/location/{location_id}/data?date={date}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `location_id` | Yes | Unique identifier of the location assigned at resource creation | | `date` | Yes | Date in the `YYYY-MM-DD` format for which data is requested. Date available from 1979-01-01 up to +15 days to the current date | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | > If the service detected timezone for your location incorrectly you can specify correct timezone manually by adding `tz` parameter in the ±XX:XX format to API call. > > API call > > `https://api.openweathermap.org/energy/1.0/location/{location_id}/data?date={date}&tz={tz}&appid=`[`{API key}`](https://home.openweathermap.org/api_keys) > > URL example > > `https://api.openweathermap.org/energy/1.0/location/F01E165B-22F3-4591-89D4-F238E92F6885/data?date=2023-03-30&tz=+05:45&appid=`[`{API key}`](https://home.openweathermap.org/api_keys) > > Please pay attention that in case timezone is specified time of sunset and sunrise will be returned in accordance with this specified timezone. ### URL example ```text https://api.openweathermap.org/energy/1.0/location/0189d066-983b-8a33-ae7a-b60be1ab759f/data?date=2023-08-07&appid={API key} ``` ### Example of API response ```json { "location_id": "0189d066-983b-8a33-ae7a-b60be1ab759f", "lat": 42.301, "lon": 19.185, "date": "2023-08-07", "tz": "+02:00", "sunrise": "2023-08-07T05:41:22", "sunset": "2023-08-07T19:56:06", "irradiance": { "daily": [ { "clear_sky": { "ghi": 7738.01, "dni": 10286.11, "dhi": 1275.66 }, "cloudy_sky": { "ghi": 7695.01, "dni": 9659.94, "dhi": 1363.06 } } ], "hourly": [ { "hour": 0, "clear_sky": { "ghi": 0.0, "dni": 0.0, "dhi": 0.0 }, "cloudy_sky": { "ghi": 0.0, "dni": 0.0, "dhi": 0.0 } }, { "hour": 1, "clear_sky": { "ghi": 0.0, "dni": 0.0, "dhi": 0.0 }, "cloudy_sky": { "ghi": 0.0, "dni": 0.0, "dhi": 0.0 } }, { "hour": 2, "clear_sky": { "ghi": 0.0, "dni": 0.0, "dhi": 0.0 }, "cloudy_sky": { "ghi": 0.0, "dni": 0.0, "dhi": 0.0 } }, { "hour": 3, "clear_sky": { "ghi": 0.0, "dni": 0.0, "dhi": 0.0 }, "cloudy_sky": { "ghi": 0.0, "dni": 0.0, "dhi": 0.0 } }, { "hour": 4, "clear_sky": { "ghi": 0.0, "dni": 0.0, "dhi": 0.0 }, "cloudy_sky": { "ghi": 0.0, "dni": 0.0, "dhi": 0.0 } }, { "hour": 5, "clear_sky": { "ghi": 0.0, "dni": 0.0, "dhi": 0.0 }, "cloudy_sky": { "ghi": 0.0, "dni": 0.0, "dhi": 0.0 } }, { "hour": 6, "clear_sky": { "ghi": 86.4, "dni": 390.66, "dhi": 43.5 }, "cloudy_sky": { "ghi": 77.43, "dni": 226.55, "dhi": 47.13 } }, { "hour": 7, "clear_sky": { "ghi": 266.08, "dni": 634.47, "dhi": 71.86 }, "cloudy_sky": { "ghi": 239.15, "dni": 506.18, "dhi": 78.42 } }, { "hour": 8, "clear_sky": { "ghi": 457.79, "dni": 757.88, "dhi": 90.29 }, "cloudy_sky": { "ghi": 457.77, "dni": 750.01, "dhi": 87.66 } }, { "hour": 9, "clear_sky": { "ghi": 635.88, "dni": 831.13, "dhi": 103.17 }, "cloudy_sky": { "ghi": 635.84, "dni": 822.81, "dhi": 101.84 } }, { "hour": 10, "clear_sky": { "ghi": 782.37, "dni": 876.2, "dhi": 111.98 }, "cloudy_sky": { "ghi": 782.34, "dni": 869.32, "dhi": 110.03 } }, { "hour": 11, "clear_sky": { "ghi": 883.76, "dni": 902.16, "dhi": 117.42 }, "cloudy_sky": { "ghi": 883.74, "dni": 873.35, "dhi": 134.33 } }, { "hour": 12, "clear_sky": { "ghi": 931.14, "dni": 913.16, "dhi": 119.81 }, "cloudy_sky": { "ghi": 931.12, "dni": 873.19, "dhi": 147.55 } }, { "hour": 13, "clear_sky": { "ghi": 920.39, "dni": 910.73, "dhi": 119.27 }, "cloudy_sky": { "ghi": 920.34, "dni": 873.2, "dhi": 144.54 } }, { "hour": 14, "clear_sky": { "ghi": 852.42, "dni": 894.54, "dhi": 115.78 }, "cloudy_sky": { "ghi": 852.37, "dni": 872.57, "dhi": 126.4 } }, { "hour": 15, "clear_sky": { "ghi": 733.11, "dni": 862.22, "dhi": 109.15 }, "cloudy_sky": { "ghi": 731.35, "dni": 830.9, "dhi": 123.29 } }, { "hour": 16, "clear_sky": { "ghi": 573.05, "dni": 808.17, "dhi": 98.94 }, "cloudy_sky": { "ghi": 571.38, "dni": 804.41, "dhi": 92.96 } }, { "hour": 17, "clear_sky": { "ghi": 387.35, "dni": 720.06, "dhi": 84.24 }, "cloudy_sky": { "ghi": 385.39, "dni": 710.72, "dhi": 79.66 } }, { "hour": 18, "clear_sky": { "ghi": 196.09, "dni": 565.48, "dhi": 62.93 }, "cloudy_sky": { "ghi": 194.76, "dni": 516.5, "dhi": 65.89 } }, { "hour": 19, "clear_sky": { "ghi": 32.18, "dni": 219.25, "dhi": 27.32 }, "cloudy_sky": { "ghi": 32.03, "dni": 130.23, "dhi": 23.36 } }, { "hour": 20, "clear_sky": { "ghi": 0.0, "dni": 0.0, "dhi": 0.0 }, "cloudy_sky": { "ghi": 0.0, "dni": 0.0, "dhi": 0.0 } }, { "hour": 21, "clear_sky": { "ghi": 0.0, "dni": 0.0, "dhi": 0.0 }, "cloudy_sky": { "ghi": 0.0, "dni": 0.0, "dhi": 0.0 } }, { "hour": 22, "clear_sky": { "ghi": 0.0, "dni": 0.0, "dhi": 0.0 }, "cloudy_sky": { "ghi": 0.0, "dni": 0.0, "dhi": 0.0 } }, { "hour": 23, "clear_sky": { "ghi": 0.0, "dni": 0.0, "dhi": 0.0 }, "cloudy_sky": { "ghi": 0.0, "dni": 0.0, "dhi": 0.0 } } ] }, "panels": [ { "panel_id": "0189d067-a458-8dd9-8058-deac073e01de", "output": { "daily": { "clear_sky": { "power": 13.4922 }, "cloudy_sky": { "power": 13.1875 } }, "hourly": { "clear_sky": [ { "hour": 0, "power": 0.0 }, { "hour": 1, "power": 0.0 }, { "hour": 2, "power": 0.0 }, { "hour": 3, "power": 0.0 }, { "hour": 4, "power": 0.0 }, { "hour": 5, "power": 0.0 }, { "hour": 6, "power": 0.2537 }, { "hour": 7, "power": 0.6937 }, { "hour": 8, "power": 1.1348 }, { "hour": 9, "power": 1.507 }, { "hour": 10, "power": 1.7635 }, { "hour": 11, "power": 1.8755 }, { "hour": 12, "power": 1.8316 }, { "hour": 13, "power": 1.6378 }, { "hour": 14, "power": 1.3167 }, { "hour": 15, "power": 0.9065 }, { "hour": 16, "power": 0.4601 }, { "hour": 17, "power": 0.0926 }, { "hour": 18, "power": 0.0162 }, { "hour": 19, "power": 0.0027 }, { "hour": 20, "power": 0.0 }, { "hour": 21, "power": 0.0 }, { "hour": 22, "power": 0.0 }, { "hour": 23, "power": 0.0 } ], "cloudy_sky": [ { "hour": 0, "power": 0.0 }, { "hour": 1, "power": 0.0 }, { "hour": 2, "power": 0.0 }, { "hour": 3, "power": 0.0 }, { "hour": 4, "power": 0.0 }, { "hour": 5, "power": 0.0 }, { "hour": 6, "power": 0.1854 }, { "hour": 7, "power": 0.5894 }, { "hour": 8, "power": 1.1211 }, { "hour": 9, "power": 1.492 }, { "hour": 10, "power": 1.7483 }, { "hour": 11, "power": 1.8536 }, { "hour": 12, "power": 1.8105 }, { "hour": 13, "power": 1.6212 }, { "hour": 14, "power": 1.3054 }, { "hour": 15, "power": 0.8984 }, { "hour": 16, "power": 0.4534 }, { "hour": 17, "power": 0.0901 }, { "hour": 18, "power": 0.016 }, { "hour": 19, "power": 0.0026 }, { "hour": 20, "power": 0.0 }, { "hour": 21, "power": 0.0 }, { "hour": 22, "power": 0.0 }, { "hour": 23, "power": 0.0 } ] } } } ] } ``` ### Fields in API response - `location_id`Unique identifier of the location assigned at resource creation - `lat` Latitude of the location, decimal (−90; 90) - `lon` Longitude of the location, decimal (-180; 180) - `date` Date specified in the API request in the `YYYY-MM-DD` format (from 1979-01-01 up to +15 days to the current date) - `tz` Timezone in the ±XX:XX format - `sunrise` Date and time of sunrise based on date specified in the API request and timezone authomatically determinated by on latitude and longitute of requested location. If you added timezone parameter into API request, then time of sunrise will be recalculated in accordance with this timezone. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `sunset`Date and time of sunset based on date specified in the API request and timezone authomatically determinated by on latitude and longitute of requested location. If you added timezone parameter into API request, then time of sunset will be recalculated in accordance with this timezone. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `irradiance`Irradiance related information - `daily` Daily aggregated irradiation data for the requested date - `clear_sky`Clear sky model - `ghi` Clear sky GHI - [Global Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dni` Clear sky DNI - [Direct Normal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dhi` Clear sky DHI - [Diffuse Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `cloudy_sky`Cloudy sky model - `ghi` Cloudy sky GHI - [Global Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dni` Cloudy sky DNI - [Direct Normal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dhi` Cloudy sky DHI - [Diffuse Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `hourly` Hourly detalization of daily aggregated irradiation data for the requested date - `hour` the ordinal number of the hour of start for which the energy is summed up. The parameter can take integer values from 0 to 23 - `clear_sky`Clear sky model - `ghi` Clear sky GHI - [Global Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dni` Clear sky DNI - [Direct Normal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dhi` Clear sky DHI - [Diffuse Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `cloudy_sky`Cloudy sky model - `ghi` Cloudy sky GHI - [Global Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dni` Cloudy sky DNI - [Direct Normal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dhi` Cloudy sky DHI - [Diffuse Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `panels` Solar panels related information - `panel_id` Unique identifier of the solar panel assigned at resource creation - `output`Solar panel power output data - `daily`Daily aggeregated solar panel power output data. Please pay attention that solar panel output values are given for averaged efficiency with a performance ratio 0.75 - `clear_sky`Clear sky model - `power`Daily solar panel power output amount for clear sky model, kW. Please pay attention that solar panel output values are given for averaged efficiency with a performance ratio 0.75 - `cloudy_sky`Cloudy sky model - `power`Daily solar panel power output amount for cloudy sky model, kW. Please pay attention that solar panel output values are given for averaged efficiency with a performance ratio 0.75 - `hourly`Hourly detalization of solar panel power output data. Please pay attention that solar panel output values are given for averaged efficiency with a performance ratio 0.75 - `clear_sky`Clear sky model - `hour`the ordinal number of the hour of start for which the power output is calculated. The parameter can take integer values from 0 to 23 - `power`Hourly solar panel power output amount for clear sky model, kW. Please pay attention that solar panel output values are given for averaged efficiency with a performance ratio 0.75 - `cloudy_sky`Cloudy sky model - `hour`the ordinal number of the hour of start for which the power output is calculated. The parameter can take integer values from 0 to 23 - `power`Hourly solar panel power output amount for cloudy sky model, kW. Please pay attention that solar panel output values are given for averaged efficiency with a performance ratio 0.75 ### Route 2: daily aggregation with detalization by intervals of solar panel power output and solar irradiation data In this section you will find how to request historical starting from 1st January 1979, current or forecast for 15 days ahead daily aggregated and accumulated 1 hour and 15 minutes interval detalization for solar panel power output and solar irradiation data for particular geographical location and for specified date. If you are interested in daily aggregation with hourly detalization for solar panel power output and solar irradiation data please use section [Route 1: daily aggregation with hourly detalization](#route1). ### URL ```text https://api.openweathermap.org/energy/1.0/location/{location_id}/interval_data?date={date}&interval={interval}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `location_id` | Yes | Unique identifier of the location assigned at resource creation | | `date` | Yes | Date in the `YYYY-MM-DD` format for which data is requested. Date available from 1979-01-01 up to +15 days to the current date | | `interval` | optional | The time interval during which the energy is summed up and solar panel power output is calculated, defines the temporary resolution of solar radiation data. If not specified, the default interval of "1h" (1 hour) will be used. Available values for this parameter include: "1h" (1 hour) and "15m" (15 minutes) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | > If the service detected timezone for your location incorrectly you can specify correct timezone manually by adding `tz` parameter in the ±XX:XX format to API call. > > API call > > `https://api.openweathermap.org/energy/1.0/location/{location_id}/interval_data?date={date}&interval={interval}&tz={tz}&appid=`[`{API key}`](https://home.openweathermap.org/api_keys) > > URL example > > `https://api.openweathermap.org/energy/1.0/location/F01E165B-22F3-4591-89D4-F238E92F6885/interval_data?date=2023-03-30&interval=1h&tz=+05:45&appid=`[`{API key}`](https://home.openweathermap.org/api_keys) > > Please pay attention that in case timezone is specified time of sunset and sunrise will be returned in accordance with this specified timezone. ### URL example ```text https://api.openweathermap.org/energy/1.0/location/018aa7aa-3d5f-85a2-91ee-b1b53c3e98a4/interval_data?date=2021-05-01&interval=1h&appid={API key} ``` ### Example of API response ```json { "location_id":"018aa7aa-3d5f-85a2-91ee-b1b53c3e98a4", "lat":60.16986, "lon":24.93838, "date":"2021-05-01", "tz":"+03:00", "interval":"1h", "sunrise":"2021-05-01T05:16:36", "sunset":"2021-05-01T21:19:47", "irradiance":{ "daily":[ { "clear_sky":{ "ghi":6428.85, "dni":10469.57, "dhi":1271.66 }, "cloudy_sky":{ "ghi":6318.7, "dni":9562.88, "dhi":1491.64 } } ], "intervals":[ { "start":"00:00", "end":"01:00", "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "start":"01:00", "end":"02:00", "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "start":"02:00", "end":"03:00", "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "start":"03:00", "end":"04:00", "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "start":"04:00", "end":"05:00", "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "start":"05:00", "end":"06:00", "clear_sky":{ "ghi":8.56, "dni":66.34, "dhi":10.37 }, "cloudy_sky":{ "ghi":8.56, "dni":7.47, "dhi":8.14 } }, { "start":"06:00", "end":"07:00", "clear_sky":{ "ghi":84.84, "dni":377.47, "dhi":42.87 }, "cloudy_sky":{ "ghi":84.84, "dni":334.94, "dhi":38.4 } }, { "start":"07:00", "end":"08:00", "clear_sky":{ "ghi":203.02, "dni":572.19, "dhi":64.42 }, "cloudy_sky":{ "ghi":203.02, "dni":551.03, "dhi":61.66 } }, { "start":"08:00", "end":"09:00", "clear_sky":{ "ghi":332.67, "dni":687.73, "dhi":79.94 }, "cloudy_sky":{ "ghi":332.53, "dni":670.61, "dhi":79.13 } }, { "start":"09:00", "end":"10:00", "clear_sky":{ "ghi":458.18, "dni":762.29, "dhi":91.47 }, "cloudy_sky":{ "ghi":456.73, "dni":732.71, "dhi":97.91 } }, { "start":"10:00", "end":"11:00", "clear_sky":{ "ghi":567.24, "dni":811.26, "dhi":99.86 }, "cloudy_sky":{ "ghi":560.89, "dni":766.56, "dhi":113.13 } }, { "start":"11:00", "end":"12:00", "clear_sky":{ "ghi":649.96, "dni":842.02, "dhi":105.5 }, "cloudy_sky":{ "ghi":611.09, "dni":683.8, "dhi":164.13 } }, { "start":"12:00", "end":"13:00", "clear_sky":{ "ghi":699.11, "dni":858.29, "dhi":108.63 }, "cloudy_sky":{ "ghi":660.3, "dni":681.77, "dhi":184.85 } }, { "start":"13:00", "end":"14:00", "clear_sky":{ "ghi":710.5, "dni":861.83, "dhi":109.35 }, "cloudy_sky":{ "ghi":708.26, "dni":812.08, "dhi":135.12 } }, { "start":"14:00", "end":"15:00", "clear_sky":{ "ghi":683.19, "dni":853.1, "dhi":107.65 }, "cloudy_sky":{ "ghi":675.85, "dni":793.48, "dhi":133.9 } }, { "start":"15:00", "end":"16:00", "clear_sky":{ "ghi":619.53, "dni":831.16, "dhi":103.51 }, "cloudy_sky":{ "ghi":607.9, "dni":767.8, "dhi":125.36 } }, { "start":"16:00", "end":"17:00", "clear_sky":{ "ghi":525.02, "dni":793.54, "dhi":96.78 }, "cloudy_sky":{ "ghi":523.37, "dni":759.9, "dhi":106.81 } }, { "start":"17:00", "end":"18:00", "clear_sky":{ "ghi":408.06, "dni":735.34, "dhi":87.18 }, "cloudy_sky":{ "ghi":406.77, "dni":711.18, "dhi":89.93 } }, { "start":"18:00", "end":"19:00", "clear_sky":{ "ghi":279.52, "dni":646.85, "dhi":74.18 }, "cloudy_sky":{ "ghi":279.15, "dni":627.16, "dhi":72.79 } }, { "start":"19:00", "end":"20:00", "clear_sky":{ "ghi":152.75, "dni":506.63, "dhi":56.64 }, "cloudy_sky":{ "ghi":152.75, "dni":483.2, "dhi":52.63 } }, { "start":"20:00", "end":"21:00", "clear_sky":{ "ghi":46.07, "dni":257.91, "dhi":31.36 }, "cloudy_sky":{ "ghi":46.07, "dni":179.19, "dhi":27.13 } }, { "start":"21:00", "end":"22:00", "clear_sky":{ "ghi":0.63, "dni":5.62, "dhi":1.98 }, "cloudy_sky":{ "ghi":0.63, "dni":0, "dhi":0.63 } }, { "start":"22:00", "end":"23:00", "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } }, { "start":"23:00", "end":"00:00", "clear_sky":{ "ghi":0, "dni":0, "dhi":0 }, "cloudy_sky":{ "ghi":0, "dni":0, "dhi":0 } } ] }, "panels":[ { "panel_id":"018aa7aa-f224-893a-9907-ff7befe87968", "output":{ "daily":{ "clear_sky":{ "power":3.3902 }, "cloudy_sky":{ "power":3.2197 } }, "intervals":{ "clear_sky":[ { "start":"00:00", "end":"01:00", "power":0 }, { "start":"01:00", "end":"02:00", "power":0 }, { "start":"02:00", "end":"03:00", "power":0 }, { "start":"03:00", "end":"04:00", "power":0 }, { "start":"04:00", "end":"05:00", "power":0 }, { "start":"05:00", "end":"06:00", "power":0.0215 }, { "start":"06:00", "end":"07:00", "power":0.1544 }, { "start":"07:00", "end":"08:00", "power":0.2852 }, { "start":"08:00", "end":"09:00", "power":0.388 }, { "start":"09:00", "end":"10:00", "power":0.4554 }, { "start":"10:00", "end":"11:00", "power":0.4825 }, { "start":"11:00", "end":"12:00", "power":0.468 }, { "start":"12:00", "end":"13:00", "power":0.4147 }, { "start":"13:00", "end":"14:00", "power":0.3292 }, { "start":"14:00", "end":"15:00", "power":0.2214 }, { "start":"15:00", "end":"16:00", "power":0.1037 }, { "start":"16:00", "end":"17:00", "power":0.0278 }, { "start":"17:00", "end":"18:00", "power":0.0196 }, { "start":"18:00", "end":"19:00", "power":0.0142 }, { "start":"19:00", "end":"20:00", "power":0.0035 }, { "start":"20:00", "end":"21:00", "power":0.0011 }, { "start":"21:00", "end":"22:00", "power":0 }, { "start":"22:00", "end":"23:00", "power":0 }, { "start":"23:00", "end":"00:00", "power":0 } ], "cloudy_sky":[ { "start":"00:00", "end":"01:00", "power":0 }, { "start":"01:00", "end":"02:00", "power":0 }, { "start":"02:00", "end":"03:00", "power":0 }, { "start":"03:00", "end":"04:00", "power":0 }, { "start":"04:00", "end":"05:00", "power":0 }, { "start":"05:00", "end":"06:00", "power":0.0058 }, { "start":"06:00", "end":"07:00", "power":0.1375 }, { "start":"07:00", "end":"08:00", "power":0.2747 }, { "start":"08:00", "end":"09:00", "power":0.379 }, { "start":"09:00", "end":"10:00", "power":0.443 }, { "start":"10:00", "end":"11:00", "power":0.4657 }, { "start":"11:00", "end":"12:00", "power":0.4191 }, { "start":"12:00", "end":"13:00", "power":0.3757 }, { "start":"13:00", "end":"14:00", "power":0.3237 }, { "start":"14:00", "end":"15:00", "power":0.2185 }, { "start":"15:00", "end":"16:00", "power":0.1056 }, { "start":"16:00", "end":"17:00", "power":0.0308 }, { "start":"17:00", "end":"18:00", "power":0.0209 }, { "start":"18:00", "end":"19:00", "power":0.0148 }, { "start":"19:00", "end":"20:00", "power":0.0035 }, { "start":"20:00", "end":"21:00", "power":0.0011 }, { "start":"21:00", "end":"22:00", "power":0.0003 }, { "start":"22:00", "end":"23:00", "power":0 }, { "start":"23:00", "end":"00:00", "power":0 } ] } } } ] } ``` ### Fields in API response - `location_id`Unique identifier of the location assigned at resource creation - `lat` Latitude of the location, decimal (−90; 90) - `lon` Longitude of the location, decimal (-180; 180) - `date` Date specified in the API request in the `YYYY-MM-DD` format (from 1979-01-01 up to +15 days to the current date) - `tz` Timezone in the ±XX:XX format - `interval` Time interval during which the energy is summed up and solar panel power output is calculated. Determines temporary resolution of solar radiation data. If not specified "1h" interval will be used. Available values : 1h, 15m - `sunrise` Date and time of sunrise based on date specified in the API request and timezone authomatically determinated by on latitude and longitute of requested location. If you added timezone parameter into API request, then time of sunrise will be recalculated in accordance with this timezone. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `sunset`Date and time of sunset based on date specified in the API request and timezone authomatically determinated by on latitude and longitute of requested location. If you added timezone parameter into API request, then time of sunset will be recalculated in accordance with this timezone. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `irradiance`Irradiance related information - `daily` Daily aggregated irradiation data for the requested date - `clear_sky`Clear sky model - `ghi` Clear sky GHI - [Global Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dni` Clear sky DNI - [Direct Normal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dhi` Clear sky DHI - [Diffuse Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `cloudy_sky`Cloudy sky model - `ghi` Cloudy sky GHI - [Global Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dni` Cloudy sky DNI - [Direct Normal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dhi` Cloudy sky DHI - [Diffuse Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `intervals` Interval detalization of daily aggregated irradiation data for the requested date - `start`Start of the time interval for which the energy is summed up. Time interval displays hour and minutes of the day for which indexes were aggregated in "hh:mm" format - `end`End of the time interval for which the energy is summed up. Time interval displays hour and minutes of the day for which indexes were aggregated in "hh:mm" format - `clear_sky`Clear sky model - `ghi` Clear sky GHI - [Global Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dni` Clear sky DNI - [Direct Normal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dhi` Clear sky DHI - [Diffuse Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `cloudy_sky`Cloudy sky model - `ghi` Cloudy sky GHI - [Global Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dni` Cloudy sky DNI - [Direct Normal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dhi` Cloudy sky DHI - [Diffuse Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `panels` Solar panels related information - `panel_id` Unique identifier of the solar panel assigned at resource creation - `output`Solar panel power output data - `daily`Daily aggeregated solar panel power output data. Please pay attention that solar panel output values are given for averaged efficiency with a performance ratio 0.75 - `clear_sky`Clear sky model - `power`Daily solar panel power output amount for clear sky model, kW. Please pay attention that solar panel output values are given for averaged efficiency with a performance ratio 0.75 - `cloudy_sky`Cloudy sky model - `power`Daily solar panel power output amount for cloudy sky model, kW. Please pay attention that solar panel output values are given for averaged efficiency with a performance ratio 0.75 - `intervals` Interval detalization of daily aggregated solar panel power output data for the requested date. Please pay attention that solar panel output values are given for averaged efficiency with a performance ratio 0.75 - `clear_sky`Clear sky model - `start`Start of the time interval for which the solar panel power output is calculated. Time interval displays hour and minutes of the day for which indexes were aggregated in "hh:mm" format - `end`End of the time interval for which the solar panel power output is calculated. Time interval displays hour and minutes of the day for which indexes were aggregated in "hh:mm" format - `power`Solar panel power output amount per requeted interval for clear sky model, kW. Please pay attention that solar panel output values are given for averaged efficiency with a performance ratio 0.75 - `cloudy_sky`Cloudy sky model - `start`Start of the time interval for which the solar panel power output is calculated. Time interval displays hour and minutes of the day for which indexes were aggregated in "hh:mm" format - `end`End of the time interval for which the solar panel power output is calculated. Time interval displays hour and minutes of the day for which indexes were aggregated in "hh:mm" format - `power`Solar panel power output amount per requeted interval for cloudy sky model, kW. Please pay attention that solar panel output values are given for averaged efficiency with a performance ratio 0.75 ## API errors ### Structure of API errors In case of incorrected API call you will receive API error response. Error response payload returned for all types of errors with the structure below. ### Example of error response ```json { "code": "400", "message": "Invalid date format", "parameters": [ "date" ] } ``` ### Fields in error response - `code` Code of error - `message` Description of error - `parameters`(optional) List of request parameters names that are related to this particular error ### Errors list Please find more detailed information about some popular errors below. #### API calls return an error 400 Error 400 - Bad Request. You can get error 400 error if either some mandatory parameters in the request are missing or some of request parameters have incorrect format or values out of allowed range. List of all parameters names that are missong or incorrect will be returned in `parameters`attribute of the `ErrorResponse` object. #### API calls return an error 401 Error 401 - Unauthorized. You can get 401 error if API token did not providen in the request or in case API token provided in the request does not grant access to this API. You must add API token with granted access to the product to the request before returing it. #### API calls return an error 404 Error 404 - Not Found. You can get 404 error if data with requested parameters (`lat`, `lon`, `date`, `location_id`, `panel_id`) does not exist in service database. You must not retry the same request. #### API calls return an error 429 Error 429 - Too Many Requests. You can get 429 error if key quato of requests for provided API to this API was exceeded. You may retry request after some time or after extending your key quota. #### API calls return errors '5xx' Errors 5xx - Unexpected Error. You can get '5xx' error in case of other internal errors. Error Response code will be `5xx`. Please [contact us](https://home.openweathermap.org/questions) and enclose an example of your API request that receives this error into your email to let us analyze it and find a solution for you promptly. You may retry the request which led to this error. --- ## Solar Panel Energy Prediction ✔** This is the latest version of the API (v2).** [Looking for the previous version? You can find the v1 documentation here.](/api/solar-panels-and-energy-prediction.md) ## Product concept Solar Panel Energy Prediction service allows users to accurately estimate solar power generation and determine the energy output of each PV panel. Main features of Solar Panel Energy Prediction: - API response contains daily solar panel power output data for each solar panel with 1 hour, 15 minutes and 1 day detalization - Each API response contains also essential solar irradiation data (DNI, GHI and DHI) - Current and 15 days ahead forecast data for solar panel power output - Historical solar panel power output data is available for 47+ years back (from 1st January 1979) - Create an unlimited number of solar panels for a particular location. Users could define solar panel by specifying its type, tilt and azimuth angles - Making API call to particular location get solar panel power output data for all solar panels associated with this location - Global coverage [You can find the previous documentation v1 here](/api/solar-panels-and-energy-prediction.md) Data is available in JSON format. ## How to use the service 1. [Sign up](https://home.openweathermap.org/users/sign_up) to OpenWeather service in case you haven't got your [OpenWeather API key](https://home.openweathermap.org/api_keys) yet. Do not forget to add your key to the each API call in paragraphs 3, 4 and 5. 2. Follow the [pricing page](/price.md#solar_energy) to learn details about the price. Please note that product is available via the separate subscription only, which allows you to pay only for the created locations. 3. Create a unique location via API call according ["Step 1: Manage my location"](#step1). Create a location where your solar panels are located in accordance with chapter ["How to create a unique location"](#post_location) and receive location ID number. Please pay attention that chapters ["How to get a location"](#get_location), ["How to get a list of created locations"](#get_all_locations) ,["How to delete a location"](#delete_location) described how to manage created locations. 4. Create a solar panels for your location according ["Step 2: Operations with solar panels"](#step2). Create a solar panel for location created at the previous step according to the documentation ["How to create a solar panel"](#post_panel). Please note that you could create unlimited number of panels for one location. 5. Make an API call to get location solar panels power output and location solar irradiation data according [step 3](#step3). > Please note that product is available via the separate subscription only, which allows you to pay only for the created locations. ## Step 1: Manage my location ### How to create a unique location This HTTP method is used to create a new location and receive location ID for it. You need to pass a geographical coordinates of location in parameters. In case of successful creation method returns an HTTP code `201`. Method: `POST` Header: `Content-Type: application/json` ### URL ```text https://api.openweathermap.org/energy/2.0/locations?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### Example of the request body ```json { "type": "point", "coordinates": [ { "lat": 51.507222, "lon": -0.1275 } ] } ``` | Parameters | | | | --- | --- | --- | | `type` | Yes | Type of the location. Allowed type - point | | `lat` | Yes | Latitude, decimal (−90; 90) | | `lon` | Yes | Longitude, decimal (−180; 180) | ### Example of API response ```json { "location_id": "F01E165B-22F3-4591-89D4-F238E92F6885", "type": "point", "coordinates": [ { "lat": 51.507222, "lon": -0.1275 } ] } ``` ### Fields in API response - `location_id` Unique identifier of the location assigned at resource creation - `type` Type of the location - `lat` Latitude of the location, decimal (−90; 90) - `lon` Longitude of the location, decimal (-180; 180) > Please note: > > - When creating unique locations, coordinates are rounded to 6 decimal places > - To check geographical coordinates of previously created location, please see section ["How to get location"](/api/solar-panels-and-energy-prediction-2.md#get_location) ### How to get a location data You could get geographical coordinates for previously created location by its id number following instruction below. In case of success method returns an HTTP code `200`. Method: `GET` ### URL ```text https://api.openweathermap.org/energy/2.0/location/{location_id}?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `location_id` | Yes | Unique identifier of the location assigned at resource creation. You could find all created locations id using instruction [here](#get_all_locations) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### URL example ```text https://api.openweathermap.org/energy/2.0/location/F01E165B-22F3-4591-89D4-F238E92F6885?appid={API key} ``` ### Example of API response ```json { "location_id": "F01E165B-22F3-4591-89D4-F238E92F6885", "type": "point", "coordinates": [ { "lat": 51.507222, "lon": -0.1275 } ] } ``` ### Fields in API response - `location_id` Unique identifier of the location assigned at resource creation - `type` Type of the location - `lat` Latitude of the location, decimal (−90; 90) - `lon` Longitude of the location, decimal (-180; 180) ### How to get a list of created locations You could get a list of all created locations using your [OpenWeather API key](https://home.openweathermap.org/api_keys) and instruction below. In case of success method returns an HTTP code `200`. Method: `GET` ### URL ```text https://api.openweathermap.org/energy/2.0/locations?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### Example of API response ```json { "location_id": "F01E165B-22F3-4591-89D4-F238E92F6885", "type": "point", "coordinates": [ { "lat": 51.5072, "lon": -0.1275 } ] } ] ``` ### Fields in API response - `location_id` Unique identifier of the location assigned at resource creation - `type` Type of the location - `lat` Latitude of the location, decimal (−90; 90) - `lon` Longitude of the location, decimal (-180; 180) ### How to delete a location You could delete created location by its id number using folowing URL. Please pay attention, that all solar panels assosiated with this location will deleted as well. In case of successful removing method returns an HTTP code `204`. Method: `DELETE` ### URL ```text https://api.openweathermap.org/energy/2.0/location/{location_id}?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `location_id` | Yes | Unique identifier of the location assigned at resource creation | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### URL example ```text https://api.openweathermap.org/energy/2.0/location/F01E165B-22F3-4591-89D4-F238E92F6885?appid={API key} ``` ### API response Please pay attention if the delete request is successfully processed, then no response will be returned. ## Step 2: Operations with solar panels ### How to create a solar panel This HTTP method is used to create a new solar panel associated with location and receive solar panel ID for this panel. You need to pass a set of solar panel parameters: tilt, azimuth and peak power. In case of successful creation method returns an HTTP code `201`. Method: `POST` Header: `Content-Type: application/json` ### URL ```text https://api.openweathermap.org/energy/2.0/location/{location_id}/panels?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `location_id` | Yes | Unique identifier of the location assigned at resource creation | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### Example of the request body ```json { "type": "mono-si", "area": 1.5, "tilt": 45, "azimuth": 182, "peak_power": 2.5 } ``` | Parameters | | | | --- | --- | --- | | `type` | Yes | PV technology type used in solar panel. In case not specified `mono-si` will be assumed. Allowed technology types: `mono-si`┃`poly-si`┃`tf-as`┃`cdte` | | `area` | Yes | Area of solar panel in square meters. In case `peak_power` is not specified then in the `POST` request then `area` must be specified instead to be able to estimate panel power output. Solar panel area must not be equal to or less than 0. | | `tilt` | Yes | Panel installation tilt angle in degrees (0; 90) | | `azimuth` | Yes | Panel installation azimuth angle in degrees (0; 360). An azimuth circle consists of 360 degrees. Ninety degrees corresponds to east, 180 degrees is south, 270 degrees is west, and 360 degrees and 0 degrees mark north | | `peak_power` | Yes | Total solar panel installation peak power output in kilowatts. In case `area` is not specified in the `POST` request then `peak_power` must be specified instead. In case both `area` and `peak_power` are specified, `peak_power` will be used. In case only `area` is specified, `peak_power` will be calculated from `area` and `type`. Solar panel peak power must not be equal to or less than 0. | ### Example of API response ```json { "panel_id": "F48BE762-6101-405B-BB72-E0CA9FE1A8FF", "location_id": "F01E165B-22F3-4591-89D4-F238E92F6885", "type": "mono-si", "area": 1.5, "tilt": 45, "azimuth": 182, "peak_power": 2.5 } ``` ### Fields in API response - `panel_id`Unique identifier of the solar panel assigned at resource creation - `location_id`Unique identifier of the location assigned at resource creation - `type`PV technology type used in solar panel - `area` Area of solar panel, m2 - `tilt` Panel installation tilt angle in degrees (0; 90) - `azimuth` Panel installation azimuth angle in degrees (0; 360) - `peak_power` Total solar panel installation peak power output in kilowatts ### How to get a solar panel data You could get information about created solar panel by its id number using API call below. In case of success method returns an HTTP code `200`. Method: `GET` ### URL ```text https://api.openweathermap.org/energy/2.0/panel/{panel_id}?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `panel_id` | Yes | Unique identifier of the solar panel assigned at resource creation | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### URL example ```text https://api.openweathermap.org/energy/2.0/panel/F48BE762-6101-405B-BB72-E0CA9FE1A8FF?appid={API key} ``` ### Example of API response ```json { "panel_id": "F48BE762-6101-405B-BB72-E0CA9FE1A8FF", "location_id": "F01E165B-22F3-4591-89D4-F238E92F6885", "type": "mono-si", "area": 1.5, "tilt": 45, "azimuth": 182, "peak_power": 2.5 } ``` ### Fields in API response - `panel_id` Unique identifier of the solar panel assigned at resource creation - `location_id`Unique identifier of the location assigned at resource creation - `type`PV technology type used in solar panel - `area` Area of solar panel, m2 - `tilt` Panel installation tilt angle in degrees (0; 90) - `azimuth` Panel installation azimuth angle in degrees (0; 360) - `peak_power` Total solar panel installation peak power output in kilowatts (kW) ### How to get a list of created solar panels You could get a list of all created solar panels for particular location using [OpenWeather API key](https://home.openweathermap.org/api_keys). In case of success method returns an HTTP code `200`. Method: `GET` ### URL ```text https://api.openweathermap.org/energy/2.0/location/{location_id}/panels?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `location_id` | Yes | Unique identifier of the location assigned at resource creation | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### URL example ```text https://api.openweathermap.org/energy/2.0/location/F01E165B-22F3-4591-89D4-F238E92F6885/panels?appid={API key} ``` ### Example of API response ```json [ { "panel_id": "F48BE762-6101-405B-BB72-E0CA9FE1A8FF", "location_id": "F01E165B-22F3-4591-89D4-F238E92F6885", "type": "mono-si", "area": 1.5, "tilt": 45, "azimuth": 182, "peak_power": 2.5 } ] ``` ### Fields in API response - `panel_id` Unique identifier of the solar panel assigned at resource creation - `location_id`Unique identifier of the location assigned at resource creation - `type`PV technology type used in solar panel - `area` Area of solar panel, m2 - `tilt` A Panel installation tilt angle in degrees (0; 90) - `azimuth` Panel installation azimuth angle in degrees (0; 360) - `peak_power` Total solar panel installation peak power output in kilowatts ### How to delete a solar panel You could delete created solar panel by its id number using folowing API call. In case of successful removing method returns an HTTP code `204`. Method: `DELETE` ### URL ```text https://api.openweathermap.org/energy/2.0/panel/{panel_id}?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `panel_id` | Yes | Unique identifier of the solar panel assigned at resource creation | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### URL example ```text https://api.openweathermap.org/energy/2.0/panel/F01E165B-22F3-4591-89D4-F238E92F6885?appid={API key} ``` ### API response Please pay attention if the delete request is successfully processed, then no response will be returned. ## Step 3: Get solar panel power output and solar irradiation data by location To get solar panel power output data make an API call according rules below. In this section you will find how to request historical starting from 1st January 1979, current or forecast for 15 days ahead daily aggregated and accumulated 1 day, 1 hour or 15 minutes interval detalization for solar panel power output and solar irradiation data for particular geographical location and for specified date. You could find detailed information about what technologies, algorithms, etc. are behind the solar irradiation calculations [here](/api/solar-radiation/behind-solar-radiation-api.md) . In case of success method returns an HTTP code 200. Please pay attention that solar panel output values are given for averaged efficiency with a performance ratio 0.75. ### How to make an API call ### URL ```text https://api.openweathermap.org/energy/2.0/location/{location_id}/interval_data?date={date}&interval={interval}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `location_id` | Yes | Unique identifier of the location assigned at resource creation | | `date` | Yes | Date in the `YYYY-MM-DD` format for which data is requested. Date available from 1979-01-01 up to +15 days to the current date | | `interval` | optional | The time interval during which the energy is summed up and solar panel power output is calculated, defines the temporary resolution of solar radiation data. If not specified, the default interval of "1h" (1 hour) will be used. Available values for this parameter include: "15m" (15 minutes), "1h" (1 hour) and "1d" (1 day) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | > If the service detected timezone for your location incorrectly you can specify correct timezone manually by adding `tz` parameter in the ±XX:XX format to API call. > > API call > > `https://api.openweathermap.org/energy/2.0/location/{location_id}/interval_data?date={date}&interval={interval}&tz={tz}&appid=`[`{API key}`](https://home.openweathermap.org/api_keys) > > URL example > > `https://api.openweathermap.org/energy/2.0/location/F01E165B-22F3-4591-89D4-F238E92F6885/interval_data?date=2023-03-30&interval=1h&tz=+05:45&appid=`[`{API key}`](https://home.openweathermap.org/api_keys) > > Please pay attention that in case timezone is specified time of sunset and sunrise will be returned in accordance with this specified timezone. ### URL example ```text https://api.openweathermap.org/energy/2.0/location/018aa7aa-3d5f-85a2-91ee-b1b53c3e98a4/interval_data?date=2021-05-01&interval=1h&appid={API key} ``` ### Example of API response ```json { "location_id": "01955d08-a960-8b0a-819c-553b7b742ebe", "lat": 70.609, "lon": 170.89, "date": "2025-03-01", "tz": "+12:00", "interval": "1h", "sunrise": "2025-03-01T08:06:48", "sunset": "2025-03-01T17:32:34", "intervals": [ { "start": "00:00", "end": "00:59", "avg_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "max_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "irradiation": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } } ] }, { "start": "01:00", "end": "01:59", "avg_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "max_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "irradiation": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } } ] }, { "start": "02:00", "end": "02:59", "avg_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "max_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "irradiation": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } } ] }, { "start": "03:00", "end": "03:59", "avg_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "max_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "irradiation": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } } ] }, { "start": "04:00", "end": "04:59", "avg_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "max_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "irradiation": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } } ] }, { "start": "05:00", "end": "05:59", "avg_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "max_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "irradiation": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } } ] }, { "start": "06:00", "end": "06:59", "avg_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "max_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "irradiation": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } } ] }, { "start": "07:00", "end": "07:59", "avg_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "max_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "irradiation": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } } ] }, { "start": "08:00", "end": "08:59", "avg_irradiance": { "clear_sky": { "ghi": 8.16, "dni": 66.84, "dhi": 11.48 }, "cloudy_sky": { "ghi": 2.04, "dni": 0, "dhi": 2.04 } }, "max_irradiance": { "clear_sky": { "ghi": 20.56, "dni": 160.2, "dhi": 22.64 }, "cloudy_sky": { "ghi": 5.12, "dni": 0, "dhi": 5.12 } }, "irradiation": { "clear_sky": { "ghi": 8.15, "dni": 66.82, "dhi": 11.48 }, "cloudy_sky": { "ghi": 2.04, "dni": 0, "dhi": 2.04 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 6.13633, "max_power": 13.06448, "energy": 6.13634 }, "cloudy_sky": { "avg_power": 0.82957, "max_power": 2.09231, "energy": 0.82958 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0.14946, "max_power": 0.3503, "energy": 0.14946 }, "cloudy_sky": { "avg_power": 0.00406, "max_power": 0.01025, "energy": 0.00406 } } ] }, { "start": "09:00", "end": "09:59", "avg_irradiance": { "clear_sky": { "ghi": 52.32, "dni": 295.32, "dhi": 35.12 }, "cloudy_sky": { "ghi": 13.08, "dni": 0, "dhi": 13.08 } }, "max_irradiance": { "clear_sky": { "ghi": 72, "dni": 360.12, "dhi": 41.24 }, "cloudy_sky": { "ghi": 18, "dni": 0, "dhi": 18 } }, "irradiation": { "clear_sky": { "ghi": 52.33, "dni": 295.31, "dhi": 35.11 }, "cloudy_sky": { "ghi": 13.08, "dni": 0, "dhi": 13.08 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 24.88815, "max_power": 31.64728, "energy": 24.88815 }, "cloudy_sky": { "avg_power": 5.34521, "max_power": 7.35579, "energy": 5.34521 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0.63126, "max_power": 0.76034, "energy": 0.63125 }, "cloudy_sky": { "avg_power": 0.02617, "max_power": 0.03602, "energy": 0.02616 } } ] }, { "start": "10:00", "end": "10:59", "avg_irradiance": { "clear_sky": { "ghi": 102.28, "dni": 430.76, "dhi": 48.44 }, "cloudy_sky": { "ghi": 25.56, "dni": 0, "dhi": 25.56 } }, "max_irradiance": { "clear_sky": { "ghi": 118.96, "dni": 464.84, "dhi": 52 }, "cloudy_sky": { "ghi": 29.72, "dni": 0, "dhi": 29.72 } }, "irradiation": { "clear_sky": { "ghi": 102.27, "dni": 430.77, "dhi": 48.43 }, "cloudy_sky": { "ghi": 25.57, "dni": 0, "dhi": 25.57 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 41.03859, "max_power": 45.96232, "energy": 41.03859 }, "cloudy_sky": { "avg_power": 10.44522, "max_power": 12.14523, "energy": 10.44522 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0.86729, "max_power": 0.90358, "energy": 0.86728 }, "cloudy_sky": { "avg_power": 0.05115, "max_power": 0.05947, "energy": 0.05116 } } ] }, { "start": "11:00", "end": "11:59", "avg_irradiance": { "clear_sky": { "ghi": 139.88, "dni": 500.6, "dhi": 55.96 }, "cloudy_sky": { "ghi": 34.96, "dni": 0, "dhi": 34.96 } }, "max_irradiance": { "clear_sky": { "ghi": 150.04, "dni": 516.8, "dhi": 57.76 }, "cloudy_sky": { "ghi": 37.52, "dni": 0, "dhi": 37.52 } }, "irradiation": { "clear_sky": { "ghi": 139.87, "dni": 500.59, "dhi": 55.95 }, "cloudy_sky": { "ghi": 34.97, "dni": 0, "dhi": 34.97 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 51.40534, "max_power": 53.76556, "energy": 51.40534 }, "cloudy_sky": { "avg_power": 14.29476, "max_power": 15.33274, "energy": 14.29475 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0.88541, "max_power": 0.90707, "energy": 0.88541 }, "cloudy_sky": { "avg_power": 0.07, "max_power": 0.07508, "energy": 0.07 } } ] }, { "start": "12:00", "end": "12:59", "avg_irradiance": { "clear_sky": { "ghi": 158, "dni": 528.48, "dhi": 59.12 }, "cloudy_sky": { "ghi": 39.88, "dni": 0, "dhi": 39.88 } }, "max_irradiance": { "clear_sky": { "ghi": 160.04, "dni": 531.48, "dhi": 59.44 }, "cloudy_sky": { "ghi": 40.8, "dni": 0, "dhi": 40.8 } }, "irradiation": { "clear_sky": { "ghi": 158.01, "dni": 528.49, "dhi": 59.11 }, "cloudy_sky": { "ghi": 39.89, "dni": 0, "dhi": 39.89 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 54.55715, "max_power": 54.8701, "energy": 54.55715 }, "cloudy_sky": { "avg_power": 16.30533, "max_power": 16.67312, "energy": 16.30533 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0.74458, "max_power": 0.8173, "energy": 0.74459 }, "cloudy_sky": { "avg_power": 0.07984, "max_power": 0.08164, "energy": 0.07984 } } ] }, { "start": "13:00", "end": "13:59", "avg_irradiance": { "clear_sky": { "ghi": 154.08, "dni": 522.68, "dhi": 58.44 }, "cloudy_sky": { "ghi": 39.16, "dni": 0, "dhi": 39.16 } }, "max_irradiance": { "clear_sky": { "ghi": 159.08, "dni": 530.04, "dhi": 59.28 }, "cloudy_sky": { "ghi": 40.8, "dni": 0, "dhi": 40.8 } }, "irradiation": { "clear_sky": { "ghi": 154.09, "dni": 522.69, "dhi": 58.44 }, "cloudy_sky": { "ghi": 39.15, "dni": 0, "dhi": 39.15 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 50.37289, "max_power": 53.04252, "energy": 50.37289 }, "cloudy_sky": { "avg_power": 15.99884, "max_power": 16.67312, "energy": 15.99884 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0.50046, "max_power": 0.60307, "energy": 0.50046 }, "cloudy_sky": { "avg_power": 0.07834, "max_power": 0.08164, "energy": 0.07834 } } ] }, { "start": "14:00", "end": "14:59", "avg_irradiance": { "clear_sky": { "ghi": 128.64, "dni": 481.48, "dhi": 53.84 }, "cloudy_sky": { "ghi": 32.16, "dni": 0, "dhi": 32.16 } }, "max_irradiance": { "clear_sky": { "ghi": 141.28, "dni": 503.08, "dhi": 56.2 }, "cloudy_sky": { "ghi": 35.32, "dni": 0, "dhi": 35.32 } }, "irradiation": { "clear_sky": { "ghi": 128.63, "dni": 481.49, "dhi": 53.83 }, "cloudy_sky": { "ghi": 32.16, "dni": 0, "dhi": 32.16 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 39.80273, "max_power": 44.60321, "energy": 39.80272 }, "cloudy_sky": { "avg_power": 13.14235, "max_power": 14.43369, "energy": 13.14234 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0.21531, "max_power": 0.32235, "energy": 0.21531 }, "cloudy_sky": { "avg_power": 0.06435, "max_power": 0.07067, "energy": 0.06436 } } ] }, { "start": "15:00", "end": "15:59", "avg_irradiance": { "clear_sky": { "ghi": 85.72, "dni": 393, "dhi": 44.56 }, "cloudy_sky": { "ghi": 21.88, "dni": 0, "dhi": 21.88 } }, "max_irradiance": { "clear_sky": { "ghi": 103.96, "dni": 435.52, "dhi": 48.88 }, "cloudy_sky": { "ghi": 26, "dni": 0, "dhi": 26 } }, "irradiation": { "clear_sky": { "ghi": 85.71, "dni": 393, "dhi": 44.56 }, "cloudy_sky": { "ghi": 21.89, "dni": 0, "dhi": 21.89 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 25.16378, "max_power": 30.99857, "energy": 25.16378 }, "cloudy_sky": { "avg_power": 8.94546, "max_power": 10.62503, "energy": 8.94546 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0.0944, "max_power": 0.10434, "energy": 0.09439 }, "cloudy_sky": { "avg_power": 0.0438, "max_power": 0.05203, "energy": 0.04381 } } ] }, { "start": "16:00", "end": "16:59", "avg_irradiance": { "clear_sky": { "ghi": 34.6, "dni": 223.8, "dhi": 28.44 }, "cloudy_sky": { "ghi": 9.36, "dni": 0, "dhi": 9.36 } }, "max_irradiance": { "clear_sky": { "ghi": 53.72, "dni": 304.84, "dhi": 35.92 }, "cloudy_sky": { "ghi": 14.28, "dni": 0, "dhi": 14.28 } }, "irradiation": { "clear_sky": { "ghi": 34.62, "dni": 223.79, "dhi": 28.46 }, "cloudy_sky": { "ghi": 9.36, "dni": 0, "dhi": 9.36 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 11.5478, "max_power": 15.53669, "energy": 11.54779 }, "cloudy_sky": { "avg_power": 3.82092, "max_power": 5.83559, "energy": 3.82092 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0.05874, "max_power": 0.07492, "energy": 0.05875 }, "cloudy_sky": { "avg_power": 0.01871, "max_power": 0.02857, "energy": 0.0187 } } ] }, { "start": "17:00", "end": "17:59", "avg_irradiance": { "clear_sky": { "ghi": 1.76, "dni": 15.8, "dhi": 4.16 }, "cloudy_sky": { "ghi": 0.48, "dni": 0, "dhi": 0.48 } }, "max_irradiance": { "clear_sky": { "ghi": 6.52, "dni": 60.2, "dhi": 12.88 }, "cloudy_sky": { "ghi": 1.84, "dni": 0, "dhi": 1.84 } }, "irradiation": { "clear_sky": { "ghi": 1.76, "dni": 15.79, "dhi": 4.14 }, "cloudy_sky": { "ghi": 0.49, "dni": 0, "dhi": 0.49 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 1.68101, "max_power": 5.20536, "energy": 1.68101 }, "cloudy_sky": { "avg_power": 0.20024, "max_power": 0.75193, "energy": 0.20024 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0.00824, "max_power": 0.02579, "energy": 0.00824 }, "cloudy_sky": { "avg_power": 0.00098, "max_power": 0.00368, "energy": 0.00098 } } ] }, { "start": "18:00", "end": "18:59", "avg_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "max_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "irradiation": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } } ] }, { "start": "19:00", "end": "19:59", "avg_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "max_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "irradiation": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } } ] }, { "start": "20:00", "end": "20:59", "avg_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "max_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "irradiation": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } } ] }, { "start": "21:00", "end": "21:59", "avg_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "max_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "irradiation": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } } ] }, { "start": "22:00", "end": "22:59", "avg_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "max_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "irradiation": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } } ] }, { "start": "23:00", "end": "23:59", "avg_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "max_irradiance": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "irradiation": { "clear_sky": { "ghi": 0, "dni": 0, "dhi": 0 }, "cloudy_sky": { "ghi": 0, "dni": 0, "dhi": 0 } }, "panels": [ { "panel_id": "01956c1a-e7ac-85ae-9a03-86208c2f6f83", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } }, { "panel_id": "0196afd6-ffe3-885c-8132-53993fbd511a", "clear_sky": { "avg_power": 0, "max_power": 0, "energy": 0 }, "cloudy_sky": { "avg_power": 0, "max_power": 0, "energy": 0 } } ] } ] } ``` ### Fields in API response - `location_id` Unique identifier of the location assigned at resource creation - `lat` Latitude of the location,decimal (−90; 90) - `lon` Longitude of the location,decimal (-180; 180) - `date` Date specified in the API request in the `YYYY-MM-DD` format (from 1979-01-01 up to +15 days to the current date) - `tz` Timezone in the ±XX:XX format - `interval` Time interval during which the energy is summed up. Determines temporary resolution of solar radiation data. If not specified "1h" interval will be used. Available values : 15m, 1h and 1d. - `sunrise` Date and time of sunrise based on date specified in the API request and timezone authomatically determinated by on latitude and longitute of requested location. If you added timezone parameter into API request, then time of sunrise will be recalculated in accordance with this timezone. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `sunset` Date and time of sunset based on date specified in the API request and timezone authomatically determinated by on latitude and longitute of requested location. If you added timezone parameter into API request, then time of sunset will be recalculated in accordance with this timezone. For polar areas in midnight sun and polar night periods this parameter is not returned in the response - `intervals` Interval detalization of daily aggregated irradiation data for the requested date - `start` Start of the time interval for which the energy is summed up. Time interval displays hour and minutes of the day for which indexes were aggregated in "hh:mm" format - `end` End of the time interval for which the energy is summed up. Time interval displays hour and minutes of the day for which indexes were aggregated in "hh:mm" forma - `avg_irradiance` Average irradiance per period - `clear_sky`Clear sky model - `ghi` Clear sky GHI - [Global Horizontal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `dni` Clear sky DNI - [Direct Normal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `dhi` Clear sky DHI - [Diffuse Horizontal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `cloudy_sky`Cloudy sky model - `ghi` Cloudy sky GHI - [Global Horizontal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `dni` Cloudy sky DNI - [Direct Normal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `dhi` Cloudy sky DHI - [Diffuse Horizontal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `max_irradiance` Maximum irradiance per period - `clear_sky`Clear sky model - `ghi` Clear sky GHI - [Global Horizontal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `dni` Clear sky DNI - [Direct Normal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `dhi` Clear sky DHI - [Diffuse Horizontal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `cloudy_sky`Cloudy sky model - `ghi` Cloudy sky GHI - [Global Horizontal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `dni` Cloudy sky DNI - [Direct Normal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `dhi` Cloudy sky DHI - [Diffuse Horizontal Irradiance](/api/solar-radiation/behind-solar-radiation-api.md#introduction), W/m2 - `irradiation` Irradiation related information - `clear_sky`Clear sky model - `ghi` Clear sky GHI - [Global Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dni` Clear sky DNI - [Direct Normal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dhi` Clear sky DHI - [Diffuse Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `cloudy_sky`Cloudy sky model - `ghi` Cloudy sky GHI - [Global Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dni` Cloudy sky DNI - [Direct Normal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `dhi` Cloudy sky DHI - [Diffuse Horizontal Irradiation](/api/solar-radiation/behind-solar-radiation-api.md#introduction), Wh/m2 - `panels` Solar panels related information - `panel_id` Unique identifier of the solar panel assigned at resource creation - `clear_sky` Clear sky model - `avg_power` Solar panel average power output amount per requested interval for clear sky model, kW. Please pay attention that solar panel output values are given for averaged efficiency with a performance ratio 0.75 - `max_power` Solar panel maximum power output amount per requested interval for clear sky model, kW. Note that for the smallest available interval max_power and avg_power will be the same. Please pay attention that solar panel output values are given for averaged efficiency with a performance ratio 0.75 - `energy` Solar panel energy output amount per requested interval for clear sky model, kWh. Note that for the 1h interval energy and avg_power will be the same. Please pay attention that solar panel output values are given for averaged efficiency with a performance ratio 0.75 - `cloudy_sky` Cloudy sky model - `avg_power` Solar panel average power output amount per requested interval for cloudy sky model, kW. Please pay attention that solar panel output values are given for averaged efficiency with a performance ratio 0.75 - `max_power` Solar panel maximum power output amount per requested interval for cloudy sky model, kW. Note that for the smallest available interval max_power and avg_power will be the same. Please pay attention that solar panel output values are given for averaged efficiency with a performance ratio 0.75 - `energy` Solar panel energy output amount per requested interval for cloudy sky model, kWh. Note that for the 1h interval energy and avg_power will be the same. Please pay attention that solar panel output values are given for averaged efficiency with a performance ratio 0.75 ## API errors ### Structure of API errors In case of incorrected API call you will receive API error response. Error response payload returned for all types of errors with the structure below. ### Example of error response ```json { "code": "400", "message": "Invalid date format", "parameters": [ "date" ] } ``` - `code` Code of error - `message` Description of error - `parameters`(optional) List of request parameters names that are related to this particular error ### Errors list Please find more detailed information about some popular errors below. #### API calls return an error 400 Error 400 - Bad Request. You can get error 400 error if either some mandatory parameters in the request are missing or some of request parameters have incorrect format or values out of allowed range. List of all parameters names that are missong or incorrect will be returned in `parameters`attribute of the `ErrorResponse` object. #### API calls return an error 401 Error 401 - Unauthorized. You can get 401 error if API token did not providen in the request or in case API token provided in the request does not grant access to this API. You must add API token with granted access to the product to the request before returing it. #### API calls return an error 404 Error 404 - Not Found. You can get 404 error if data with requested parameters (`lat`, `lon`, `date`, `location_id`, `panel_id`) does not exist in service database. You must not retry the same request. #### API calls return an error 429 Error 429 - Too Many Requests. You can get 429 error if key quato of requests for provided API to this API was exceeded. You may retry request after some time or after extending your key quota. #### API calls return errors '5xx' Errors 5xx - Unexpected Error. You can get '5xx' error in case of other internal errors. Error Response code will be `5xx`. Please [contact us](https://home.openweathermap.org/questions) and enclose an example of your API request that receives this error into your email to let us analyze it and find a solution for you promptly. You may retry the request which led to this error. --- ## Solar Irradiance technology ### Introduction Considering the importance of ecology and the search for renewable energy sources in the modern world, our company has decided to make a contribution to this cause. We wanted to give all our users an opportunity to get valuable data easily, regardless of the size of their projects. Although [Solar Irradiance](/api/solar-irradiance.md) & [Energy Prediction](/api/solar-panels-and-energy-prediction-2.md) service was created on the basis of a large number of scientific articles, algorithms, models and data sources, we wanted, as always, to ensure that our final product is as versatile and easy to use as possible. The basic definitions of solar power sector are solar irradiation and solar irradiance and are often used interchangeably. However, they are not a synonyms: - **Solar irradiation** is the total energy received by a surface of the Earth per unit area over a given period of time. It is the amount of radiation (also known as shortwave radiation) passing through a horizontal plane. Solar irradiance is measured in Wh/m2. - **Solar irradiance** is the surface power density received by a surface of the Earth. Solar irradiance is measured in W/m2. To convert irradiance to irradiation please use the formula below: **Energy(Wh/m****2****) = Power(W/m****2****) * TimeInterval(h)** where energy is a solar irradiation; power is a solar irradiance. For energy data values for 1 h period of TimeInterval = 1 For energy data values for 15 min period of TimeInterval = 0.25 At the first stage of product development, we have selected the most common indices for solar irradiation measurements: DNI, DHI and GHI. We provide each of them for the Clear Sky and Cloudy Sky models: - **Direct Normal Irradiation (DNI)** is the amount of solar irradiation received per unit area by a surface that is always held perpendicular (or normal) to the rays that come in a straight line from the sun at its current position in the sky. Typically, you can maximise the amount of irradiation that a surface receives annually by keeping it normal to incoming irradiation. This quantity is of particular interest to concentrating solar thermal installations and installations that track the position of the sun. - **Diffuse Horizontal Irradiation (DHI)** is the amount of irradiation received per unit area by a surface (not subject to any shade or shadow) that does not arrive on a direct path from the sun, but has been scattered by molecules and particles in the atmosphere and comes equally from all directions. - **Global Horizontal Irradiation (GHI)** is the total amount of short-wave radiation received from above by a surface horizontal to the ground. This value is of particular interest to photovoltaic installations, and includes both DNI and DHI. To calculate these indices, we use the most accurate algorithms available, such as Simplified Solis for Clear Sky and DirInt for Cloudy Sky. Nevertheless, when we employed these algorithms in their original form, we obtained results of unsatisfactory accuracy ([here](#reference) are the materials that we used as reference data). So that we could deliver a great product, we did a lot of additional work on further refining the algorithms to get more accurate output. Below are descriptions of the data in the OpenWeather algorithms. ## OpenWeather Clear Sky model Based on the Simplified Solis algorithm, we have developed our own algorithm called the OpenWeather Clear Sky model. In comparison with the standard input data for the Simplified Solis algorithm, we have enriched the set of input data to our algorithm. As a result, the following input data is used in the OpenWeather Clear Sky model: - Date and time - Geographical coordinates - Sunrise and sunset times - Height above sea level - Ground pressure - Air temperature on the surface - Solar zenith angle. Here are our proprietary improvements to the original algorithm. We send date and time data to the algorithm with a shift of half of a time cycle. According to the 1-hour step of solar radiation forecast data, we shift the date and time half an hour backward for hourly data. This was implemented in order to better consider the position of the sun. When we use the data for the middle of an hour, the model works with values of sun position that are close to the average value of the period, which gives a more accurate result than the values at the beginning or end of the period. Besides this, we correct the calculation of the sun angles, and transfer them to the OpenWeather Clear Sky algorithm by using the sunrise and sunset times within the algorithm. This is needed in order to minimise the anomalous values of the calculated radiation when the altitude angle of the sun approaches 0 degrees during sunrise and sunset (when the angle approaches these values, the radiation values do not increase adequately, becoming unrealistic). Based on the results of the OpenWeather Clear Sky algorithm, we obtain three parameters: DNI Clear Sky, DHI Clear Sky and GHI Clear Sky. The Simplified Solis algorithm description, which is part of the ‘pvlib’ library, can be found [here](https://github.com/pvlib/pvlib-python/blob/709daa6f8feddb50ae50b1da13f5f720d8ebb78f/pvlib/clearsky.py#L406). ## OpenWeather Cloudy Sky model We have also developed the OpenWeather Cloudy Sky model for the calculation of cloudy sky solar radiation data, by improving and correcting the DirInt algorithm. For instance, we have derived the formula for cloudiness correction, which is one of the most important elements of calculating cloudy sky solar radiation data. Basically, all OpenWeather products provide the cloudiness data as a percentage, but our correction is allowed to get the new cloudiness correction coefficient. It means that we convert the percentage values (which show how cloudy the area is) to the exact coefficient of cloud transmittance (which can be multiplied by the radiation value to get its real value). For example, if we have a high percentage of cloudiness, this means that the radiation in this place will be weak due to the clouds. As the next step, we calculate the correction factor of cloudiness to get cloud transmittance. After that, we multiply the radiation value by this coefficient and get the final version for solar radiation. If we have no clouds, which means the radiation will be strong, the cloudiness correction coefficient has no effect on the solar radiation level. Finally, we have the following input data for OpenWeather Cloudy Sky: - GHI index from OpenWeather Clear Sky model results - Dew point - Cloudiness - Date and time - Geographical coordinates - Height above sea level - Ground pressure - Air temperature on the surface - Solar zenith angle. As before, most of the input data is taken from the [OpenWeather datasets and products](/api.md). As a result of the OpenWeather Cloudy Sky algorithm, we have three parameters: DNI Cloudy Sky, DHI Cloudy Sky and GHI Cloudy Sky. The DirInt algorithm description can be found [here](https://github.com/pvlib/pvlib-python/blob/709daa6f8feddb50ae50b1da13f5f720d8ebb78f/pvlib/irradiance.py#L1277). ![solar radiation](/payload/api/media/file/solarradiation-1.png) ## Reference data for solar radiation model experiments We conducted training and corrected our models by using reference data. As a result, we managed to achieve a sufficiently high accuracy from the product. As reference data, we used data from the ECMWF meteorological agency and the Copernicus programme (the European Union’s Earth Observation Programme). Thus we not only took data from weather models but also measured historical data from sensors. We used ERA5 as a weather model source and the CAMS programme data as a sensor’s real data. The ERA5 model has a resolution of 0.36 degrees and contains only historical data with a one-week delay. You can learn more about ERA5 [here](https://confluence.ecmwf.int/display/CKB/ERA5%3A+data+documentation). More information on data from the CAMS programme can be found [here](https://atmosphere.copernicus.eu/solar-radiation). Most of the input data to the OpenWeather Cloudy Sky and Clear Sky models is taken from the [OpenWeather datasets and products](/api.md). Please let us know if you have any questions about the Solar Irradiance API, and our [technical support team](mailto:info@openweathermap.org) will be happy to help you. --- ## Weather stations ### How to connect your weather station to OpenWeatherMap We are glad to announce our new API version for managing your personal weather stations - Weather Stations API 3.0 (beta). It went through some essential changes in comparison with the previous version. The biggest improvement is that users have more flexibility of their stations, and can share/transfer data related to them. The new RESTful style eases this process. In the previous version, a user account was limited to a single station, but with the new version, users can add as many stations as they need. The second innovation is an extended set of parameters which you can pass in the measurements. The data transfer protocol based on METAR and CWOP networks. You could learn more about it [here](#measurement). We are launching the new API version in two stages. As for now you have the possibility to add and set up your meteorological stations using Weather Stations API 3.0 methods for stations management and measurements transmissions. In the nearest future we are planning to provide additional methods which will allow you to collect data from your stations for any period of time. Also we will add support for obtaining the aggregated information with various intervals (minute/hour/day). It'll be possible to receive aggregated history of measurements from your meteorological station for several years by a single query. ## Three simple steps to connect your station to Weather Station API 3.0: 1. Create an account in [members area](/register.md) and [receive a key to access API methods](/appid.md) 2. Register your station in our system using the new API version and get a unique identifier for the station. 3. Transfer weather data using special API method. Note that now you may have several stations attached to your account, so it's important to pass the unique station identifier in every query. ## Basic methods to retrieve data from station These are two methods necessary to start working with OpenWeatherMap service: creation of the station and measurements transfer. Access to full list of API methods [requires you to pass your personal key in the query](/appid.md). When calling methods PUT and POST it's necessary to specify the header `Content-Type: application/json` ### [POST] /stations This method is used to register a station in the OpenWeatherMap service. You need to pass a set of parameters: external identifier, station name and its geographical arrangement. In case of successful creation method returns an HTTP code `201`. ### URL example ```text http://api.openweathermap.org/data/3.0/stations ``` ### Request parameters ```json { "external_id": "SF_TEST001", "name": "San Francisco Test Station", "latitude": 37.76, "longitude": -122.43, "altitude": 150 } ``` ### Headers ```text Content-Type: application/json ``` ### API Response ```json { "ID": "583436dd9643a9000196b8d6", "updated_at": "2016-11-22T12:15:25.96727176Z", "created_at": "2016-11-22T12:15:25.967271732Z", "user_id": "557066d0ff7a7e3897531d94", "external_id": "SF_TEST001", "name": "San Francisco Test Station", "latitude": 37.76, "longitude": -122.43, "altitude": 150, "source_type": 5 } ``` ### [POST] /measurements This method is used to transfer measurements collected from your station. Full description of possible data structures is provided below. Measurements are transferred in an array which allows to specify several data sets at once and to perform a postponed sending. In case of successful measurements dispatch method returns an HTTP code `204`. ### URL example ```text http://api.openweathermap.org/data/3.0/measurements ``` ### Request parameters ```json [ { "station_id": "583436dd9643a9000196b8d6", "dt": 1479817340, "temperature": 18.7, "wind_speed": 1.2, "wind_gust": 3.4, "pressure": 1021, "humidity": 87, "rain_1h": 2, "clouds": [ { "condition": "NSC" } ] } ] ``` ### Headers ```text Content-Type: application/json ``` ### API Response ```json [ { "type": "m", "date": 1480508280, "station_id": "583d7bbbebb3ff000123f1ce", "temp": { "max": 22.7, "min": 21.7, "average": 22.03, "weight": 3 }, "humidity": { "average": 76.33, "weight": 3 }, "wind": { "deg": 160, "speed": 3.3 }, "pressure": { "min": 1031, "max": 1033, "average": 1031.67, "weight": 3 }, "precipitation": {} }, { "type": "m", "date": 1480599660, "station_id": "583d7bbbebb3ff000123f1ce", "temp": { "max": 21.7, "min": 21.7, "average": 21.7, "weight": 1 }, "humidity": { "average": 77, "weight": 1 }, "wind": {}, "pressure": { "min": 1031, "max": 1031, "average": 1031, "weight": 1 }, "precipitation": {} } ] ``` | Parameter | Type & Units | Description | | --- | --- | --- | | `station_id` | | The internal ID of the station which is generated during creation | | `dt` | Unix Timestamp | Time of measurement | | `temperature` | Celsius | The air temperature | | `wind_speed` | m/s | Wind speed | | `wind_gust` | m/s | Maximum speed of wind gusts | | `wind_deg` | Degrees from 0 to 360 | Wind direction | | `pressure` | Hectopascal | Atmospheric pressure | | `humidity` | % | Relative air humidity | | `rain_1h` | mm | Rainfall in the last hour | | `rain_6h` | mm | Rainfall in the last 6 hours | | `rain_24h` | mm | Rainfall for the last days | | `snow_1h` | mm | Snow in the last hour | | `snow_6h` | mm | Snow in the last 6 hours | | `snow_24h` | mm | Snow for the last days | | `dew_point` | Celsius | Dew point | | `humidex` | Celsius | Index of temperature and humidity | | `heat_index` | Celsius | Heat index | | `visibility_distance` | km | Distance of direct visibility, METAR | | `visibility_prefix` | N, E, S, W | Prefix at distinctions of visibility in the directions, METAR | | `clouds[]:distance` | m | Height of the lower bound of overcast, METAR | | `clouds[]:condition` | SKC, NSC, FEW, SCT, BKN, OVC | Cloud amount, METAR | | `clouds[]:cumulus` | CB, TCU | Convective overcast, METAR | | `weather[]:precipitation` | | Additional description, METAR | | `weather[]:descriptor` | | Additional description, METAR | | `weather[]:intensity` | | Additional description, METAR | | `weather[]:proximity` | | Additional description, METAR | | `weather[]:obscuration` | | Additional description, METAR | | `weather[]:other` | | Additional description, METAR | ### [GET] /measurements This method is used for receiving aggregated measurements from stations. In total, there are 3 supported unit types - minutes, hours, and days. Thus, there is a possibility to query the station’s historical measurements for any time interval with the desired level of detail. At the moment the aggregation uses the fixed list of parameters from the collection of measurements - temperature, humidity, pressure, speed and wind direction, precipitation. In the future this list will extend. The following parameters are mandatory in the request - an interval of measurements, the internal identifier of the station, type of the unit and the maximum number of records which can be returned. They are transferred in a line of GET-request as parameters. ### URL Example ```text http://api.openweathermap.org/data/3.0/measurements?station_id=...&type=...&limit=... ``` ### URL Example ```json [ { "type": "m", "date": 1480508280, "station_id": "583d7bbbebb3ff000123f1ce", "temp": { "max": 22.7, "min": 21.7, "average": 22.03, "weight": 3 }, "humidity": { "average": 76.33, "weight": 3 }, "wind": { "deg": 160, "speed": 3.3 }, "pressure": { "min": 1031, "max": 1033, "average": 1031.67, "weight": 3 }, "precipitation": {} }, { "type": "m", "date": 1480599660, "station_id": "583d7bbbebb3ff000123f1ce", "temp": { "max": 21.7, "min": 21.7, "average": 21.7, "weight": 1 }, "humidity": { "average": 77, "weight": 1 }, "wind": {}, "pressure": { "min": 1031, "max": 1031, "average": 1031, "weight": 1 }, "precipitation": {} } ] ``` | Parameter | Description | Example | | --- | --- | --- | | `station_id` | The internal ID of the station which you got during her creation | 583d7bbbebb3ff000123f1ce | | `type` | Type of the aggregated data - minute, hour or day. Specifies the letters `m`, `h` or `d` respectively | m | | `limit` | The maximum number of records with the aggregated measurements which can return in the answer | 100 | | `from` | The beginning of an interval on which data are requested. Is specified in Unix Timestamp format | 1480300000 | | `to` | The end of an interval on which data are requested. Is specified in Unix Timestamp format | 1480700000 | ## Additional features of Weather Stations API 3.0 List all stations, show information about one station, change and remove stations attached to your account. ### [GET] /stations This method is used to obtain the list of all stations added to your account with a standard set of attributes: external and internal identifiers, creation and update timestamps, name, geographical arrangement, height above sea level and station rank. ```text http://api.openweathermap.org/data/3.0/stations ``` ```json [ { "id": "583436dd9643a9000196b8d6", "created_at": "2016-11-22T12:15:25.967Z", "updated_at": "2016-11-22T12:15:25.967Z", "external_id": "SF_TEST001", "name": "San Francisco Test Station", "longitude": -122.43, "latitude": 37.76, "altitude": 150, "rank": 0 }, { "id": "5834367b9643a9000196b8d5", "created_at": "2016-11-22T12:13:47.135Z", "updated_at": "2016-11-22T12:13:47.135Z", "external_id": "NY_TEST001", "name": "New York Test Station", "longitude":-73.99, "latitude": 40.72, "altitude": 30, "rank": 0 } ] ``` ### [GET] /stations/{:id} This method is used to get information about one station with a standard set of attributes: external and internal identifiers, creation and update timestamps, name, geographical arrangement, height above sea level and station rank. ```text http://api.openweathermap.org/data/3.0/stations/583436dd9643a9000196b8d6 ``` ```json { "id": "583436dd9643a9000196b8d6", "created_at": "2016-11-22T12:15:25.967Z", "updated_at": "2016-11-22T12:15:25.967Z", "external_id": "SF_TEST001", "name": "San Francisco Test Station", "longitude": -122.43, "latitude": 37.76, "altitude": 150, "rank": 0 } ``` ### [PUT] /stations/{:id} This method is used to change information about the station. Parameters available for modification: external identifier, name, geographical arrangement, height above sea level. In case of successful change method returns an HTTP code `200`. ### URL Example ```text http://api.openweathermap.org/data/3.0/stations/583436dd9643a9000196b8d6 ``` ### Request parameters ```json { "external_id": "SF_UPD001", "name": "San Francisco Updated Station", "latitude": 37.80, "longitude": -122.47, "altitude": 143 } ``` ### Headers ```text Content-Type: application/json ``` ### API Response ```json { "id": "583436dd9643a9000196b8d6", "created_at": "2016-11-22T12:15:25.967Z", "updated_at": "2016-11-22T12:44:20.170544353Z", "external_id": "SF_UPD001", "name": "San Francisco Updated Station", "longitude": -122.47, "latitude": 37.8, "altitude": 143, "rank": 0 } ``` ### [DELETE] /stations/{:id} This method is used to remove a station from your account. In case of successful removal method returns an HTTP code `204` (Successful answer). Be careful: after this operation all measurements received from the removed station are deleted permanently, so they couldn't be restored. ### URL Example ```text http://api.openweathermap.org/data/3.0/stations/583436dd9643a9000196b8d6 ``` ### URL Example ```json { "id": "583436dd9643a9000196b8d6", "created_at": "2016-11-22T12:15:25.967Z", "updated_at": "2016-11-22T12:15:25.967Z", "external_id": "SF_TEST001", "name": "San Francisco Test Station", "longitude": -122.43, "latitude": 37.76, "altitude": 150, "rank": 0 } ``` ### Possible errors: In case of an error you will receive six-digit HTTP codes: | Parameters | | | --- | --- | | `400` `000` | Error in input data | | `500` `000` | Internal error | | `404` `000` | Object not found | With the following structure: ### Possible errors: ```json { "code": 000000, "message": "string" } ``` - `code` Six-digit error code. First three digits stands for an HTTP code, second - for a special error code. - `message` Error description --- ## Statistical Weather Data API Statistical Weather Data API allows you to get statistical data by main weather parameters for a chosen date or month of the year, or for the entire year. This product is useful for analysis of climate indicators and statistical approach to weather forecasting. Statistical Weather Data API is calculated based on our [Historical weather data](/history.md). In this product, you will be able to request basic statistical data for the following weather characteristics: - Temperature - Pressure - Humidity - Wind - Precipitation - Clouds All weather data can be obtained only in JSON format. The frequency of data update is 1 hour. > Please note that Statistical API **doesn't return real historical data**, but statistically calculated data based on real historical data for a specific period of time. ## Yearly aggregation By using this API, you will be able to receive statistical data for all 365 days of the entire year in one single API response. To get aggregated data only for a specific month or for a specific day, use the methods of [Monthly](/api/statistics-api.md#month) or [Daily Aggregation](/api/statistics-api.md#day). ### API call ```text history.openweathermap.org/data/2.5/aggregated/year?lat={lat}&lon={lon}&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `lat, lon` | Yes | Geographical coordinates (latitude, longitude). If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md). | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | > Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around. > > Please note that [built-in geocoder](/api/statistics-api.md#geocoding) has been deprecated. Although it is still available for use, bug fixing and updates are no longer available for this functionality. ### Example of API call ```text https://history.openweathermap.org/data/2.5/aggregated/year?lat=35&lon=139&appid={API key} ``` The response of API contains 365 groups of statistical data for each day of the entire calendar year. ### Response of Yearly aggregation ```json { "cod":200, "city_id":5400075, "calctime":3.105838634, "result":[ { "month": 1, "day": 1, "temp":{ "record_min":274.44, "record_max":290.45, "average_min":276.79, "average_max":286.5, "median":281.26, "mean":281.29, "p25":278.57, "p75":283.83, "st_dev":3.69, "num":136 }, "pressure":{ "min":1014, "max":1026, "median":1021, "mean":1020.5, "p25":1019, "p75":1023, "st_dev":3.25, "num":135 }, "humidity":{ "min":23, "max":100, "median":70, "mean":65.88, "p25":47, "p75":82, "st_dev":20.63, "num":133 }, "wind":{ "min":0, "max":10, "median":1, "mean":2.36, "p25":1, "p75":3, "st_dev":2.3, "num":136 }, "precipitation":{ "min":0, "max":0.3, "median":0, "mean":0.01, "p25":0, "p75":0, "st_dev":0.04, "num":136 }, "clouds":{ "min":0, "max":90, "median":1, "mean":20.18, "p25":1, "p75":40, "st_dev":31.91, "num":136 } }, ..... ] } ``` - `code`Internal parameter - `city_id`City ID. Please note that built-in geocoder functionality has been deprecated. Learn more [here](/api/statistics-api.md#builtin). - `calctime`Internal parameter - `result` - `month` Month of the year - `day`Day of the month - `temp` - `record_min`Absolute temperature minimum based on all historical measurements for this day, Kelvin. - `record_max`Absolute temperature maximum based on all historical measurements for this day, Kelvin. - `average_min`Average of all minimum temperature values for this day, Kelvin. - `average_max`Average of all maximum temperature values for this day, Kelvin. - `median`The [median value](https://en.wikipedia.org/wiki/Median) of the temperature, Kelvin. - `mean`Average of all temperature measurements for this day, Kelvin. - `p25`The [first quartile](https://en.wikipedia.org/wiki/Quartile) value of the temperature, Kelvin. - `p75` The [third quartile](https://en.wikipedia.org/wiki/Quartile) value of the temperature, Kelvin. - `st_dev`The [standard deviation](https://en.wikipedia.org/wiki/Standard_deviation) of the temperature, Kelvin. - `num`Number of measurements. - `pressure` - `min`Absolute pressure minimum based on all historical measurements for this day, hPa. - `max`Absolute pressure maximum based on all historical measurements for this day, hPa. - `median`The [median value](https://en.wikipedia.org/wiki/Median) of the pressure, hPa. - `mean`Average of all pressure measurements for this day, hPa. - `p25`The [first quartile](https://en.wikipedia.org/wiki/Quartile) value of the pressure, hPa. - `p75` The [third quartile](https://en.wikipedia.org/wiki/Quartile) value of the pressure, hPa. - `st_dev`The [standard deviation](https://en.wikipedia.org/wiki/Standard_deviation) of the pressure, hPa. - `num`Number of measurements. - `humidity` - `min`Absolute humidity minimum based on all historical measurements for this day, %. - `max`Absolute humidity maximum based on all historical measurements for this day, %. - `median`The [median value](https://en.wikipedia.org/wiki/Median) of the humidity, %. - `mean`Average of all humidity measurements for this day, %. - `p25`The [first quartile](https://en.wikipedia.org/wiki/Quartile) value of the humidity, %. - `p75` The [third quartile](https://en.wikipedia.org/wiki/Quartile) value of the humidity, %. - `st_dev`The [standard deviation](https://en.wikipedia.org/wiki/Standard_deviation) of the humidity, %. - `num`Number of measurements. - `wind` - `min`Absolute wind speed minimum based on all historical measurements for this day, meter/sec. - `max`Absolute wind speed maximum based on all historical measurements for this day, meter/sec. - `median`The [median value](https://en.wikipedia.org/wiki/Median) of the wind speed, meter/sec. - `mean`Average of all wind speed measurements for this day, meter/sec. - `p25`The [first quartile](https://en.wikipedia.org/wiki/Quartile) value of the wind speed, meter/sec. - `p75` The [third quartile](https://en.wikipedia.org/wiki/Quartile) value of the wind speed, meter/sec. - `st_dev`The [standard deviation](https://en.wikipedia.org/wiki/Standard_deviation) of the wind speed, meter/sec. - `num`Number of measurements. - `precipitation` - `min`Absolute precipitation volume minimum based on all historical measurements for this day, mm. - `max`Absolute precipitation volume maximum based on all historical measurements for this day, mm. - `median`The [median value](https://en.wikipedia.org/wiki/Median) of the precipitation volume, mm. - `mean`Average of all precipitation volume measurements for this day, mm. - `p25`The [first quartile](https://en.wikipedia.org/wiki/Quartile) value of the precipitation volume, mm. - `p75` The [third quartile](https://en.wikipedia.org/wiki/Quartile) value of the precipitation volume, mm. - `st_dev`The [standard deviation](https://en.wikipedia.org/wiki/Standard_deviation) of the precipitation volume, mm. - `num`Number of measurements. ### Monthly aggregation By using this API, you will be able to request statistical monthly weather data for any month of the entire year in a single API response. If you like to receive aggregated data only for one specific day, please use the [Daily Aggregation](/api/statistics-api.md#day) approach described below. ### API call ```text history.openweathermap.org/data/2.5/aggregated/month?lat={lat}&lon={lon}&month={number of the month} ``` | Parameters | | | | --- | --- | --- | | `lat, lon` | Yes | Geographical coordinates (latitude, longitude). If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md). | | `month` | Yes | A number of the month in the year. Available values: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`. | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | > Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around. > > Please note that [built-in geocoder](/api/statistics-api.md#geocoding) has been deprecated. Although it is still available for use, bug fixing and updates are no longer available for this functionality. ### Example of API call ```text https://history.openweathermap.org/data/2.5/aggregated/month?month=2&lat=35&lon=139&appid={API key} ``` The Response of API contains 1 group of statistical data for selected month. ### Example of API response ```json { "cod":200, "city_id":5400075, "calctime":0.417010027, "result":{ "month": 2, "temp":{ "record_min":269.85, "record_max":296.05, "average_min":274.17, "average_max":291.97, "median":283.71, "mean":283.69, "p25":281.05, "p75":286.18, "st_dev":3.98, "num":3953 }, "pressure":{ "min":988, "max":1036, "median":1020, "mean":1019.34, "p25":1016, "p75":1024, "st_dev":6.94, "num":3942 }, "humidity":{ "min":17, "max":100, "median":81, "mean":77.38, "p25":67, "p75":89, "st_dev":16.33, "num":3669 }, "wind":{ "min":0, "max":17, "median":1, "mean":2.06, "p25":1, "p75":3, "st_dev":1.96, "num":3953 }, "precipitation":{ "min":0, "max":3, "median":0, "mean":0.16, "p25":0, "p75":0, "st_dev":0.46, "num":3953 }, "clouds":{ "min":0, "max":90, "median":12, "mean":37.4, "p25":1, "p75":90, "st_dev":39.94, "num":3953 }, "sunshine_hours":102.17 } } ``` - `code`Internal parameter - `city_id`City ID. Please note that built-in geocoder functionality has been deprecated. Learn more [here](/api/statistics-api.md#builtin). - `calctime`Internal parameter - `result` - `month`Month of the year - `temp` - `record_min`Absolute temperature minimum based on all historical measurements for this month, Kelvin. - `record_max`Absolute temperature maximum based on all historical measurements for this month, Kelvin. - `average_min`Average of all minimum temperature values for this month, Kelvin. - `average_max`Average of all maximum temperature values for this month, Kelvin. - `median`The [median value](https://en.wikipedia.org/wiki/Median) of the tempreture, Kelvin. - `mean`Average of all temperature measurements for this month, Kelvin. - `p25`The [first quartile](https://en.wikipedia.org/wiki/Quartile) value of the temperature, Kelvin. - `p75` The [third quartile](https://en.wikipedia.org/wiki/Quartile) value of the temperature, Kelvin. - `st_dev`The [standard deviation](https://en.wikipedia.org/wiki/Standard_deviation) of the temperature, Kelvin. - `num`Number of measurements. - `pressure` - `min`Absolute pressure minimum based on all historical measurements for this month, hPa. - `max`Absolute pressure maximum based on all historical measurements for this month, hPa. - `median`The [median value](https://en.wikipedia.org/wiki/Median) of the pressure, hPa. - `mean`Average of all pressure measurements for this month, hPa. - `p25`The [first quartile](https://en.wikipedia.org/wiki/Quartile) value of the pressure, hPa. - `p75` The [third quartile](https://en.wikipedia.org/wiki/Quartile) value of the pressure, hPa. - `st_dev`The [standard deviation](https://en.wikipedia.org/wiki/Standard_deviation) of the pressure, hPa. - `num`Number of measurements. - `humidity` - `min`Absolute humidity minimum based on all historical measurements for this month, %. - `max`Absolute humidity maximum based on all historical measurements for this month, %. - `median`The [median value](https://en.wikipedia.org/wiki/Median) of the humidity, %. - `mean`Average of all humidity measurements for this month, %. - `p25`The [first quartile](https://en.wikipedia.org/wiki/Quartile) value of the humidity, %. - `p75` The [third quartile](https://en.wikipedia.org/wiki/Quartile) value of the humidity, %. - `st_dev`The [standard deviation](https://en.wikipedia.org/wiki/Standard_deviation) of the humidity, %. - `num`Number of measurements. - `wind` - `min`Absolute wind speed minimum based on all historical measurements for this month, meter/sec. - `max`Absolute wind speed maximum based on all historical measurements for this month, meter/sec. - `median`The [median value](https://en.wikipedia.org/wiki/Median) of the wind speed, meter/sec. - `mean`Average of all wind speed measurements for this month, meter/sec. - `p25`The [first quartile](https://en.wikipedia.org/wiki/Quartile) value of the wind speed, meter/sec. - `p75` The [third quartile](https://en.wikipedia.org/wiki/Quartile) value of the wind speed, meter/sec. - `st_dev`The [standard deviation](https://en.wikipedia.org/wiki/Standard_deviation) of the wind speed, meter/sec. - `num`Number of measurements. - `precipitation` - `min`Absolute precipitation volume minimum based on all historical measurements for this month, mm. - `max`Absolute precipitation volume maximum based on all historical measurements for this month, mm. - `median`The [median value](https://en.wikipedia.org/wiki/Median) of the precipitation volume, mm. - `mean`Average of all precipitation volume measurements for this month, mm. - `p25`The [first quartile](https://en.wikipedia.org/wiki/Quartile) value of the precipitation volume, mm. - `p75` The [third quartile](https://en.wikipedia.org/wiki/Quartile) value of the precipitation volume, mm. - `st_dev`The [standard deviation](https://en.wikipedia.org/wiki/Standard_deviation) of the precipitation volume, mm. - `num`Number of measurements. - `sunshine_hours`The number of sunny hours in the selected month. ### Daily aggregation Using this API method, you will receive in one API response statistical data for any day during the entire calendar year. To get aggregated data only for a specific month, use methods of [Month Aggregation](#month). ### API call ```text history.openweathermap.org/data/2.5/aggregated/day?lat={lat}&lon={lon}&month={number of the month}&day={number of the day} ``` | Parameters | | | | --- | --- | --- | | `lat, lon` | Yes | Geographical coordinates (latitude, longitude). If you need the geocoder to automatic convert city names and zip-codes to geo coordinates and the other way around, please use our [Geocoding API](/api/geocoding-api.md). | | `month` | Yes | A number of the month in the year. Available values: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`. | | `day` | Yes | A number of the day in month. Available values: `1` - `31` | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | > Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around. > > Please note that [built-in geocoder](#geocoding) has been deprecated. Although it is still available for use, bug fixing and updates are no longer available for this functionality. ### Example of API call ```text https://history.openweathermap.org/data/2.5/aggregated/day?lat=35&lon=139&month=2&day=2&appid={API key} ``` The response of API contains 1 group of statistical data for selected day. ### Example of API response ```json { "cod":200, "city_id":5400075, "calctime":0.022604633, "result":{ "month":1, "day":1, "temp":{ "record_min":275.9, "record_max":291.14, "average_min":283.27, "average_max":289.06, "median":285.41, "mean":285.17, "p25":283.52, "p75":287.59, "st_dev":3.32, "num":124 }, "pressure":{ "min":1014, "max":1027, "median":1019, "mean":1019.02, "p25":1017, "p75":1020, "st_dev":2.65, "num":124 }, "humidity":{ "min":32, "max":100, "median":81, "mean":80.51, "p25":76, "p75":87, "st_dev":11.05, "num":111 }, "wind":{ "min":0, "max":8, "median":2, "mean":2.14, "p25":1, "p75":3, "st_dev":1.69, "num":124 }, "precipitation":{ "min":0, "max":0.9, "median":0, "mean":0.09, "p25":0, "p75":0, "st_dev":0.2, "num":124 }, "clouds":{ "min":1, "max":90, "median":90, "mean":68.52, "p25":75, "p75":90, "st_dev":31.45, "num":124 } } } ``` ### Fields in API response - `code`Internal parameter - `city_id`City ID. Please note that built-in geocoder functionality has been deprecated. Learn more [here](#builtin). - `calctime`Internal parameter - `result` - `month` Month of the year - `day` Day of the month - `temp` - `record_min`Absolute temperature minimum based on all historical measurements for this day, Kelvin. - `record_max`Absolute temperature maximum based on all historical measurements for this day, Kelvin. - `average_min`Average of all minimum temperature values for this day, Kelvin. - `average_max`Average of all maximum temperature values for this day, Kelvin. - `median`The [median value](https://en.wikipedia.org/wiki/Median) of the tempreture, Kelvin. - `mean`Average of all temperature measurements for this day, Kelvin. - `p25`The [first quartile](https://en.wikipedia.org/wiki/Quartile) value of the tempreture, Kelvin. - `p75` The [third quartile](https://en.wikipedia.org/wiki/Quartile) value of the tempreture, Kelvin. - `st_dev`The [standard deviation](https://en.wikipedia.org/wiki/Standard_deviation) of the tempreture, Kelvin. - `num`Number of measurements. - `pressure` - `min`Absolute pressure minimum based on all historical measurements for this day, hPa. - `max`Absolute pressure maximum based on all historical measurements for this day, hPa. - `median`The [median value](https://en.wikipedia.org/wiki/Median) of the pressure, hPa. - `mean`Average of all pressure measurements for this day, hPa. - `p25`The [first quartile](https://en.wikipedia.org/wiki/Quartile) value of the pressure, hPa. - `p75` The [third quartile](https://en.wikipedia.org/wiki/Quartile) value of the pressure, hPa. - `st_dev`The [standard deviation](https://en.wikipedia.org/wiki/Standard_deviation) of the pressure, hPa. - `num`Number of measurements. - `humidity` - `min`Absolute humidity minimum based on all historical measurements for this day, %. - `max`Absolute humidity maximum based on all historical measurements for this day, %. - `median`The [median value](https://en.wikipedia.org/wiki/Median) of the humidity, %. - `mean`Average of all humidity measurements for this day, %. - `p25`The [first quartile](https://en.wikipedia.org/wiki/Quartile) value of the humidity, %. - `p75` The [third quartile](https://en.wikipedia.org/wiki/Quartile) value of the humidity, %. - `st_dev`The [standard deviation](https://en.wikipedia.org/wiki/Standard_deviation) of the humidity, %. - `num`Number of measurements. - `wind` - `min`Absolute wind speed minimum based on all historical measurements for this day, meter/sec. - `max`Absolute wind speed maximum based on all historical measurements for this day, meter/sec. - `median`The [median value](https://en.wikipedia.org/wiki/Median) of the wind speed, meter/sec. - `mean`Average of all wind speed measurements for this day, meter/sec. - `p25`The [first quartile](https://en.wikipedia.org/wiki/Quartile) value of the wind speed, meter/sec. - `p75` The [third quartile](https://en.wikipedia.org/wiki/Quartile) value of the wind speed, meter/sec. - `st_dev`The [standard deviation](https://en.wikipedia.org/wiki/Standard_deviation) of the wind speed, meter/sec. - `num`Number of measurements. - `precipitation` - `min`Absolute precipitation volume minimum based on all historical measurements for this day, mm. - `max`Absolute precipitation volume maximum based on all historical measurements for this day, mm. - `median`The [median value](https://en.wikipedia.org/wiki/Median) of the precipitation volume, mm. - `mean`Average of all precipitation volume measurements for this day, mm. - `p25`The [first quartile](https://en.wikipedia.org/wiki/Quartile) value of the precipitation volume, mm. - `p75` The [third quartile](https://en.wikipedia.org/wiki/Quartile) value of the precipitation volume, mm. - `st_dev`The [standard deviation](https://en.wikipedia.org/wiki/Standard_deviation) of the precipitation volume, mm. - `num`Number of measurements. ### Other features ### Geocoding API Requesting API calls by geographical coordinates is the most accurate way to specify any location. If you need to convert city names to geo coordinates and the other way around automatically, please use our [Geocoding API](/api/geocoding-api.md). > Please use [Geocoder API](/api/geocoding-api.md) if you need automatic convert city names and zip-codes to geo coordinates and the other way around. > > **Please note that API requests by city name and city id have been deprecated. Although they are still available for use, bug fixing and updates are no longer available for this functionality.** ### Built-in API request by city name Please use the parameter `q` instead of the parameters `lat,lon` to specify the city name in the API requests. | Parameters | | | | --- | --- | --- | | `q` | Yes | City name, state code and country code divided by comma, please refer to [ISO 3166](https://www.iso.org/obp/ui/) for the state codes or country codes. You can specify the parameter not only in English. In this case, the API response should be returned in the same language as the language of requested location name if the location is in our predefined list of more than 200,000 locations. | Yearly aggregation ### Example of API calls ```text https://history.openweathermap.org/data/2.5/aggregated/year?q=London,GB&appid={API key} ``` Monthly aggregation ### Example of API call ```text https://history.openweathermap.org/data/2.5/aggregated/month?q=London,GB&month=2&appid={API key} ``` Daily aggregation ### Example of API call ```text https://history.openweathermap.org/data/2.5/aggregated/day?q=London,GB&month=2&day=1&appid={API key} ``` ### Built-in API request by city id Please use the parameter `id` instead of the parameters `lat,lon` to specify the city id in the API requests. | Parameters | | | | --- | --- | --- | | `id` | Yes | City ID. The list of city IDs 'city.list.json.gz' can be downloaded [here](http://bulk.openweathermap.org/sample/). | Yearly aggregation ### Example of API calls ```text https://history.openweathermap.org/data/2.5/aggregated/year?id=2643743&appid={API key} ``` Monthly aggregation ### API call ```text https://history.openweathermap.org/data/2.5/aggregated/month?id=2643743&month=2&appid={API key} ``` Daily aggregation ### Example of API call ```text https://history.openweathermap.org/data/2.5/aggregated/day?id=2643743&month=2&day=2&appid={API key} ``` --- ## US Precipitation Map Get current, forecast and historical US precipitation weather maps with a 10 minutes-step via the easy-to-work API. ## Features of US Precipitation Map 1. Current, forecast and historical weather maps 2. - Forecast US precipitation map for the next 5 hours - Historical weather map for the previous 2 days 3. Update period is every 10 minutes 4. Resolution less than 1 km 5. Coverage: for US only 6. Weather sources US Precipitatoin Map is based on global weather models, satellites, radars and our OWM NWP-ML technology. 7. There is the [OpenWeather Interactive Weather Maps](/weathermap.md?basemap=map&cities=true&layer=radar&lat=56.9510&lon=24.1064&zoom=5) with Global Precipitation layer, which provide users with free access to visual data. ## URL format and parameters Use the following URL format and parameters to get weather maps. Please pay attention to the URL example. ### API call ```text https://maps.openweathermap.org/maps/2.0/radar/us/forecast/{z}/{x}/{y}?appid={API key}&tm={date} ``` | Parameters | | | | --- | --- | --- | | `{z}` | Yes | Number of zoom level The minimum value is **3**, and the maximum value is **7** | | `{x}` | Yes | Number of x tile coordinate | | `{y}` | Yes | Number of y tile coordinate | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `tm` | Yes | Date and time of (Unix time, UTC), e.g. 1600781192. To get historical or forecast data, please specify the date in your API request. | > Please pay attention to the points bellow to avoid possible errors: > > - Please specify dates in all API requests. > - Please specify dates with 10 minutes steps. For example, 1600780200, 1600780800, 1600781400, etc. > - Please specify dates not earlier than 2 days from the current time and not later than 5 hours from the current time. > - Please specify {x} and {y} for US locations only. ### URL example ```text https://maps.openweathermap.org/maps/2.0/radar/us/forecast/3/1/3?&appid={API key}&tm=1600781400 ``` > You need to insert the generated URL into special plugins. > > For example, Leaflet, OpenLayers. You can also use any other apps that support the display of layers. [Learn more](#library). ## Libraries to connect weather layers ### Open Layers The following functions are available for the OpenLayers library: - Classes of weather layer and weather stations layer - Possibility to set your own style - Classes with clustered markers - Support of marker server clustering ### Leaflet The OpenWeatherMap javascript library is designed to work with the Leaflet mapping service. The current version of the library allows the following: - Embedding of layer with current weather in cities - Embedding of layer with weather stations - The library supports customer clustering --- ## Ultraviolet Index (Deprecated) > The product retired on **1st April 2021**, please find UV data in [One Call API 4.0](/api/one-call-4.md). One Call API includs current, hourly forecast for 7 days and 5 days historical UV data. Access current, forecast and historical UV data for any location on Earth including over 200,000 cities! Data is available in the JSON format. ## Call current UV data | Parameters of API call | | | | --- | --- | --- | | `lat, lon` | Yes | Geographical coordinates (latitude, longitude) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### Example of API response ```json { "lat":37.75, "lon":-122.37, "date_iso":"2017-06-26T12:00:00Z", "date":1498478400, "value":10.06 } ``` ## Call forecast UV data The data is available for 8 days ahead. | Parameters of API call | | | | --- | --- | --- | | `lat, lon` | Yes | Geographical coordinates (latitude, longitude) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `cnt` | optional | A number of timestamps in response. | ### Example of API call ```json [ { "lat":37.75, "lon":-122.37, "date_iso":"2017-06-27T12:00:00Z", "date":1498564800, "value":10.1 }, { "lat":37.75, "lon":-122.37, "date_iso":"2017-06-28T12:00:00Z", "date":1498651200, "value":10.19 }, ... { "lat":37.75, "lon":-122.37, "date_iso":"2017-07-04T12:00:00Z", "date":1499169600, "value":10.05 } ] ``` ## Call historical UV data | Parameters | | | | --- | --- | --- | | `lat, lon` | Yes | Geographical coordinates (latitude, longitude) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `cnt` | optional | A number of timestamps in response. | | `start` | optional | Starting point of time period in UNIX time | | `end` | optional | Final point of time period in UNIX time | ### Example of API call ```json [ { "lat":37.75, "lon":-122.37, "date_iso":"2017-06-22T12:00:00Z", "date":1498132800, "value":9.92 }, { "lat":37.75, "lon":-122.37, "date_iso":"2017-06-23T12:00:00Z", "date":1498219200, "value":10.09 }, { "lat":37.75, "lon":-122.37, "date_iso":"2017-06-24T12:00:00Z", "date":1498305600, "value":10.95 }, { "lat":37.75, "lon":-122.37, "date_iso":"2017-06-25T12:00:00Z", "date":1498392000, "value":11.03 }, { "lat":37.75, "lon":-122.37, "date_iso":"2017-06-26T12:00:00Z", "date":1498478400, "value":10.06 } ] ``` > The data is available starting from the 2017-06-22. ## Server response format > Please remember that data is provided only for 12:00 p.m. ```json { "lat": 38.75, "lon": 40.25, "date_iso": "2017-06-23T12:00:00Z", "date": 1498219200, "value": 10.16 } ``` - `lat` float latitude for returned data - `lon` float longitude for returned data - `date_iso` string date and time corresponding to returned date - `date` integer ISO 8601 timestamp - `value` float longitude for returned data ### Codes of requests > If API call is successful - 200 HTTP-code is returned. If location is not found or wrong APPID is specified then HTTP-code 404 or HTTP-code 400 are returned accordingly. --- ## Weather Conditions ### Weather icons **Example of API response** [https://api.openweathermap.org/data/2.5/weather?q=London](https://samples.openweathermap.org/data/2.5/weather?q=London&appid=b1b15e88fa797225412429c1c50c122a1) ### Example of API response ```text ... "weather": [ { "id": 500, "main":"Rain", "description": "light rain", "icon": "10n" } ], ... ``` > NOTE: It is possible to meet more than one weather condition for a requested location. The first weather condition in API respond is primary. [An example](http://samples.openweathermap.org/data/2.5/find?q=London&appid=b1b15e88fa797225412429c1c50c122a1r) ### How to get icon URL For code 500 - light rain icon = "10d". See below a [full list of codes](/weather-conditions.md#Weather-Condition-Codes-2) URL is [https://openweathermap.org/payload/api/media/file/10d@2x.png](/payload/api/media/file/10d%402x.png) [.png](/payload/api/files/file/10d%402x.png). ### Icon list | **Day icon** | **Night icon** | **Description** | | --- | --- | --- | | 01d.png ![clear sky](/payload/api/media/file/01d.png) | 01n.png ![clear sky](/payload/api/media/file/01n.png) | clear sky | | 02d.png ![few clouds](/payload/api/media/file/02d.png) | 02n.png ![few clouds](/payload/api/media/file/02n.png) | few clouds | | 03d.png ![03d.png](/payload/api/media/file/03d.png) | 03n.png ![03n.png](/payload/api/media/file/03n.png) | scattered clouds | | 04d.png ![cloud](/payload/api/media/file/04d.png) | 04n.png ![04n.png](/payload/api/media/file/04n.png) | broken clouds | | 09d.png ![09d.png](/payload/api/media/file/09d.png) | 09n.png ![09n.png](/payload/api/media/file/09n.png) | shower rain | | 10d.png ![rain](/payload/api/media/file/10d.png) | 10n.png ![10n.png](/payload/api/media/file/10n.png) | rain | | 11d.png ![11d.png](/payload/api/media/file/11d.png) | 11n.png ![11n.png](/payload/api/media/file/11n.png) | thunderstorm | | 13d.png ![13d.png](/payload/api/media/file/13d.png) | 13n.png ![13n.png](/payload/api/media/file/13n.png) | snow | | 50d.png ![50d.png](/payload/api/media/file/50d.png) | 50n.png ![50n.png](/payload/api/media/file/50n.png) | mist | ### Weather condition codes | Group 2xx: Thunderstorm | | | | | --- | --- | --- | --- | | 200 | Thunderstorm | thunderstorm with light rain | ![11d.png](/payload/api/media/file/11d.png) 11d | | 201 | Thunderstorm | thunderstorm with rain | ![11d.png](/payload/api/media/file/11d.png) 11d | | 202 | Thunderstorm | thunderstorm with heavy rain | ![11d.png](/payload/api/media/file/11d.png) 11d | | 210 | Thunderstorm | light thunderstorm | ![11d.png](/payload/api/media/file/11d.png) 11d | | 211 | Thunderstorm | thunderstorm | ![11d.png](/payload/api/media/file/11d.png) 11d | | 212 | Thunderstorm | heavy thunderstorm | ![11d.png](/payload/api/media/file/11d.png) 11d | | 221 | Thunderstorm | ragged thunderstorm | ![11d.png](/payload/api/media/file/11d.png) 11d | | 230 | Thunderstorm | thunderstorm with light drizzle | ![11d.png](/payload/api/media/file/11d.png) 11d | | 231 | Thunderstorm | thunderstorm with drizzle | ![11d.png](/payload/api/media/file/11d.png) 11d | | 232 | Thunderstorm | thunderstorm with heavy drizzle | ![11d.png](/payload/api/media/file/11d.png) 11d | | Group 3xx: Drizzle | | | | | --- | --- | --- | --- | | 300 | Drizzle | light intensity drizzle | ![09d.png](/payload/api/media/file/09d.png) 09d | | 301 | Drizzle | drizzle | ![09d.png](/payload/api/media/file/09d.png) 09d | | 302 | Drizzle | heavy intensity drizzle | ![09d.png](/payload/api/media/file/09d.png) 09d | | 310 | Drizzle | light intensity drizzle rain | ![09d.png](/payload/api/media/file/09d.png) 09d | | 311 | Drizzle | drizzle rain | ![09d.png](/payload/api/media/file/09d.png) 09d | | 312 | Drizzle | heavy intensity drizzle rain | ![09d.png](/payload/api/media/file/09d.png) 09d | | 313 | Drizzle | shower rain and drizzle | ![09d.png](/payload/api/media/file/09d.png) 09d | | 314 | Drizzle | heavy shower rain and drizzle | ![09d.png](/payload/api/media/file/09d.png) 09d | | 321 | Drizzle | shower drizzle | ![09d.png](/payload/api/media/file/09d.png) 09d | | Group 5xx: Rain | | | | | --- | --- | --- | --- | | 500 | Rain | light rain | ![rain](/payload/api/media/file/10d.png) 10d | | 501 | Rain | moderate rain | ![rain](/payload/api/media/file/10d.png) 10d | | 502 | Rain | heavy intensity rain | ![rain](/payload/api/media/file/10d.png) 10d | | 503 | Rain | very heavy rain | ![rain](/payload/api/media/file/10d.png) 10d | | 504 | Rain | extreme rain | ![rain](/payload/api/media/file/10d.png) 10d | | 511 | Rain | freezing rain | ![13d.png](/payload/api/media/file/13d.png) 13d | | 520 | Rain | light intensity shower rain | ![09d.png](/payload/api/media/file/09d.png) 09d | | 521 | Rain | shower rain | ![09d.png](/payload/api/media/file/09d.png) 09d | | 522 | Rain | heavy intensity shower rain | ![09d.png](/payload/api/media/file/09d.png) 09d | | 531 | Rain | ragged shower rain | ![09d.png](/payload/api/media/file/09d.png) 09d | | Group 6xx: Snow | | | | | --- | --- | --- | --- | | 600 | Snow | light snow | ![13d.png](/payload/api/media/file/13d.png) 13d | | 601 | Snow | snow | ![13d.png](/payload/api/media/file/13d.png) 13d | | 602 | Snow | heavy snow | ![13d.png](/payload/api/media/file/13d.png) 13d | | 611 | Snow | sleet | ![13d.png](/payload/api/media/file/13d.png) 13d | | 612 | Snow | light shower sleet | ![13d.png](/payload/api/media/file/13d.png) 13d | | 613 | Snow | shower sleet | ![13d.png](/payload/api/media/file/13d.png) 13d | | 615 | Snow | light rain and snow | ![13d.png](/payload/api/media/file/13d.png) 13d | | 616 | Snow | rain and snow | ![13d.png](/payload/api/media/file/13d.png) 13d | | 620 | Snow | light shower snow | ![13d.png](/payload/api/media/file/13d.png) 13d | | 621 | Snow | shower snow | ![13d.png](/payload/api/media/file/13d.png) 13d | | 622 | Snow | heavy shower snow | ![13d.png](/payload/api/media/file/13d.png) 13d | | Group 7xx: Atmosphere | | | | | --- | --- | --- | --- | | 701 | Mist | mist | ![50d.png](/payload/api/media/file/50d.png) 50d | | 711 | Smoke | smoke | ![50d.png](/payload/api/media/file/50d.png) 50d | | 721 | Haze | haze | ![50d.png](/payload/api/media/file/50d.png) 50d | | 731 | Dust | sand/dust whirls | ![50d.png](/payload/api/media/file/50d.png) 50d | | 741 | Fog | fog | ![50d.png](/payload/api/media/file/50d.png) 50d | | 751 | Sand | sand | ![50d.png](/payload/api/media/file/50d.png) 50d | | 761 | Dust | dust | ![50d.png](/payload/api/media/file/50d.png) 50d | | 762 | Ash | volcanic ash | ![50d.png](/payload/api/media/file/50d.png) 50d | | 771 | Squall | squalls | ![50d.png](/payload/api/media/file/50d.png) 50d | | 781 | Tornado | tornado | ![50d.png](/payload/api/media/file/50d.png) 50d | | Group 800: Clear | | | | | --- | --- | --- | --- | | 800 | Clear | clear sky | ![clear sky](/payload/api/media/file/01d.png) 01d ![clear sky](/payload/api/media/file/01n.png) 01n | | Group 80x: Clouds | | | | | --- | --- | --- | --- | | 801 | Clouds | few clouds: 11-25% | ![few clouds](/payload/api/media/file/02d.png) 02d ![few clouds](/payload/api/media/file/02n.png) 02n | | 802 | Clouds | scattered clouds: 25-50% | ![03d.png](/payload/api/media/file/03d.png) 03d ![03n.png](/payload/api/media/file/03n.png) 03n | | 803 | Clouds | broken clouds: 51-84% | ![cloud](/payload/api/media/file/04d.png) 04d ![04n.png](/payload/api/media/file/04n.png) 04n | | 804 | Clouds | overcast clouds: 85-100% | ![cloud](/payload/api/media/file/04d.png) 04d ![04n.png](/payload/api/media/file/04n.png) 04n | --- ## Units in API response ### API response parameters with available units of measurement Table below contains paramers, their description and units of measure for `standard`, `imperial` and `metric` systems of measurement. > Please note, that parameter names and their descriptions and data format of API responce may slightly differ from products documentation, but have the same physical meaning. | Parameter | Description | Standard | Metric | Imperial | | --- | --- | --- | --- | --- | | `dt` | Data | unix, UTC | unix, UTC | unix, UTC | | `start` | Date and time of the start | unix, UTC | unix, UTC | unix, UTC | | `end` | Date and time of the end | unix, UTC | unix, UTC | unix, UTC | | `timezone` | Shift in seconds from UTC | unix, UTC | unix, UTC | unix, UTC | | `sunrise` | Sunrise time | unix, UTC | unix, UTC | unix, UTC | | `sunset` | Sunset time | unix, UTC | unix, UTC | unix, UTC | | `lat` | Latitude | - | - | - | | `lon` | Longitude | - | - | - | | `temp` | Temperature | Kelvin | Celsius | Fahrenheit | | `temp` | Accumulated indicator (only for Accumulated parameters) | Kelvin | Kelvin | Kelvin | | `temp_min` | Minimum temperature | Kelvin | Celsius | Fahrenheit | | `temp_max` | Maximum temperature | Kelvin | Celsius | Fahrenheit | | `temp.day` | Temperature at 12:00 local time | Kelvin | Celsius | Fahrenheit | | `temp.night` | Temperature at 00:00 local time | Kelvin | Celsius | Fahrenheit | | `temp.eve` | Temperature at 18:00 local time | Kelvin | Celsius | Fahrenheit | | `temp.morn` | Temperature at 06:00 local time | Kelvin | Celsius | Fahrenheit | | `feels_like` | Temperature in account with the human perception of weather | Kelvin | Celsius | Fahrenheit | | `feels_like.day` | Temperature at 12:00 local time in account with the human perception of weather | Kelvin | Celsius | Fahrenheit | | `feels_like.night` | Temperature at 00:00 local time in account with the human perception of weather | Kelvin | Celsius | Fahrenheit | | `feels_like.eve` | Temperature at 18:00 local time in account with the human perception of weather | Kelvin | Celsius | Fahrenheit | | `feels_like.morn` | Temperature at 06:00 local time in account with the human perception of weather | Kelvin | Celsius | Fahrenheit | | `road.temp` | Road surface temperature | Kelvin | Celsius | Fahrenheit | | `temp_record_min` | Absolute temperature minimum based on all historical measurements | Kelvin | Kelvin | Kelvin | | `temp_record_max` | Absolute temperature maximum based on all historical measurements | Kelvin | Kelvin | Kelvin | | `temp_average_min` | Average of all minimum temperature values | Kelvin | Kelvin | Kelvin | | `temp_average_max` | Average of all maximum temperature values for this day | Kelvin | Kelvin | Kelvin | | `temp_median` | The median value of the temperature | Kelvin | Kelvin | Kelvin | | `temp_mean` | Average of all temperature measurements | Kelvin | Kelvin | Kelvin | | `temp_p25` | The first quartile of the temperature | Kelvin | Kelvin | Kelvin | | `temp_p75` | The third quartile of the temperature | Kelvin | Kelvin | Kelvin | | `temp_st_dev` | The standard deviation of the temperature | Kelvin | Kelvin | Kelvin | | `pressure` | Atmospheric pressure | hPa | hPa | hPa | | `sea_level` | Atmospheric pressure on the sea level | hPa | hPa | hPa | | `grnd_level` | Atmospheric pressure on the ground level | hPa | hPa | hPa | | `pressure_min` | Absolute pressure minimum based on all historical measurements | hPa | hPa | hPa | | `pressure_max` | Absolute pressure maximum based on all historical measurements | hPa | hPa | hPa | | `pressure_median` | The median value of the pressure | hPa | hPa | hPa | | `pressure_mean` | Average of all pressure measurements | hPa | hPa | hPa | | `pressure_p25` | The first quartile of the pressure | hPa | hPa | hPa | | `pressure_p75` | The third quartile of the pressure | hPa | hPa | hPa | | `pressure_st_dev` | The standard deviation of the pressure | hPa | hPa | hPa | | `humidity` | Humidity | % | % | % | | `humidity_min` | Absolute humidity minimum based on all historical measurements | % | % | % | | `humidity_max` | Absolute humidity maximum based on all historical measurements | % | % | % | | `humidity_median` | The median value of the humidity | % | % | % | | `humidity_mean` | Average of all humidity measurements | % | % | % | | `humidity_p25` | The first quartile of the humidity | % | % | % | | `pressure_p75` | The third quartile of the humidity | % | % | % | | `humidity_st_dev` | The standard deviation of the humidity | % | % | % | | `visibility` | Visibility | m | m | m | | `speed` | Wind speed | meter/sec | meter/sec | miles/hour | | `deg` | Wind direction | meteorological degrees | meteorological degrees | meteorological degrees | | `gust` | Wind gust | meter/sec | meter/sec | miles/hour | | `wind_min` | Absolute wind speed minimum based on all historical measurements | meter/sec | meter/sec | meter/sec | | `wind_max` | Absolute wind speed maximum based on all historical measurements | meter/sec | meter/sec | meter/sec | | `wind_median` | The median value of the wind speed | meter/sec | meter/sec | meter/sec | | `wind_mean` | Average of all wind speed measurements | meter/sec | meter/sec | meter/sec | | `wind_p25` | The first quartile of the wind speed | meter/sec | meter/sec | meter/sec | | `wind_p75` | The third quartile of the wind speed | meter/sec | meter/sec | meter/sec | | `wind_st_dev` | The standard deviation of the wind speed | meter/sec | meter/sec | meter/sec | | `clouds` | Cloudiness | % | % | % | | `rain` | Precipitation volume | mm | mm | mm | | `rain` | Precipitation accumulation indicator (only for Accumulated parameters) | mm | mm | mm | | `rain.1h` | Rain volume for last hour | mm | mm | mm | | `rain.1h` | Precipitation (only for One Call 3.0) | mm/h | mm/h | mm/h | | `rain.3h` | Rain volume for last 3 hours | mm | mm | mm | | `snow` | Precipitation volume | mm | mm | mm | | `snow.1h` | Snow volume for last hour | mm | mm | mm | | `snow.1h` | Precipitation (only for One Call 3.0) | mm/h | mm/h | mm/h | | `snow.3h` | Snow volume for last 3 hours | mm | mm | mm | | `pop` | Probability of precipitation | % | % | % | | `precipitation` | Precipitation (only for One Call 3.0 minutely section) | mm/hour | mm/hour | mm/hour | | `precipitation` | Precipitation volume | mm | mm | mm | | `precipitation_intensity` | Intensity of precipitation | mm/hour | mm/hour | mm/hour | | `precipitation.snow` | Snow water equivalent | mm | mm | mm | | `precipitation.rate` | Intensity of precipitation | mm/s | mm/s | mm/s | | `precipitation.fr_rain` | Freezing rain | mm | mm | mm | | `precipitation.ice` | Ice pellets | mm | mm | mm | | `convective` | Convective precipitation | mm | mm | mm | | `accumulated` | Accumulated volume of precipitation | mm | mm | mm | | `precipitation_min` | Absolute precipitation volume minimum based on all historical measurements | mm | mm | mm | | `precipitation_max` | Absolute precipitation volume maximum based on all historical measurements | mm | mm | mm | | `precipitation_median` | The median value of the precipitation volume | mm | mm | mm | | `precipitation_mean` | Average of all precipitation volume measurements | mm | mm | mm | | `precipitation_p25` | The first quartile of the precipitation volume | mm | mm | mm | | `precipitation_p75` | The third quartile of the precipitation volume | mm | mm | mm | | `precipitation_st_dev` | The standard deviation of the precipitation volume | mm | mm | mm | | `dew_point` | Temperature of dew point | Kelvin | Celsius | Fahrenheit | | `snow_deep` | Depth of snow | cm | cm | cm | | `uvi` | UVI index | W/m2 | W/m2 | W/m2 | | `radiation.ghi_cs` | Global Horizontal Irradiance | W/m2 | W/m2 | W/m2 | | `radiation.dni_cs` | Direct Normal Irradiance | W/m2 | W/m2 | W/m2 | | `radiation.dhi_cs` | Diffuse Horizontal Irradiance | W/m2 | W/m2 | W/m2 | | `components.co` | Сoncentration of CO | μg/m3 | μg/m3 | μg/m3 | | `components.no` | Сoncentration of NO | μg/m3 | μg/m3 | μg/m3 | | `components.no2` | Сoncentration of NO2 | μg/m3 | μg/m3 | μg/m3 | | `components.o3` | Сoncentration of O3 | μg/m3 | μg/m3 | μg/m3 | | `components.so2` | Сoncentration of SO2 | μg/m3 | μg/m3 | μg/m3 | | `components.pm2_5` | Сoncentration of PM2.5 | μg/m3 | μg/m3 | μg/m3 | | `components.pm10` | Сoncentration of PM10 | μg/m3 | μg/m3 | μg/m3 | | `components.nh3` | Сoncentration of NH3 | μg/m3 | μg/m3 | μg/m3 | ## Product list In this section you could find list of products where choice of units of measurement is [available](#with_units) and [not applicable.](#no_units) Products for which `standard`, `imperial` and `metric` units are available are collected below: - [One Call API 4.0](/api/one-call-4.md) - [Current weather data](current) - [Hourly forecast](api/hourly-forecast) - [Daily Forecast 16 Days](forecast16) - [Climatic forecast for 30 days](api/forecast30) - [5 day weather forecast](forecast5) - [Weather History API](/history.md) Please note, that for parameters related to precipitation, rain and snow only mm and mm/h as units of measure are available for `standard`, `imperial` and `metric` systems of measurement. Please find below the list of products for which there are no units selection: - [Road Risk API](api/road-risk) - [Solar Irradiance & Energy Prediction](api/solar-energy-prediction) - [Bulk Download](bulk) - [History API for Timestamp](api/history-api-timestamp) - [History API Full archive](api/history-api-full-archive) - [History Bulk](history-bulk) - [History Forecast Bulk](api/history-forecast-bulk) - [Statistical Weather Data API](api/statistics-api) - [Accumulated Parameters](api/accumulated-parameters) - [Historical Weather Data by State](api/history-data-state) - [Air Pollution API](api/air-pollution) --- ## Weather maps 2.0 with 1-hour step Forecast, historical and current weather maps with 1-hour step. 14 weather map [layers](#layers). You can get all of them using only one simple URL! Using this product you can get the following weather maps: - Current weather maps - Forecast weather maps for 4 days (96 measurements) - Historical weather map archive since 14 September, 2020 ## URL format and parameters Use the following URL format and parameters to get weather maps. Please pay attention to the URL example. ### API call ```text https://maps.openweathermap.org/maps/2.0/weather/1h/{op}/{z}/{x}/{y}?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `{op}` | Yes | Weather map layer. Full list of available weather map layers [here](#layers) | | `{z}` | Yes | Number of zoom level. You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `{x}` | Yes | Number of x tile coordinate. You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `{y}` | Yes | Number of y tile coordinate. You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `date` | optional | Date and time of (Unix time, UTC), e.g. date=1618898990. If you do not specify any date and time, you will get Current weather map. More information about how to get Current, Forecast and Historical maps you can find [here](#data). | | `opacity` | optional | Degree of layer opacity. Available value from 0 to 1 (default - 0.8) | | `palette` | optional | Color palette. You can use custom palettes for each layer. You can also create a palette for yourself and pass it to the URL as follows `{value}:{HEX color};..;{value}:{HEX color}`. More information about it [here](#palette). | | `fill_bound` | optional | `true` or `false`. If `true`, then all weather values outside the specified set of values will be filled by color corresponding to the nearest specified value (default value - `false`: all weather values outside the specified set of values are not filled). | | `arrow_step` | optional | Step of values for drawing wind arrows, specify in pixels (default - 32). Parameter is available only for the `WNDUV` wind layer. | | `use_norm` | optional | `true` or `false`. If `true`, then the length of the arrows is normalizing (default - `false`: the length of the arrows is proportional to the speed wind value). Parameter is available only for the `WNDUV` wind layer. | ### URL example ```text https://maps.openweathermap.org/maps/2.0/weather/1h/TA2/4/1/6?appid={API key} ``` > You need to insert the generated URL into special plugins. > > For example, Leaflet, OpenLayers. You can also use any other apps that support the display of layers. [Learn more](#library). ## How to get current, forecast and historical weather maps using only 'date' parameter? To get current, forecast or historical weather maps you just need to change only `date` parameter in the URL request: **1. Current weather maps. **If you do not put the `date` parameter to the API request, you will receive the current state by default. **2. Forecast weather maps.** You can specify any date and time within the next 4 days to get the Forecast weather maps for the specified time. If you do not specify any date and time, you will get Current weather map. **3. Historical weather maps. **If you specify any date and time since 14 September, 2020, you will receive Historical weather maps for the selected date and time. If you do not specify any date and time, you will get Current weather map. > The date and time specified in the request will be rounded to the previous 1-hour interval. ### URL example ```text https://maps.openweathermap.org/maps/2.0/weather/1h/HRD0/4/1/6?date=1618898990&appid={API key} ``` ## What layers are there in the new weather maps? To specify the selected layer in the URL, insert instead of the `{op}` parameter one of the following values: | {Op} | Meaning | Units | | --- | --- | --- | | PAC0 | Convective precipitation | mm | | PR0 | Precipitation intensity | mm/s | | PARAIN | Accumulated precipitation - rain | mm | | PASNOW | Accumulated precipitation - snow | mm | | SD0 | Depth of snow | m | | WS10UV | Wind speed at an altitude of 10 meters | m/s | | WNDUV | Joint display of speed wind (color) and wind direction (arrows), received by U and V components | m/s | | APM | Atmospheric pressure on mean sea level | hPa | | TA2 | Air temperature at a height of 2 meters | °C | | TD2 | Temperature of a dew point | °C | | TS0 | Soil temperature 0-10 сm | K | | TS10 | Soil temperature >10 сm | K | | HRD0 | Relative humidity | % | | CL | Cloudiness | % | ## How to pass my palette in the map? For each layer we have custom palettes, but you can use your own palette and pass it to the URL as shown `{value}:{HEX color};..;{value}:{HEX color}`. The number of values in the custom palette can be any, but not less than 2. You can set the color for any value with any precision. To pass the code of color, use the HEX format. ### URL Example ```text https://maps.openweathermap.org/maps/2.0/weather/1h/TA2/{z}/{x}/{y}?date=1618898990&opacity=0.9&fill_bound=true&palette=0:FF0000;10:00FF00;20:0000FF&appid={API key} ``` ## Examples of Weather maps ### Air temperature at a height of 2 meters weather layer Default parameters `op` : **TA2** `fill_bound` : **false** ### URL example ```text https://maps.openweathermap.org/maps/2.0/weather/1h/TA2/{z}/{x}/{y}?appid={API key} ``` ### Air temperature at a height of 2 meters weather layer Custom palette `op` : **TA2** `opacity` : **0.6** `fill_bound` : **true** `palette` : custom (see example) ![Palette current weathermaps2](/payload/api/media/file/Palette_current_weathermaps2.jpg) ### URL example ```text https://maps.openweathermap.org/maps/2.0/weather/1h/TA2/{z}/{x}/{y}?appid={API key}&fill_bound=true&opacity=0.6&palette=-65:821692;-55:821692;-45:821692;-40:821692;-30:8257db;-20:208cec;-10:20c4e8;0:23dddd;10:c2ff28;20:fff028;25:ffc228;30:fc8014 ``` ### Accumulated precipitation weather layer Default parameters `op` : **PARAIN** ![PA0 current weathermaps2](/payload/api/media/file/PA0_current_weathermaps2.jpg) ### URL example ```text https://maps.openweathermap.org/maps/2.0/weather/1h/PARAIN/{z}/{x}/{y}?date=1618898990&appid={API key} ``` ### Atmospheric pressure on mean sea level weather layer Default parameters `op` : **APM** ![APM_current_weathermaps2](/payload/api/media/file/APM_current_weathermaps2.jpg) ### URL example ```text https://maps.openweathermap.org/maps/2.0/weather/1h/APM/{z}/{x}/{y}?date=1618898990&appid={API key} ``` ### Joint display of speed wind (color) and wind direction (arrows) weather layer Default parameters `op` : **WNDUV** `use_norm` : **false** `arrow_step` : **32** ![WND current weathermaps2](/payload/api/media/file/WND_current_weathermaps2.jpg) ### URL example ```text https://maps.openweathermap.org/maps/2.0/weather/1h/WNDUV/{z}/{x}/{y}?date=16188989909&appid={API key} ``` ### Joint display of speed wind (color) and wind direction (arrows) weather layer Custom parameters `op` : **WNDUV** `use_norm` : **true** `arrow_step` : **16** ![WND2 current weathermaps2](/payload/api/media/file/WND2_current_weathermaps2.jpg) ### URL example ```text https://maps.openweathermap.org/maps/2.0/weather/1h/WNDUV/{z}/{x}/{y}?date=1618898990&use_norm=true&arrow_step=16&appid={API key} ``` ## Default palettes | Weather layer | Palette | Opacity | Fill bound | Use norm | Arrow step | | --- | --- | --- | --- | --- | --- | | `PAC0` Convective precipitation | 1:ACAAF7; 10:8D8AF3; 20:706EC2; 40:5658FF; 100:5B5DB1; 200:3E3F85 | 0.8 | 0 | - | - | | `PR0` Precipitation intensity | 0.000005:FEF9CA; 0.000009:B9F7A8; 0.000014:93F57D; 0.000023:78F554; 0.000046:50B033; 0.000092:387F22; 0.000231:204E11; 0.000463:F2A33A; 0.000694:E96F2D; 0.000926:EB4726; 0.001388:B02318; 0.002315:971D13; 0.023150:090A08 | 0.8 | 0 | - | - | | `PARAIN` Accumulated precipitation - rain | 0:E1C86400; 0.1:C8963200; 0.2:9696AA00; 0.5:7878BE00; 1:6E6ECD4C; 10:5050E1B2; 140:1414FFE5 | 0.6 | 0 | - | - | | `PASNOW` Accumulated precipitation - snow | 0:00000000; 5:00D8FFFF; 10:00B6FFFF; 25.076:9549FF | 0.7 | 0 | - | - | | `SD0` Depth of snow | 0.05:EDEDED; 0.1:D9F0F4; 0.2:A5E5EF; 0.3:7DDEED; 0.4:35D2EA; 0.5:00CCE8; 0.6:706DCE; 0.7:514FCC; 0.8:3333CC; 0.9:1818CC; 1.2:C454B7; 1.5:C12CB0; 1.8:BF00A8; 2.5:85408C; 3.0:7F2389; 4.0:790087; 15:E80068 | 0.8 | 0 | - | - | | `WS10UV` Wind speed at an altitude of 10 meters | 1:FFFFFF00; 5:EECECC66; 15:B364BCB3; 25:3F213BCC; 50:744CACE6; 100:4600AFFF; 200:0D1126FF | 0.6 | 0 | - | - | | `WNDUV` Joint display of speed wind (color) and wind direction (arrows) | 1:FFFFFF00; 5:EECECC66; 15:B364BCB3; 25:3F213BCC; 50:744CACE6; 100:4600AFFF; 200:0D1126FF | 0.6 | 0 | 0 | 32 | | `APM` Atmospheric pressure on mean sea level | 94000:0073FF; 96000:00AAFF; 98000:4BD0D6; 100000:8DE7C7; 101000:B0F720; 102000:F0B800; 104000:FB5515; 106000:F3363B; 108000:C60000 | 0.4 | 1 | - | - | | `TA2` Air temperature at a height of 2 meters | -65:821692; -55:821692; -45:821692; -40:821692; -30:8257DB; -20:208CEC; -10:20C4E8; 0:23DDDD; 10:C2FF28; 20:FFF028; 25:FFC228; 30:FC8014 | 0.3 | 1 | - | - | | `TD2` Temperature of a dew point | -65:821692; -55:821692; -45:821692; -40:821692; -30:8257DB; -20:208CEC; -10:20C4E8; 0:23DDDD; 10:C2FF28; 20:FFF028; 25:FFC228; 30:FC8014 | 0.3 | 1 | - | - | | `TS0` Soil temperature 0-10 сm | 203.15:491763; 228.15:4E1378; 235.15:514F9B; 239.15:446DA9; 243.15:5C85B7; 247.15:739FC5; 251.15:88A7C9; -255.15:6CBCD4; 259.15:87CADC; 263.15:A7D8E5; 267.15:A7D5AD; 271.15:D2E9C8; 275.15:FEFEBB; 279.15:F5CEBB; 283.15:F2B68A; 287.15:EE934F; 291.15:EB702D; 295.15:E8706E; 303.15:CC2C44; 313.15:CC0000; 323.15:990000 | 0.8 | 1 | - | - | | `TS10` Soil temperature >10 сm | 203.15:491763; 228.15:4E1378; 235.15:514F9B; 239.15:446DA9; 243.15:5C85B7; 247.15:739FC5; 251.15:88A7C9; -255.15:6CBCD4; 259.15:87CADC; 263.15:A7D8E5; 267.15:A7D5AD; 271.15:D2E9C8; 275.15:FEFEBB; 279.15:F5CEBB; 283.15:F2B68A; 287.15:EE934F; 291.15:EB702D; 295.15:E8706E; 303.15:CC2C44; 313.15:CC0000; 323.15:990000 | 0.8 | 0 | - | - | | `HRD0` Relative humidity | 0:db1200; 20:965700; 40:ede100; 60:8bd600; 80:00a808; 100:000099; 100.1:000099 | 0.8 | 1 | - | - | | `CL` Cloudiness | 0:FFFFFF00; 10:FDFDFF19; 20:FCFBFF26; 30:FAFAFF33; 40:F9F8FF4C; 50:F7F7FF66; 60:F6F5FF8C; 70:F4F4FFBF; 80:E9E9DFCC; 90:DEDEDED8; 100:D2D2D2FF; 200:D2D2D2FF | 0.5 | 0 | - | - | ## Libraries to connect weather layers **Open Layers** The following functions are available for the OpenLayers library: - Classes of weather layer and weather stations layer - Possibility to set your own style - Classes with clustered markers - Support of marker server clustering **Leaflet** The OpenWeatherMap javascript library is designed to work with the Leaflet mapping service. The current version of the library allows the following: - Embedding of layer with current weather in cities - Embedding of layer with weather stations - The library supports customer clustering **Leaflet library** Another implementation of map based on Leaflet technology supports OWM's TileLayers and current city/station data. It is configurable with many options. For current city/station data the library supports refreshing the data in intervals, some types of client-side clustering (show only the station/city with the highest rank for a defined pixel square), custom image set (if you provide one), different languages (`en`, `de`, `ru`, `fr`, but translation is incomplete), `minZoom` and others. Source and documentation (README.md) is available on GitHub [https://github.com/buche/leaflet-openweathermap](https://github.com/buche/leaflet-openweathermap) Example of weather map: [https://github.com/owm-inc/VANE-intro/tree/master/apps](https://github.com/owm-inc/VANE-intro/tree/master/apps) Using OpenWeatherMap weather tiles with leaflet: [PDF](https://files/Using_OpenWeatherMap_Weather_Tiles_with_Leaflet.pdf) --- ## Weather maps 2.0 Forecast, Historical and Current weather maps. 15 weather map [layers](#layers).You can get all of them using only one simple URL! Using one simple URL you can get the following weather maps: - **Current weather maps** - **Forecast weather maps**: The forecast for 10 days with a 3 hours-step - **Historical weather map**: Archive since March, 2019 ## URL format and parameters Use the following URL format and parameters to get weather maps. Please pay attention to the URL example. ### API call ```text http://maps.openweathermap.org/maps/2.0/weather/{op}/{z}/{x}/{y}?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `{op}` | Yes | Weather map layer. Full list of available weather map layers [here](#layers) | | `{z}` | Yes | Number of zoom level. You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `{x}` | Yes | Number of x tile coordinate. You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `{y}` | Yes | Number of y tile coordinate. You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | | `date` | optional | Date and time of (Unix time, UTC), e.g. date=1552861800. If you do not specify any date and time, you will get Current weather map. More information about how to get Current, Forecast and Historical maps you can find [here](#data). | | `opacity` | optional | Degree of layer opacity. Available value from 0 to 1 (default - 0.8) | | `palette` | optional | Color palette. You can use custom palettes for each layer. You can also create a palette for yourself and pass it to the URL as follows `{value}:{HEX color};..;{value}:{HEX color}`. More information about it [here](#palette). | | `fill_bound` | optional | `true` or `false`. If `true`, then all weather values outside the specified set of values will be filled by color corresponding to the nearest specified value (default value - `false`: all weather values outside the specified set of values are not filled). | | `arrow_step` | optional | Step of values for drawing wind arrows, specify in pixels (default - 32). Parameter only for wind layers (WND). | | `use_norm` | optional | `true` or `false`. If `true`, then the length of the arrows is normalizing (default - `false`: the length of the arrows is proportional to the speed wind value). Parameter only for wind layers (WND). | ### URL example ```text http://maps.openweathermap.org/maps/2.0/weather/TA2/{z}/{x}/{y}?date=1552861800&opacity=0.9&fill_bound=true&appid={API key} ``` > You need to insert the generated URL into special plugins. > > For example, Leaflet, OpenLayers. You can also use any other apps that support the display of layers. [Learn more](#library). ## How to get current, forecast and historical weather maps using only 'date' parameter? To get current, forecast or historical weather maps you just need to change only `date` parameter in the URL request: **1. Current weather maps. **Specify the current date and time to get Current weather map. The date and time specified in the request will be rounded to the previous 3-hour interval. **2. Forecast weather maps.** You can specify any date and time within the next 10 days to get the Forecast weather maps for the specified time. If you do not specify any date and time, you will get Current weather map. Not available for [TS0](#layers) and [TS10](#layers) layers. **3. Historical weather maps. **If you specify any date and time since 18 March 2019, you will receive Historical weather maps for the selected date and time. If you do not specify any date and time, you will get Current weather map. > Please note that the date and time specified in the request will be rounded to the previous 3-hour interval (except [TS0](#layers) and [TS10](#layers) layers). > > Date and time specified in the request will be rounded to the previous 12-hour interval for [TS0](#layers) and [TS10](#layers) layers. ## What layers are there in the new weather maps? To specify the selected layer in the URL, insert instead of the `{op}` parameter one of the following values: | {Op} | Meaning | Units | | --- | --- | --- | | PAC0 | Convective precipitation | mm | | PR0 | Precipitation intensity | mm/s | | PA0 | Accumulated precipitation | mm | | PAR0 | Accumulated precipitation - rain | mm | | PAS0 | Accumulated precipitation - snow | mm | | SD0 | Depth of snow | m | | WS10 | Wind speed at an altitude of 10 meters | m/s | | WND | Joint display of speed wind (color) and wind direction (arrows), received by U and V components | m/s | | APM | Atmospheric pressure on mean sea level | hPa | | TA2 | Air temperature at a height of 2 meters | °C | | TD2 | Temperature of a dew point | °C | | TS0 | Soil temperature 0-10 сm | K | | TS10 | Soil temperature >10 сm | K | | HRD0 | Relative humidity | % | | CL | Cloudiness | % | ## How to pass my palette in the map? For each layer we have custom palettes, but you can use your own palette and pass it to the URL as shown `{value}:{HEX color};..;{value}:{HEX color}`. The number of values in the custom palette can be any, but not less than 2. You can set the color for any value with any precision. To pass the code of color, use the HEX format. ### URL Example ```text http://maps.openweathermap.org/maps/2.0/weather/TA2/{z}/{x}/{y}?date=1552861800&opacity=0.9&fill_bound=true&palette=0:FF0000;10:00FF00;20:0000FF&appid={API key} ``` ## Examples of Weather maps ### Air temperature at a height of 2 meters weather layer Default parameters `op` : **TA2** `fill_bound` : **false** ### URL example ```text http://maps.openweathermap.org/maps/2.0/weather/TA2/{z}/{x}/{y}?appid={API key} ``` ### Air temperature at a height of 2 meters weather layer Custom palette `op` : **TA2** `opacity` : **0.6** `fill_bound` : **true** `palette` : custom (see example) ![Palette current weathermaps2](/payload/api/media/file/Palette_current_weathermaps2.jpg) ### URL example ```text http://maps.openweathermap.org/maps/2.0/weather/TA2/{z}/{x}/{y}?appid={API key}&fill_bound=true&opacity=0.6&palette=-65:821692;-55:821692;-45:821692;-40:821692;-30:8257db;-20:208cec;-10:20c4e8;0:23dddd;10:c2ff28;20:fff028;25:ffc228;30:fc8014 ``` ### Accumulated precipitation weather layer Default parameters `op` : **PA0** ![PA0 current weathermaps2](/payload/api/media/file/PA0_current_weathermaps2.jpg) ### URL example ```text http://maps.openweathermap.org/maps/2.0/weather/PA0/{z}/{x}/{y}?date=1552861800&appid={API key} ``` ### Atmospheric pressure on mean sea level weather layer Default parameters `op` : **APM** ![APM_current_weathermaps2](/payload/api/media/file/APM_current_weathermaps2.jpg) ### URL example ```text http://maps.openweathermap.org/maps/2.0/weather/PA0/{z}/{x}/{y}?date=1552861800&appid={API key} ``` ### Joint display of speed wind (color) and wind direction (arrows) weather layer Default parameters `op` : **WND** `use_norm` : **false** `arrow_step` : **32** ![WND current weathermaps2](/payload/api/media/file/WND_current_weathermaps2.jpg) ### URL example ```text http://maps.openweathermap.org/maps/2.0/weather/WND/{z}/{x}/{y}?date=1552861800&appid={API key} ``` ### Joint display of speed wind (color) and wind direction (arrows) weather layer Custom parameters `op` : **WND** `use_norm` : **true** `arrow_step` : **16** ![WND2 current weathermaps2](/payload/api/media/file/WND2_current_weathermaps2.jpg) ### URL example ```text http://maps.openweathermap.org/maps/2.0/weather/WND/{z}/{x}/{y}?date=1552861800&use_norm=true&arrow_step=16&appid={API key} ``` ## Default palettes | Weather layer | Palette | Opacity | Fill bound | Use norm | Arrow step | | --- | --- | --- | --- | --- | --- | | `PAC0` Convective precipitation | 1:ACAAF7; 10:8D8AF3; 20:706EC2; 40:5658FF; 100:5B5DB1; 200:3E3F85 | 0.8 | 0 | - | - | | `PR0` Precipitation intensity | 0.000005:FEF9CA; 0.000009:B9F7A8; 0.000014:93F57D; 0.000023:78F554; 0.000046:50B033; 0.000092:387F22; 0.000231:204E11; 0.000463:F2A33A; 0.000694:E96F2D; 0.000926:EB4726; 0.001388:B02318; 0.002315:971D13; 0.023150:090A08 | 0.8 | 0 | - | - | | `PA0` Accumulated precipitation | 0:00000000; 0.1:C8969600; 0.2:9696AA00; 0.5:7878BE19; 1:6E6ECD33; 10:5050E1B2; 140:1414FFE5 | 0.6 | 0 | - | - | | `PAR0` Accumulated precipitation - rain | 0:E1C86400; 0.1:C8963200; 0.2:9696AA00; 0.5:7878BE00; 1:6E6ECD4C; 10:5050E1B2; 140:1414FFE5 | 0.6 | 0 | - | - | | `PAS0` Accumulated precipitation - snow | 0:00000000; 5:00D8FFFF; 10:00B6FFFF; 25.076:9549FF | 0.7 | 0 | - | - | | `SD0` Depth of snow | 0.05:EDEDED; 0.1:D9F0F4; 0.2:A5E5EF; 0.3:7DDEED; 0.4:35D2EA; 0.5:00CCE8; 0.6:706DCE; 0.7:514FCC; 0.8:3333CC; 0.9:1818CC; 1.2:C454B7; 1.5:C12CB0; 1.8:BF00A8; 2.5:85408C; 3.0:7F2389; 4.0:790087; 15:E80068 | 0.8 | 0 | - | - | | `WS10` Wind speed at an altitude of 10 meters | 1:FFFFFF00; 5:EECECC66; 15:B364BCB3; 25:3F213BCC; 50:744CACE6; 100:4600AFFF; 200:0D1126FF | 0.6 | 0 | - | - | | `WND` Joint display of speed wind (color) and wind direction (arrows) | 1:FFFFFF00; 5:EECECC66; 15:B364BCB3; 25:3F213BCC; 50:744CACE6; 100:4600AFFF; 200:0D1126FF | 0.6 | 0 | 0 | 32 | | `APM` Atmospheric pressure on mean sea level | 94000:0073FF; 96000:00AAFF; 98000:4BD0D6; 100000:8DE7C7; 101000:B0F720; 102000:F0B800; 104000:FB5515; 106000:F3363B; 108000:C60000 | 0.4 | 1 | - | - | | `TA2` Air temperature at a height of 2 meters | -65:821692; -55:821692; -45:821692; -40:821692; -30:8257DB; -20:208CEC; -10:20C4E8; 0:23DDDD; 10:C2FF28; 20:FFF028; 25:FFC228; 30:FC8014 | 0.3 | 1 | - | - | | `TD2` Temperature of a dew point | -65:821692; -55:821692; -45:821692; -40:821692; -30:8257DB; -20:208CEC; -10:20C4E8; 0:23DDDD; 10:C2FF28; 20:FFF028; 25:FFC228; 30:FC8014 | 0.3 | 1 | - | - | | `TS0` Soil temperature 0-10 сm | 203.15:491763; 228.15:4E1378; 235.15:514F9B; 239.15:446DA9; 243.15:5C85B7; 247.15:739FC5; 251.15:88A7C9; -255.15:6CBCD4; 259.15:87CADC; 263.15:A7D8E5; 267.15:A7D5AD; 271.15:D2E9C8; 275.15:FEFEBB; 279.15:F5CEBB; 283.15:F2B68A; 287.15:EE934F; 291.15:EB702D; 295.15:E8706E; 303.15:CC2C44; 313.15:CC0000; 323.15:990000 | 0.8 | 1 | - | - | | `TS10` Soil temperature >10 сm | 203.15:491763; 228.15:4E1378; 235.15:514F9B; 239.15:446DA9; 243.15:5C85B7; 247.15:739FC5; 251.15:88A7C9; -255.15:6CBCD4; 259.15:87CADC; 263.15:A7D8E5; 267.15:A7D5AD; 271.15:D2E9C8; 275.15:FEFEBB; 279.15:F5CEBB; 283.15:F2B68A; 287.15:EE934F; 291.15:EB702D; 295.15:E8706E; 303.15:CC2C44; 313.15:CC0000; 323.15:990000 | 0.8 | 0 | - | - | | `HRD0` Relative humidity | 0:db1200; 20:965700; 40:ede100; 60:8bd600; 80:00a808; 100:000099; 100.1:000099 | 0.8 | 1 | - | - | | `CL` Cloudiness | 0:FFFFFF00; 10:FDFDFF19; 20:FCFBFF26; 30:FAFAFF33; 40:F9F8FF4C; 50:F7F7FF66; 60:F6F5FF8C; 70:F4F4FFBF; 80:E9E9DFCC; 90:DEDEDED8; 100:D2D2D2FF; 200:D2D2D2FF | 0.5 | 0 | - | - | ## Libraries to connect weather layers **Open Layers** The following functions are available for the OpenLayers library: - Classes of weather layer and weather stations layer - Possibility to set your own style - Classes with clustered markers - Support of marker server clustering **Leaflet** The OpenWeatherMap javascript library is designed to work with the Leaflet mapping service. The current version of the library allows the following: - Embedding of layer with current weather in cities - Embedding of layer with weather stations - The library supports customer clustering **Leaflet library** Another implementation of map based on Leaflet technology supports OWM's TileLayers and current city/station data. It is configurable with many options. For current city/station data the library supports refreshing the data in intervals, some types of client-side clustering (show only the station/city with the highest rank for a defined pixel square), custom image set (if you provide one), different languages (`en`, `de`, `ru`, `fr`, but translation is incomplete), `minZoom` and others. Source and documentation (README.md) is available on GitHub [https://github.com/buche/leaflet-openweathermap](https://github.com/buche/leaflet-openweathermap) Example of weather map: [https://github.com/owm-inc/VANE-intro/tree/master/apps](https://github.com/owm-inc/VANE-intro/tree/master/apps) Using OpenWeatherMap weather tiles with leaflet: [PDF](https://) --- ## Weather maps 1.0 OpenWeatherMap provides many kinds of weather maps including Precipitation, Clouds, Pressure, Temperature, Wind. You can connect them to mobile and web apps. > We have launched [Weather maps 2.0](/api/weather-map-1h.md)! > > Now available Forecast, Historical and Current weather maps. 14 weather map layers with 1-hour step. You can get all of them using only one simple URL! > > [Learn more](/api/weather-map-1h.md) ## URL format The following endpoint is available for everyone. It requires only the [API key](https://home.openweathermap.org/api_keys) authentication. ### API call ```text https://tile.openweathermap.org/map/{layer}/{z}/{x}/{y}.png?appid={API key} ``` | Parameters | | | | --- | --- | --- | | `{layer}` | Yes | layer name | | `{z}` | Yes | number of zoom level. You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `{x}` | Yes | number of x tile coordinate. You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `{y}` | Yes | number of y tile coordinate. You could find information about correlation between zoom levels, X, Y tile coordinate numbers and level scale [here](/faq.md#zoom_levels) | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ## Examples of weather map layers ### Clouds `layer` : **clouds_new** `area` : **worldwide** ![clouds new](/payload/api/media/file/clouds_new.jpg) - [Preview weathermap](/weathermap.md?basemap=map&cities=false&layer=clouds&lat=30&lon=-20&zoom=3) ### Precipitation `layer` : **precipitation_new** `area` : **worldwide** ![precipitation new](/payload/api/media/file/precipitation_new.jpg) ### Sea level pressure `layer` : **pressure_new** `area` : **worldwide** ![pressure new](/payload/api/media/file/pressure_new.jpg) - [Preview weathermap](http://openweathermap.org/weathermap?basemap=map&cities=false&layer=pressure&lat=30&lon=-20&zoom=3) ### Wind speed `layer` : **wind_new** `area` : **worldwide** ![wind new](/payload/api/media/file/wind_new.jpg) - [Preview weathermap](http://openweathermap.org/weathermap?basemap=map&cities=false&layer=windspeed&lat=30&lon=-20&zoom=3) ### Temperature `layer` : **temp_new** `area` : **worldwide** ![temperature new](/payload/api/media/file/temperature_new.jpg) - [Preview weathermap](http://openweathermap.org/weathermap?basemap=map&cities=false&layer=temperature&lat=30&lon=-20&zoom=3) ## Map styles legend [Default styles for weather layers](/map_legend.md) ## Google Maps JavaScript API based on OpenWeatherMap API Google has closed their Weather and Cloud solutions since 4th of June 2015 and recommended to use OpenWeatherMap with the Google Maps JavaScript API as an alternative solution. 'Displaying weather data with the Google Maps API and OpenWeatherMap' [manual](https://github.com/google/maps-for-work-samples/blob/master/samples/maps/OpenWeatherMapLayer/OpenWeatherMapLayer.pdf). ## Libraries to connect weather layers **Open Layers** The following functions are available for the OpenLayers library: - Classes of weather layer and weather stations layer - Possibility to set your own style - Classes with clustered markers - Support of marker server clustering **Leaflet** The OpenWeatherMap javascript library is designed to work with the Leaflet mapping service. The current version of the library allows the following: - Embedding of layer with current weather in cities - Embedding of layer with weather stations - The library supports customer clustering Another implementation of map based on Leaflet technology supports OWM's TileLayers and current city/station data. It is configurable with many options. For current city/station data the library supports refreshing the data in intervals, some types of client-side clustering (show only the station/city with the highest rank for a defined pixel square), custom image set (if you provide one), different languages ("en", "de", "ru", "fr", but translation is incomplete), minZoom and others. Source and documentation (README.md) is available on GitHub [https://github.com/buche/leaflet-openweathermap](https://github.com/buche/leaflet-openweathermap) Example of weather map: [https://github.com/owm-inc/VANE-intro/tree/master/apps](https://github.com/owm-inc/VANE-intro/tree/master/apps) Using OpenWeatherMap weather tiles with leaflet: [PDF](https://files/Using_OpenWeatherMap_Weather_Tiles_with_Leaflet.pdf) --- ## Wind Energy Prediction API ### Product Overview **Wind Energy Prediction API** provides a forecast of expected electricity generation for wind turbines at a specified location. The API combines high-resolution wind forecasts with turbine performance parameters to estimate the expected power output. The forecast is provided with a **15-minute time step** and covers **up to 16 days ahead**, enabling accurate planning for renewable energy operations, grid management, and energy trading. The API allows users to configure turbine characteristics and operational parameters to better reflect the real-world performance of specific wind turbines. ### API request ### Endpoint ### GET ```text /wind-heights/1.0/forecast/power_generation ``` ### Example of the API request ```text https://demo.openweathermap.org/wind- heights/1.0/forecast/power_generation?lat=40.7128&lon=-74.006&altitude_meters=10&turbine_power_w=80000&cut_in_speed=1&appid=YOUR_API_KEY ``` ## API request parameters ### Required parameters | Parameter | Type | **Description** | | --- | --- | --- | | lat | float | Latitude of the location | | lon | float | Longitude of the location | | altitude_meters | integer | Height of the wind turbine hub above ground level in meters | | turbine_power_w | integer | Rated power of the wind turbine in watts | ### Optional turbine configuration parameters These parameters allow tuning the turbine power curve and operational characteristics. If not provided, the API uses default values. | **Parameter** | Type | Default **value ** | **Description** | | --- | --- | --- | --- | | cut_in_speed | float | 3.0 | Wind speed (m/s) at which the turbine starts generating power | | rated_speed | float | 12.0 | Wind speed (m/s) at which the turbine reaches rated power output | | cut_out_speed | float | 25.0 | Wind speed (m/s) at which the turbine shuts down to prevent damage | | reference_density | float | 1.225 | Reference air density (kg/m³) used for power calculations | | gas_constant_dry_air | float | 287.05 | Gas constant for dry air used in density calculations | | availability_factor | float | 0.95 | Fraction of time the turbine is available for operation (accounts for maintenance and downtime) | | electrical_losses | float | 0.97 | Efficiency factor accounting for electrical system losses | | wake_losses | float | 0.90 | Efficiency factor accounting for wake effects and aerodynamic losses in wind farms | ### API response example ```json { "latitude": 40.7128, "longitude": -74.006, "altitude_meters": 10, "elevation_meters": 5, "target_pressure_hpa": 1011, "turbine_power_w": 80000, "step_minutes": 15, "timestamp": "2026-03-16T11:10:41.896670", "forecast_data": [ { "forecast_timestamp": "2026-03-16T00:00:00", "temperature_1011hPa": { "value": 6.13, "units": "Celsius", "height": 1011 }, "wind_1011hPa": { "speed": 6.8, "direction": 112.4, "units": { "speed": "m/s", "direction": "degrees" }, "height": 1011 }, "generated_power_w": 12397.56 }, { "forecast_timestamp": "2026-03-16T00:15:00", "temperature_1011hPa": { "value": 6.23, "units": "Celsius", "height": 1011 }, "wind_1011hPa": { "speed": 6.81, "direction": 113.7, "units": { "speed": "m/s", "direction": "degrees" }, "height": 1011 }, "generated_power_w": 12448.03 }, { "forecast_timestamp": "2026-03-16T00:30:00", "temperature_1011hPa": { "value": 6.33, "units": "Celsius", "height": 1011 }, "wind_1011hPa": { "speed": 6.83, "direction": 115.1, "units": { "speed": "m/s", "direction": "degrees" }, "height": 1011 }, "generated_power_w": 12553.86 }, … ], "algorithm_parameters": { "cut_in_speed": 1, "rated_speed": 12, "cut_out_speed": 25, "reference_density": 1.225, "gas_constant_dry_air": 287.05, "availability_factor": 0.95, "electrical_losses": 0.97, "wake_losses": 0.9, "use_density_correction": true } } ``` ### API response fields - latitude - Latitude of the location, decimal (−90; 90) - longitude - Longitude of the location, decimal (-180; 180) - altitude_meters - Requested turbine hub height above ground level in meters. - elevation_meters - Ground elevation at the requested location in meters above sea level. - target_pressure_hpa - Atmospheric pressure level used to derive wind and temperature values corresponding to the turbine hub height. - turbine_power_w - Rated power of the wind turbine in watts used in the generation calculations. - step_minutes - Temporal resolution of the forecast data in minutes. - timestamp - Time when the forecast was generated. - forecast_data - - forecast_data.forecast_timestamp - Timestamp of the forecasted data point. - forecast_data.temperature_1011hPa - Air temperature at the pressure level corresponding to the turbine hub height. - - forecast_data.temperature_1011hPa.value - Forecast temperature value. - forecast_data.temperature_1011hPa.units - Units of temperature measurement (Celsius). - forecast_data.temperature_1011hPa.height - Pressure level (hPa) used to derive temperature data. - forecast_data.wind_1011hPa - Wind conditions at the pressure level corresponding to the turbine hub height. - - forecast_data.wind_1011hPa.speed - Wind speed. - forecast_data.wind_1011hPa.direction - Wind direction in degrees (meteorological convention). - forecast_data.wind_1011hPa.units.speed - Units of wind speed (m/s). - forecast_data.wind_1011hPa.units.direction - Units of wind direction (degrees). - forecast_data.wind_1011hPa.height - Pressure level (hPa) used to derive wind data. - forecast_data.generated_power_w - Estimated electrical power generation of the wind turbine in watts for the given time step. - algorithm_parameters - - algorithm_parameters.cut_in_speed - Wind speed (m/s) at which the turbine starts generating electricity. - algorithm_parameters.rated_speed - Wind speed (m/s) at which the turbine reaches its rated power output. - algorithm_parameters.cut_out_speed - Wind speed (m/s) at which the turbine automatically shuts down for safety. - algorithm_parameters.reference_density - Reference air density (kg/m³) used for turbine power calculations. - algorithm_parameters.gas_constant_dry_air - Gas constant used for dry air density calculations. - algorithm_parameters.availability_factor - Operational availability factor accounting for maintenance downtime. - algorithm_parameters.electrical_losses - Efficiency factor accounting for electrical losses. - algorithm_parameters.wake_losses - Efficiency factor accounting for aerodynamic wake effects in wind farms. - algorithm_parameters.use_density_correction - Indicates whether air density correction was applied in the power generation calculations. --- ## Wind API This spec covers REST endpoint: ### GET ```text /wind-heights/1.0/forecast ``` The **Wind API** provides wind speed and direction forecasts at specific altitudes above ground level. The API calculates atmospheric pressure levels corresponding to the requested altitude and returns detailed wind and temperature forecasts at 15-minute intervals. ### Overview - **Spatial coverage:** Global. - **Temporal resolution:** 15 minutes. - **Forecast horizon:** Up to 384 hours (16 days). - **Level type:** up to 1,000 meters above ground. ### Authentication - **appid** — Your OpenWeather API key (required) to be sent as a query parameter. ### Endpoints **Get Current Pollen** **HTTP** ### GET ```text http://demo.openweathermap.org/wind-heights/1.0/forecast? ``` ### Example ```text http://demo.openweathermap.org/wind-heights/1.0/forecast?lat=40.7128&lon=-74.006&altitude_meters=100&max_hours=2&appid=CLIENT_API_KEY ``` ### Query parameters | Name | Type | **Required** | **Description** | | --- | --- | --- | --- | | lat | number | ✓ | Latitude in decimal degrees (-90...90) | | lon | number | ✓ | Longitude in decimal degrees (-180...180) | | altitude_meters | number | ✓ | Target altitude above ground level in meters (0 to 1,000) | | appid | string | ✓ | Open Weather API key | | max_hours | number | - | Maximum number of hours for forecast data | ### Response (200) — JSON ```json { "latitude": 40.7128, "longitude": -74.006, "altitude_meters": 100, "elevation_meters": 5, "target_pressure_hpa": 1001, "timestamp": "2025-08-28T11:04:21.528243", "step_minutes": 15, "forecast_data": [ { "forecast_timestamp": "2025-08-28T00:00:00", "wind_1001hPa": { "speed": 6.6, "direction": 324.6, "units": { "speed": "m/s", "direction": "degrees" }, "height": 1001 }, "temperature_1001hPa": { "value": 20.34, "units": "Celsius", "height": 1001 } }, { "forecast_timestamp": "2025-08-28T00:15:00", "wind_1001hPa": { "speed": 6.33, "direction": 324.9, "units": { "speed": "m/s", "direction": "degrees" }, "height": 1001 }, "temperature_1001hPa": { "value": 20.25, "units": "Celsius", "height": 1001 } }, // …hourly steps up to requested/available horizon } ``` ### Field descriptions - latitude, longitude (number): Echo of the request coordinates. - altitude_meters (number): Echo of the request altitude meters. - elevation_meters (number): Ground elevation above sea level for the location - target_pressure_hpa (number): Atmospheric pressure level corresponding to requested altitude - timestamp (string): ISO-8601 timestamp, timestamp when the forecast was generated - step_minutes (number): Time interval between forecast data points - forecast_data (object of number): - - forecast_timestamp (string): ISO-8601 timestamp, timestamp for the specific forecast data point - wind_[]hPa - - speed (float): Wind speed at the specified pressure level - direction (float): Wind direction in meteorological convention - units (object of number): - - speed (string): Unit of measurement for wind speed - direction (string): Unit of measurement for wind direction - height (number): Pressure level height identifier - temperature_[]hPa - - value (float): Temperature at the specified pressure level - units (string): Unit of measurement for temperature - height (number): Pressure level height identifier ### Error handling | **HTTP** | **Meaning** | **Payload example** | | --- | --- | --- | | 400 | Validation error (e.g., missing/invalid required parameter lat, lon, altitude_meters) | {"error":"Missing lat/lon parameters in query"} | | 401 | Unauthorized (bad appid) | {"cod":401,"message":"Invalid API key"} | | 429 | Rate limited | {"cod":429,"message":"Too many requests"} | | 500 | Internal server error | {"cod":500,"message":"Internal error"} | --- ## How to start using professional collections ### Best way to start and continue calling OpenWeather APIs OpenWeather offers a set of widely recognised and reliable APIs. Powered by advanced machine learning, our platform provides weather information essential for decision-making at any location worldwide. To start using our APIs, please sign up [here](https://home.openweathermap.org/users/sign_up). ## How to call OpenWeather APIs with a freemium plan The API key is all you need to call any of our weather APIs. Once you [sign up](/home/sign_up.md) using your email, the API key (APPID) will be sent to you in a confirmation email. Your API keys can always be found on your [account page](https://home.openweathermap.org/api_keys), where you can also generate additional API keys if needed. API call limits are applied at the account level, not per API key or per product. Usage from all API keys and subscribed products is combined and counted toward the same account limits. Check our [documentation page](/api.md) to find all technical information for each product. Documentation is an essential guide with actual examples and comprehensive description of API calls, responses and parameters. ## How to call OpenWeather APIs with a paid plan In case your weather data requirements go beyond our Free plan, you may consider signing up for our [paid subscription plans](/price.md). The subscription plans differ in the APIs products range, level of service provided, the overall amount of calls per minute and other features. ## API key is everything you need to call for weather data Please, use your API key in every API call you make. Our platform only processes the API requests with an API key included. API usage is accumulated across all API keys associated with your account and across all subscribed products. ## Example on how to make an API call using your API key ### API call ```text http://api.openweathermap.org/data/2.5/forecast?id=524901&appid={API key} ``` | Parameters | | | | --- | --- | --- | | `appid` | Yes | Your unique API key (you can always find it on your account page under the ["API key" tab](https://home.openweathermap.org/api_keys)) | ### Example of API call ```text api.openweathermap.org/data/2.5/forecast?id=524901&appid={API key} ``` ## API care recommendations Like any other tool, the API requires some attention. To let it serve you properly, we suggest that you carefully read these instructions and care recommendations. First, we recommend making API calls no more than once in 10 minutes for each location, whether you call it by city name, geographical coordinates or by zip code. The update frequency of the OpenWeather model is not higher than once in 10 minutes. Second, the only endpoint for making **free** API calls is **api.openweathermap.org**. Please, don’t use the server’s IP address. The endpoint for paid subscription plans is different and it can be found in the confirmation email we send you once your subscription is activated Third, to get a precise geocoding searching result would rather call API by geographical coordinates. You can always call the OpenWeather APIs using the city name or zip/post code. In case you need to get geographical coordinates by name of your location please use our [Geocoding API](/api/geocoding-api.md). > We support over 200,000 cities worldwide and our data is available for any coordinates around the globe. However, we don't recommend using large locations or countries as it will not be weather data for a large location (aggregated data or averages), but weather data for **a central point of the territory**. Finally, please mind that all our tariff plans have caps on the quantity of calls made to API and it varies depending on the subscription type. Subscription plans provide different account-level daily and per-minute API call limits. These limits apply to the total usage of your account, regardless of which API key or subscribed product is used. In case you don’t obtain an API response due to hitting the limit of calls, we would ask you to repeat your request in 10 minutes. On this occasion, we also recommend to keep the API request unamended, since it would help our internal caching service to process your request timely. ## When you exceed the API call limit We take a count of calls made with all API keys assigned to your account. To avoid service interruptions for your users, we won’t immediately suspend your API key if you exceed the call limit. An automatic notification will be sent to your email, suggesting to switch to a [paid subscription plan](/price.md) which would meet your requirements. In case we don’t hear back from you, your API key will be suspended. You will still be able to resume your subscription by contacting our [customer support team](mailto:info@openweathermap.org). ### Response from API when your account is suspended ```json { "cod": 429, "message": "Your account is temporary blocked due to exceeding of requests limitation of your subscription type. Please choose the proper subscription http://openweathermap.org/price" } ``` If you do not find a reply to your questions on this page, please, look at our comprehensive [FAQ](/faq.md) or contact our [customer support team](mailto:info@openweathermap.org). ## Support for third-party applications OpenWeather provides support for our own products and API services, including API key activation, account-related questions, subscription issues, and access to OpenWeather API endpoints. However, we do not provide technical support for using an OpenWeather API key inside third-party applications, such as Google Calendar, Garmin apps, watch faces, Home Assistant integrations, or similar external platforms. Although some third-party applications may use OpenWeather data, they are developed, maintained, and configured by their respective owners. We do not have access to their codebase, settings, integration logic, or technical documentation. For this reason, we cannot troubleshoot issues related to how an API key is used inside those applications. If you experience a problem with a third-party application, please get in touch with the application’s support team or developer directly. They are responsible for the integration and can provide the most accurate guidance for setup, configuration, and troubleshooting. --- # Donation We want to do everything we can to support the children and families of Ukraine, who lost everything during this conflict. That is why we created a donation program where **we donate along with every our customer**: ## We will double the amount of each donation, thus the triple amount of your contribution will go to the fund All funds raised will go to the [Disasters Emergency Committee](http://www.dec.org.uk/). Here is a [link](https://www.dec.org.uk/appeal/ukraine-humanitarian-appeal) to the Ukraine Humanitarian Appeal description. ## How to donate 1. [Sign up](https://home.openweathermap.org/users/sign_up) at OpenWeather and choose any [OpenWeather subscription](/price.md) according to your needs. 2. When you choose the subscription plan then go to payment process. 3. On the last step of the payment process you will find the check-box with activation of the donating programm (see the screen below). 4. Activate the check-box with donation programma and complete the payment. Once you complete the payment, we will start processing your donation and sent the tripple amount to the DEC. If you have any questions, please refer to the FAQ section below. **Other details about donation** ### Can I donate another amount with OpenWeather? We are currently working on extending this program. Once we finish it, we will provide our clients with it as soon as possible. ### Can I donate separately from an OpenWeather subscription? You can always donate to the DEC directly [here](https://donation.dec.org.uk/ukraine-humanitarian-appeal). ### When will my funds be credited to the Disasters Emergency Committee? Your funds and our part will be credited to the DEC in a month. Once it happens, you will receive a confirmation letter with transaction details. ### Will I receive any confirmation that my donation will be delivered to the DEC? Yes, as soon as the funds are credited to the DEC, we will send you the confirmation email with transaction details. You can always check the payment with DEC. --- # Partners and solutions > If you have not found a proper solution on this page, just look at the **20,000** OpenWeatherMap repositories on [GitHub](https://github.com/search?q=openweathermap&ref=cmdform) ## Google Weather-Based Campaign Management with OpenWeatherMap API Demand for certain products and services varies greatly depending on the weather. For example, users are much more likely to search for information on amusement parks on a hot, sunny day than if it's cold and raining. An amusement park company may want to increase their bids when the weather is nice, but doing so every day would require a lot of manual work. Using AdWords scripts, you can programmatically fetch weather data and adjust bids in minutes. This script uses Google Spreadsheets to store the list of campaigns and their associated locations. A call to the OpenWeatherMap API is made for each location and weather conditions are calculated using some basic rules. If a rule evaluates as true, a location bid multiplier is applied to the campaign’s targeting. - [More detailes with source code](https://developers.google.com/adwords/scripts/docs/solutions/weather-based-campaign-management) ## Google Maps JavaScript API based on OpenWeatherMap API Google has closed their Weather and Cloud solutions since 4th of June 2015 and recommended to use OpenWeatherMap with the Google Maps JavaScript API as an alternative solution. - [View on Github](https://github.com/google/maps-for-work-samples/blob/master/samples/maps/OpenWeatherMapLayer/index.html) - [Open manual](https://github.com/google/maps-for-work-samples/blob/master/samples/maps/OpenWeatherMapLayer/OpenWeatherMapLayer.pdf) ## OpenWeather current weather data in Mozilla's IoT project The WebThings Gateway for home automation: Monitor and control all your smart home devices via a unified web interface. - [Open Website](https://iot.mozilla.org/gateway/) Weather add-on for the gateway allows users to select from OpenWeatherMap or some other providers. - [View on Github](https://github.com/mozilla-iot/weather-adapter) ## Ubuntu Ubuntu My Weather Indicator - [Open website](https://launchpad.net/my-weather-indicator) Ubuntu Unity OpenWeatherMap Scope - [Open website](https://launchpad.net/unity-scope-openweathermap) ## Android **Android weather app: JSON, HTTP and Openweathermap** In this post we want to describe how to create a weather app for **Android** that gives current weather information. This app will use JSON, HTTP connection and AsyncTask to get this information. [http://www.survivingwithandroid.com/2016/01/4-free-weather-providers-api-to-develop.html](http://www.survivingwithandroid.com/2016/01/4-free-weather-providers-api-to-develop.html) [http://www.survivingwithandroid.com/2013/05/build-weather-app-json-http-android.html](http://www.survivingwithandroid.com/2013/05/build-weather-app-json-http-android.html) [http://survivingwithandroid.github.io/WeatherLib](http://survivingwithandroid.github.io/WeatherLib) **Weather Notification** Simple application which displays the air temperature and other weather conditions in the Android notification bar. The air temperature is always visible like a system clock. - [See on Bitbucket](https://github.com/gelin/weather-notification) ## Leaflet **A Leaflet plugin for adding a weather widget to the map using OpenWeatherMap API** - [View on Github](https://github.com/oskosk/Leaflet.Weather) **OpenWeatherMap for Leaflet based maps** A JavaScript library for including OpenWeatherMap's layers and OWM's current city/station data in leaflet based maps without hassle. - [View on Github](https://github.com/buche/leaflet-openweathermap) **Leaflet providers** Leaflet-providers provides tile layers from different providers, including OpenStreetMap, OpenWeatherMap and others. - [View on Github](https://github.com/leaflet-extras/leaflet-providers/) ## Java **OpenWeatherMap JSON API client library in Java** Java library to retrieve weather information and forecasts from Open Weather Map - [View on Github](https://github.com/migtavares/owmClient) **OWM JAPIs** OWM JAPIs lets you develop weather-aware applications for Java and Android platforms in minimum time using OWM JAPIs, an easy-to-use, detailed and documented weather APIs' wrapper library for retrieving weather data from OpenWeatherMap.org. You can easily retrieve and use weather data in your applications using this library. OWM JAPIs allows you to fetch weather data in only 3-5 lines of code (excluding any other/skeleton code, of course). You can develop applications and services for multiple platforms using this library, such as Windows, Mac OS X, Linux, and Android. - [View on Github](http://go.aksingh.net/owm-japis-src) ## Go (golang) **OpenWeatherMap Go API** Go (golang) library for use with openweathermap.org's API - [See library](http://briandowns.github.io/openweathermap/) ## JavaScript **Weather.js** Weather.js fetches data from openweathermap.org and makes querying all kinds of weather related information easy. - [weatherjs.com](http://weatherjs.com/) **JavaScript libraries for OpenStreetMap applications** - [View on Github](https://github.com/alno/osm-js-libs/) **Weather Display** - [View on Github](https://github.com/nils-werner/owm-display) ## CMS **Drupal OpenLayers Open Weather Map** Provides default OpenWeatherMap layers and a new layer type to display weather forecast and weather stations all around the globe. - [See on the website](http://drupal.org/project/olowm) **WordPress HD Weather Widget by The Waypoint** This plugin uses HD 331dpi images, in beautiful responsive circles, to display weather for your location. Images included in this package now. The plugin parses data from the OWM api to display information. The HD background image changes, based on the condition outside, aptly named "the Feels". We have provided one Feel in the initial v.1. Use the documentation to xref the api condition statements, against file names. The images get loaded via css, so they don't interfere with layered objects on the site. - [View plugin](http://wordpress.org/plugins/waypoint-hd-weather-widget/) **WordPress WPCloudy Plugin** WP Cloudy is a powerful weather plugin for WordPress, based on OpenWeatherMap API, using Custom Post Types and shortcodes, and much more. - [View Location Weather plugin](https://wordpress.org/plugins/location-weather) - [View WP Forecast plugin](https://wordpress.org/plugins/wp-forecast/) - [View Extended Weather plugin](https://wordpress.org/plugins/extended-weather/) ## Raspberry Pi **Raspberry_temperature_log** Turn Raspberry Pi into temperature and humidity logging station with DHT11 sensor - [View on Github](https://github.com/DzikuVx/raspberry_temperature_log) ## Python **PyOWM** PyOWM is a client Python wrapper library for the OpenWeatherMap. It allows quick and easy consumption of OWM weather data (either observations and forecast) from Python applications via a simple object model. No additional libraries are requested: only the Python 2.6/2.7 standard library modules. PyOWM currently supports version 2.5 of the OWM API. - [View on Github](https://github.com/csparpa/pyowm) - [View on YouTube](https://www.youtube.com/watch?v=123Vz_3E0Zs&feature=youtu.be) **pywws** This guide gives brief instructions on how to use pywws with some other weather services and software. - [See the docs](http://pywws.readthedocs.org/en/latest/guides/integration.html#open-weather-map) ## PHP **OpenWeatherMap-PHP-Api** Php api to parse weather data from OpenWeatherMap.org - [View on Github](https://github.com/cmfcmf/OpenWeatherMap-PHP-Api) ## Apache Camel **Weather Component** Component is used for polling weather information from Open Weather Map - a site that provides free global weather and forecast information. The information is returned as a json String object. - [See on the website](http://camel.apache.org/weather.html) ## Desktop **Weather-Map** Weather-Map is a desktop application that provides free weather data. Weather-Map wide range of weather data - map with current weather, quantity of precipitation, wind speed, clouds cover, sea Level Pressure contour maps, temperature, snow precipitation, data from weather stations, data from radars, data for cities. Weather data is received from OpenWeatherMap api. - [View on Github](https://github.com/rafaelkyrdan/Weather-Map) ## 20,000 repositories on GitHub GitHub library of codes and scripts operating with OpenWeatherMap API - [View solutions](https://github.com/search?q=openweathermap&ref=cmdform) --- # Frequently Asked Questions ### About the company: what is OpenWeather? OpenWeather (headquartered in London) is a team of IT-intellectuals that create pivotal products for business using climate data. For each point on the globe, OpenWeather provides hyperlocal minutely forecast, historical data, current state, and from short-term to annual forecasted weather data. All data is available via [industry standard APIs](/api.md). OpenWeather Ltd. has more than 9 million users including Fortune 500 companies and thousands of other businesses globally. ### How to get an API key? To use OpenWeather services, you first need to create an OpenWeather account. Once your account is created and your email address is verified, you will receive your personal API key (APPID), which is required to access our APIs and other OpenWeather services. Getting started is easy: 1. [Sign up](https://home.openweathermap.org/users/sign_up) for an OpenWeather account to get an API key (APPID) on [your account page](https://home.openweathermap.org/api_keys) 2. Verify your email address using the confirmation email we sent you. If you do not receive it, you can resend the verification email from your profile settings one hour after registration 3. After verification, check your Inbox again to find our welcome email that contains your API key and important information Congratulations! Now you have a Free [OpenWeather account](https://home.openweathermap.org/subscriptions) and can start using our services. We also recommend reading our [API documentation](/api.md) to learn how to integrate and use our APIs effectively. ### What products and types of data can I request? For each point on the globe, OpenWeather provides hyperlocal minutely forecast, historical data, current state, and from short-term to annual and forecasted weather data. All data is available via [industry standard APIs](/api.md). [One Call API by call](/api/one-call-4.md): Make just one API call and get all your essential weather data for a specific location with One Call API 4.0. - Current weather - 1-minute forecast for 1 hour - Hourly forecast for 48 hours - Daily forecast for 8 days - National weather alerts - Weather data for 47+ years history archive and 4 days ahead forecast by timestamp - Daily aggregated weather data for 47+ years historical archive and 1,5 year forecast ahead - Weather overview with a human-readable weather summary for today and tomorrow's forecast, utilizing OpenWeather AI technologies - AI Weather Assistant for retrieving weather data and weather-related advice in a human-readable and friendly format For more functionality, please consider our generous professional subscriptions. Professional collections: [Current Weather and Forecasts Collection](/api.md#current) How to get: - [APIs](/api.md) (you can request data for geographic coordinates, ZIP codes, city name, city ID, number of cities) - [Bulk Download](/bulk.md) (download already collected and regularly updated data for a list of global locations; available for premium subscriptions) [Historical Weather Collection](/api.md?filter=historical#collections) How to get: - On-the-fly bulks for customised lists of coordinates - [Marketplace](https://home.openweathermap.org/marketplace) of prepared data sets (coordinates, cities, zip codes) - History Bulk (47+ years back), History Forecast Bulk (from 7 Oct 2017) - APIs to a timestamp / a period (subscriptions with different limits on calls and depth of archive) [Specialised products:](/full-price.md#alerts) - [Solar Irradiance API](/api/solar-irradiance.md) - [Solar Panels Energy Prediction](/api/solar-panels-and-energy-prediction-2.md) - [Global Weather Alerts](/api/push-weather-alerts.md) - [Road Risk API](/api/road-risk.md) - [Global Precipitation Maps - Forecast and historical data](/api/global-precipitation-map-forecast.md) - [Weather Maps 2.0 with 1-hour step](/api/weather-map-1h.md) Detailed information about all our products can be found on the [Pricing page](/full-price.md). ### Do I need to activate my API key? Your API key will be activated automatically, up to 2 hours after your successful registration. We invite you to read the [API documentation](/api.md) that explains how to use our APIs. ### How can I use an API key in API calls? To authorise a request from you and process it, we require you to use your unique API key in each API call. In order to do this, add your API key as an *appid* parameter to the GET request, like in the following example: `api.openweathermap.org/data/2.5/weather?id=524901&appid=YOUR_API_KEY` Just use your API key instead of “YOUR_API_KEY” with your personal API key, it can be found in your personal account on the [“API keys” page](https://home.openweathermap.org/api_keys). You can also create additional API keys there. ### Where can I find my API key(s) and generate additional ones? Your API key can be found in your personal account on the [“API keys” page](https://home.openweathermap.org/api_keys). You can always create additional API keys there. ### How many keys can I create? You can create as many keys as you like. Any API key associated with your account can be used with all subscribed products. API call limits are applied at the account level, not per API key. Usage from all API keys associated with your account is combined and counted toward the same account limits. When choosing a subscription plan, make sure to consider the total expected API usage across all your API keys and subscribed products, as subscription plans have different daily and per-minute API call limits. More information about subscription limits can be found on the [Pricing page](/full-price.md). ### How to delete an API key? You can delete unnecessary API keys but please note that your account with us should have at least 1 API key at any time. To find your API key, go to your personal account and click the [“API keys” tab](https://home.openweathermap.org/api_keys) When you have more than 1 registered API key, there will be an option to delete an API key. ### How often is the weather data updated? The frequency of weather data updates depends on your subscription. Please find more information on our [“Detailed pricing” page](/full-price.md#current), the “Weather API data update” part. ### What should I do if I subscribed before creating an account? If you subscribed before creating an OpenWeather account, an account was automatically created using the email address you provided during the subscription process. To access your account, you need to reset your password: 1. Click [“Sign in”](https://home.openweathermap.org/users/sign_in) in the top-right corner of the website 2. Click on "Select Lost your password? Click here to recover" 3. Follow the instructions sent to your email address ### What should I do if I didn't receive the confirmation email? If you haven't received the confirmation email, try the following: 1. Check your **Spam** or **Junk** folder. If you find the email there, mark it as **Not Spam** to ensure future emails from OpenWeather are delivered to your Inbox 2. Wait at least **1 hour** after registration. You can then resend the verification email from your account settings: [https://home.openweathermap.org/home](https://home.openweathermap.org/home) 3. If you still don't receive the email, you can send another verification email **3 hours after your previous resend request** If you still haven't received the verification email after following these steps, please contact us at [**info@openweathermap.org**](mailto:info@openweathermap.org) for assistance. ### What is One Call API 4.0? What does this product include? [One Call API 4.0](/api/one-call-4.md) is a unified weather intelligence API designed to give developers, digital products, and enterprise teams access to current weather, short-term forecasts, long-range daily outlooks, historical weather records, and official weather alerts through a single integration. One Call API 4.0 simplifies weather data access by consolidating multiple temporal layers of weather information into one coherent API product. With a single API key and a standard request model based on geographic coordinates, teams can access: - Current weather conditions - Minute-by-minute forecast data for the next 60 minutes - 15-minute forecast data for the next 48 hours - Hourly weather timelines spanning 47 years of history and 48 hours of forecast - Daily weather timelines spanning 47 years of history and up to 1.5 years ahead - Detailed weather alert information from national agencies This combination helps businesses reduce integration complexity, shorten development time, and create richer weather-aware experiences across consumer, commercial, and industrial use cases. One Call API 4.0 is included to the ["Pay as you call" subscription type](/faq.md#payasyoucall). Please note, that you do not need to subscribe to any other OpenWeather subscription plans to get access to the One Call API 4.0. If you are ready to subscribe to the One Call API 4.0, please refer to the [Pricing page](/price.md). ### How much does subscription on the One Call API 4.0 cost? Subscription on the One Call API 4.0 allows you to pay only for the number of API calls made to this product. 1,000 API calls per day are included for free. Our system sums up the number of calls that were in excess of the free limit (1,000 calls per day). You will be automatically charged at the end of your subscription months. If you unsubscribe before the end of your subscription month, then you will be charged at the time of unsubscribing. Please refer to the [Pricing page](/price.md) to find information about actual price for calls to One Call API 4.0. ### How to start use the One Call 4.0? First, please create your account by [signing up](https://openweathermap.org/home/sign_up) with your email, if haven't OpenWeather account yet, and find API keys in the [‘API keys’ tab](https://home.openweathermap.org/api_keys). Second, on the [Pricing page](/full-price.md#onecall), click 'Subscribe' button in the "One Call API 4.0" section. Fill out a short billing form and complete your subscription. Please pay attention, that you do not need to sign up any other subscriptions to get access to the One Call API 4.0. Congratulations! Now you can start using the [One Call API 4.0](/api/one-call-4.md). Please note that the limit of 2,000 API calls per day is set by default. You can always change this limit at the ["Billing plan" tab](/subscriptions.md) in your Personal account. Before you subscribe to our service, please read [Terms and conditions of sale](https://), [Privacy policy](http://openweather.co.uk/privacy-policy), and [Websites terms and conditions of use](https://openweather.co.uk/api/files/file/Openweather_website_terms_and_conditions_of_use.pdf). Third, make an API call according [One Call API 4.0](/api/one-call-4.md) documentation. ### What is Professional API collections? The Professional API collections include several products in each subscription plan. Unlike the ["Pay as you Call" subscription type](/faq.md#payasyoucall), professional subscriptions have a fix price per month and API call limits (number of API calls per minute and number of API calls per month). The Professional API collections contain access to weather historical data, current and various forecasts. These collections also allow users to request weather maps and get weather data not only via API, but with other instruments. ### I want to start using of the professional subscriptions. Where do I begin? It is easy and takes a couple of steps. First, please create your account by [signing up](/home/sign_up.md) with your email and find API keys in the [‘API keys’ tab](https://home.openweathermap.org/api_keys). On the [Pricing page](/full-price.md#current), choose a proper subscription, click 'Subscribe'. Fill out a short billing form, check the details and complete your subscription. You can also subscribe from the settings page in the [‘Billing plans’ section](https://home.openweathermap.org/subscriptions). For bank transfer or any other individual conditions, please contact [our team](https://home.openweathermap.org/questions). Before you subscribe to our service, please read [Terms and conditions of sale](https://openweather.co.uk/api/files/file/OpenWeather_T%26C_of_sale.pdf), [Privacy policy](http://openweather.co.uk/privacy-policy), and [Websites terms and conditions of use](https://openweather.co.uk/api/files/file/Openweather_website_terms_and_conditions_of_use.pdf). ### What is the depth of historical weather data that you provide? We offer [historical weather data](/api.md?filter=historical#collections) for any location for 47+ years back (since 1st January 1979). You can find more information about specific products in the Historical Weather Collection section of our [“Pricing” page](/price.md#history). ### Do professional subscription plans provide access to historical data? The [Historical Weather Collection](/api.md?filter=historical#collections) provides access to 47+ years of historical data - please see our [Pricing page](/full-price.md#history). ### Can I download the missed historical data? At OpenWeather, we understand the importance of reliable access to weather data for your operations. To ensure data integrity and availability, our systems are designed to store historical weather data for a specified period. Exclusively for Enterprise tariff users, we provide the opportunity to download missed data free of charge by contacting our support team at [info@openweathermap.org](mailto:info@openweathermap.org). We recommend regularly downloading and backing up your data to avoid any potential disruptions. For personalised assistance with data recovery, please feel free to get in touch [with us](mailto:info@openweathermap.org). ### How do I choose the right subscription? The structure of our [Pricing](/full-price.md) is quite simple. The [Current Weather and Forecasts Collection](/price.md) provides access to a range of products such as current weather, forecasts, short-term historical data, weather maps and other products. We provide a completely Free plan. If its functionality is not enough for the size of your applications, we suggest a variety of subscriptions with ability to call APIs more intensively, higher availability of service (up to 99.9%) and premium level of support. The [Historical Weather Collection](/price.md#history) provides access to up 47+ years’ worth of detailed historical weather data for any location. You can request data via APIs [or by a one-time export of historical data](https://home.openweathermap.org/marketplace) for a list of locations. If you need an advice on choosing the correct subscription, please contact [our team](https://home.openweathermap.org/questions) for assistance. ### Can I subscribe for more than one month? Yes, we support the annual/biannual and other options. Please contact [our team](https://home.openweathermap.org/questions) for details. ### I need more information about the API call limits of my professional subscription. The number of API calls you are allowed to make depends on [the subscription](/price.md) you choose. For any professional subscription you should to maintain your usage below **both** per-minute and per-month limits. ### What happens if I exceed the API calls limit of my professional subscription? **For Free plan** We will notify you and ask you to either migrate to a subscription plan that meets your needs or reduce a number of API calls accordingly. We expect you to take one or another action to avoid suspending of your account. **For users with paid plans** We always contact you to find a suitable solution for you. ### How will I be charged for my subscription for recurring monthly payments? **For monthly recurring payments** You will be charged a fixed monthly fee based on the subscription plan you select on the [“Pricing” page](/full-price.md). In this case, the fee will be taken from your payment card. In your first month, you will be charged immediately after subscribing. The next payment will be a month later, and so on. The fee is subject to change, but we always notify you beforehand. You can subscribe [here](/price.md). **For long-term subscriptions via manual invoicing** In case of manual invoicing, the payment process is discussed personally with each customer. If you want to set up a long-term subscription, please contact our [support team](https://home.openweathermap.org/questions). ### Can you customise an API? We have a rich experience of cooperation with corporate customers providing them with an individual approach and personalised service. We are ready to discuss and estimate any customisations. It is possible for the Enterprise license holders. For more details, please [contact us](https://home.openweathermap.org/questions). ### How to unsubscribe from your service? If you would like to unsubscribe, please [log in to your account](https://home.openweathermap.org/subscriptions) on our website, then use the “Unsubscribe” button opposite your active plan in your personal account. After cancellation your subscription will still remain active until the end of the month for which you have paid. If you pay by manual invoicing and would like to cancel your subscription, please contact [our support team](https://home.openweathermap.org/questions). ### What is "Pay as you call" subscription type? What does this subscription include? The "Pay as you call" subscription type is a subscription type that allows you to pay only for the number of API calls made to the product. This subscription type is applicable to [One Call API 4.0](/api/one-call-4.md) and [Solar Irradiance API](/api/solar-irradiance.md) products. Please pay attention that each of the products has separate "pay as you call" subscription and price. If you are ready to subscribe to the "Pay as you call" subscription type, please refer to the [Pricing page](/price.md). ### I want to start using "Pay as you call" subscription type. Where do I begin? Please pay attention that "Pay as you call" subscription type is applicable to [One Call API 4.0](/api/one-call-4.md) and [Solar Irradiance API](/api/solar-irradiance.md) products. Start using "Pay as you call" subscriptionis easy and takes a couple of steps. First, please create your account by [signing up](/home/sign_up.md) with your email and find API keys in the [‘API keys’ tab](https://home.openweathermap.org/api_keys). On the [Pricing page](/full-price.md#onecall), find desired product, click 'Subscribe' button. Fill out a short billing form and complete your subscription. Please pay attention, that you do not need to sign up any other subscriptions to get access to the "Pay as you call" subscription. Congratulations! Now you can start using the "Pay as you call" subscription. Please note that the limit of API calls per day is set by default. You can always change this limit at the ["Billing plan" tab](https://home.openweathermap.org/subscriptions) in your Personal account. Before you subscribe to our service, please read [Terms and conditions of sale](https://openweather.co.uk/api/files/file/OpenWeather_T%26C_of_sale.pdf), [Privacy policy](http://openweather.co.uk/privacy-policy), and [Websites terms and conditions of use](https://openweather.co.uk/api/files/file/Openweather_website_terms_and_conditions_of_use.pdf). ### Where can I find how much calls I make? You can find the statistics of your calls usage on the "View usage statistics" button at the ["Billing plan" tab](https://home.openweathermap.org/subscriptions) in your Personal account. ### How and when I will be charged for the calls? Our system sums up the number of calls that were made or made in excess of the free limit (for products where free limit is available). You will be automatically charged at the end of your subscription months. If you unsubscribe before the end of your subscription month, then you will be charged at the time of unsubscribing. ### I'm worried that I might accidentally make too many calls and be charged for them. How can I limit API calls? When you subscribe to a Pay as you Call plan, a default daily API call limit is automatically assigned for each subscribed product. To change this limit: 1. Sign in to your OpenWeather account. 2. Open the ["Billing plans" tab](https://home.openweathermap.org/subscriptions) in your Personal account. 3. Update the daily API call limit for the desired product. Please refer to the screenshot below for an example: ![limits default](/payload/api/media/file/limits_default.png) Please note: - Daily API call limits are reset every day between 00:00 and 00:05 UTC. - If your account has already been blocked after reaching the previous daily limit, increasing the limit will not immediately remove the block. - The new daily limit will take effect after the next daily reset, when the block is automatically lifted. If you need the block removed before the next daily reset, please contact us at [info@openweathermap.org](mailto:info@openweathermap.org). ### I received the "429" error in API response. Why? You can recieve "429" error in only one case - if you make the number of calls that exceeds the set limit of calls per day or per month. Please note that the limit of API calls per day is set by default. You can always change this limit on the ["Billing plans" tab](https://home.openweathermap.org/subscriptions). Please see the screen below: ![limits default](/payload/api/media/file/limits_default.png) ### Which payment methods we accept? We accept most major credit and debit cards, as well as digital wallets, including Visa, Mastercard, UnionPay, American Express, Apple Pay, Google Pay, Link by Stripe, WeChat Pay, Alipay+, and Revolut Pay. Bank transfers are also available for premium accounts. You can select your preferred payment method during the subscription process. ### Payments we do not accept We do not accept cash or check payments. ### Is my payment secure? All transactions made on the OpenWeather website are secure. We use HTTPS secure protocol over the website. We do not collect, store or process any of your payment details. ### Where is my invoice? You can find invoices and transaction history in the ['Payments' section](https://home.openweathermap.org/payments) of your settings. Note that you need to add your company information in the ['Invoice info' tab](https://home.openweathermap.org/invoice_info) in your personal account. For bank transfer payments, our support team send invoices directly to your email. You can always [contact us](https://home.openweathermap.org/questions) if you have any questions. ### What happens after I pay for a subscription? After receiving your payment, your API key will get activated and you will receive a confirmation email with API endpoints and guides. ### How can I upgrade or downgrade my subscription plan? **Please note that you can upgrade or downgrade only one of the **[**professional subscriptions**](/price.md#current)**.** **If you pay by monthly recurring payments (via payment card):** Please [log in to your account](https://home.openweathermap.org/subscriptions) on our website, then use the “Subscribe” button underneath the desired plan in your personal account. You will be charged immediately when you upgrade or downgrade your subscription. Note, that for your automatic subscription there is no any recalculation of payment that has already been done. To avoid double payment, we recommend you to change your subscription plan at the end of the month for which you have paid. For example, if you have a Startup subscription and your billing payment date is the 15th day of each month, we would recommend to upgrade/downgrade your subscription on the 14th. **If you pay by manual invoice** You can сhange your subscription plan by [contacting us](https://home.openweathermap.org/questions). ### How can I change my payment details? To change your credit card details for your OpenWeather account, you have two options depending on your payment method: 1. If you are using a credit card directly, please sign in to your account and visit this link to update your payment card details: [this link](https://home.openweathermap.org/subscriptions/customer_portal). 2. If you have used PayPal, you can update your payment details through your registered PayPal account using: [this link](https://www.paypal.com/uk/cshelp/article/how-do-i-add-my-bank-account-to-my-paypal-account-help183). If you paid using a guest PayPal account, you should resubscribe with your API key on the last day of your current subscription to avoid any interruptions or duplicate charges by following: [this link](/price_subscribe.md). If you prefer to subscribe directly using your credit card (instead of PayPal), you will need to wait until your current subscription ends before resubscribing again. If you still have any questions please [contact us](https://home.openweathermap.org/questions)for assistance and specify your account email. ### How can I change information represented on the invoice (company info, address, etc.)? Please sign in and use this link: [https://home.openweathermap.org/invoice_info](https://home.openweathermap.org/invoice_info). ### What happens if my payment fails? If you have subscribed via our website and are paying for your monthly subscription automatically, our system will make several attempts (up to 4) to charge your payment card. These attempts will happen with a minimum of 1-day difference between each charging attempt. In case we are not able to charge you after the final attempt, your subscription will be cancelled automatically, and your account will be suspended. You have to [contact us](https://home.openweathermap.org/questions) for help if your account was suspended. ### Where can I change my password? Your password can be changed in the [“My profile/User settings”](https://home.openweathermap.org/home) section of our website. ### How can I reset my password? You can reset your password on the [“Sign in”](https://home.openweathermap.org/users/sign_in) page of our website by following the link after the question “Lost your password?” or by clicking "Change password" button at the ["User settings"](https://home.openweathermap.org/home) chapter at the "My profile" section of "Personal account" page. ### Can I change my account email? Yes, we can change your account email. Please [send us](https://home.openweathermap.org/questions) you current email, new email, and your API key. ### Can I change the country of my account? Yes, we can change your country. Please [send us](https://home.openweathermap.org/questions) the country you need to change to. ### I have exceed my subscription limits. How long my account will be suspended? Our blocking system suspends your account for a couple of hours to several days **randomly**. If you want to be unlocked immediately, please [subscribe](/price.md) to our paid subscriptions. ### I want to know how many API calls I do? For professional subscriptions we do not provide statistics on how many calls the user is making to our APIs. The best way to find how many calls you are making is to add counters on your end, so it could tell you the exact amount of how many times you have sent your request to the API. For "Pay as you call" subscription plan you can find the statistics of calls usage on the "View usage statistics" button at the ["Billing plan" tab](https://home.openweathermap.org/subscriptions) in your Personal account. ### I want to delete my account; how should I do it? You can always delete your account in the [“My profile/Privacy centre”](https://home.openweathermap.org/privacy/notifications) section of your settings. Please note: - Before deleting your account, you'll need to cancel any active paid subscriptions - Account deletion is permanent and cannot be undone - Once your account is deleted, all associated data will be permanently removed from our system ### How can I change my account type from personal to business? To change your account type from personal to business, you must first cancel your current subscription. Follow these steps: 1. Sign in to your OpenWeather account 2. Go to the Subscriptions page: [https://home.openweathermap.org/subscriptions](https://home.openweathermap.org/subscriptions) 3. Cancel your current subscription and confirm the cancellation After your subscription has been cancelled, contact us at [info@openweathermap.org](mailto:info@openweathermap.org), and we will assist you with updating your account type. Please note: Changing your account type is only possible after the current subscription has been canceled. ### How can I change the VAT ID for my account? To update the VAT ID associated with your account, you must first cancel your current subscription. Follow these steps: 1. Sign in to your OpenWeather account. 2. Go to the Subscriptions page: [https://home.openweathermap.org/subscriptions](https://home.openweathermap.org/subscriptions) 3. Cancel your current subscription and confirm the cancellation. After your subscription has been cancelled, contact us at [info@openweathermap.org](mailto:info@openweathermap.org). We will update the VAT ID associated with your account, after which you can subscribe again using the updated billing information. Please note: Your current subscription must be cancelled before we can update the VAT ID associated with your account. ### Why is my account locked? Your account can be temporarily locked after 5 unsuccessful login attempts to help protect it from unauthorised access. Here's what you need to know: - The account remains locked for 1 hour. - During the lockout period, you cannot sign in or reset your password. - Once the lockout period ends, you will have 5 new login attempts ### Can I use OpenWeather’s APIs commercially? Yes, you can. Please see our [pricing page](/full-price.md) for more details. ### How to ensure that I give the attribution to OpenWeather correctly? For the plans between Free and Professional, the attribution requirement is obligatory. When it is required by your license you should place the following information in the visible part of your solution: - ‘Weather data provided by OpenWeather’ - Hyperlink to our website [https://openweathermap.org/](/index.md) - OpenWeather logo. We provide a library of different styles to match your application design. You can [**download them here**](https://openweathermap.org/storage/app/media/logo_files.zip). If you have any doubts about your specific scenario, please reach out to our [support team](https://home.openweathermap.org/questions) and we will be glad to advise. ### What models do you use? OpenWeather provides accurate weather data by drawing on trusted sources such as weather stations, satellites, radar systems, and advanced models like GFS, ECMWF, and its own OWHL™️. These partnerships with the UK Met Office and other national meteorological agencies boost reliability, with updates released every 10 minutes to ensure precision. Remarkably, the OWHL™️ model reports less than 1% of temperature predictions deviating by more than 5°C. Widely recognised as a leading provider of short-term forecasts, OpenWeather acknowledges that accuracy diminishes over longer periods due to atmospheric complexity. Thus, while short-term forecasts remain highly reliable, it is prudent to view predictions beyond a week with a degree of caution. Continuously refining its models using real-time data, OpenWeather delivers reliable forecasts worldwide, covering both remote and densely populated areas. It also offers minute-by-minute precipitation data and hyperlocal insights, establishing itself as a trusted choice for businesses across the globe. You can find out more about OpenWeather model [here](https://openweather.co.uk/technology). ### I have a weather station. Can I connect my station with your system? If you also believe in the significance of climate data in tackling climate and healthcare challenges and would like to contribute to our initiatives, then we invite you to connect your automated weather station to our platform. The accuracy of weather data benefits from enthusiasts from all over the world and we reward these contributions with our Startup plan. To contribure your data to our system, please use the [Weather station API](/stations.md). To get access to the Startup plan, please [contact us](https://home.openweathermap.org/questions). ### What are the minimum/maximum temperature fields in the Current Weather API and Forecast Weather API? In the [Current Weather API](/current.md) and [Hourly Forecast API](/api/hourly-forecast.md): As it is a current weather data that reflect weather conditions only for the current moment, we add optional statistical parameters the `temp_min` and `temp_max` fields to show dispersion of temperature at this current moment. This is the minimum/maximum currently observed temperature or forecast temperature (within large megalopolises and urban areas). In the [16-Day Forecast API](/forecast16.md) and [30-Day Forecast](/api/forecast30.md) The `list.temp.min` and `list.temp.max` fields are minimum/maximum daily temperature, and show the minimum and maximum temperatures in the day. ### Which time format and timezone are used? OpenWeather uses Unix time and the UTC/GMT time zone for all API calls, including current weather, forecast and historical weather data. The `timezone_offset` parameter shows the shift in seconds from UTC. In the [One Call API 4.0 response](/api/one-call-4.md), there is also a timezone parameter that shows the time zone name for the requested location. ### Why I do not see some parameters in the API response? If you do not see some of the parameters in your API response, it means that these weather phenomena just have not happened for the selected location at the time of measurement. Only actually measured or calculated data is displayed in an API response. ### What is the format of the API response? The JSON format is used by default. To get data in the XML or HTML format, just use “xml” or “html” for the `mode` parameter. The HTML format is available for [Current Weather API](/current.md) only. For the [One Call API 4.0](/api/one-call-4.md), data is only available in the JSON format. If the `mode` parameter is omitted, the format is JSON by default. Examples of API calls: - JSON: `api.openweathermap.org/data/2.5/weather?q=London&{YOUR_API_KEY}` - XML: `api.openweathermap.org/data/2.5/weather?q=London&mode=xml&{YOUR_API_KEY}` - HTML: `api.openweathermap.org/data/2.5/weather?q=London&mode=html&{YOUR_API_KEY}` ### What are the weather condition codes and icons? A list of weather condition codes with icons (range of thunderstorm, drizzle, rain, snow, clouds, atmosphere including extreme conditions such as tornado or hurricane) can be found [here](/weather-conditions.md#How-to-get-icon-URL). You are free to use these icons in your own solutions. ### How can I specify locations in API calls? Requesting API calls by geographical coordinates is the most accurate way to specify any location. If you need to convert city names and zip-codes to geo coordinates and the other way around automatically, please use our [Geocoding API](/api/geocoding-api.md). However, some of our APIs support in-built geocoding, which allows users to call weather data by city name, city ID and Zip-code. If the chosen API supports built-in geocoding, then you will find the "Buil-it geocoding" section in the API documentation. We support over 200,000 cities worldwide and our data is available for any coordinates around the globe. However, we don't recommend using large locations or countries as it will not be weather data for a large location (aggregated data or averages), but weather data for a central point of the territory. ### Where can I find a list of City IDs? For current and forecast products (Current API, Hourly Forecast API, Daily Forecast for 16 days, Climatic forecast for 30 days, 5 day/3 hour forecast data) can be downloaded [here](http://bulk.openweathermap.org/sample/). Please note that you can also make requests to our APIs by using coordinates, ZIP codes, etc. Please refer to documentation of specific API to see all available options. ### How to determine polar day and polar night using sunset and sunrise time? Polar day and polar night are natural phenomenons which occur when day and night respectively lasts more than 24 hours and observed for the northernmost and southernmost regions of Earth. During polar day and polar night time of sunset and sunrise are coincide. So, if sunset and sunrise time for specified location are the same: - Polar day will be observed for locations in North hemisphere from March till September and for locations in South hemisphere from September till March - Polar night will be observed for locations in North hemisphere from September till March and for locations in South hemisphere from March till September ### What X, Y tile coordinate numbers are possible for given zoom level in the OpenWeather tiled map? The following table provides an indication of zoom levels, possible X, Y tile coordinate numbers, the quantity of tiles at each zoom level, and the scale of each level. | Zoom level | Possible X, Y tile coordinate number (only integers are available) | Quantity of tiles | Examples of area to represent | | --- | --- | --- | --- | | 0 | 1 | 1 | whole world | | 1 | 0-1 | 4 | one quarter of the world | | 2 | 0-3 | 16 | subcontinental area | | 3 | 0-7 | 64 | largest country | | 4 | 0-15 | 256 | largest country | | 5 | 0-31 | 1024 | large African country | | 6 | 0-63 | 4,096 | large European country | | 7 | 0-127 | 16,384 | small country, US state | | 8 | 0-255 | 65,536 | wide area, large metropolitan area | | 9 | 0-511 | 262,144 | wide area, metropolitan area | ### What is the correlation between solar irradiance and solar irradiation? The basic definitions of solar power sector are solar irradiation and solar irradiance and are often used interchangeably. However, they are not a synonyms: **Solar irradiation** is the total energy received by a surface of the Earth per unit area over a given period of time. It is the amount of radiation (also known as shortwave radiation) passing through a horizontal plane. Solar irradiance is measured in Wh/m2. **Solar irradiance** is the surface power density received by a surface of the Earth. Solar irradiance is measured in W/m2. To convert irradiance to irradiation please use the formula below: **Energy(Wh/m****2****) = Power(W/m****2****) * TimeInterval(h)** where energy is a solar irradiation; power is a solar irradiance. For energy data values for 1 h period of TimeInterval = 1 For energy data values for 15 min period of TimeInterval = 0.25 For more details about what technologies, algorithms, etc. are behind the Solar Irradiance & Energy Prediction service can be found [here](/api/solar-radiation/behind-solar-radiation-api.md). ### Wind cardinal and degree directions correlation Wind direction is reported as an orientation from where the wind is blowing. The directions of the wind is determined at the geographical system of coordinates and could be represented in degrees and cardinals terms. wind direction in degrees -azimuth degrees, i.e., in a numerical measure that moves around the Rose of the Winds in a clockwise circle from 0 degrees (N) to 360 degrees (N).Wind direction in cardinals - direction based on are the four main compass directions: north, south, east, and west. Relative to north, the directions east, south, and west are at 90 degree intervals in the clockwise direction. Please find below the table with correlations between cardinal and degree wind directions: | Cardinal Direction | Degree Direction | ![wind cardinal direction](/payload/api/media/file/wind-cardinal-direction.png) | | --- | --- | --- | | N | 348.75-11.25 | | | NNE | 11.25-33.75 | | | NE | 33.75-56.25 | | | ENE | 56.25-78.75 | | | E | 78.75-101.25 | | | ESE | 101.25-123.75 | | | SE | 123.75-146.25 | | | SSE | 146.25-168.75 | | | S | 168.75-191.25 | | | SSW | 191.25-213.75 | | | SW | 213.75-236.25 | | | WSW | 236.25-258.75 | | | W | 258.75-281.25 | | | WNW | 281.25-303.75 | | | NW | 303.75-326.25 | | | NNW | 326.25-348.75 | | ### API calls return an error 400000 You can get the 400000 error when you request data for a period not covered by your subscription. Access to specific time ranges in each product depends on your subscription level. You can check the allowed data range for each subscription and product on the [Pricing page](/price.md). If you need access to data beyond the permitted range, consider upgrading your plan. ### API calls return an error 401 You can get the error 401 in the following cases: - You did not specify your [API key](https://home.openweathermap.org/api_keys) in API request. - Your API key is not activated yet. Within the next couple of hours, it will be activated and ready to use. - You are using wrong API key in API request. Please, check your right API key in [personal account](https://home.openweathermap.org/api_keys). - You are using a Free subscription and try requesting data available in other subscriptions . For example, [16 days/daily forecast API](/forecast16.md), [any historical weather data](/price.md#history), [Weather maps 2.0](/api/weather-map-2.md), etc). Please, check your subscription in your [personal account](https://home.openweathermap.org/). ### API calls return an error 404 You can get this error when you specified the wrong city name, ZIP-code or city ID. For your reference, this list contains City name, City ID, Geographical coordinates of the city (lon, lat), Zoom, etc. You can also get the error 404 if the format of your API request is incorrect. In this case, please review it and check for any mistakes. To see examples of correct API requests, please visit the [Documentation](/api.md) of a specific API and read the examples of API calls there. ### API calls return an error 429 You can recieve this error in the following cases: - If you have a Free plan of Professional subscriptions and make more than 60 API calls per minute (surpassing the limit of your subscription). To avoid this situation, please consider upgrading to a [subscription plan](/full-price.md#current) that meets your needs or reduce the number of API calls in accordance with the limits. ### API calls return errors 500, 502, 503 or 504 In case you receive one of the following errors 500, 502, 503 or 504 please [contact us](https://home.openweathermap.org/questions) for assistance. Please enclose an example of your API request that receives this error into your email to let us analyze it and find a solution for you promptly. --- ## Detailed Self-Service Pricing and Limits These plans are self-service subscriptions for fast, direct access to OpenWeather services. If you need contracts, procurement support, broader licensing, or industry-specific solutions, explore Enterprise Service below. | Prices are fixed. No additional or hidden fees apply. VAT is not included. | Free — Permanent free access | One Call API 4.0 — Timeline-Based Weather | Startup — Small apps | Developer — Growing apps | Professional — Production use | Expert — High-volume use | | --- | --- | --- | --- | --- | --- | --- | | Price per month | Free | Pay as you call 1,000 API calls per day for free 0.0012 GBP per API call over the daily limit | 30 GBP | 140 GBP | 370 GBP | 1200 GBP | ### API limits | Prices are fixed. No additional or hidden fees apply. VAT is not included. | Free — Permanent free access | One Call API 4.0 — Timeline-Based Weather | Startup — Small apps | Developer — Growing apps | Professional — Production use | Expert — High-volume use | | --- | --- | --- | --- | --- | --- | --- | | API calls | 60 calls/minute 1,000,000 calls/month | No API call limits Pay as you call | 600 calls/minute 10,000,000 calls/month | 3,000 calls/minute 100,000,000 calls/month | 30,000 calls/minute 1,000,000,000 calls/month | 100,000 calls/minute 3,000,000,000 calls/month | ### Current weather and forecasts data | Prices are fixed. No additional or hidden fees apply. VAT is not included. | Free — Permanent free access | One Call API 4.0 — Timeline-Based Weather | Startup — Small apps | Developer — Growing apps | Professional — Production use | Expert — High-volume use | | --- | --- | --- | --- | --- | --- | --- | | [Current weather API](/current.md) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | [Minute-by-minute forecast the next hour](/api/one-call-4.md) | — | ✓ | — | — | — | — | | [15-Minute Forecast for the next 48 hours](/api/one-call-4.md?collection=one_call_api#15min) | — | ✓ | — | — | — | — | | [Hourly forecast for 4 days API](/api/hourly-forecast.md) | — | [for 2 days](/api/one-call-4.md?collection=one_call_api#hourly) | — | ✓ | ✓ | ✓ | | [3-hourly forecast for 5 days API](/forecast5.md) | ✓ | — | ✓ | ✓ | ✓ | ✓ | | [Daily forecast for 16 days API](/forecast16.md) | — | [for 1,5 years](/api/one-call-4.md?collection=one_call_api#daily) | ✓ | ✓ | ✓ | ✓ | | [Daily forecast for 30 days API](https://openweathermap.org/api/forecast30?collection=current_forecast) | — | — | — | ✓ | ✓ | ✓ | | [Long-term forecast (1.5 years)](/api/one-call-4.md?collection=one_call_api#daily) | — | ✓ | — | — | — | — | | [Bulk Download (standard presets)](/bulk.md) | — | — | — | — | [by global cities](/bulk.md) | [by global cities + ZIPs of US, EU, UK](/bulk.md) | | [Bulk Download (custom)](https://openweather.co.uk/custom-bulks-openweather-business) | — | — | — | — | — | ✓ | ### Weather alerts | Prices are fixed. No additional or hidden fees apply. VAT is not included. | Free — Permanent free access | One Call API 4.0 — Timeline-Based Weather | Startup — Small apps | Developer — Growing apps | Professional — Production use | Expert — High-volume use | | --- | --- | --- | --- | --- | --- | --- | | [Government weather alerts by location](/api/one-call-4.md?collection=one_call_api#alerts) | — | ✓ | — | — | — | — | | [OpenWeather alerts](https://openweather.co.uk/products/openweather-alerts): customisable weather alerts for business | — | — | — | — | — | — | ### Weather Maps | Prices are fixed. No additional or hidden fees apply. VAT is not included. | Free — Permanent free access | One Call API 4.0 — Timeline-Based Weather | Startup — Small apps | Developer — Growing apps | Professional — Production use | Expert — High-volume use | | --- | --- | --- | --- | --- | --- | --- | | [Weather maps 1.0 API](/api/weathermaps.md) | ✓ | — | ✓ | ✓ | ✓ | ✓ | | [Weather maps 2.0 API: Model-based maps (current, forecast, historical)](/api/weather-map-2.md) | — | — | — | ✓ | ✓ | ✓ | | [Global precipitation maps API- Historical](/api/global-precipitation-map.md) | — | — | — | — | ✓ | ✓ | | [Global precipitation maps API - Historical and Forecast](/api/global-precipitation-map-forecast.md) | — | — | — | — | — | — | | [Weather maps 2.0 API with 1-hour step](/api/weather-map-1h.md) | — | — | — | — | — | — | | [Relief maps API](/api/relief.md) | — | — | — | ✓ | ✓ | ✓ | | [Fire Weather Maps API](/api/fire-index-map.md) | — | — | — | — | — | — | ### Historical data | Prices are fixed. No additional or hidden fees apply. VAT is not included. | Free — Permanent free access | One Call API 4.0 — Timeline-Based Weather | Startup — Small apps | Developer — Growing apps | Professional — Production use | Expert — High-volume use | | --- | --- | --- | --- | --- | --- | --- | | [Weather History API](/history.md) | — | — | — | — | 1 month back 5,000 calls/day | 1 year back 50,000 calls/day | | [Accumulated Parameters API](/api/accumulated-parameters.md) | — | — | — | — | 1 month back 5,000 calls/day | 1 year back 50,000 calls/day | | [Statistical Weather Data API](/api/statistics-api.md) | — | — | — | — | — | 50,000 calls/day | | [History Bulk](/history-bulk.md) | — | — | — | — | — | — | | [History Forecast Bulk](/api/history-forecast-bulk.md) | — | — | — | — | — | — | | [Historical data with 1-hour step for 47+ years back](/api/one-call-4.md?collection=one_call_api#hourly) | — | ✓ | — | — | — | — | | [Historical data with 1-day step for 47+ years back](/api/one-call-4.md?collection=one_call_api#daily) | — | ✓ | — | — | — | — | ### Special products | Prices are fixed. No additional or hidden fees apply. VAT is not included. | Free — Permanent free access | One Call API 4.0 — Timeline-Based Weather | Startup — Small apps | Developer — Growing apps | Professional — Production use | Expert — High-volume use | | --- | --- | --- | --- | --- | --- | --- | | [Road Risk API](/api/road-risk.md) | — | — | — | — | — | [basic configuration](/api/road-risk.md) | | [Solar Irradiance API](/api/solar-irradiance.md) | — | — | — | — | — | — | | [Solar Panel Energy Prediction API](/api/solar-panels-and-energy-prediction-2.md) | — | — | — | — | — | — | | [Wind speed on different heights](https://openweather.co.uk/products/wind-service) | — | — | — | — | — | — | | [Solar Irradiance History Bulk](/api/solar-irradiance-history-bulks.md) | — | — | — | — | — | — | | [Solar Irradiance History Forecast Bulk](/api/solar-irradiance-history-forecast-bulks.md) | — | — | — | — | — | — | | [Fire Weather Index API](/api/fire-index-api.md) | — | — | — | — | — | — | | [Air Pollution API](/api/air-pollution.md) | ✓ | — | ✓ | ✓ | ✓ | ✓ | | [Geocoding API](/api/geocoding-api.md) | ✓ | — | ✓ | ✓ | ✓ | ✓ | | [Weather widgets](/widgets-constructor.md) | ✓ | — | ✓ | ✓ | ✓ | ✓ | ### Service | Prices are fixed. No additional or hidden fees apply. VAT is not included. | Free — Permanent free access | One Call API 4.0 — Timeline-Based Weather | Startup — Small apps | Developer — Growing apps | Professional — Production use | Expert — High-volume use | | --- | --- | --- | --- | --- | --- | --- | | Procurement | — | — | — | — | Manual invoicing and supplier portal registration for invoicing only; no procurement or agreement support | Manual invoicing and supplier portal registration for invoicing only; no procurement or agreement support | | Availability | 95.0% | 99,5% | 95,0% | 99,5% | 99,5% | 99,9% | | Business API end-point | — | — | — | — | ✓ | ✓ | | License | [ODbL](/full-price.md#licenses) | [ODbL](/full-price.md#licenses) | [ODbL](/full-price.md#licenses) | [ODbL](/full-price.md#licenses) | [ODbL](/full-price.md#licenses) | [ODbL](/full-price.md#licenses) | | SLA | — | — | — | — | — | — | | [Attribution](/faq.md#license) | Yes | Yes | Yes | Yes | Yes | Yes | | Technical support | Help Desk | Help Desk | Help Desk | Help Desk | Help Desk | Help Desk | | Weather API data update | Every 2 hours | Every 10 min | Every 2 hours | Every 1 hour | Every 10 min | Every 10 min | | Weather maps data update | Every 3 hours | N/A | Every 3 hours | Every 3 hours | Every 1 hour | Every 1 hour | | API lifetime support | Current version | Current version | Current version | Current version | All versions | All versions | ## Need more than self-service? If self-service plans no longer fit your buying model or operational requirements, OpenWeather Enterprise offers a more structured service with contracts, licensing flexibility, onboarding, and support for business-critical use cases. ### Enterprise Service When self-service is no longer enough OpenWeather Enterprise provides contract-based access to OpenWeather’s broadest weather, forecast, alerting, mapping, historical, and specialist-data capabilities, combined with enterprise licensing, SLA-backed service, procurement support, and dedicated account management. - **Stay with self-service if you need:**: - fast onboarding - standard pricing - standard commercial use - direct subscription - standard terms and limits - **Move to Enterprise if you need:**: - a contract or invoicing - procurement or legal review - broader licensing or custom terms - onboarding and account support - a service for operationally critical or multi-team use - [Explore Enterprise Service](https://openweather.co.uk/pricing-corp) - [Contact Sales](mailto:info@openweathermap.org) ## How automatic API subscriptions work ### Self-service subscriptions Self-service plans are built for developers, data scientists, businesses, and product teams who need immediate API access to globally available, high-coverage weather data delivered through reliable, production-grade infrastructure. Our datasets provide broad geographic reach and trusted weather information used worldwide, allowing teams to build and scale independently under standard public terms. **Included** - Immediate online activation - Independent subscription management - API access under the ODbL licence - Commercial and non-commercial use - Technical support via our Support Centre - Published, predictable pricing **Licence Requirement** - Visible attribution to OpenWeather in your application or service **Not Included** - Contract negotiation or customised terms - Procurement or compliance documentation - Dedicated account management - Modified attribution conditions - Enterprise service commitments > For contract-based licensing, customised terms, or enterprise-grade usage, please see our [Enterprise Service](https://openweather.co.uk/pricing-corp). ### Self-Service Subscription Process #### Create an Account - [Sign up](https://openweathermap.org/home/sign_up) with your email address. Your API key is generated automatically and available in your account. #### Choose a Plan - Select a [subscription](https://openweathermap.org/price) based on the endpoints, usage limits, and call volume you need. #### Subscribe online - Complete the billing form and confirm payment. - Your API key is activated immediately after payment. You can view, upgrade, downgrade, or cancel your subscription at any time in your account settings. ### License All automated self-service plans are provided under the ODbL (Open Database License). Commercial use is allowed. **Standard commercial use - Attribution** If you use OpenWeather data to power: - Mobile apps - Websites - SaaS platforms - Dashboards - Analytics tools - Internal business systems etc. You only need to: - Provide visible attribution to OpenWeather This does **not** require you to: - Open-source your application - Share your product code - Disclose your business logic **Adapted Weather Databases - Share-Alike ** Share-alike applies only if you: - Build a reusable dataset from OpenWeather data - Restructure, combine, or enrich it - Operate your own weather dataset or API based on stored OpenWeather data - Make that dataset or API available outside your organisation If the result remains fundamentally weather data derived from OpenWeather, the nature of the data has not changed. If such a database is distributed externally, it must be offered under the same ODbL license. > In most commercial use cases, you only need to provide **attribution** on the screen or page where weather data appears. > > Attribution placed only in hidden documentation or deep legal pages is not sufficient. > > **Recommended line:** > > Weather data © OpenWeather > > ![Openweather_attribution](/payload/api/media/file/Openweather_attribution1.png) > > ![Openweather_attribution](/payload/api/media/file/Openweather_attribution2.png) ### Support & Service Model - All support is provided via our [**Help Desk ticket system**](https://openweathermap.org/support-centre) - No phone support is offered - Written support ensures clear, traceable responses Professional and Expert plans receive **priority response** in the support queue. ### Billing & Payments **Payment Methods** - Credit & debit cards (Visa, MasterCard, American Express, UnionPay) - Apple Pay, Google Pay, Stripe Link, WeChat Pay, Alipay+, Revolut Pay - Bank transfers (available for selected plans and longer terms) Cash and checks are not accepted. **Recurring Billing** - Your card is charged immediately upon subscription - Billing repeats automatically each billing cycle - Pricing changes are communicated in advance Invoices and payment history are available in your account dashboard. ### Subscription Management & Cancellation - Subscriptions renew automatically each billing period - You can cancel anytime; access remains until the end of the paid cycle - No partial refunds or proration - Upgrades apply immediately; downgrades take effect next cycle Accounts can be deleted at any time from the [Privacy Centre](https://home.openweathermap.org/privacy/notifications). ### Usage Limits, Reliability & Security - Each plan includes defined usage limits; overage fees may apply - Service uptime and data accuracy are continuously monitored - Weather data accuracy may vary due to external factors - Industry-standard security and data protection practices are applied Full details are available in our Privacy Policy and Terms. ### Need enterprise-grade service or custom terms? Self-service plans are automated subscriptions under a public licence (ODbL) with mandatory attribution and standard terms. [Enterprise Service](https://openweather.co.uk/pricing-corp) is a contract-based service designed for organisations that require: - A negotiated commercial agreement, SLA (not ODbL) - Procurement and compliance documentation - Defined service parameters and usage volumes - Dedicated account coordination - Customised terms or modified attribution conditions If your organisation requires governed, contractually licensed access to weather data, please refer to our [Enterprise Service](https://openweather.co.uk/pricing-corp). ### Important Policies to Review Before Payment - License [ODbL](https://opendatacommons.org/licenses/odbl/) - [Terms and Conditions of Sale](https://) - [Privacy Policy](http://openweather.co.uk/privacy-policy) - [Website Terms and Conditions of Use](https://openweather.co.uk/api/files/file/Openweather_website_terms_and_conditions_of_use.pdf) ### Resources - [Support Centre](https://openweathermap.org/support-centre): Submit a ticket if you need further assistance. - [FAQ](/faq.md): Quick answers regarding subscription, billing, and product usage. - [API Documentation](/api.md): Detailed examples for each API call and its responses. **By subscribing to any plan above, you agree to our **[**Terms and Conditions of Sale**](https://openweather.co.uk/api/files/file/OpenWeather_T%26C_of_sale.pdf)**, **[**Privacy Policy**](https://openweather.co.uk/privacy-policy)**, and **[**Website Terms of Use**](https://openweather.co.uk/api/files/file/Openweather_website_terms_and_conditions_of_use.pdf)**.** --- # How to start working with OpenWeather APIs **OpenWeather delivers reliable, global weather data through structured APIs designed for straightforward integration. Access current conditions, forecasts, historical archives, and specialised datasets to support applications ranging from lightweight services to large-scale operational systems.** ## OpenWeather APIs overview OpenWeather provides reliable, global weather data through structured, industry-standard APIs. Our services support a wide range of applications, from lightweight integrations to large-scale data systems, delivering current conditions, forecasts, historical weather, and specialised datasets. Access is immediate. Integration is straightforward. Pricing is transparent. - [View pricing & subscribe](/price.md) ## What data is available OpenWeather APIs provide: - Current weather conditions - Minute-by-minute forecasts - Hourly and daily forecasts - Short-term and extended outlooks - Government weather alerts - 47+ years of historical observations - Historical forecast archives - Statistical climate data - Air quality data - Weather maps and geospatial layers - Industry-focused APIs (Solar, Road Risk, Agromonitoring, and others) Coverage is global, data is available for any coordinate worldwide. All services are delivered via REST APIs with structured JSON responses suitable for integration into web, mobile, analytics, IoT, and enterprise environments. - [Documentation](/api.md) ## Core API products **One Call API 4.0**. A comprehensive weather endpoint for a specific location, combining current, forecast, historical data, and alerts within a single API call. **Forecast & Current Weather APIs**. Short-term and extended forecasts with frequent updates. **Historical Weather APIs**. 47+ years of hourly archive data, forecast history, and statistical datasets. **Weather Maps & Geospatial APIs**. Layer-based weather maps, precipitation data, and visual datasets. Detailed API documentation and integration guidance are available for all products. - [Documentation](/api.md) ## Technology and data quality OpenWeather OWHL™ model operates with: - Ground weather stations and sensors - Satellite systems - Radar networks - Global forecast models including GFS and ECMWF Data updates are released every 10 minutes to ensure timely delivery. Short-term forecasts demonstrate strong predictive performance. As with all atmospheric modelling, forecast uncertainty increases over longer time horizons. Continuous model refinement and real-time data processing ensure consistent global coverage across both urban and remote regions. - [Technology](https://openweather.co.uk/technology) - [Accuracy](/accuracy-and-quality.md) ## How to start using Weather API Getting started requires only a few steps: 1. Create an OpenWeather [account](https://home.openweathermap.org/users/sign_in) 2. Select the API product appropriate for your needs on the [APIs page](https://openweathermap.org/api) 3. Choose a subscription plan on the [Pricing](https://openweathermap.org/price) page 4. Receive your API key instantly (no approval or onboarding process required) 5. Integrate using the provided [documentation](https://openweathermap.org/api) [Free](https://openweathermap.org/price) plans are available for evaluation and development. [Paid plans](/price.md) scale according to usage. - [Select plan and subscribe](/price.md) ## Licensing OpenWeather self-service products are provided under the **Open Database License (ODbL)** framework. You may use the data to build applications, websites, dashboards, analytics tools, and commercial products. The key difference under ODbL is **whether your product is only showing results** from OpenWeather data, or whether you are **building a new dataset/API where the data is still essentially weather data derived from OpenWeather**. In other words: **the “nature” of the data matters**. 1) Displaying weather in your app or service (Produced Work) If you use OpenWeather data to show weather information to end users, for example in an app, website, dashboard, or report, you are producing a **Produced Work**. In this case, you are presenting outputs (maps, charts, forecasts, insights), not providing a database to others. **Main requirement:** attribution to OpenWeather. 2) Building a weather dataset or API where the data is still “weather data” (Adapted Database) If you store, restructure, combine, or enrich OpenWeather data and the result is still fundamentally **weather data derived from OpenWeather**, even if delivered through your own dataset, feed, or API, this may be considered an **Adapted Database**. Examples include: - Storing large volumes of OpenWeather data as a reusable dataset - Restructuring the data into your own schema or database - Combining OpenWeather data with other data and keeping it as a structured dataset - Creating a weather API or data service backed by stored OpenWeather-derived data **Important:** changing the format, schema, or adding calculations does not remove the origin of the data. If it still functions as weather data derived from OpenWeather, Adapted Database rules may apply. If that adapted database (or a service giving access to it) is made available **outside your organisation**, **share-alike conditions apply** meaning the adapted database must be offered under the same ODbL terms. - [License](https://openweathermap.org/full-price#licenses) ## Support and resources - [API documentation](https://openweathermap.org/api) - [Pricing](https://openweathermap.org/price) - [HelpDesk](https://openweathermap.org/support-centre) - [FAQ](https://openweathermap.org/support-centre) - [Terms of sale](https://openweather.co.uk/api/files/file/OpenWeather_T%26C_of_sale.pdf) - [Privacy policy](https://openweather.co.uk/privacy-policy) - [Licensing](https://openweathermap.org/full-price#licenses) - [Enterprise solutions](https://openweather.co.uk/pricing-corp) ## Enterprise Solutions For organisations that require: - Contract-based licensing - Custom commercial terms - Procurement documentation - Higher usage volumes - API customisation or configuration OpenWeather Enterprise services are available under separate commercial agreements. Enterprise operates independently from self-service API subscriptions and is designed for corporate procurement frameworks. - [Enterprise Solutions](https://openweather.co.uk/pricing-corp) ## Academic Initiatives OpenWeather supports academic and research communities via non-profit [Weather Foundation](https://weatherfoundation.org). Universities, research institutions, professors, and students can use OpenWeather data for: - Scientific research - Climate studies - Environmental modelling - Urban planning research - Academic publications - Student projects and theses Weather data plays a critical role in global research, and we believe it should be accessible for scientific progress. Academic usage is typically supported through: - Special academic access options - Educational discounts or dedicated plans (where applicable) - Clear licensing under the open data framework For larger institutional research projects, data redistribution, or long-term structured datasets, Enterprise arrangements may be required. - [Explore free data and initiatives](https://weatherfoundation.org) --- # Historical Weather Data: Formats, APIs, and Bulk Downloads Explore the different ways to access historical weather data with OpenWeather — from bulk archives to API queries for any timestamp. This guide helps you choose the best option depending on your use case, data volume, and level of detail. ## What historical weather data OpenWeather provides OpenWeather provides several types of historical weather data designed for different use cases — from long-term climate analysis to retrieving weather conditions for a specific moment in the past. Depending on your needs, you can access historical data in several formats: - Bulk downloadable archives covering many years - Historical forecasts (past model outputs) - API access to weather data for any past timestamp - Aggregated daily historical statistics - Timeline endpoints combining historical and forecast data ### History Bulks Downloadable datasets in CSV and JSON formats Time Coverage: 47+ years back (from January 01, 1979) Geo coverage: Worldwide Access Method: Downloadable datasets Available through our [Marketplace](https://home.openweathermap.org/marketplace) ### History Forecast Bulks Downloadable Historical archive of 16-days forecast weather data, CSV and JSON formats Time Coverage: 8+ years back (from October 7, 2017) Geo coverage: Worldwide Access Method: Downloadable datasets Available through our [Marketplace](https://home.openweathermap.org/marketplace) ### Historical weather via One Call 4.0 Historical weather via One Call 4.0 for any timestamp Time Coverage: 47+ years back (from January 01, 1979) Geo coverage: Worldwide Access Method: API via One Call API 4.0 ### Daily aggregated history Daily aggregated historical weather via One Call 4.0 Time Coverage: 47+ years back (from January 01, 1979) Geo coverage: Worldwide Access Method: API via One Call API 4.0 ### Statistical Weather API Statistical data on main weather parameters for any day and month of the year The statistics are calculated based on our [Historical weather data](https://openweathermap.org/history) JSON format The weather data updated every hour Statistical Weather Data API is available in Expert subscription plan ## Historical data access methods **1️⃣ Downloadable historical datasets** Large downloadable archives covering multiple years of historical weather observations and model data. Includes: - History Bulks - History Forecast Bulks Best for: Machine learning, climate research, long-term analytics. Available through our [Marketplace](https://home.openweathermap.org/marketplace) **2️⃣ Historical weather via API** Retrieve historical weather conditions for specific locations and timestamps via API. Includes: - One Call 4.0 Historical endpoint - Daily aggregated history Best for: Analytical Dashboards, on-demand queries. Available via [One Call API 4.0 subscription](/price.md#one_call) or [Professional subscriptions](/full-price.md). --- Your easy and reliable way to purchase historical weather data archives. Access the data you need in just a few clicks. Please note that most requests are processed quickly. However, larger historical datasets may take longer to generate, and specific delivery times cannot be guaranteed. For high-volume or custom orders, please [**contact our sales team**](https://). ### History Bulk Download up to 47+ years back historical weather data for any location worldwide. - Data available from January 1, 1979 - Worldwide availability, any location - Hourly step - CSV, JSON formats Ideal for long-term analysis, climate research, modelling, and data-driven forecasting. ### History Forecast Bulk Get data on previously made 16-day forecasts for any coordinates on the globe. - Data available from October 7, 2017 - Worldwide availability, any location - Archive of 16-days forecasts - CSV, JSON formats Ideal for forecast verification, model validation, and performance analysis. ### Solar Irradiance History Bulk Download 47+ years of historical solar irradiance data for any location worldwide via bulk access. - Data available for 47+ years back - 15-minute and 1-hour resolution - GHI, DNI, DHI indices - Clear-sky and cloudy-sky models - Available by geographic point (lat/lon coordinates) --- # One Call API 2.5 Deprecated One Call API 2.5 has been deprecated in June 2024. We advise you to switch to [One Call API 3.0](/api/one-call-3.md) and prepared the [detailed guide](/one-call-transfer.md) for transitioning. ## About One Call API 3.0 As opposed to our subscriptions with fixed monthly cost, [One Call API 3.0](/api/one-call-3.md) has its own, separate subscription that has a variable cost, in proportion to your actual use of the API. Apart from additional functionality (47+ years of historical data are now available via this API), users can configure and limit their usage to ensure that they don’t make more request than expected. Read more about this subscription plan in the [FAQ](/faq.md#onecall). Here are the types of data that are available: - [**Current weather and forecasts:**](/api/one-call-3.md#current) and government weather alerts - - minute forecast for 1 hour - hourly forecast for 48 hours - daily forecast for 8 days - [**Weather data for any timestamp**](/api/one-call-3.md#history) for 47+ years historical archive and 4 days ahead forecast - [**Daily aggregation**](/api/one-call-3.md#history_daily_aggregation) of weather data for 47+ years archive and 1.5 years ahead forecast - [**Weather overview**](/api/one-call-3.md#weather_overview) with a human-readable weather summary for today and tomorrow's forecast, utilizing OpenWeather AI technologies ## Pay as you call 1,000 API calls per day for free **0.0012 GBP** per API call over the daily limit - [Subscribe to One Call by Call](https://home.openweathermap.org/subscriptions/unauth_subscribe/onecall_30/base) If you have any questions, please fell free to [contact us](https://home.openweathermap.org/questions). --- # Empowering Impact Through Weather Data Our initiatives bridge data and purpose, creating community-driven solutions for education, health, and climate resilience. ### [object Object] Initiatives participants already received our data and support ### [object Object] Partnerships with leading global universities ### [object Object] Invested annually in climate research and education --- # Self-Service API Pricing **Start free with self-service plans for OpenWeather APIs, or explore Enterprise options for larger-scale needs.** ## Timeline-Based Weather ## API One Call 4.0 The next generation of One Call with one smooth timeline for future and past, available in 1-minute, 15-minute, 1-hour, and 1-day steps. ### One Call 4.0 pay-per-call **One Call 4.0 weather API** First 1,000 API calls per day are FREE Each additional call costs 0.0012 GBP - **What's included in One Call 4.0**: - One Smooth Timeline for Future and Past - 1-Minute Step - 15-Minute Step - 1-Hour Step - 1-Day Step - Government Alerts [Read Detailed Product Description](/api/one-call-4-desciption.md) - **Built for Developers**: - Global coverage via latitude & longitude - Simple RESTful API - Flexible JSON output - One request logic for forecast and history - [Subscribe](https://home.openweathermap.org/subscriptions/unauth_subscribe/onecall_40/base) - [Explore API Docs](/api/one-call-4.md) ## Weather API plans | Subscriptions — Choose the plan aligned with your project scope, usage volume, and development needs | Startup — Small apps | Developer — Growing apps | Professional — Production use | Expert — High-volume use | | --- | --- | --- | --- | --- | | Price per month | 30 GBP | 140 GBP | 370 GBP | 1200 GBP | | API Calls/Minute | 600 | 3,000 | 30,000 | 100,000 | | API Calls/Month | 10M | 100M | 1B | 3B | ### Products | Subscriptions — Choose the plan aligned with your project scope, usage volume, and development needs | Startup — Small apps | Developer — Growing apps | Professional — Production use | Expert — High-volume use | | --- | --- | --- | --- | --- | | [Current Weather API](/current.md) | ✓ | ✓ | ✓ | ✓ | | [3-hourly forecast for 5 days API](/forecast5.md) | ✓ | ✓ | ✓ | ✓ | | [Daily forecast for 16 days API](/forecast16.md) | ✓ | ✓ | ✓ | ✓ | | [Daily forecast for 30 days API](https://openweathermap.org/api/forecast30?collection=current_forecast) | — | ✓ | ✓ | ✓ | | [Hourly forecast for 4 days API](/api/hourly-forecast.md) | — | ✓ | ✓ | ✓ | | [Weather maps API - Current](/api/weathermaps.md) | ✓ | ✓ | ✓ | ✓ | | [Weather maps API - History and Forecast](/api/weather-map-2.md) | — | ✓ | ✓ | ✓ | | [Air Pollution API](/api/air-pollution.md) | ✓ | ✓ | ✓ | ✓ | | [Geocoding API](/api/geocoding-api.md) | ✓ | ✓ | ✓ | ✓ | | [Bulk Download](/bulk.md) | — | — | ✓ | ✓ | | [Global Precipitation maps API - Historical](/api/global-precipitation-map.md) | — | — | ✓ | ✓ | | [Road Risk API (Basic)](/api/road-risk.md) | — | — | — | ✓ | | [Statistical Weather Data API](/api/statistics-api.md) | — | — | — | ✓ | | [Weather History API](/history.md) | — | — | ✓ | ✓ | | [Accumulated Parameters API](/api/accumulated-parameters.md) | — | — | ✓ | ✓ | ### Service | Subscriptions — Choose the plan aligned with your project scope, usage volume, and development needs | Startup — Small apps | Developer — Growing apps | Professional — Production use | Expert — High-volume use | | --- | --- | --- | --- | --- | | License Type | [ODbL](https://openweathermap.org/full-price#licenses) | [ODbL](https://openweathermap.org/full-price#licenses) | [ODbL](https://openweathermap.org/full-price#licenses) | [ODbL](https://openweathermap.org/full-price#licenses) | | Availability | 95% | 99,5% | 99,5% | 99,9% | | Weather Data Update Frequency | Every 2 hrs | Every 1 hr | Every 10 min | Every 10 min | - [Detailed pricing](/full-price.md) ### History bulk Download up to 47+ years back historical weather data for any location worldwide. Key features: - Data available from January 1, 1979 - Global coverage (any coordinates) - Hourly data resolution - Available in CSV and JSON formats Ideal for long-term analysis, climate research, modelling, and data-driven forecasting. ### History forecast bulk Access archived 16-day forecasts exactly as they were issued for any location worldwide. Key features: - Data available from October 7, 2017 - Global coverage (any coordinates) - Archive of previously generated 16-day forecasts - Available in CSV and JSON formats Ideal for forecast verification, model validation, and performance analysis. ### Global Precipitation Maps (history and forecast) Radar-based maps providing highly precise precipitation data for any location worldwide. Key features: - Global coverage - Current precipitation data - Short-term forecast: - - Up to 6 hours for the US - Up to 2 hours for other regions - Historical data: last 2 days with 10-minute frequency - Designed for real-time monitoring and high-resolution visualization Ideal for flood monitoring, transport operations, outdoor planning, and weather-sensitive decision-making. ### Weather Maps 2.0 1-hour Access hourly updated global weather map layers for visualization and monitoring applications. Key features: - Hourly forecast map layers - Parameters including temperature, precipitation, clouds, pressure, wind, and more - Global coverage - Tile-based map format for easy integration - Designed for web and mobile weather map visualization Ideal for building interactive weather maps, dashboards, and geospatial monitoring tools. ### Solar Irradiance API Access real-time and forecasted solar irradiance data for any location worldwide. Key features: - Current and 16-day solar irradiance forecasts - GHI, DNI, and DHI indices - Clear-sky and cloudy-sky models - Global coverage by geographic coordinates - Pay-as-you-call - Delivered via API in JSON format Ideal for solar energy monitoring, system optimization, and performance forecasting. ### Solar Panel Energy Prediction Estimate solar power generation and panel performance for any location worldwide using advanced weather and irradiance models. Key features: - Solar energy production forecasts based on panel configuration - Support for tilt angle, orientation, and system parameters - Current conditions and forecast-based energy output - Global coverage by geographic coordinates - Delivered via API in JSON format Ideal for solar project planning, system optimization, and performance forecasting. ### Wind service Accurate wind speed and direction data for any location worldwide, available for hub heights between 10 and 500 meters. Key features: - Wind data at custom heights (10–500 m) - Current conditions and 16-day forecasts - High-resolution time steps (hourly or 15-minute) - Global coverage by coordinates - Flexible delivery options (API, bulk, S3, FTP, dashboard) Ideal for wind energy assessment, turbine optimization, and wind-sensitive operations. ### Solar Irradiance History Bulk Download 47+ years of historical solar irradiance data for any location worldwide via bulk access. Key features: - Data available for 47+ years back - 15-minute and 1-hour resolution - GHI, DNI, DHI indices - Clear-sky and cloudy-sky models - Available by geographic point (lat/lon coordinates) Ideal for solar energy modelling, performance assessment, and long-term resource analysis. ### Solar Irradiance History Forecast Bulk Download an archive of previously generated 16-day solar irradiance forecasts for any location worldwide. Key features: - Historical forecasts available from April 2017 onward - 16-day forecast archive with 1-hour resolution (15-minute step available on request) - Includes clear-sky and cloudy-sky solar irradiance forecasts - Global coverage by coordinates - Exportable in CSV and JSON formats Access to the full archive by request ### Road Risk API Access real-time and forecasted road weather risk data for any location worldwide to support safer and more efficient transport operations. Key features: - Current and forecast road risk conditions - Risk indicators based on weather parameters (e.g., temperature, precipitation, wind, visibility, national alerts, etc.) - Global coverage by geographic coordinates - Designed for route planning and fleet management systems - Delivered via API in JSON format Ideal for logistics, fleet operators, navigation platforms, and weather-sensitive transportation services. ### Fire Weather Index Advanced fire danger assessment data to support wildfire prevention, monitoring, and risk management. Key features: - Fire risk index based on weather conditions - Current data and forecast availability - High-resolution coverage by geographic coordinates - Designed for environmental monitoring and emergency planning - Delivered via [Index API](/api/fire-index-api.md) and [Fire Weather Index Maps](/api/fire-index-map.md) Ideal for forestry services, environmental agencies, insurers, and risk management platforms. ### AgroMonitoring A professional agricultural intelligence platform delivering satellite-based crop and field monitoring data worldwide. Key features: - Vegetation indices (NDVI, EVI, NDWI, DSWI, NRI, and more) - Soil temperature and soil moisture data - Weather-based agricultural insights - Historical and forecast data integration - Field-level monitoring by polygon or coordinates Ideal for precision agriculture, farm management, agribusiness analytics, and yield optimization. For organisations that require more than standard self-service access, OpenWeather Enterprise provides a contract-based service with broader licensing, procurement support, tailored commercial terms, and enterprise-grade delivery. ## Free Weather API access ### Current weather and forecasts **Free for everyone** - 60 API calls/minute, 1,000,000 calls/month - [Current Weather API](/current.md) - [3-hour Forecast (5 days)](/forecast5.md) - [Air Pollution API](/api/air-pollution.md) - [Weather Maps (15 layers)](/api/weathermaps.md) - [Geocoding API](/api/geocoding-api.md) - [Subscribe](https://home.openweathermap.org/users/sign_up) ### Current, Forecast and Historical data **Free for students** - 60 API calls/minute, 1,000,000 calls/month - [Current Weather API](/current.md) - [3-hour Forecast (5 days)](/forecast5.md) - [Air Pollution API](/api/air-pollution.md) - [Weather Maps (15 layers)](api/weather-map-2) - [Geocoding API](/api/geocoding-api.md) - [Weather History API](/history.md) - [Statistical Weather Data API](/api/statistics-api.md) - [Accumulated Parameters](/api/accumulated-parameters.md) - [Hourly Forecast (4 days)](/api/hourly-forecast.md) - [Daily Forecast (16 days)](/forecast16.md) - [Subscribe](https://home.openweathermap.org/users/sign_up) --- # Support centre OpenWeather’s support centre is not only a team of specialists ready to help you with any issue but also a set of tools and resources designed to make it easier for you to use our services. Whether you are just starting out with APIs, an experienced developer, or a business, our team is ready to provide answers to your questions. ## OpenWeather AI assistant Ulla Ulla, the OpenWeather AI assistant, is an AI-powered tool trained on our products and services to provide seamless support. Whether you are exploring APIs, troubleshooting issues, or seeking guidance, Ulla is designed to aid you in navigating OpenWeather's product offerings. What is Ulla: it is the advanced AI technology powering the OpenWeather assistant. Originally developed as a corporate AI assistant, Ulla specialises in transcriptions, summaries, and secure data management, supporting business across industries with innovative solutions. Explore more at [ulla.bot](https://ulla.bot/). Ulla is just starting out in beta and may make some mistakes. Consider checking important information. We are working to improve and develop the assistant to give the most accurate answers. Let us know if you notice any mistakes, and we will correct it. FAQ is a collection with a detailed information about most popular topics ### Payment process The "Payment process" chapter is designed to help customers navigate various aspects of the payment process more effectively and reduce the number of inquiries related to payment issues. In this section, you'll find guidance on: - Changing Your Tariff Plan: Instructions on how to effortlessly modify your current plan. - Obtaining an Invoice: Steps to request and receive your invoices quickly and easily. - Adjusting Payment Information: Information on how to update your payment methods and invoice details as needed. - Accepted Payment Methods: A comprehensive list of the payment options available for your convenience. - Payment Processing including Information about security measures in place to protect payment information. - Troubleshooting Payment Issues: Helpful tips for resolving common payment problems you may encounter. ### Subscriptions and collection The Professional API Collection section is designed to assist in navigating in the the available subscriptions and the products included with each plan. This section covers the following key topics: - Types of Products and Data Included: Comprehensive details on the various APIs available. - How to Choose the Right Subscription: Evaluate the different subscription plans and select the one that best meets your specific needs and objectives. - Subscription Payments: Access detailed information about the various payment methods available. ### Personal account The "Personal Account" chapter aims to assist users in understanding and managing their personal accounts effectively. This chapter covers topics related to account management, and troubleshooting, ensuring users can quickly find the information they need. Key areas include: - Account Management: Guidance on updating personal details such as email address and password, as well as how to set preferences and notification settings. - Subscription Limits Exceeded: Information on what to do if you subscription limits are surpassed. - API Call Count: Instructions on how to locate information regarding your API calls and guidance on calculating them. ### API errors The API Errors chapter is go-to guide for understanding the various error codes you might encounter while using our API. By familiarizing with most common errors, you’ll be better equipped to diagnose problems and troubleshoot effectively. For each error code, we provide a clear explanation of what it means and how it relates to your request or operation and describe common reasons why errors might occur, such as incorrect parameters, authentication failures, or connectivity issues. This information is designed to help you identify the issue quickly and take appropriate action. - [Read FAQ](/faq.md) ## Enquiry to OpenWeather Support If you didn't find the answer on your question, our qualified support team is on hand to answer your questions. You can send a message on [info@openweathermap.org](mailto:info@openweathermap.org) or via special form. - [Contact Support](https://home.openweathermap.org/questions) --- # TEST PAGE ### New One Call pay-per-call **New One Call** First 1,000 API calls per day are FREE Each additional call costs 0.0012 GBP - **What’s included in one call**: - Current weather (updated every minute) - 1-minute forecast (next hour) - Hourly forecast (48 hours) - 8-day daily forecast - Historical data (up to 47+ years back) - Government weather alerts - **Built for Developers**: - Global coverage via latitude & longitude - Simple RESTful API - Flexible JSON output - Dynamic exclusions to reduce response size - [Subscribe](https://home.openweathermap.org/subscriptions/unauth_subscribe/onecall_30/base) - [Explore API Docs](/api/one-call-4.md) ### One Call pay-per-call **One Call** First 1,000 API calls per day are FREE Each additional call costs 0.0012 GBP - **What’s included in one call**: - Current weather (updated every minute) - 1-minute forecast (next hour) - Hourly forecast (48 hours) - 8-day daily forecast - Historical data (up to 47+ years back) - Government weather alerts - **Built for Developers**: - Global coverage via latitude & longitude - Simple RESTful API - Flexible JSON output - Dynamic exclusions to reduce response size - [Subscribe](https://home.openweathermap.org/subscriptions/unauth_subscribe/onecall_30/base) - [Explore API Docs](/api/one-call-4.md) ### One Call pay-per-call **One Call** First 1,000 API calls per day are FREE Each additional call costs 0.0012 GBP - **What’s included in one call**: - Current weather (updated every minute) - 1-minute forecast (next hour) - Hourly forecast (48 hours) - 8-day daily forecast - Historical data (up to 47+ years back) - Government weather alerts - **Built for Developers**: - Global coverage via latitude & longitude - Simple RESTful API - Flexible JSON output - Dynamic exclusions to reduce response size - [Subscribe](https://home.openweathermap.org/subscriptions/unauth_subscribe/onecall_30/base) - [Explore API Docs](/api/one-call-4.md) --- # Weather Triggers > The Weather Triggers API has been deprecated on 2025. > > If you are seeking functionality related to weather-based triggers, we recommend using the [OpenWeather Dashboard](https://dashboard.openweather.co.uk/), which provides a wide range of tools and customizable features for monitoring weather conditions. > > For those looking to implement similar functionality via API, we suggest exploring the [OpenWeather Alerts product](https://openweather.co.uk/products/openweather-alerts). This service offers robust and flexible alerting capabilities designed to meet a variety of use cases. > > If you require a custom solution or have specific integration needs, please don’t hesitate to contact our [Support team](mailto:info@openweathermap.org).