How to transfer from One Call API 2.5 to the One Call API 3.0

×

OpenWeather
Meteorological Service

Dan Hart Speak to the Chief
Meteorologist Dan Hart and
his team!

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 45+ 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:

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

You can also ask any questions you have our OpenWeather AI assistant.

About One Call API 3.0

The One Call API 3.0 contains 4 endpoints and provides access to various data:

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

Subscribe

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: info@openweathermap.org

Please find more about One Call API 3.0 at the documentation page and FAQ.

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 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 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 45+ years historical archive and 4 days ahead forecast
Daily aggregation - Daily aggregation of weather data for 45+ 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

To match One Call API 2.5 parameters to the equivalent OpenWeather One Call API 3.0 parameters, please read "Matching parameters" chapter.

How to start using One Call API 3.0

  1. First, please subscribe to the One Call API 3.0 clicking 'Subscribe' button in the "One Call API 3.0" section on the Pricing page. You will get a confirmation email and activation of your API keys can take several minutes.
  2. You don’t need to get new API keys, your current API keys will work with One Call API 3.0 after subscribing finishing

  3. 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}
    • 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}
    • 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}
    • 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}
Parameters
lat required Latitude of coordinates
lon required Longitude of coordinates
appid required Your unique API key (you can always find it on your account page under the "API key" tab)
dt required Timestamp (Unix time, UTC time zone), e.g. dt=1586468027. Data is available from January 1st, 1979 till 4 days ahead forecast
date required Date in the YYYY-MM-DD format for which data is requested. Date is available for 45+ 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 documentation (complete description of API calls and parameters in API response, with examples).

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 in the daily forecast for 8 days.
  • One Call API 3.0 included new 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 endpoint that provides with with a human-readable weather summary for today and tomorrow's forecast, utilizing OpenWeather AI technologies.
  • 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 endpoint in the One Call API 3.0.

Please use the below comparison table 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
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
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
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 ). Get the output in your language
current.weather.icon current.weather.icon Weather icon id. How to get icons
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
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
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
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
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). Get the output in your language
hourly.weather.icon hourly.weather.icon Weather icon id. How to get icons
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
daily.temp.day daily.temp.day Day temperature. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. How to change units used
daily.temp.eve daily.temp.eve Evening temperature. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. How to change units used
daily.temp.night daily.temp.night Night temperature. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. How to change units used
daily.temp.min daily.temp.min Min daily temperature. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. How to change units used
daily.temp.max daily.temp.max Max daily temperature. Units – default: Kelvin, metric: Celsius, imperial: Fahrenheit. How to change units used
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
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
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
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
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
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
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
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). Get the output in your language
daily.weather.icon daily.weather.icon Weather icon id. How to get icons
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
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.
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
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
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). Get the output in your language
current.weather.icon data.weather.icon Weather icon id. How to get icons

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 endpoint in the One Call API 3.0.

We use cookies to personalize content and to analyze our traffic. Please decide if you are willing to accept cookies from our website.