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

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

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

### Overview

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## Your migration checklist

1. **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.
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 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.
4. **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.
5. **Add pagination support** anywhere you're pulling large hourly/daily/15-minute ranges.

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

## 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](https://openweathermap.org/price#one_call) |

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

## We're here to help

One Call API endpoint version 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 we document these areas.

Thanks for building with OpenWeather.

*Sources:*

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

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

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

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