Terrain Server

STK Terrain Server Public REST API

The STK Terrain Server is a solution for creating and hosting Terrain Tilesets. The STK Terrain Server uses a REST web service API for discovering Terrain Tilesets available on the server and requesting individual tiles from a given Tileset. Here, we document the REST API for use by clients to stream terrain tiles to their application.

The public REST API sits behind a URL versioning scheme, with v1 being the current API version. If breaking changes are introduced into the REST API, a new API version will be introduced to ensure that applications developed against earlier versions of the API will continue to operate as designed.

The workflow for client-side streaming of a Terrain Tileset is to first request the tileset’s layer.json before requesting individual tiles. The layer.json contains the necessary metadata to describe a given Tileset. Once the layer.json is obtained, the client can request individual tiles that are available on the STK Terrain Server instance.

Public API

/v1/tilesets
/v1/tilesets/{tileset_name}/tiles/layer.json
/v1/tilesets/{tileset_name}/tiles/{z}/{x}/{y}.terrain?v={version}

[GET] /v1/tilesets

Returns the list of tilesets available on the STK Terrain Server instance.

Available Responses

Response Code Content-type
200 - Ok application/json

Response Description

Property Description
name A name describing the Terrain Tileset.
description A text description of the Tileset.
dataSources A list of input Data Sources that were incorporated into this Terrain Tileset.
dataSources.name A name describing the Data Source.
dataSources.description A text description of the Data Source.
dataSources.attribution The attribution string that credits the source of the raw input data.
dataSources._rev Revision number that is incremented each time this Data Source is modified.

Example

Request the Terrain Tilesets defined on the STK Terrain Server running on localhost. http://localhost/stk-terrain/v1/tilesets
{ name: "World", description: "Global tileset with high resolution terrain defined around Yosemite National Park", dataSources: [ { name: "NED - Yosemite", description: "National Elevation Dataset 1/3 arc second data for a small area near Yosemite National Park.", attribution: "Data available from the National Elevation Dataset", _rev: 3 }, { name: "GMTED2010", description: "Global Multi-resolution Terrain Elevation Data, 2010 7.5 arc second", attribution: "Data available from the U.S. Geological Survey", _rev: 3 } ], _rev: 3 }

[GET] /v1/tilesets/{tileset_name}/tiles/layer.json

Returns the metadata file that describes the tileset on the STK Terrain Server instance. The format returned is an extension of the tile.json spec, an open format used to represent metadata about map layers.

Parameters

tileset_name Name of the Terrain Tileset

Available Responses

Response Code Content-type
200 - Ok application/json
404 - Not Found text/html

Response Description

Property Description
tilejson A semver.org style version number. Describes the version of the TileJSON spec implemented by this JSON object.
name Optional. Default: null. A name describing the tileset. The name can contain any legal character. Implementations SHOULD NOT interpret the name as HTML
description Optional. Default: null. A text description of the Tileset. The description can contain any legal character. Implementations SHOULD NOT interpret the name as HTML
version A smver.org style version number. When changes across tiles are introduced , the minor version will be increased. Implementors can decide to clean their cache when the minor version changes.
format Describes the data structure used for Terrain Tile geometry.
attribution Optional. Default: null. Contains an attribution to be displayed when the map is shown to a user.
scheme Either "xyz" or "tms". Influences the y direction of the tile coordinates. For the Terrain Server, this is always "tms".
extensions Optional. Default: null. A list of extension data available for each Terrain Tile in this Tileset. These extensions are documented in the Quantized-Mesh format document.
tiles An array of tile endpoints. {z}, {x}, and {y}, if present, are replaced with the corresponding integers. If multiple endpoints are specified, clients may use any combination of endpoints. All endpoints MUST return the same content for the same URL. The array MUST contain at least one endpoint.
minzoom Optional. Default 0. An integer specifying the minimum zoom level.
maxzoom Optional. Default: 22. An integer specifying the maximum zoom level. MUST be >= minzoom
bounds Optional. Default: [-180, -90, 180, 90]. The maximum extent of available map tiles. Bounds MUST define an area covered by all zoom levels. The bounds are represented in WGS84 latitude and longitude values, in the order left, bottom, right, top. Values may be integers or floating point numbers. The Terrain Server will at a minimum generate terrain tiles for levels 0 through 4; in the absence of input elevations, the EGM96 15-minute Geoid is used to fill the remainder of the globe with sea level offsets from the WGS84 ellipsoid. For that reason, bounds will always specify the full WGS84 extents, [-180, -90, 180, 90].
projection The coordinate system of the height data defined in the Terrain Tiles. For the Terrain Server, this is always EPSG:4326 (WGS84).
available For each tile zoom level, a list of tile ranges are included that defines the tiles that are available in this Tileset. Each tile range is defined by x and y Tile Map Service (TMS) coordinates that bound a range of tiles. Each zoom level, from 0 to maxzoom, will define a list of available Tile Ranges, where the first list of Tile Ranges belongs to TMS Level 0, index 1 into the availabile list property defines the Terrain Tiles available for TMS Level 1, and so on.
available[zoom_level].startX TMS x coordinate of the westernmost tile in this tile range.
available[zoom_level].endX The TMS x coordinate of the easternmost tile in this tile range.
available[zoom_level].startY The TMS y coordinate of the southernmost tile in this tile range.
available[zoom_level].endY The TMS y coordinate of the northernmost tile in this tile range.

Example

Request metadata for the "World" Tileset defined on the STK Terrain Server running on localhost. http://localhost/stk-terrain/v1/tilesets/World/tiles/layer.json
{ tilejson: "2.1.0", name: "World", description: "Global tileset with high resolution terrain defined around Yosemite National Park", version: "1.2.0", format: "quantized-mesh-1.0", attribution: null, scheme: "tms", extensions: ["vertexnormals"], tiles: ["{z}/{x}/{y}.terrain?v={version}"], minzoom: 0, maxzoom: 12, bounds: [-180, -90, 180, 90], projection: "EPSG:4326", available: [ [ {startX: 0, startY: 0, endX: 1, endY: 0 } ], [ { startX: 0, startY: 0, endX: 3, endY: 1 } ], ... ] }

[GET] /v1/tilesets/{tileset_name}/tiles/{z}/{x}/{y}.terrain?v={version}

Returns a Terrain Tile as a GZipped byte array in the Quantized-Mesh format. The organization of the terrain tiles follow the Tile Map Service (TMS) layout of tiles.

Parameters

tileset_name Name of the Terrain Tileset
z The TMS zoom level of the requested Terrain Tile
x The TMS x coordinate of the requested Terrain Tile
y The TMS y coordinate of the requested Terrain Tile
version The Tileset Version. This is used to ensure that as changes are made to the Terrain Tileset, the new tiles are requested rather than retrieved from the browser’s cache. When requesting a tile, use the value specified by the version property defined in the Tileset's layer.json

Accept Header Content-types

Content-type Description
Accept: application/vnd.quantized-mesh Request the Quantized-Mesh without any extension data
Accept: application/vnd.quantized-mesh;extensions={extensions} Request the Quantized-Mesh with extension data. The list of available extensions is defined in the layer.json extensions property. For example, the following requests the octvertexnormals extension:
Accept: application/vnd.quantized-mesh;extensions=octvertexnormals

Available Responses

Response Code Content-type
200 - Ok GZipped Byte Array in the Quantized-Mesh format
400 - Bad Request text/html
404 - Not Found text/html