How to query weather forecasts from the past – Historical Forecasts

Analyzing historical weather forecast data is an important facet for many weather data users beyond standard forecasts and historical observations. Historical forecasts are often more important for business analysis than traditional historical observation data because customers in many cases base their decisions on future forecast and not the actual weather on a given day. Consider an amusement park. In many cases people start planning their weekend activities earlier in the week instead of waking up on Saturday morning and deciding what to do. They do this by using forecasts. If the weekend forecast delivered on Tuesday shows a good chance of rain for the weekend, people will avoid outdoor activities. Even if the forecast changes later in the week and the actual weekend weather is sunny, those indoor activities are often committed and people are unlikely to change their plans.

This “forecast effect” influences all types of obvious activities in both the B2C and B2B space. In the consumer space, any type of travel or preplanned events can be affected. In the business space, costly decisions in construction, building trades, and agriculture must be scheduled in advance based on a forecast. In cases when the actual weather on a given day differs significantly from earlier forecasts, analyzing business results based on weather observations alone can lead to faulty conclusions.

In the past, historical forecasts were difficult to obtain. In many cases they were not available or often prohibitively expensive. Visual Crossing Weather is now able to bring you historical forecasts at a price point that makes them accessible for all types of analysis.

What is a historical forecast?

Just as the name implies, historical forecasts are weather forecasts that were given in the past as a prediction for weather on another date that is also now in the past. For example, on July 1, 2021, there was a forecast given for July 4, 2021. For a person viewing data on August 1, 2021, that forecast given on July 1 for July 4, is a historical forecast. Since that forecast given on July 1 was used by a large number of people planning their 4th of July plans, it is a very valuable data point for businesses who want to analyze their actual July 4th results. While the actual July 4th historical weather observations can be useful also to see how people reacted to the weather on that specific day, the historical forecast given a few days before shows the information which people used to make their plans.

Visual Crossing currently provides the historical forecasts based on the full forecast model runs stored at midnight UTC each day.

What types of historical forecast queries are available?

There are two types of historical forecast queries. The first type gives you a single forecast record for a specific day and location. This is useful when you know the day an activity occurred and how far ahead it was planned. For example, if you know that your customer booked their Saturday tickets on the Tuesday before, you can make a historical forecast query with Tuesday as the “basis date”, Saturday as the “target date”, and your activity location. This query will return a record that shows the exact Saturday forecast that the customer was viewing on the Tuesday before they booked their tickets. Even if the actual weather on Saturday ended up being very different than the forecast, the historical forecast data will be able to show the exact information that the customer used to make their purchase decision, not what happened later.

The second type of query is one in which you need the entire 15-day forecast for a specific location as given on a specific date. This is most useful when you know how far in advance the activity is being planned, but the activity itself is done over time. Consider a vacation or a construction project. For example, in the construction business you may allocate certain equipment every Wednesday for the following week. When you want to historically analyze the allocation of equipment to a job site you want to make a query that shows the forecast for that specific job site location as it appeared on a given Wednesday. In this case, you would set the basis date to be Wednesday and omit the target date. This would provide the 15-day forecast as the equipment planner saw it on Wednesday when he or she was making the allocation.

NOTE: The historical forecast data is as of now available starting 1st January 2020

How to retrieve historical forecast data via the Weather API

The Timeline Weather API seamlessly integrates historical forecast data into the results using the ‘basis date’ concept. When the API receives a request including a basis date, then the results will include weather forecast data created on that basis date for the days following that basis date.

The following returns the historical forecast for the 1st May 2023 for London,UK. The historical forecast uses the ‘forecastBasisDate’ parameter to instruct the API that the data from the basis date should use the weather forecast that was created on that date:,UK/2023-05-01/2023-05-15?unitGroup=us&key=YOUR_API_KEY&include=days&forecastBasisDate=2023-05-01

The ‘forecastBasisDay’ parameter is an alternative to the forecastBasisDate parameter and automatically set the forecastBasisDate relative to the start date of the query. For example, if you specify the start date as 2023-05-01 and a forecastBasisDay value of 5, then the value for 2023-05-01 will be the 5th day forecast (i.e. it will be based on the weather forecast produced five days earlier ( 2023-04-26). You can use this parameter to quickly find the forecast that was predicted for a particular day on multiple days (for example the 5, 3 and 1 day forecast). Setting the value of this to zero is the equivalent of the above request:,UK/2023-05-01/2023-05-15?unitGroup=us&key=YOUR_API_KEY&include=days&forecastBasisDay=0

Here the resolved forecast basis date will be 2023-05-01.

How to retrieve historical forecast data via the Query Builder

You can also construct and retrieve weather data queries with historical forecast data directly in the weather data query builder. To enter the historical forecast basis date, open the query options by hitting any of the ‘query options’ links at the top of the builder.

After query options dialog opens, click ‘Historical forecast’ on the left and the historical basis date option is then available.

How can I access historical forecast data?

Visual Crossing offers historical forecast data in two different ways depending upon your needs.

Historical forecast subscription

You can upgrade to a historical forecast subscription as part of any Visual Crossing Weather data plan. Whether you are analyzing a small amount of data for a team or data across an entire enterprise, Visual Crossing Weather has convenient and cost-effective plans for every use case.

You can access historical forecast data via our Timeline Weather API. Using the API, you can specify the basis date on which the forecast was generated and the target date along with the location, and our weather engine will find the matching historical forecast for you. As in the example above, you can query the forecast for July 4, 2021 that was initially given on July 1, 2021 for any location worldwide. Alternatively you can query the entire 15-day forecast as it was given for any location on any specific day.

To add Historical Forecast to your existing subscription, please visit your account page and select the Historical Forecast Addon subscription.


Historical forecast data is a powerful data source for advanced weather analysis. By using historical forecast data, you can compare business data to the forecasts that were being used by your customers or resources planners at the time they were planning their activities. In certain businesses this can be more powerful than actual weather observations, which may not accurately describe the information available earlier in the planning process. So, if your business involves activities that must be planned based on forecasts, then historical forecasts represent the best way for you to intelligently analyze your business results.

Questions or need help?

If you have a question or need help, please post on our actively monitored forum for the fastest replies. You can also contact us via our support site or drop us an email at