The Tile Request
Tile RequestsNow 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
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}.
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:
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:
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:
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:
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:
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