Table of Contents
Introduction
The Stored Dataset APIs are a set of RESTful APIs designed to make it easy to view, modify, and execute stored datasets created using the Visual Crossing Weather Query Builder.
These APIs enable automation of tasks that involve large datasets—particularly those that are best executed through the Query Builder infrastructure—without requiring manual intervention.
A common use case for the Stored Dataset APIs is updating the locations in an existing dataset, such as changing the set of shipping destinations.
Beta Availability
The Stored Dataset APIs are currently in beta testing and open for feedback. During this testing phase, the parameters, response format, and response structure may change. For more information, please contact support.
Licensing requirements
The Stored Dataset APIs are currently available to users with Corporate-level subscriptions or higher. For details on available plans, please visit our Pricing page.
API Key and Secret
The Stored Dataset APIs require both an API key and an API secret. The API key is the same one used for the Timeline Weather API. The secret provides an additional layer of authentication to ensure that changes cannot be made to stored datasets without it—even if the API key is known.
To view or modify your API key or to create a new API secret, visit your account page.
Stored Dataset API Endpoints
Retrieve Stored Dataset Info
Retrieves metadata about a particular dataset, including its name, description, and execution status. This endpoint allows API users to poll the dataset to determine whether it is ready for download.
Example request
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/retrievestoreddatasetinfo?key=YOUR_API_KEY&taskId=b96efe450aa91095c4c863174ddd6&includeLocations=false
Example response
{
"id": "b96efe450aa91095c4c863174ddd6",
"name": "UK Locations Daily Forecast - CSV",
"description": "Forecast for UK locations each day",
"enabled": true,
"runOnce": false,
"hasSchedule": false,
"result": {
"status": 3,
"contentType": null,
"completed": 3,
"total": 3,
"successful": 3,
"failed": 0,
"info": "Completed",
"dateTime": "2025-04-04T20:27:09Z",
"endDatetime": "2025-04-04T16:28:27Z",
"expirationDateTime": "2025-04-11T23:28:26Z"
}
}
- id – unique id for the dataset.
- name – name of the of data set.
- description – description of the data set.
- enabled – is the data set enabled.
- runOnce – true if the data set execution has been requested.
- hasSchedule – true if the data set has a scheduled execution time.
- status – status of the dataset execution:
- 0 – data set execution requested
- 1-2 – data set executing
- 3 – data set ready
- 4 – data set execution failed
- 5 – data set expired.
- contentType – content type of the result data (CSV, JSON, Excel etc.)
- completed – number of locations that have been completed
- total – total number of locations in the data set.
- successful – number of locations in the data set that completed successfully.
- failed – number of locations in the data set that failed.
- info – text message about the execution. May include additional details about which locations failed and why.
- dateTime – latest date time that the data set definition was updated.
- endDateTime – latest time the dataset finished execution.
- expirationDateTime – the date time when the current dataset will expire.
Retrieve Stored Dataset
Downloads the dataset. The dataset definition includes the content type (CSV, JSON, Excel) and unit group settings. For CSV output, the file can be returned either as a plain CSV stream or as a ZIP archive. Other formats with multiple locations typically require a ZIP archive.
Example request
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/retrievestoreddataset?key=YOUR_API_KEY&taskId=b96efe450aa91095c4c863174ddd6&zip=false
Update Stored Dataset Locations
Changes the list of locations associated with the dataset. In addition, optionally sets location-by-location date ranges to allow different data ranges for each location.
To set up a dataset to retrieve data for changing locations, first set up a dataset within the Weather Query Builder for one location, ensuring that the exact data options are configured such as which weather elements should be included and which dataset (days, hours, current etc.) is chosen correctly in the export configuration.
The following request updates the locations for data set with id ‘b96efe450aa91095c4c863174ddd6’ with the four new locations given by the list “Hamburg,DE”,”London,UK”,”Hereford,UK”,”Herndon,VA”
Example request
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/updatestoreddatasetlocations?key=YOUR_API_KEY&secret=YOUR_SECRET&taskId=b96efe450aa91095c4c863174ddd6&locations=%22Hamburg%2CDE%22%2C%22London%2CUK%22%2C%22Hereford%2CUK%22%2C%22Herndon%2CVA%22
Update Stored Dataset Locations with dates and times
In addition to passing in a simple list of locations, it is possible to update the locations with names, start dates and end dates. In this, case each location can have a different date range. Datasets with multiple columns may be included in the locations parameter. Possible column names include name, location, latitude, longitude, startdate and enddate.
In the following example, individual start and end dates are applied to an existing stored dataset that retrieves daily weather data. Each location will have a unique start and end date.
"Location","StartDate","EndDate"
"Hamburg,DE","2024-01-01","2024-01-02"
"London,UK","2024-02-02","2024-02-03"
"Hereford,UK","2024-03-03","2024-03-04"
"Herndon,VA","2024-04-04","2024-04-05"
Retrieving weather data a long the route of a moving vehicle
In this second example, we have modelled a moving delivery vehicle travelling between Madrid, Spain and Paris, France. The vehicle sets off at 8am and we record the latitude,longitude location each hour after based on the expected route and time of arrival at each point. The dataset for this will return exact time data using the ‘current’ dataset view (for more information, see the API Documentation).
"Location","StartDate"
"40.4168,-3.7038","2025-05-23T08:00:00"
"41.6716,-3.6890","2025-05-23T09:00:00"
"42.3439,-3.6969","2025-05-23T10:00:00"
"42.8591,-2.6819","2025-05-23T11:00:00"
"43.4832,-1.5586","2025-05-23T12:00:00"
"43.7102,-1.0530","2025-05-23T13:00:00"
"44.8378,-0.5792","2025-05-23T14:00:00"
"45.0000,0.0000","2025-05-23T15:00:00"
"46.5802,0.3404","2025-05-23T16:00:00"
"47.3941,0.6848","2025-05-23T17:00:00"
"47.9029,1.9093","2025-05-23T18:00:00"
"48.8566,2.3522","2025-05-23T19:00:00"
"48.8566,2.3522","2025-05-23T20:00:00"
Example request
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/updatestoreddatasetlocations?key=YOUR_API_KEY&secret=YOUR_SECRET&taskId=b96efe450aa91095c4c863174ddd6&locations=%22Hamburg%2CDE%22%2C%22London%2CUK%22%2C%22Hereford%2CUK%22%2C%22Herndon%2CVA%22
Refresh Stored Dataset
Triggers a refresh of the dataset. This sets the runOnce property to true, prompting a new execution. You can monitor progress using the retrievestoreddatasetinfo endpoint.
Example request
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/refreshstoreddataset?key=YOUR_API_KEY&secret=YOUR_API_SECRET&taskId=b96efe450aa91095c4c863174ddd6