The Timeline Weather API permits a single location for each API request. In some situations, it is convenient to submit multiple locations in the same request rather than as separate API calls. This article describes how to use the Multiple Timeline Weather API endpoint to request weather data for multiple locations in the same call.
The Multiple Location Timeline Weather API is currently in beta testing. If you have any comments or questions please contact support.
When should the Timeline Multiple Weather API be used?
The Multiple Location Timeline Weather API is designed for situations where it is difficult to request data for multiple locations in separate API requests but where the resulting, combined dataset is still small. Common examples we see of this are loading data directly into tools such as Microsoft Excel, Power BI or Google Sheets.
Please note that Multiple Location Timeline Weather API requests are limited to single concurrency. It is not designed for loading large datasets into databases or other large data set retrieval. In these cases, we recommend using scheduled queries or multiple, single location, Timeline Weather API requests.
Multiple Location Timeline Weather API Request Format
The Multiple Location Timeline API request follows the same format and parameters as the regular Timeline Weather API however the location list, start date and end date values are passed as query parameters rather than as a part of the URL path query.
The simplest form of the API query to request the weather forecast for multiple locations is therefore:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timelinemulti?key=YOUR_API_KEY&locations=[List Of Locations]
This simple form will return the daily weather forecast for the next seven days for each location. With the datestart and include parameters missing, they default to ‘next7days’ and ‘days’ respectfully. Therefore the above API query is equivalent to:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timelinemulti?key=YOUR_API_KEY&locations=[List Of Locations]&datestart=next7days&include=days
To request historical data, you can provide the optional datestart and dateend parameters.
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timelinemulti?key=YOUR_API_KEY&locations=[List Of Locations]&datestart=[date1]&dateend=[date2]
These parameters work in exactly the same way as the standard Timeline Weather API. You can supply dates in the form ‘yyyy-MM-dd’, for example 2023-06-01 for June 1st 2023. You can also supply dynamic date values to create date ranges that will automatically adjust to the current date.
How to supply the location parameter
The location parameter is a list of locations separated by the pipe (‘|’) character. The locations can be addresses, partial addresses (such as city, state, country) or decimal longitude and latitude values. It is always necessary to URL encode the values before transmission. For example consider the list of four cities:
London,UK
Paris,France
Tokyo, Japan,
Cape Town, South Africa
First the list must be combined with the ‘|’ character:
London,UK|Paris,France|Tokyo,Japan|Cape Town, South Africa
And then it must be encoded for transmission:
London%2CUK%7CParis%2CFrance%7CTokyo%2CJapan%7CCape%20Town%2C%20South%20Africa
We can then use these in the locations parameter:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timelinemulti?key=YOUR_API_KEY&locations=London%2CUK%7CParis%2CFrance%7CTokyo%2CJapan%7CCape%20Town%2C%20South%20Africa
The optional ‘locationNames’ parameter allows you to use a different name for the locations in the results. For example if you have customer names or want to return a shorter city name than that used for looking up the location:
https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/timelinemulti?key=YOUR_API_KEY&locations=London%2CUK%7CParis%2CFrance%7CTokyo%2CJapan%7CCape%20Town%2C%20South%20Africa&locationNames=London%7CParis%7CTokyo%7CCape%20Town
The API supports submitting the request parameters as GET and POST. If the location list is long, you may need to submit the request as a POST request to prevent experiencing problems with URL length limits.
Specifying other Timeline Weather API parameters
The remaining Timeline Weather API parameters are fully supported and will be supplied to each location returned in the Multiple Timeline Weather API request. Please see the Timeline Weather API documentation for more information.
Result format
The Multiple Timeline Weather API supports JSON and CSV output format. When the result is requested in JSON format, the result includes an array of standard Timeline API JSON requests. For example the above request for four locations results in a JSON structure with a ‘locations’ array. Each element of that array contains the full Timeline API JSON result.
When the CSV result format is request, the results are returned in a single CSV formatted dataset with each location listed merged together with the others. The set is sorted by the location and then the date time values. Each location within the CSV is formatted in the same way as the standard Timeline Weather API CSV dataset.
Query costs and limits
Query costs and limits are enforced in the same way as the Timeline API. The costs for each location is summed together to create the cost for the overall multiple location query. Therefore a request for the forecast for four locations will result in a total query cost of four. The request for a seven day, daily history will result in a query cost of four locations multiplied by seven and so a cost of 28.
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.