The Point Request

Point Requests
This section will cover how to use the dataserver API to obtain geo-referenced weather data via xml response. This will allow you to obtain text weather information specific to your latitude and longitude.

Required Parameters for a point request

type

type=point

This specifies that this request is asking for a XML response.

format
This parameter determines the XML response format. There are six currently supported format types by the Weather Central Dataserver API:

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 in the inventory request section.

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
Weather variable name of the data you are requesting. This can be found using the inventory request method.

Examples:

var=Temperature
var=WindSpeed

Multiple Variables can be request by using a comma as a separator.

Example:

var=Temperature,AccumRain,Windspeed

Additionally within the forecast, currents, and alerts datasets there is a summary variable that contains a collection of variables.

Example:

var=Summary

lat/lon
These parameters specify the latitude and longitude of your data request and are in decimal format. West and South are defined as negative.

Example:

lat=35.3424&lon=-95.35332

You can also request multiple datapoint by using the comma as a separator.

Example of a data request for 3 locations:

lat=35.3424,36.4336,45.1&lon=-95.35332,-98.3,-102.2

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.




Optional Parameters for a point request

offset

(default offset=0:00:00)

Offset hours from GMT time that you would like the data response to come back in. This enables you to get the data returned in your local time. This should be in HH:MM:SS format.

Example:

offset=-6:00:00

This would be the United States CDT timezone.

units

(default=English)

This provides a way to easily convert and round the data to common units such as English and Metric. The currently supported options are:

units=english
units=metric
units=metric_alt1
units=raw

Note:  This is currently not supported in the currents and alerts datatypes.

For more information on units please see the Weather 101: Unit Explanations section.

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.  With point requests there are two possible values.

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>