Documentation

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, 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 or 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	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

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.
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 3.0 sections (current, minutely, hourly, daily, alerts) your integration actually uses today - this tells you exactly which 4.0 endpoints you'll need.
Update your endpoint URLs, splitting combined One Call 3.0 calls into the specific One Call 4.0 endpoints you need.
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	Pay-as-you-call — see pricing
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.