The Tile Request

Tile Requests
Now that we have obtained some basic information on what data is available to access via the inventory request methods, we can start bringing data into our application. This section will cover queries which will generate PNG image responses.

Required Parameters

type

type=tile

This specifies that this request is asking for a PNG tile response

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.

Examples:

datatype=forecast

var
Weather variable name of the data you are requesting. This can be found using the weather variable inventory request method.

Examples:

var=Temperature
var=WindSpeed

time
Timestamp of the data you are requesting. This can be found using the weather variable timestep inventory request method.


Return Tile Format
Additionally you must select a return tile format. There are two projection types that the Data API will output.

Bing Map Tile
Returns Bing 256x256 tile

Custom Tile
Returns a specific navigation of tile based on request.

Bing Map Tile Required Parameters

bing
his is the Bing Quad Key value. For more information on Bing Quad key maps see this reference:
http://msdn.microsoft.com/en-us/library/bb259689.aspx

Examples:

bing=0320
bing=02131013

http://datacloud.wxc.com/?type=tile&datatype=forecast&var=Temperature&time=2010-01-18T19:00:00&bing=03200&vs=1.0&passkey=123456789

http://betadataserver.wxc.com/?type=tile&datatype=forecast&var=Temperature&time=2010-01-18T19:00:00&bing=03200&vs=0.9&passkey=123456789

Example Bing Map Tile Response:


Additionally you are encouraged to explore the Bing Map AJAX VEMap.AddTileLayer Method. Using this method you are able to automatically insert the Weather Central Data API into a Bing Maps javascript application using the VETileSourceSpecification Class. For javascript 6.3, simply use the parameter bing=%4 inside of your Bing javascript which uses this functionality.  For javascript 7.0, use the parameter bing={quad}.

To use this simply use the parameter bing=%4 inside of your Bing javascript which uses this functionality.

Example VETileSourceSpecification line for javascript: 6.3

var tileSourceSpec = new VETileSourceSpecification(“Temperature”, “http://betadataserver.wxc.com/?type=tile&datatype=forecast&var=Temperature&time=2010-01-08T19:00:00&bing=%4&vs=1.0&passkey=123456789);

Example VETileSourceSpecification line for javascript: 7.0

ar tileSourceSpec = new VETileSourceSpecification(“Temperature”, “http://betadataserver.wxc.com/?type=tile&datatype=forecast&var=Temperature&time=2010-01-08T19:00:00&bing={quad}&vs=1.0&passkey=123456789);

Custom Map Tile Required Parameters

latupper
This is the Northern Boundary of your tile in latitude degrees.

Example:

latupper=40.5

latlower
This is the Southern Boundary of your tile in latitude degrees.

Example:

latlower=25.5

loncenter
This is the center of your tile in longitude degrees.

Example:

loncenter=-105.5

width
This is the width in pixels of your output image.

Example:

width=500

height
This is the width in pixels of your output image.

Example:

height=300



Custom Map Tile Optional Parameters

pro
This is the projection type of the output image

Current Supported Types:

pro=merc – Mercator Projection (default)
pro=pmerc – Psuedo-Mercator Projection


Example Custom Map Tile Request:

http://datacloud.wxc.com/?type=tile&datatype=forecast&latupper=40&latlower=25&loncenter=-105&height=300&width=500&var=Temperature&time=2010-01-08T19:00:00&vs=0.9&passkey=123456789

Example Custom Map Tile Response:


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.  With tiles you cannot request a range, only a specific time or timestep.

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: now

time=now

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

Time Format Example #4: 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

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.  With a tile request there is one type of timesteps requests with two arguments

Timesteps Format Example: 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.

Tile Request Optional Parameters (bing or custom)

mask
(default = 0)
Setting the mask parameter to 1 will mask out the water

Example Water Mask tile request:

http://datacloud.wxc.com/?type=tile&datatype=forecast&latupper=40&latlower=25&loncenter=-105&height=300&width=500&mask=1&var=Temperature&time=2010-01-08T19:00:00&vs=0.9&passkey=123456789

Example Water Mask tile response:

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 four 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=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>

Blank formatted exceptions- tile only

exceptions=blank

Along with the HTTP 400 Error you will receive a blank image.  This is only applicable to if you are using type=tile and have a valid bing or height/width in your request.

Example Request:

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

InImage formatted exceptions- tile only

exceptions=inimage

Along with the HTTP 400 Error you will receive an image that contains the error code as well as the request used to generate the tile.  This is only applicable to if you are using type=tile and have a valid bing or height/width in your request.

Example Request:

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