Enhanced Forecast - Marine - Image TileServer

Overview

The Marine - Image Tile Server API features a set of tile-based products utilizing marine forecast data from the Global Forecast System (GFS) forecast model produced by the National Centers for Environmental Prediction (NCEP). It provides the ability to request tiles of varying resolution up to the data’s nativere resolution of ¼ degree (~27.5 km). The API provides a total of 7 days worth of data, delivering 3-hour windows across a span of 7 days with a new set of forecasts generated every 6 hours (00z, 06z, 12z, 18z). The Image Tile Server product provides access to mapping layers pre-rendered with appropriate palettes, ready to be applied to your base map. Layers are served as precut 256x256 png image files for interactive maps and other data visualization, addressed according to a XYZ tile address schema.

The process of identifying available layer data and corresponding layer tiles requires a 3-step process.

1. Get Inventory Series List which returns the valid timeslice and metadata for each tile layer.
2. Use the appropriate valid timeslice (ts & fts) as input to the timeslice parameters, and base map tile address as input into the XYZ parameter of the layer tile request.
3. Get specified Layer Tiles using the data from the Inventory Series response as input into the ‘ts’ and ‘fts’ parameters.

HTTP Headers and Data Lifetime - Caching and Expiration

For details on appropriate header values as well as caching and expiration definitions, see The Weather Company Data | API Common Usage Guide.

Update Frequency

In the Inventory Series each available layer includes a time slice (ts); The time slice (ts) is an Epoch formatted time stamp. This timestamp is used as input into the atomic layer api request for the available layers (with the given timestamp). Each layer timestamp is updated on a frequency dependent on the layer type (Marine). A new Inventory Series request should be made at correlating intervals to the Layer type used in the client application.

For example: if the client application is using Marine layers, then the Inventory Series API should be made in at least 30 minute intervals.

URL Construction

Atomic API URL Examples:

Inventory Series List: Required Parameters: apiKey Optional Parameters:cb, filter

https://api.weather.com/v3/TileServer/series/productSet/marine?apiKey=yourApiKey

https://api.weather.com/v3/TileServer/series/productSet/marine?apiKey=yourApiKey

Optional cb parameter can be added (optional) if a jsonp callback is required. Get Inventory Series List with optional cb parameter:

https://api.weather.com/v3/TileServer/series/productSet/marine?cb=padding_wrapper&apiKey=yourApiKey

Optional filter parameter can be added (optional) to filter results on a specific product:

https://api.weather.com/v3/TileServer/series/productSet/marine?filter=primaryWaveDirection&apiKey=yourApiKey

Forecast Layer: Required Parameters: ts, fts, X:Y:Z, apiKey

https://api.weather.com/v3/TileServer/tile/<layer_name>?ts=<ts>&fts=<fts>&xyz=<X:Y:Z>&apiKey=yourApiKey

https://api.weather.com/v3/TileServer/tile/significantHeightofSwellWaves?ts=1428948600&fts=1428949000&xyz=0:0:1&apiKey=yourApiKey

NOTE: Products make use of a land/sea mask to exclude data over bodies of land.

Retrieving Tiles:

Request a 256x256 image tile or UTFGrid for a given layer. The XYZ parameters must be integer coordinates describing the tile position according to the XYZ tiling scheme. Once the client has parsed the series list and determined what layer they wish to display, they then need to request the appropriate tiles for their base map viewport. If the viewport contains tile addresses outside of this window, no call is needed as the tile will be empty. Clients will use the data returned in the Inventory Series response as input into the layer tile request via a series of calls, providing the layer, timestamp, and the X:Y:Z tile address.

JSON Sample - The Series List:

The Image Tile Server API will serve a series list, in Json / Jsonp, which will describe the layers that are available, the time slices which are currently available, the native zoom for the layer, the maximum zoom for the layer, and a bounding box confining the layer. The Series list will contain entries for each layer such as:

{
"seriesInfo": {
"marineWindspeed": {
"nativeZoom": 5,
"maxZoom": 13,
"bb": {
"tl": {
"lat": "-180.0",
"lng": "90.0"
},
"br": {
"lat": "179.959936523",
"lng": "-90.00000762939453"
}
},
"series": [
{
"ts": 1458304200,
"fts": [
1458329400,1458328500,1458327600,1458326700,1458325800,1458324900,1458324000,1458323100,1458322200,1458321300,1458320400,1458319500,1458318600,1458317700,1458316800,14583159
00,1458315000,1458314100,1458313200,1458312300,1458311400,1458310500,1458309600,1458308700,1458307800,1458306900,1458306000,1458305100]
},
{
"ts": 1458303300,
"fts": [] (fts Series data collapsed for presentation only)
}
]
},
"marineWindDirection": {}, (Layer & Series data collapsed for presentation only)
“significantHeightofCombinedWindWavesAndSwell”: {},
“significantHeightofCombinedWindWavesAndSwell”: {} (Additional layers omitted for presentation only)
}
}

Address Tile Scheme

Converting between QuadKey and XYZ:

The subsequent tile layer requires a tile address in the XYZ scheme. The XYZ parameters must be integer coordinates describing the tile position according to the XYZ tiling scheme.

The tile address format is determined by the underlying base map that a client chooses to use. For example:

• Google uses XYZ scheme

• Mapbox uses XYZ scheme

• Bing uses the QuadKey scheme

The Bing Base Map tile address requires conversion from QuadKey to the XYZ scheme; see linked reference: - Bing Maps Reference - https://msdn.microsoft.com/en-us/library/bb259689.aspx.

Example code to convert the QuadKey tile address to XYZ scheme

object QuadKey {
  def getQuadKey(x:Int, y:Int, level:Int):String = {
    val quadKey = new StringBuilder()
    (level to 1 by -1).foreach( zoomLevel => {
      val mask = 1 << (zoomLevel-1)
      quadKey.append(appendValue( (x & mask) != 0, (y & mask) != 0) )
    })
    quadKey.toString()
  }
  def appendValue(xMask:Boolean, yMask:Boolean):Int = (xMask,yMask) match {
    case (true, true) => 3
    case (_, true)    => 2
    case (true, _)    => 1
    case _            => 0
  }

  def getXYZoom(quadKey:String):XYZ =
 {
    var x = 0
    var y = 0
    var zoom = quadKey.length

    (zoom to 1 by -1).foreach(i => {
      val mask = 1 << (i - 1)
      val cell = quadKey.charAt(zoom - i).toInt
      if ((cell & 1) != 0)
      {
        x = x + mask
      }
      if ((cell & 2) != 0)
      {
        y = y + mask
      }
    })
    XYZ(x, y, zoom)
  }}

object QuadKey {

def getQuadKey(x:Int, y:Int, level:Int):String = {

val quadKey = new StringBuilder()

(level to 1 by -1).foreach( zoomLevel => {

val mask = 1 << (zoomLevel-1)

quadKey.append(appendValue( (x & mask) != 0, (y & mask) != 0) )

})

quadKey.toString()

}

def appendValue(xMask:Boolean, yMask:Boolean):Int = (xMask,yMask) match {

case (true, true) => 3

case (_, true) => 2

case (true, _) => 1

case _ => 0

}

def getXYZoom(quadKey:String):XYZ =

{

var x = 0

var y = 0

var zoom = quadKey.length

(zoom to 1 by -1).foreach(i => {

val mask = 1 << (i - 1)

val cell = quadKey.charAt(zoom - i).toInt

if ((cell & 1) != 0)

{

x = x + mask

}

if ((cell & 2) != 0)

{

y = y + mask

}

})

XYZ(x, y, zoom)

}}

Base Map Implementation: Google

Using the Google API, a custom weather layer is done by extending the ImageMapType. The Google API will make a number of calls to the ImageMapType.getTile() when the layer is displayed. The getTile() function takes the tileCoord: Point, and a zoom: Int variable, which create the XYZ parameter needed in the Tile request url.

Weather Imagery Layers: Color Palette Legends

Please use SSDS Catalog for additional information on palettes.

significantHeightofCombinedWindWavesAndSwell : Forecast Layer - Significant height of combined wind waves and swell

significantHeightofSwellWaves : Forecast Layer - Significant height of primary swell waves

significantHeightofWindWaves : Forecast Layer - Significant height of primary wind waves at surface

primaryWaveDirection : Forecast Layer - Primary wave direction at surface

directionofSwellWaves : Forecast Layer - Primary swell direction

directionofWindWaves : Forecast Layer - Primary wind waves direction at surface

marineWindDirection : Forecast Layer - Ten-meter wind direction

primaryWavePeriod : Forecast Layer - Primary wave mean period at surface

periodofSwellWaves : Forecast Layer - Primary swell mean period at surface

periodofWindWaves : Forecast Layer - Primary wind waves mean period at surface

marineWindspeed : Forecast Layer - Ten-meter wind speed at specified height level above ground