How to submit weather API asynchronously

By /

Some more complex weather API requests such as history summary requests can take longer times to execute. In those cases, we offer the ability to execute the requests asynchronously. In these cases, the same weather API request is made but, rather than waiting for the full request to complete and return data, the request will immediately return and present a new request URL to use to request the data.

Note that the content type of the request must be ‘JSON’ to be able to use asynchronous requests.

Steps to create and monitor asynchronous weather API requests

Step one – Indicate an asynchronous request using the ‘allowAsynch=true’ parameter.

Add allowAsynch=true to your request:

https://weather.visualcrossing.com/VisualCrossingWebServices/rest/services/weatherdata/historysummary?&allowAsynch=true&aggregateHours=24&combinationMethod=aggregate&maxStations=-1&maxDistance=-1&minYear=1990&maxYear=2020&chronoUnit=months&breakBy=self&dailySummaries=false&contentType=json&unitGroup=us&locationMode=single&key=YOUR_API_KEY&dataElements=default&locations=Binghamton%2CNY

Step two – Handle the request status

The request will return with a status indicating it’s finished with success, finished with error or still processing. Here is a sample return from the initial request:

{
"errorCode":0,
"executionTime":-1,
"sessionId":"",
"message":"",
"id":"939",
"status":2,
"info":"Retrieving history summary...0/1",
"directCallback":"https://weather1.visualcrossing.com/VisualCrossingWebServices/rest/services/jobstatus/939",
"result":null
}

The possible status values are:

QUEUED=1 - the request is waiting to execute.
EXECUTING=2 - the request is executing.
COMPLETE=3 - the request finished successfully.
ERROR=4 - the request finished with an error.
CANCELLED=5 - the request was manually cancelled.

Step three – handling executing or queued requests

If the request returns a queued or executing status (1 or 2), the response will also include a ‘directCallback’ url to request the status again. Your code should use this URL to request the latest status until the request finishes. When submitting the callback requests, you should add your API key as a parameter.

For example, in the above response your code should submit the ‘https://weather1.visualcrossing.com/VisualCrossingWebServices/rest/services/jobstatus/939?key=YOUR_API_KEY’ request to retrieve the latest status.

Note: do not call the directCallback request too often. You should wait at least one second before requesting the latest status. If the server detects status requests are being submitted too quickly the account may be limited or locked.

Step four – handling successful requests

When the request is finished, the status will change to status 3. The response will then include a last ‘directCallback’ parameter to use to request the final result data (again you should add your API Key to the call back request). The result data of that callback will be the same format as is returned by a normal synchronous request.

Step five – handling error or cancelled requests

if the result of the request is either error or cancelled (4 or 5), the last response will include more information in the ‘info’ parameter. No directCallback URL will be included in these requests.

Scroll to Top