Programming Guide - WeatherSentry® Web Mapping Service

Version 12

    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.telventdtn.com/digest/wms_v{X} where {X} is the major revision number. (e.g. http://weather-services.telventdtn.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.

     

    Back to top

     

    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:

    http://weather-services.telventdtn.com/digest/wms_v1/wms.wsgi?REQUEST=GetCapabilities

    and log in with your Schneider Electric WMS Account.

     

    Back to top

     

    Building a Map Request

     

    Build a map request by using the basic WMS URL

     

    For HTTP Basic: https://weather-services.telventdtn.com/basic/wms_v1/wms.wsgi?

    For HTTP Digest: http://weather-services.telventdtn.com/digest/wms_v1/wms.wsgi?

    For OAuth 1.0a: http://weather-services.telventdtn.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.

     

    ParameterDescriptionRequired/OptionalValid ValuesDefault Value
    SERVICE=WMSThe name of the service. In this case, Web Map Service.RequiredWMS
    REQUEST=GetMapThe type of request.RequiredGetMap
    VERSION=versionThe version of the requested service.Optional1.3.01.3.0
    FORMAT=output_formatImage file format of the map.RequiredPNG, GIF
    WIDTH=output_widthWidth in pixels of resulting map.RequiredA valid whole number expressed in pixels.
    HEIGHT=output_heightHeight in pixels of resulting map.RequiredA valid whole number expressed in pixels.
    LAYERS=layer_listComma-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.RequiredIndividually listed in the capabilities file.
    CRS=EPSG:id_codeCoordinate Reference System (CRS)RequiredEPSG:4326, EPSG:3857, EPSG:900913

    BBOX=minx,miny,

    maxx,maxy

    Bounding box corners (lower left, upper right) in SRS units.RequiredFour comma-delimited numeric values.
    TRANSPARENT=valueMap’s background transparency.OptionalTRUE, FALSETRUE for PNG images; otherwise FALSE
    BGCOLOR=color_valueHexadecimal value for the map’s background color.OptionalA hexadecimal value, e.g. 0xFFFFFF is white.0xFFFFFF
    TIME=valueTime value of layer desired.OptionalSingle 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_listComma-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.OptionalXMLXML

    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.

     

    http://weather-services.telventdtn.com/digest/wms_v1/wms.wsgi?SERVICE=WMS&VERSION=1.3.0&REQUEST=GetMap&BBOX=-90.000000,-180.000000,90.000000,180.000000&CRS=EPSG:4326&WIDTH=1371
    &HEIGHT=687&LAYERS=TEMPERATURE_F_CURRENT&STYLES=&FORMAT=image/png&DPI=96&TRANSPARENT=TRUE

     

    WMS_Developer_1.png

    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.telventdtn.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.telventdtn.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.

     

    ParameterDescriptionRequired/ Optional Valid Values Default Value
    map request parametersA 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.RequiredSee Table 3, above.

    REQUEST=GetFeatureInfo

    The type of request.RequiredGetFeatureInfo

    QUERY_LAYERS=layer_list

    Comma-separated list of the layers to be queried.RequiredMust be one or more of the layers specified in the LAYERS parameter.
    For WMS version 1.3.0:
    I=pixel_columnThe 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.RequiredA valid whole number expressed in pixels. Must be between 0 and the width of the original map image.
    J=pixel_rowThe 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.RequiredA 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.Requiredtext/html, text/xml

    FEATURE_COUNT=number

    The maximum number of features per layer to return.OptionalA positive integer ≥ 1.1
    TIME=valueTime value of layer desired.OptionalSingle 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.OptionalXMLXML

    Table 2: GetFeatureInfo Request Parameters

     

    Using the map request from Figure 1 as an example, start with the original GetMap request:

    http://weather-services.telventdtn.com/digest/wms_v1/wms.wsgi?
    SERVICE=WMS&VERSION=1.3.0&REQUEST=GetMap&BBOX=-90.000000,-180.000000,90.000000,180.000000&CRS=EPSG:4326&WIDTH=1371
    &HEIGHT=687&LAYERS=TEMPERATURE_F_CURRENT&STYLES=&FORMAT=image/png&DPI=96&TRANSPARENT=TRUE

     

    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:

    http://weather.telventdtn.com/digest/wms_v1/wms.wsgi?
    SERVICE=WMS&VERSION=1.3.0&REQUEST=GetFeatureInfo&BBOX=-90.000000,-180.000000,90.000000,180.000000&CRS=EPSG:4326&WIDTH=1371
    &HEIGHT=687&LAYERS=TEMPERATURE_F_CURRENT&STYLES=&FORMAT=image/png&QUERY_LAYERS=TEMPERATURE_F_CURRENT&INFO_FORMAT=text/html&I=283&J=147

     

    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

     

    Back to top

    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.telventdtn.com/legends/temperature_c.png"/>

    WMS_Developer_2.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.

     

    WMS_Developer_4.gif

    Figure 4: Sample animation from a GetAnimationFile request

     

     

    ParameterDescriptionRequired/Optional Valid Values Default Value
    REQUEST=GetAnimationFileField to indicated that an animation is to be displayedRequiredGetAnimationFile
    VERSION=1.3.0WMS version.Required1.3.0
    STYLES=style_listStyles for each layer to be displayedRequiredComma-separated list of one style per layer requested.

    LAYERS=

    layer_list

    Comma-separated list of the layers to be queried.RequiredMust be one or more of the layers specified in the LAYERS parameter.
    CRS=namespace:identifierCoordinate reference system map typeRequiredA valid map specification
    BBOX=minY,minX,maxY,maxXBounding box cornersRequiredCRS Units.

    FORMAT=

    output_format

    The format of the returned query, listed as a MIME type.Requiredimage/gif
    WIDTH=numberwidth of animation in pixelsRequiredA positive integer
    HEIGHT=numberHeight of animation in pixels.RequiredA positive integer
    FRAMEDELAY=numbernumber of 1/100'ths of a second of the delay between each frame.Requiredpositive integer between 1 and 6000
    ANIMATION_FILE_STYLES=style_listStyles 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_TOPLEFT
    TIME_TOPCENTER
    TIME_TOPRIGHT
    TIME_CENTERLEFT
    TIME_CENTERRIGHT
    TIME_BOTTOMLEFT
    TIME_BOTTOMCENTER
    TIME_BOTTOMRIGHT
    TIME_FORMAT_12HR
    TIME_FORMAT_24HR
    TIME_NONE

    TIME_TOPRIGHT
    TIME_FORMAT_24HR
    TIME= beginDate/endDate/periodStart/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.OptionalXMLXML

    Table 3: GetAnimationFile Request Parameters

     

    The following is a sample GetAnimationFile request:

    http://weather-services.telventdtn.com/basic/wms_v1/wms.wsgi?
    VERSION=1.3.0&SERVICE=WMS&REQUEST=GetAnimationFile&WIDTH=800&HEIGHT=400&LAYERS=RADAR_US_CURRENT&BBOX=20.0,-130.0,50.0,-60.0&CRS=EPSG:4326
    &FORMAT=image/gif&TRANSPARENT=true&DPI=96&FRAMEDELAY=10&STYLES=&EXCEPTIONS=XML

     

    The following is a sample GetAnimationFile request for timestamps in a non-default location:

    http://weather-services.telventdtn.com/basic/wms_v1/wms.wsgi?
    VERSION=1.3.0&SERVICE=WMS&REQUEST=GetAnimationFile&WIDTH=800&HEIGHT=400&LAYERS=RADAR_US_CURRENT&BBOX=20.0,-130.0,50.0,-60.0&CRS=EPSG:4326
    &FORMAT=image/gif&TRANSPARENT=true&DPI=96&FRAMEDELAY=10&STYLES=&ANIMATION_FILE_STYLES=TIME_TOPLEFT,TIME_FORMAT_12HR&EXCEPTIONS=XML

     

    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:

    http://weather-services.telventdtn.com/basic/wms_v1/wms.wsgi?
    VERSION=1.3.0&SERVICE=WMS&REQUEST=GetAnimationFile&WIDTH=800&HEIGHT=400&LAYERS=RADAR_US_CURRENT&BBOX=20.0,-130.0,50.0,-60.0&CRS=EPSG:4326
    &FORMAT=image/gif&TRANSPARENT=true&TIME=2014-09-16T01%3A35%3A01%2B00%3A00-05:00/2014-09-16T04%3A35%3A01%2B00%3A00-05:00&DPI=96&FRAMEDELAY=10&STYLES=&ANIMATION_FILE_STYLES=&EXCEPTIONS=XML

     

    Exceptions and Errors

    When a request experiences errors, an error message will indicate what happened according to the format of the Exceptions type.

     

    Back to top