Weather Central DataCloud API

Taking Inventory of the Data

Inventory Requests
Because Weather data in constantly changing, the datasets are dynamic. It will be necessary in your application to make an inventory request so you now what data is available. This will consist of making two requests to the Data API.

1. Request to get an inventory of weather datatypes available via the API.
2. Request to get an inventory of weather variables available for a particular weather data type.
3. Request to get an inventory of what timestamps are available for a particular weather variable.

1. Weather Datatype Inventory Request

This request will show you which datatypes are currently available via the API. Datatypes represent key weather categories such as forecast, radar, and satellite.

Required Parameters

type

type=inventory

This specifies that this request is gathering basic information about data availability.

Example Weather Variable Inventory Request:
http://datacloud.wxc.com/?type=inventory&vs=0.9&passkey=123456789

Example Weather Variable Inventory Response:

Example Weather Variable Inventory Return Values:

Datatypes
Description Datatypes is an element that contains a list of datatype elements that are to be queried within the API.

Datatype
Description: The Datatype element contains an individual weather datatype which is available within the API. Currently there are two datatypes supported (Radar and Forecast). For more information on the details of those datatypes please see the Weather 101: Available Weather Data section

Example:

<Datatype>Forecast</Datatype>


2. Weather Variable Inventory Request

This request will show you which variables are currently in a specific datatype. Variables represent key specific weather datasets that have values such as temperature, wind speed, and cloud cover.

Required Parameters

type

type=inventory

This specifies that this request is gathering basic information about data availability.

datatype
This defines the weather datatype for which you are requesting variable information.   A list of datatypes can be found by making the weather datatype inventory request outlined above.

Using the datatype parameter will give you a list of variables that you will be able to use in your next inventory request for finding available timestamps.

Example:

datatype=forecast

 

Example Weather Variable Inventory Request:
http://datacloud.wxc.com/?type=inventory&datatype=forecast&vs=0.9&passkey=123456789

Example Weather Variable Inventory Response:

Example Weather Variable Inventory Return Values

Variables
Description: Variables is an element that contains a list of weather variables that are available for this particular weather datatype.

var
Description: The var element contains a value name of an individual weather variable. For more information on the details of variables please see the Weather 101: Available Weather Data section.

Example:

<var>Temperature</var>

usage
Description: usage is an attribute of the var element that contains what type of requests you can make on this particular variable. Some variable can only return an XML value and not a tiled PNG image. If an variable can be queried in both point and tile format, the usage value will be “Tile,Point”

Example:

usage="point"

hasruntimes
Description: hasruntimes is an attribute of the var element that contains information as to whether this particular variable was based on a weather forecast model run or not.  This has no function in the current API and can be ignored.  Values are true or false.

Example:

hasruntimes="true"

3. Weather Variable Timestamp Inventory Request

This request will show you which timestamps are available for a specific variable.

Required Parameters

type

type=inventory

This specifies that this request is gathering basic information about variable and timestamps availability.

datatype
This defines the weather datatype for which you are requesting variable information.   A list of datatypes can be found by making the weather datatype inventory request outlined above.

Using the datatype parameter will give you a list of variables that you will be able to use in your next inventory request for finding available timestamps.

Example:

datatype=forecast

var
This defines the weather variable type that you are seeking inventory information about. The value is specific to the inventory type you are working with and is found using the Weather Variable Inventory Request.

Using the inventory and var parameters together in a request will return the timestamps available for that particular variable.

Example:

var=temperature

Example Weather Variable Timestamp Inventory Request:

http://datacloud.wxc.com/?type=inventory&datatype=forecast&var=Temperature&vs=0.9&passkey=123456789

Example Weather Variable Timestamp Inventory Response:

Example Weather Variable Timestamp Inventory Return Values

Times
Description: Times is an element that contains a list of weather timestamps that are available for this particular weather variable.

time
Description: a time element contains a time value (in GMT) of an available forecast time for this particular weather variable in the format YYYY-MM-DDTHH:MM:SS.

Example:

2010-02-04T18:00:00

 

Optional PARAMETERS

time or timesteps
There are two parameters to call out the time of the data you are requesting: time, and timesteps.  Time allows you to request the data specific to the clock, for example I want the forecast for 3PM Tomorrow.  Timesteps allows you to call the data specific to the dataset and frequency, for example I want the 3rd oldest radar image regardless of what time it was.

time
Timestamp of the data you are requesting. The timestamps that are available for a particular datatype can be found using the inventory request method. There are multiple formats that you can use with this parameter:

Time Format Example #1: all

time=all

This will give you all of the time steps available for this point request.

Time Format Example #2: specific time

time=YYYY-MM-DDTHH:MM:SS
example time=2010-02-04T18:00:00

This allows you to request one individual time step in GMT.

Time Format Example #3: range of times

time=YYYY-MM-DDTHH:MM:SS,YYYY-MM-DDTHH:MM:SS
example time=2010-02-04T18:00:00,2010-02-05T06:00:00

This allows you to request a range of two time step in GMT separated by a comma.

Time Format Example #4: now

time=now

This allows you to request the closest data available to the current time.

Time Format Example #5: now with offset

time=now+HH:MM:SS
example time=now-03:00:00

This allows you to request the closest data available to the specific time in relation to the current time

Time Format Example #6: time range using now

time=now-HH:MM:SS,now
example time=now,now+36:00:00

This allows you to request the closest data available to the specific time in relation to the current time

timesteps
Timesteps is an alternative to using the time parameter.  This lets you request a specific datapoint without knowledge of time.  It is particularly useful in the tile request if you want your application to just show the last 10 images regardless of when they occurred.  There are two types of timesteps requests: one with two arguments and one with three.

Timesteps Format Example #1: 2 argument format- Specific timestep

timesteps=[timestamp or now],[frame]
example timesteps=YYYY-MM-DDTHH:MM:SS,-10
Return the timestep 10 timesteps into the past in relation to a specific time
example timesteps=now,3
Return the timestep 3 timesteps into the future in relation to a specific time.

The two argument format allows you to request a specific timestep of data.  The first argument calls out the timestamp and the 2nd calls out the specific frame of data you are looking for.

Timesteps Format Example #2: 3 argument format- Range of timesteps

timesteps=[timestamp or now],[startframe],[endframe]
example timesteps=YYYY-MM-DDTHH:MM:SS,-10,0
Return timesteps -10,-9,-8…,-2,-1,0  proceeding a specific time
example timesteps=now,36,48
Return timesteps 36, 37,..47,48 into the future from right now

The three argument format allows you to request a range of  timesteps of data.  The first argument calls out the timestamp and the 2nd calls out the start frame, and the 3rd calls out the endframe for the range of data you are requesting.

exceptions
When you issue an invalid request the dataserver will issue and HTTP Error (400) and some information as to why the error is invalid. The exceptions pararmater defines the error response you will receive when the dataserver is unable to give a valid response to your query.  There are two possible values of exceptions in the inventory request.

Text formatted exceptions - default

exceptions=txt

Along with the HTTP 400 Error you will receive a text string that defines the error condition.

Here is an example where a user is requesting a tile where no data exists

Example Request:

http://datacloud.wxc.com/?type=tile&datatype=forecast&var=Temperature&time=now&bing=2&vs=0.9&passkey=123456789&exceptions=txt

Example Response:

Can not get tile data. The render stack is empty because the request was not in bounds.

XML formatted exceptions

exceptions=xml

Along with the HTTP 400 Error you will receive an xml response that defines the error condition.

Here is an example where a user is requesting a tile where no data exists

Example Request:

http://datacloud.wxc.com/?type=tile&datatype=forecast&var=Temperature&time=now&bing=2&vs=0.9&passkey=123456789&exceptions=xml

Example Response:

<!DOCTYPE ServiceExceptionReport>
<ServiceExceptionReport version="1.3.0">
<ServiceException>
Can not get tile data. The render stack is empty because the request was not in bounds.
</ServiceException>
</ServiceExceptionReport>