What exactly is a weather record?

A weather record is the smallest unit of weather data that is used in the Visual Crossing Weather accounting process for our plans. Whether you have unlimited data access or are limited to 1000 records per day as a member of our Free plan, it is useful to understand the accounting behind weather records

What is a forecast record?

A full 15-day forecast for one location counts as a single record. This is true even for an hourly forecast. If you query the forecast for additional locations, each location will count as an additional record. This means that you can get a forecast for 1000 different locations or for the same location 1000 times per day every day without any cost ever on our Free plan.

What is a history record?

One weather history record is defined as a single row of history data. A single row of history data contains the weather data for a single location at a single time period. That time period is typically either a day, an hour, or a sub-hourly record. An example of a one-record query is a daily report of the weather conditions on Friday, 1/11/2022 in Herndon, VA. If you query multiple days, each day would be a single record. If you instead query hourly data, each hour in each requested day at a given location would be one record. Thus, a full day of hourly data at a single location would be counted as 24 records. If a query makes that same hourly request for two location, the number of result records doubles to 48.

Frequently asked questions

If I reduce the number of weather elements in my query, does it count as fewer records?


Advanced users can benefit from the reduced transfer bandwidth, faster performance, and easier parsing obtained by requesting only a limited number of weather elements in your result dataset. For example, if you only are analyzing temperature and precipitation, there is no need to request cloud cover, humidity and our other weather elements in your result. You can limit the elements returned and thereby receive a much smaller and simpler result set to process. However, even if your result row contains only a single weather element for a given location and time, that row counts as a single record.

I need a single hour’s data for a given day. Can I request only that hour at the cost of a single record?


In the Timeline API you can request the information for a specific time on a single date by including time into the date1 query field using the format yyyy-MM-ddTHH:mm:ss. For example 2022-01-19T13:00:00. The results are returned in the ‘currentConditions’ field and count as only a single record. To learn more about this technique, please read our API Documentation.

If I request only a subset of a forecast instead of all 15 days, does that change the record accounting?


Forecasts count as a single record up to the full 15 days. Any subset of a 15-day forecast also counts as a single record as one record is the smallest accounting increment.

How are statistical weather records counted?

They are counted in the same way as weather history records.

You can use the statistical forecast feature to request typical weather conditions for any day of the year. When you do so, each row of result data is counted as one record. For example, the daily statistical forecast for a single location on January 1 counts as one record. Making the same request for January 1-3 counts as three records since your query will return three rows.

When counting records, does it matter if I request the output in CSV, JSON, or Excel format?


The accounting for weather records is identical no matter what output format you request.

Can you give me some help in determining the number of records my query will return?

Of course.

If you are using our web-based query UI, the Query Builder will show you the exact number of records generated by your query before you request to download the data.

If you want to calculate the record cost manually for any type of query, you can use our Data Cost Calculator. Simply enter the parameters of your query, and it will calculate the exact query cost. As an added benefit, the Cost Calculator will recommend the appropriate service plan based on the result size of your query.

The Timeline Weather API JSON responses include a ‘queryCost’ property indicating the result record cost of the query. For more information, please see ‘What is the queryCost parameter?

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 support@visualcrossing.com.