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.

Common Use Case – Getting the “yesterday” or “tomorrow” forecast for a date range

One common use case is to obtain the historical forecast a specific numbers of days earlier for every date in a given window. For example, you might want to get the forecast from “yesterday” for every day of a given month. Assuming that your given month is January, then this dataset would be the forecast for January 1 and it appeared on December 31 of the prior year, the forecast for January 2 as it appeared on January 1, the forecast for January 3 as it appeared on January 2, and so on. Another variation of this use case applies to business that know approximately when their customers are making plans. For example, you may operate a golf course and know that certain customers tend to plan about three days in advance when scheduling their tee time. In this case, you want to consider the forecast as it appeared “three day ago” for each day instead of the “yesterday” forecast since the forecast from “three days ago” is what people were using when making their plans. However, the mechanics are the same.

In order to query this data over a range of dates, you will need to make a separate query for each date in your range. Simply create a loop in your code or script and inside that loop run a query like this (assuming that your target location in London):,UK/TARGET_DATE?unitGroup=us&key=YOUR_API_KEY&include=days&forecastBasisDay=1

Note the TARGET_DATE placeholder. That is where you put the target date for your query, and you will increment that date for each date in your range. Setting the forecastBasisDay to 1 tells the query that you would like the forecast as it appeared one day before the TARGET_DATE date.

By way of our previous example, let says that you wanted to get the forecast as it appeared “yesterday” for every day in January 2024. The first query in your loop would be for the target date January 1, 2024, so our query would look like this (again, assuming London):,UK/2024-01-01?unitGroup=us&key=YOUR_API_KEY&include=days&forecastBasisDay=1

That gives us the forecast for January 1, 2024 as it appeared one day earlier on December 31, 2023. We would continue our loop by incrementing the date to 2024-01-02 and letting the forecastBasisDay remain 1. That would make our second query this:,UK/2024-01-02?unitGroup=us&key=YOUR_API_KEY&include=days&forecastBasisDay=1

This query provides the forecast for January 2 as it appeared one day earlier on January 1. To get the entire month or even the entire year, you would continue to loop through all of the days of interest. Each iteration of the loop would increment the date by one day.

It is useful to note that this exact same loop would work for the golf course case described above. That is, one simple change would allow you to query the forecast from three days earlier instead of just one. Simply change the forecastBasisDay parameter in the queries above from 1 to 3, and your result will be the forecast from three days earlier instead of one.

One additional, useful observation to make is that this “forecast from yesterday” loop solution is exactly the same solution as that required for the “forecast for tomorrow” problem. The only difference is how you look at the dates in your query range. If you want to think about querying the “forecast for tomorrow,” simply use the same loop described above but start your dates one date later. In our example, you would start your first TARGET_DATE to be 2024-01-02. You would store the result of the query as the record for January 1, 2024 since it would contain the forecast for January 2 as it appeared on January 1. The loop is otherwise identical; the primary difference is how you wish to store the data. In the “forecast from yesterday” case, the record that you store for January 1 is the forecast for January 1 as it appeared on December 31 of the prior year. In the “forecast for tomorrow” case, the record that you store for January 1 is the forecast for January 2 as it was given on January 1. The only difference is in how you like to think about your dates.

How can I access historical forecast data?

In order to query Historical Forecast data, you will need an Historical Forecast subscription.

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