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

About One Call API 3.0

The One Call API 3.0 contains 3 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 45 years historical archive and 4 days ahead forecast
• Daily aggregation of weather data for 45 years archive and 1.5 years ahead forecast

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

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

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.

You don’t need to get new API keys, your current API keys will work with One Call API 3.0 after subscribing finishing

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

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

Historical weather data (One Call 2.5) / Weather data for timestamp (One Call 3.0)

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.