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

How to start using One Call API 3.0

Matching parameters

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:

Current weather and forecasts:
- minute forecast for 1 hour
- hourly forecast for 48 hours
- daily forecast for 8 days
- and government weather alerts
Weather data for any timestamp for 47+ years historical archive and 4 days ahead forecast
Daily aggregation of weather data for 47+ years archive and 1.5 years ahead forecast
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

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 ...

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: [email protected]

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:

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).
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 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" 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. 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 datahttps://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 forecasthttps://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 forecasthttps://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 technologieshttps://api.openweathermap.org/data/3.0/onecall/overview?lat={lat}&lon={lon}&appid={API key}
Read AI Weather Assistant documentation to get weather data and weather-related advice in a human-readable and friendly format

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 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 documentation (complete description of API calls and parameters in API response, with examples).

One Call API documentation

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 and 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 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.