Overview
WeatherSentry® Web Mapping Service (WMS) is a version 1.3.0 OGC WMS. WMS has three primary methods:
- GetCapabilities: Returns the entire catalog of available data and requests. For each GetMap request (layer) it provides descriptive information in the Title and Abstract. Your GetCapabilities only has the GetMap requests for the package you’ve purchased.
- GetMap: Returns PNG or GIF image for the layer or layers you’ve requested.
- GetFeatureInfo: Returns attribute information for the layer or layers associated with the pixel you’ve requested. This is how NWS bulletin text is displayed. You can request the attribute information in HTML or XML.
Release Management
As we add features and enhancements, new revisions will become available. If the change causes a reverse compatibility issue, we will release it under a new major revision. An example of this would be a layer name change or removal.
Major revisions are part of the url. e.g. http://weather-services.dtn.com/digest/wms_v{X} where {X} is the major revision number. (e.g. http://weather-services.dtn.com/digest/wms_v1) Only the two latest major revisions are supported at any given time. Therefore, when we release a major revision, we will remove the link to the oldest major revision, which we will no longer support.
For example: If version 1 and 2 currently exist, at the release of version 3 we will remove all the links to version 1 and will no longer support that version.
Authentication
Using our WMS requires an account. If you don’t have an account, contact Sales toll-free at (800) 610-0777 and +34 91 714-7002 outside of North America.
Currently HTTP Basic over SSL, HTTP Digest, and OAuth 1.0a are supported. Other authentication protocols will be coming in subsequent releases. One of these will be a Secure Token Service(STS).
Accessing the Capabilities Document
Once you have a login to the service you can make a request for GetCapabilities.
The GetCapabilities request provides an XML catalog file of all the layers and information available through the service – including layer specific data availability information (e.g., the TIME parameter).
Visit the GetCapabilities link at:
https://weather-services.dtn.com/digest/wms_v1/wms.wsgi?REQUEST=GetCapabilities
and log in with your DTN WMS Account.
Building a Map Request
Build a map request by using the basic WMS URL
For HTTP Basic: https://weather-services.dtn.com/basic/wms_v1/wms.wsgi?
For HTTP Digest: https://weather-services.dtn.com/digest/wms_v1/wms.wsgi?
For OAuth 1.0a: https://weather-services.dtn.com/oauth/wms_v1/wms.wsgi?
followed by valid parameter/value pairs separated by an ampersand (&).
Note: The STYLES= parameter is used for the copyright and logo placement. You can choose 8 different positions for the logo which allows you to prevent images colliding on the final map you are producing.
| Parameter | Description | Required/Optional | Valid Values | Default Value |
|---|---|---|---|---|
| SERVICE=WMS | The name of the service. In this case, Web Map Service. | Required | WMS | |
| REQUEST=GetMap | The type of request. | Required | GetMap | |
| VERSION=version | The version of the requested service. | Optional | 1.3.0 | 1.3.0 |
| FORMAT=output_format | Image file format of the map. | Required | PNG, GIF | |
| WIDTH=output_width | Width in pixels of resulting map. | Required | A valid whole number expressed in pixels. | |
| HEIGHT=output_height | Height in pixels of resulting map. | Required | A valid whole number expressed in pixels. | |
| LAYERS=layer_list | Comma-separated list of layers to be mapped. The order they are listed in determines drawing order: first in the list = bottom-most layer; last in the list = top-most layer. | Required | Individually listed in the capabilities file. | |
| CRS=EPSG:id_code | Coordinate Reference System (CRS) | Required | EPSG:4326, EPSG:3857, EPSG:900913 | |
| BBOX=minx,miny,
maxx,maxy |
Bounding box corners (lower left, upper right) in SRS units. | Required | Four comma-delimited numeric values. | |
| TRANSPARENT=value | Map’s background transparency. | Optional | TRUE, FALSE | TRUE for PNG images; otherwise FALSE |
| BGCOLOR=color_value | Hexadecimal value for the map’s background color. | Optional | A hexadecimal value, e.g. 0xFFFFFF is white. | 0xFFFFFF |
| TIME=value | Time value of layer desired. | Optional | Single value (ccyy-mm-ddThh:mm:ssZ), a list of values (ccyy-mm-ddThh:mm:ssZ,ccyy-mm-ddThh:mm:ssZ), or an interval (ccyy-mm-ddThh:mm:ssZ/ccyy-mm-ddThh:mm:ssZ). | Layer specific. |
| STYLES=style_list | Comma-separated list of styles. Named styles are not supported, so use “STYLES=” for all map requests. | Required | ||
| EXCEPTIONS=
exception_format |
The format in which exceptions are reported. | Optional | XML | XML |
Table 1: GetMap Request Parameters
As an example, the following map request will generate the map in Figure 1. The resulting map displays the Temperature Layer in Fahrenheit at the requested bounding box and resolution which will determine the points thinning.
Figure 1: Example GetMap request image
All layers have unique names. You can find map layer names by accessing the capabilities files inGetCapabilities. The name of the map layer is defined between the Name tag, which is within the Layer tag explained in (Figure 2).
<Layer queryable=”1″>
<Name>TEMPERATURE_F_CURRENT</Name>
<Title>Temperatures – Fahrenheit</Title>
<Abstract>Temperatures in Fahrenheit</Abstract>
<CRS>EPSG:4326</CRS>
<EX_GeographicBoundingBox>
<westBoundLongitude>-180.0</westBoundLongitude>
<eastBoundLongitude>180.0</eastBoundLongitude>
<southBoundLatitude>-90.0</southBoundLatitude>
<northBoundLatitude>90.0</northBoundLatitude>
</EX_GeographicBoundingBox>
<BoundingBox CRS=”EPSG:4326″ maxx=”-90.0″ maxy=”180.0″ minx=”-90.0″ miny=”-180.0″/>
<Style>
<Name>legend</Name>
<Title>legend</Title>
–
<LegendURL>
<Format>image/png</Format>
<OnlineResource xlink:href=”http://weather-services.dtn.com/legends/temperature_f.png“/>
</LegendURL>
</Style>
</Layer>
<Layer queryable=”1″>
<Name>TEMPERATURE_C_CURRENT</Name>
<Title>Temperatures – Celcius</Title>
<Abstract>Temperatures in Celcius</Abstract>
<CRS>EPSG:4326</CRS>
<EX_GeographicBoundingBox>
<westBoundLongitude>-180.0</westBoundLongitude>
<eastBoundLongitude>180.0</eastBoundLongitude>
<southBoundLatitude>-90.0</southBoundLatitude>
<northBoundLatitude>90.0</northBoundLatitude>
</EX_GeographicBoundingBox>
<BoundingBox CRS=”EPSG:4326″ maxx=”-90.0″ maxy=”180.0″ minx=”-90.0″ miny=”-180.0″/>
<Style>
<Name>legend</Name>
<Title>legend</Title>
–
<LegendURL>
<Format>image/png</Format>
<OnlineResource xlink:href=”http://weather-services.dtn.com/legends/temperature_c.png“/>
</LegendURL>
</Style>
</Layer>
Figure 2: A portion of the GetCapabilities XML describing a couple of temperature layers.
Note: The layer name “TEMPERATURE_F_CURRENT” between the Name tags and the title, “Temperatures – Fahrenheit,” between the Title tags. Also highlighted in bold is the URL for the legend graphic (see the section below for details on the GetLegendGraphic request).
Getting Feature Information
You can get information about features displayed in map layers by using the GetFeatureInfo request. A GetFeatureInfo request is much like the GetMap request, but with several additional parameters to specify the point on the map to be queried, which layers to query, and how the output should be displayed.
To build a feature information request, start by using the original map request URL, replace the REQUEST parameter with “REQUEST=GetFeatureInfo” and then add the particular GetFeatureInfo paramer/value pairs (separated by “&”) as indicated in Table 2.
Before building the GetFeatureInfo request, you can check that the layer that interests you can be queried by going to the capabilities file and verifying that queryable=”1″ in the layer definition.
| Parameter | Description | Required/Optional | Valid Values | Default Value |
|---|---|---|---|---|
| map request parameters | A partial copy of the Map request parameters that generated the map to be queried. The following parameters from the GetMap request are required:VERSION, CRS or SRS, BBOX, WIDTH, HEIGHT, and LAYERS. | Required | See Table 3, above. | |
| REQUEST=GetFeatureInfo | The type of request. | Required | GetFeatureInfo | |
| QUERY_LAYERS=layer_list | Comma-separated list of the layers to be queried. | Required | Must be one or more of the layers specified in the LAYERS parameter. | |
| For WMS version 1.3.0: | ||||
| I=pixel_column | The horizontal coordinate of the point for which feature information is being requested. The horizontal dimension is measured as the width of the image returned from the map request, in pixels. I=0 is the coordinate for the left-most pixel, and increases to the right. | Required | A valid whole number expressed in pixels. Must be between 0 and the width of the original map image. | |
| J=pixel_row | The vertical coordinate of the point for which feature information is being requested. The vertical dimension is measured as the height of the image returned from the map request, in pixels. J=0 is the coordinate for the top-most pixel, and increases downward. | Required | A valid whole number expressed in pixels. Must be between 0 and the height of the original map image. | |
| INFO_FORMAT=output_format | The format of the returned query, listed as a MIME type. | Required | text/html, text/xml | |
| FEATURE_COUNT=number | The maximum number of features per layer to return. | Optional | A positive integer ≥ 1. | 1 |
| TIME=value | Time value of layer desired. | Optional | Single value (ccyy-mm-ddThh:mm:ssZ), a list of values (ccyy-mm-ddThh:mm:ssZ,ccyy-mm-ddThh:mm:ssZ), or an interval (ccyy-mm-ddThh:mm:ssZ/ccyy-mm-ddThh:mm:ssZ). | Layer specific. |
| EXCEPTIONS=exception_format | The format in which exceptions are reported. | Optional | XML | XML |
Table 2: GetFeatureInfo Request Parameters
Using the map request from Figure 1 as an example, start with the original GetMap request:
To get information about the area in the extend of the layer:
- replace “REQUEST=GetMap” with “REQUEST=GetFeatureInfo”
- add the parameter to query just the specific layer(s) (“QUERY_LAYERS=TEMPERATURE_F_CURRENT”)
- specify the parameter to return the results as html by adding (“INFO_FORMAT=text/html”)
- add the I and J coordinate for a point of interest (“I=283” and “J=147”)
The resulting GetFeatureInfo request would be:
and the result, in HTML (Figure 3), provide the Station Name, Station ID, Valid Time, and Temperature.
<!DOCTYPE HTML PUBLIC “-//W3C//DTD HTML 4.01 Transitional//EN” “http://www.w3.org/TR/html4/transitional.dtd“>
<html>
<head>
<!– enforce the client to display result html as UTF-8 encoding –>
<meta http-equiv=”content-type” content=”text/html; charset=UTF-8″></meta>
<title>GetFeatureInfo Response</title>
</head>
<body>
<table>
<caption>Surface Temperature</caption>
<tbody>
<th>Station Name</th>
<th>Station ID</th>
<th>Valid Time</th>
<th>Temperature</th>
<tr>
<td>MOOSE JAW</td>
<td>CYMJ</td>
<td>2012-10-10 21:00:00 UTC</td>
<td style=”text-align: right”>42 F</td>
</tr>
</tbody>
</table>
</body>
</html>
Figure 3: Output from the GetFeatureInfo Request
Getting the Legend Graphic
The URL for the legend graphic is available in the GetCapabilities file between the OnlineResource tag, which is within the LegendURL tag (Figure 2).
From the GetCapabilities response you can find the online resource link to legend of the layer. In this example it is the TEMPERATURE_C_CURRENT layer.
<OnlineResource xlink:href=”http://weather-services.dtn.com/legends/temperature_c.png“/>
Getting a Radar Animation File
You are able to create an animation of radar images using the GetAnimationFile request. You can build an animation request using the parameters in the table below. An example request is also included.
Note: The standard and recommended way of building an animation image is using multiple getMap requests.
Figure 4: Sample animation from a GetAnimationFile request
| Parameter | Description | Required/Optional | Valid Values | Default Value |
|---|---|---|---|---|
| REQUEST=GetAnimationFile | Field to indicated that an animation is to be displayed | Required | GetAnimationFile | |
| VERSION=1.3.0 | WMS version. | Required | 1.3.0 | |
| STYLES=style_list | Styles for each layer to be displayed | Required | Comma-separated list of one style per layer requested. | |
| LAYERS=
layer_list |
Comma-separated list of the layers to be queried. | Required | Must be one or more of the layers specified in the LAYERS parameter. | |
| CRS=namespace:identifier | Coordinate reference system map type | Required | A valid map specification | |
| BBOX=minY,minX,maxY,maxX | Bounding box corners | Required | CRS Units. | |
| FORMAT=
output_format |
The format of the returned query, listed as a MIME type. | Required | image/gif | |
| WIDTH=number | width of animation in pixels | Required | A positive integer | |
| HEIGHT=number | Height of animation in pixels. | Required | A positive integer | |
| FRAMEDELAY=number | number of 1/100’ths of a second of the delay between each frame. | Required | positive integer between 1 and 6000 | |
| ANIMATION_FILE_STYLES=style_list | Styles specifically for the animation file. currently relates to timestamp location and format. | Optional | Comma-separated list of one or more animation related styles.
Current list of valid values: |
TIME_TOPRIGHT TIME_FORMAT_24HR |
| TIME= beginDate/endDate/period | Start/End times of request as well as the period between the frames. | Optional | Start/End Times are in yyyy-mm-ddThh:mm:ssZ format.
Period is in PTnHnMnS format. |
The animation defaults to the last ninety minutes with five minutes between frames. It isn’t necessary to give all specifications on the period, for five minutes “PT5M” will suffice. If no time zone offset is given, UTC is used. |
| EXCEPTIONS=
exception_format |
The format in which exceptions are reported. | Optional | XML | XML |
Table 3: GetAnimationFile Request Parameters
The following is a sample GetAnimationFile request:
The following is a sample GetAnimationFile request for timestamps in a non-default location:
Note: To request local time, specify the TIME parameter including the UTC offset. UTC offset considerations are also required for Daylight Savings Time/Standard Time.
The following is a sample GetAnimationFile request for timestamps in the requester’s local time:
Exceptions and Errors
When a request experiences errors, an error message will indicate what happened according to the format of the Exceptions type.