Historical Forecast API

March 30, 2026

Overview

The Historical Weather Forecast API is a new endpoint, currently in beta, that provides access to weather forecasts as they were generated in the past.

Accessing historical weather forecasts allows you to:

  • Understand what weather conditions were expected at the time decisions were made
  • Analyze how forecasted weather influenced operational or business outcomes
  • Reconstruct the information available to systems, teams, or customers at a specific point in time
  • Support modeling and analytics that depend on forecast inputs rather than observed conditions

These end points use the same historical forecast architecture as the Timeline Weather API forecastBasisDate and forecastBasisDay parameters but make retrieving historical forecast data even easier.

The response format is fully compatible with the Timeline Weather API, enabling reuse of existing integrations. Where possible, API parameters are provided in the same way as the Timeline Weather API for straightforward integration.

Required License

A subscription to the Historical Forecast Addon subscription is required for the Historical Forecast API.

Retrieval Modes

The API supports two retrieval modes depending on how you want to query historical forecasts:

By Run (byrun)

In byrun mode, each forecast is grouped by the date it was generated. Each run produces a forward-looking forecast covering multiple days.

For example, consider the following data:

rundatetime,forecastday,datetime,tempmax,tempmin
2025-01-01,0,2025-01-01,44.7,31.9
2025-01-01,1,2025-01-02,37.7,27.2
2025-01-01,2,2025-01-03,41.8,26
...
2025-01-02,0,2025-01-02,39.3,29.6
2025-01-02,1,2025-01-03,41.3,27
2025-01-02,2,2025-01-04,31.4,22
...

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/api/v1/historicalforecast/Herndon,VA/byrun/2025-01-01/2025-01-02?unitGroup=us&include=days&key=YOUR_API_KEY&contentType=csv&elements=name,rundatetime,forecastday,datetime,tempmax,tempmin

Each group of rows shares the same rundatetime, which represents when the forecast was issued.

  • rundatetime – The date the forecast was generated
  • forecastday – The lead time (0 = same day, 1 = next day, etc.)
  • datetime – The actual date being forecast

How to interpret this

  • The forecast run on 2025-01-01 includes predictions for January 1 through January 6
  • The forecast run on 2025-01-02 includes updated predictions for January 2 through January 7

This means the same calendar date (for example, January 3) can appear multiple times—once for each forecast run that predicted it.

Example

  • January 3 was forecast as:
    • 41.8°F when predicted on January 1 (2 days ahead)
    • 41.3°F when predicted on January 2 (1 day ahead)

Key idea

Each forecast run represents the full set of expectations available at that point in time.
This allows you to reconstruct exactly what was known on any given day and how expectations evolved as new forecasts were issued.

By Target (bytarget)

In bytarget mode, forecasts are grouped by the date being predicted rather than when the forecast was issued.

Each target date appears multiple times—once for each forecast run that predicted it at different lead times.

For example, consider the following data:

rundatetime,forecastday,datetime,tempmax,tempmin
2024-12-27,5,2025-01-01,47.6,40.9
2024-12-28,4,2025-01-01,50.3,36.9
2024-12-29,3,2025-01-01,48.1,37.1
2024-12-30,2,2025-01-01,48.6,36
2024-12-31,1,2025-01-01,47.7,36
...
2024-12-28,5,2025-01-02,40,29.6
2024-12-29,4,2025-01-02,42,29.7
2024-12-30,3,2025-01-02,40.4,29.2
2024-12-31,2,2025-01-02,39.1,30.8
2025-01-01,1,2025-01-02,37.7,27.2

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/api/v1/historicalforecast/Herndon,VA/bytarget/2025-01-01/2025-01-02?unitGroup=us&include=days&key=YOUR_API_KEY&contentType=csv&elements=name,rundatetime,forecastday,datetime,tempmax,tempmin

Each group of rows shares the same datetime, which represents the day being forecast.

  • rundatetime – The date the forecast was generated
  • forecastday – The lead time (how many days ahead the forecast was made)
  • datetime – The actual date being predicted

How to interpret this:

  • For January 1, forecasts were made over multiple days leading up to it
  • Each row shows what the forecast predicted for January 1 at a specific lead time
  • As the forecast gets closer to the target date, the lead time decreases and the prediction is updated

Example:

For January 1, the forecast evolved as follows:

  • 5 days ahead (Dec 27): 47.6°F
  • 4 days ahead (Dec 28): 50.3°F
  • 3 days ahead (Dec 29): 48.1°F
  • 2 days ahead (Dec 30): 48.6°F
  • 1 day ahead (Dec 31): 47.7°F

Key idea:

Each target date shows how expectations changed over time as new forecasts were issued.
This makes it possible to analyze how a specific day was predicted in advance and how those predictions evolved leading up to that date.

Base URL

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/api/v1/historicalforecast/

Endpoints

  • /historicalforecast/[location]/byrun/[rundatestart]/[rundateend]
  • /historicalforecast/[location]/bytarget/[targetdatestart]/[targetdateend]

Request Parameters

Path Parameters (required)

  • location – Address, latitude/longitude, postal code, or weather station ID
  • datestart – Start date (yyyy-MM-dd)
  • dateend – End date (yyyy-MM-dd, inclusive)

Core Query Parameters

  • key (required) – Your API key
  • unitGroup – us, metric, uk, base
  • contentType – json (default) or csv
  • include – days, hours, current, alerts
  • elements – Filter specific weather fields
  • forecastdays – Number of forecast days returned per run (default: 5)
  • forecastDataset – Specific model (e.g., gfs, hrrr, iconeu)

Options

  • nonulls – Remove null values
  • noheaders – Remove CSV headers
  • usev2forecast – Use enhanced V2 forecast data where available

Additional Parameters

All standard Timeline API parameters are supported, including:

  • lang
  • timezone
  • iconSet
  • maxStations, maxDistance, elevationDifference
  • Degree day and solar calculation parameters

See the Timeline API documentation for full details.

Additional Fields for Historical Forecasts

The Historical Forecast API introduces two additional fields that describe how each forecast was generated:

  • rundatetime – The date the forecast model was run
  • forecastday – The lead time of the forecast (how many days ahead the prediction was made)

These fields provide context about when the forecast was created and how far into the future it was predicting.

How they work together

  • forecastday = 0 → Forecast for the same day as the run
  • forecastday = 1 → Forecast made one day in advance
  • forecastday = 5 → Forecast made five days in advance

For example:

  • A record with rundatetime = 2024-12-27 and forecastday = 5 corresponds to a prediction for 2025-01-01
  • A record with rundatetime = 2024-12-31 and forecastday = 1 also corresponds to a prediction for 2025-01-01

Both rows describe forecasts for the same target date, but from different points in time.

Why this matters

These fields allow you to:

  • Track how forecasts evolve as the target date approaches
  • Compare short-range vs long-range predictions
  • Align forecasts with business decisions based on when they were made

Together, rundatetime and forecastday define the relationship between when a forecast was issued and what date it was predicting.

Example Requests

By Run (JSON)

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/api/v1/historicalforecast/Herndon,VA/byrun/2025-01-01/2025-01-15?unitGroup=us&include=days,hours&key=YOUR_API_KEY

By Target (CSV)

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/api/v1/historicalforecast/Herndon,VA/bytarget/2020-01-01/2020-01-15?contentType=csv&include=days,hours&key=YOUR_API_KEY

Using V2 Forecast Data

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/api/v1/historicalforecast/38.9697,-77.385/byrun/2025-01-01/2025-01-15?options=usev2forecast&key=YOUR_API_KEY

POST Requests

POST requests are supported for large or structured queries. Path parameters remain in the URL.

POST /rest/api/v1/historicalforecast/Herndon,VA/byrun/2025-01-01/2025-01-15
Content-Type: application/json

{
  "key": "YOUR_API_KEY",
  "unitGroup": "us",
  "include": "days,hours",
  "forecastdays": 5
}

Response Format

Responses follow the same structure as the Timeline Weather API.

  • Location metadata – coordinates, timezone, resolved address
  • days[] – daily forecast records
  • hours[] – hourly forecast records (if requested)

Each record includes standard weather elements such as temperature, precipitation, wind, pressure, and conditions.

The source field is typically "histfcst", indicating historical forecast data.

HTTP Response Codes

  • 200 – Success
  • 400 – Invalid request
  • 401 – Unauthorized (invalid key or permissions)
  • 429 – Rate limit exceeded
  • 500 – Server error

Rate Limits and concurrency

This API integrates data from multiple forecast models and is designed to operate with a single concurrent request per account. Standard plan concurrency limits do not apply to this endpoint.

If you require bulk historical forecast data, please contact support to discuss access to our upcoming bulk download capability.

Support

Use the AI Code Generator for request examples and integration help.

For support, visit Visual Crossing Support.