<!-- block-id: overview -->

## Migrating from One Call API 3.0 to One Call API 4.0

<!-- block-id: overview -->

### Overview

Thanks for building with OpenWeather. We've just launched [**One Call API 4.0**](https://openweathermap.org/api/one-call-4), 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](https://openweathermap.org/faq) or [Support Centre](https://openweathermap.org/support-centre).

<!-- block-id: new -->

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

<!-- block-id: changes -->

## 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](https://home.openweathermap.org/subscriptions) | Same - unchanged |

<!-- block-id: fields -->

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

<!-- block-id: current -->

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

<!-- block-id: minute -->

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

<!-- block-id: 15min -->

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

<!-- block-id: houlry -->

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

<!-- block-id: daily -->

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

<!-- block-id: timemachine -->

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

<!-- block-id: alerts -->

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

<!-- block-id: checklist -->

## Your migration checklist

1. **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.
2. **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.
3. **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.
4. **Update your endpoint URLs**, splitting combined One Call 3.0 calls into the specific One Call 4.0 endpoints you need.
5. **Add pagination support** anywhere you're pulling large hourly/daily/15-minute ranges.

<!-- block-id: billing -->

## 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](https://openweathermap.org/price) | Pay-as-you-call — see [pricing](https://openweathermap.org/price) |
| 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.

## We're here to help

One Call 4.0 is a young product, and we know migration guides like this one work best when they keep pace with what we ship. If you hit a gap — especially around Daily Aggregation, Weather Overview, or the AI Assistant — please reach out via our [Support Centre](https://openweathermap.org/support-centre) or ask Ulla. We'll keep this guide updated as those areas are documented.

Thanks for building with OpenWeather.

*Sources:*

[*One Call API 4.0 documentation*](https://openweathermap.org/api/one-call-4)

[*One Call API 3.0 documentation*](https://openweathermap.org/api/one-call-3)

[*Pricing*](https://openweathermap.org/price)

[*FAQ*](https://openweathermap.org/faq)