This document provides basic instructions on accessing weather content in the format of images via WDT’s SkyWise Tiling (SWARM) API service. The service uses HTTPS access and currently consists of two types of requests:

• Valid Frames Requests

  • This type of request is used to find out what valid times are available for any of the supported product layers. In order to use the Tiles, a valid frames request must be used, as the URL for obtaining tiles contains the frame time.

• Tile Requests

  • Products may be requested as Google-compatible tiles using a Google standard tile coordinate (x, y, z) or as Bing-compatible tiles using quadkeys. Individual and composite tile product layers are supported, and this service benefits from the use of caching services via Akamai, thereby improving responsiveness. Tiles are 256 x 256 pixels in size.

The remaining sections of this document provide the mechanics and examples for each type of request as well as a list of currently available layers. Variables within a URL that need to have actual values substituted are enclosed in “ <>” characters for clarity.

Valid Frames Requests

Authentication

Requests must use Headers for authentication. The provided application ID will be entered as the value for the app_id header, and the application key will be entered as the value for the app_key header. Up to five passwords may be in use at any time. This allows old passwords to be disabled without any downtime.

General

These requests are used to determine exact valid times available for one or more products. The request returns a list of comma separated values (CSV) times. For a single product, the form is:

https://skywisetiles.wdtinc.com/swarmweb/valid_frames?product=<PRODUCT>

This will return a single line of CSV times in YYYY-MM-DDTHH:MM:SS format.

To get valid times for multiple products in a single request use plural “products” for the keyword instead of singular “product” and specify a list of products separated by commas:

https://skywisetiles.wdtinc.com/swarmweb/valid_frames?products=<PRODUCT1,PRODUCT2,...>

In this mode, the system will return the product name followed by a list of its valid times, followed by the next product name and valid times, etc. The product names will not necessarily be returned in the same order specified.

Optional Keywords

The following optional keywords can be added to a valid frames request:

1. withtz. Set to “True” (“withtz=True”) to have the returned list of times have the “Z” appended to each time string. Default value is “False”.
2. format. Set to “json” (“format=json”) to return a JSON dictionary object instead of CSV data.

Tile Requests

Single Layer Tile Requests

Tiles are provided as images with transparency applied to appropriate sections of the imagery and returned as a Google or Bing compatible tile in the web spherical Mercator map projection. The general form of a tile request is:

• Google Compatible:
  

  https://skywisetiles.wdtinc.com/swarmweb/tile/<PRODUCT>/<FRAME_TIME>/<Z>/<X>/<Y>.<IMG_TYPE>
  

• Bing Compatible:
  

  https://skywisetiles.wdtinc.com/swarmweb/qtile/PRODUCT>/<FRAME_TIME>/<QUAD_KEY>.<IMG_TYPE>
  

Note the “tile” vs. “qtile” portion of the path between the Google and Bing format URLs.

The variables are defined as follows:

1. PRODUCT. The name of the desired product layer (see list provided below)
2. FRAME_TIME. The desired valid time (UTC time zone) for the layer being requested. The time must match one of the values returned via a Valid Frames Request. Format of time request is YYYY-MM-DDThh:mm:ss, specified in UTC, with no time zone appended. For example: 2011-02-28T13:55:00. This is the same format that is returned by a valid frames request.
3. 1. Z. Google zoom level. Only used when requesting Google-compatible tiles.
4. 1. X. Google tile x-coordinate. Only used when requesting Google-compatible tiles.
5. 1. Y. Google tile y-coordinate. Only used when requesting Google-compatible tiles.
6. QUAD_KEY. Bing quadkey for specifying zoom and location when requesting Bing-compatible tiles.
7. IMG_TYPE. Use either “png” for Portable Network Graphics format (recommended) or “gif” for Graphics Interchange Format.

There are some optional parameters that may be specified at the end of the URL using the typical syntax of having a ”?” at the end of the main request followed by a list of key/value statements separated by the “&” symbol as follows:

<REQUEST>?OPTION=VALUE[&OPTION2=VALUE,..]

The following options are supported for single-image tiles:

1. STYLE. Some product layers have multiple styles available. This argument can be used to apply a particular style (e.g., color scales, etc.) instead of a default style. These are pre-defined by WDT on an as-needed basis and will be provided if/when necessary.
2. PMASK. By default, radar tiles are color coded by precipitation type (rain in shades of green, mixed in shades of pink, and snow in shades of gray/blue). Standard reflectivity with no precipitation typing applied can be requested by adding “PMASK=False” to the end of the query string.

Composite Tiles

Composite tiles (tiles containing multiple image layers) can now be requested. The form of the request is different from single layer tiles in that there must be a CSV list of layers and a corresponding CSV list of valid times for each layer provided as keywords at the end of the URL rather than as part of the path. The format for this type of request is:

• Google Compatible:
  

  https://skywisetiles.wdtinc.com/swarmweb/comptile/<Z>/<X>/<Y>.<IMG_TYPE>?LAYERS=<LLIST>&TIMES=<TLIST>[&STYLES=<SLIST>]
  

• Bing Compatible:
  

  https://skywisetiles.wdtinc.com/swarmweb/qcomptile/<QUAD_KEY>.<IMG_TYPE>?LAYERS=<LLIST>&TIMES=<TLIST>[&STYLES=<SLIST>]
  

The Z, Y, X, QUAD_KEY, and IMG_TYPE parameters are the same as for the single layer tiles. The following variables are different for composite tiles:

1. LLIST. This is a comma-separated list of product layers. They are specified from bottom to top in terms of image stacking order. So, for example, if you specify “irstatellite,compradarcontours” then the composite radar image will be “on top” of the IR satellite layer.
2. 2. TLIST: This is a comma-separated list of valid times. There MUST be an entry for each product in LLIST, and each product’s entry must be valid (i.e., the exact time requested must exist in a valid frames request for the requested product). Format is the same as for FRAME_TIME in the single-layer tile request and the same format returned by a valid frames request.
3. 3. SLIST. A list of styles specified in the optional STYLES keyword. The STYLES keyword is optional, but if specified must have the same number of entries as the LLIST and TLIST parameters. For any product using the default style, simply leave the entry blank. For example, if you have four products in LLIST, and you want ‘mystyle’ applied to the second product in the list and ‘yourstyle’ applied to the fourth product and the default style for all others, you would use ‘STYLES=,mystyle,,yourstyle’.

Response Status Codes

Product List

North American lowest-altitude radar reflectivity polygons/contours U.S, Canada, Guam, Hawaii, Alaska, Puerto Rico) ) *Requires the following attribution : ‘Canadian radar information provided by Environment Canada and WDT”

• Layer name: nalowaltradarcontours
• Update Period: 5 minutes

Global infrared satellite grid

• Layer name: globalirgrid
• Update Period: 30 minutes

Tropical storm past tracks

• Layer name: troppasttrack
• Update Period: 10 Minutes

Tropical storm current position icons

• Layer name: tropcurpos
• Update Period: 10 Minutes

Tropical storm forecast tracks

• Layer name: tropfcsttrack
• Update Period: 10 Minutes

Tropical storm forecast error fans

• Layer name: tropfcstfan
• Update Period: 10 Minutes

Tropical storm spaghetti models

• Layer name: tropmodels
• Update Period: 10 Minutes

Investigation area markers

• Layer name: tropinvest
• Update Period: 10 Minutes

All active watches and warnings

• Layer name: watchwarn
• Update Period: 2 minutes

Significant active watches and warnings

• Layer name: sigww
• Update Period: 2 minutes

U.S. surface temperature polygons/contours (derived from STMAS)

• Layer name: sfctempcontours
• Update Period: 30 minutes

U.S. surface dewpoint polygons/contours (derived from STMAS)

• Layer name: sfcdwptcontours
• Update Period: 30 minutes

U.S. surface relative humidity polygons/contours (derived from STMAS)

• Layer name: sfcrhcontours
• Update Period: 30 minutes

U.S. surface windspeed polygons/contours (derived from STMAS)

• Layer name: sfcwspdcontours
• Update Period: 30 minutes

U.S. echo top heights (numerical point data)

• Layer name: echotops
• Update Period: 5 minutes

U.S. hail markers

• Layer name: hail
• Update Period: 5 minutes

U.S. mesocyclone markers

• Layer name: meso
• Update Period: 5 minutes

U.S. storm motion svectors

• Layer name: stormvectors
• Update Period: 5 minutes

U.S. tornado vortex signature markers

• Layer name: tvs
• Update Period: 5 minutes