Taking Inventory of the Data

Inventory Requests
Because Weather data is 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.  Here is a list of various inventory requests that are detailed below:

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
4. Request to get an inventory of stations for Airport, Almanac, Buoy, Climatology, or Tide data
5. Request to get an inventory of available Airport, Almanac, Buoy, Climatology, or Tide variables
6. Request to get an inventory of available timestamps for Airport, Almanac, Buoy, Climatology, or Tide variables

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=1.0&passkey=123456789

Example Weather Variable Inventory Response

Weather Datatype Inventory Request

Example Weather Variable Inventory Return Values

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

Datatype
The Datatype element contains an individual weather datatype which is available within the API. Currently there are eight datatypes supported (Forecast, Radar, Satellite, Current, Alerts, Climatology, AQI, and AQIFcst). For more information on the details of these datatypes, please see the pages listed under the Weather 101 heading on the sidebar.

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=1.0&passkey=123456789

Example Weather Variable Inventory Response:

Weather Variable Inventory Request

EXAMPLE WEATHER VARIABLE INVENTORY RETURN VALUES

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

var
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
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
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=1.0&passkey=123456789

Example Weather Variable Timestamp Inventory Response

Weather Variable Timestamp Inventory Request

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=1.0&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=1.0&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>

4.  Station Listings for: Airport, Almanac, Buoy, Climatology, or Tide Data

This request will show you all observation sites for Airport, Almanac, Buoy, Climatology, or Tide data.

REQUIRED PARAMETERS

type

type=stations

This specifies that this request is gathering information about which stations are available.

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.

Example:

datatype=airport
datatype=almanac
datatype=buoy
datatype=climatology
datatype=tide

Example Airport Station Listing Request

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=airport&type=stations&time=all

Example Almanac Station Listing Request

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=almanac&type=stations&time=all

Example Buoy Station Listing Request

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=buoy&type=stations&time=all

Example Climatology Station Listing Inventory Request:

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=climatology&type=stations&time=all

Example Tide Station Listing Request

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=tide&type=stations&time=all

5.  Variable Inventory Request for: Airport, Almanac, Buoy, Climatology, or Tide Data

This request will show you available variables for Airport, Almanac, Buoy, Climatology, or Tide data.

REQUIRED PARAMETERS

type

type=vars

This specifies that this request is gathering information about available variables.

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.

Example:

datatype=airport
datatype=almanac
datatype=buoy
datatype=climatology
datatype=tide

Example Airport Variable Inventory Request:

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=airport&type=vars

Example Almanac Variable Inventory Request:

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=almanac&type=vars

Example Buoy Variable Inventory Request:

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=buoy&type=vars

Example Climatology Variable Inventory Request:

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=climatology&type=vars

Example Tide Variable Inventory Request:

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=tide&type=vars

 

6.  Timestamp Inventory Request for: Airport, Almanac, Buoy, Climatology, or Tide Data

This request will show you the timestamps available for Airport, Almanac, Buoy, Climatology, and Tide data.

REQUIRED PARAMETERS

type

type=times

This specifies that this request is gathering information about the timestamps available.

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.

Airport Example:

datatype=airport

Example Airport Timestamp Inventory Request:

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=airport&type=times

Returns the single most recent timestamp, since Airport data is for the current time only (updated every 15 minutes). 

Almanac Example:

datatype=almanac

Example Almanac Timestamp Inventory Request:

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=almanac&type=times

Returns the months and year of the most recent NCDC Almanac update. 

Buoy Example:

datatype=buoy

Example Buoy Timestamp Inventory Request:

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=buoy&type=times

Returns the single most recent timestamp, since Buoy data is observational data.

Climatology Example:

datatype=climatology

Example Climatology Timestamp Inventory Request:

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=climatology&type=times

Returns the 7 most recent timestamps.

Tide Example:

datatype=tide

Example Tide Timestamp Inventory Request:

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=tide&type=times

Returns all available timestamps for today and tomorrow.


OPTIONAL PARAMETERS

station
This defines the observation station that you are seeking timestamp inventory information about. 
Using the times and station parameters together in a request will return the timestamps available for that particular observation station.

Example using 4-letter Airport ID:

type=times
datatype=airport
station=kmsp

Example Airport Timestamp Inventory Request:

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=airport&type=times&station=kmsp

Example using 4-letter Almanac station ID:

type=times
datatype=almanac
station=kbos

Example Almanac Timestamp Inventory Request:

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=almanac&type=times&station=kbos

Example using 5-digit alpha-numeric Buoy station ID:

type=times
datatype=buoy
station=BSLM2

Example Buoy Timestamp Inventory Request:

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=buoy&type=times&station=BSLM2

Example using 4-letter Climatology station ID:

type=times
datatype=climatology
station=kbos

Example Climatology Timestamp Inventory Request:

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=climatology&type=times&station=kbos

Example using 7-digit Tide station ID:

type=times
datatype=tide
station=8538231

Example Tide Timestamp Inventory Request:

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=tide&type=times&station=8538231

time
This allows you to request all available timestamps for the Climatology datatype.   

Example:

time=all

http://datacloud.wxc.com/?vs=1.0&passkey=123456789&datatype=climatology&type=times&time=all