Documentation

One Call API Migration Guide: From endpoint version 3.0 to endpoint version 4.0

Overview

Thanks for building with OpenWeather. We've just launched One Call API, endpoint version 4.0, the next generation of our flagship weather product, and we want to make your move from endpoint version 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 or Support Centre.

What's new in One Call API endpoint version 4.0

One Call API endpoint version 3.0 has served developers well as an all-in-one weather response. With endpoint version 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 API endpoint version 3.0 remains available today and isn't being switched off as part of this release. We recommend endpoint version 4.0 for all new integrations, and this guide is here to help existing endpoint version 3.0 customers move over at their own pace.

At a glance: what changes

Parameters	One Call API endpoint version 3.0	One Call API endpoint version 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	Same - unchanged

Field mapping, endpoint by endpoint

Good news: the actual field names, units, and meanings you already know from endpoint version 3.0 carry over almost entirely unchanged in endpoint version 4.0. What moves is the path the data sits at (most endpoint version 3.0 sections like current, hourly, daily simply become data in endpoint version 4.0's dedicated endpoints), and — for alerts — the workflow.

Current weather

One Call API endpoint version 3.0	One Call API endpoint version 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 API endpoint version 3.0	One Call API endpoint version 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 API endpoint version 4.0

There's no One Call API endpoint version 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 API endpoint version 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)

One Call API endpoint version 3.0	One Call API endpoint version 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)

One Call API endpoint version 3.0	One Call API endpoint version 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 the Hourly endpoint in One Call API endpoint version 4.0 (/timeline/1h) instead of the Time machine endpoint in One Call API endpoint version 3.0 (/timemachine).

One Call API endpoint version 3.0	One Call API endpoint version 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 the Weather alerts endpoint in One Call API endpoint version 4.0 (/onecall/alert/{alert_id}) instead of the Current & Forecasts endpoint in One Call API endpoint version 3.0 (inline alerts[]).

One Call API endpoint version 3.0	One Call API endpoint version 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 API endpoint version 4.0	-

Your migration checklist

Access One Call API endpoint version 4.0 without a separate subscription. No additional subscription is required to migrate from endpoint version 3.0 to 4.0. API calls are billed under the same “One Call by Call” plan.
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.
Map your current usage. Note which endpoint version 3.0 sections (current, minutely, hourly, daily, alerts) your integration actually uses today - this tells you exactly which endpoint version 4.0 endpoints you'll need.
Update your endpoint URLs, splitting combined One Call API endpoint version 3.0 calls into the specific One Call API endpoint version 4.0 endpoints you need.
Add pagination support anywhere you're pulling large hourly/daily/15-minute ranges.

Billing

Parameters	One Call API endpoint version 3.0 and 4.0
Subscription	Both endpoint versions are included in the same “One Call by Call” subscription.
Free calls per day	1,000 free calls total per day
Default daily call limit	2,000 calls per day (adjustable in your account).
Cost beyond the free tier	Pay-as-you-call — see pricing

Worth knowing: because One Call API endpoint version 4.0 paginates large responses, a query that was one billed call in One Call API endpoint version 3.0 via the Current&Forecasts endpoint could become several billed calls in One Call API endpoint version 4.0 if it spans a long timeline.

Pagination	One Call API endpoint 3.0	One Call API endpoint 4.0
Paginated requests	Not applicable	Each `next`/`prev` page is billed as its own call