Stored Dataset API Documentation

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. 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

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
Scroll to Top