Terrain Server
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.
/v1/tilesets
/v1/tilesets/{tileset_name}/tiles/layer.json
/v1/tilesets/{tileset_name}/tiles/{z}/{x}/{y}.terrain?v={version}
Returns the list of tilesets available on the STK Terrain Server instance.
| Response Code | Content-type |
|---|---|
| 200 - Ok | application/json |
| 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. |
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.
| tileset_name | Name of the Terrain Tileset |
| Response Code | Content-type |
|---|---|
| 200 - Ok | application/json |
| 404 - Not Found | text/html |
| 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. |
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.
| 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 |
| 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 |
| Response Code | Content-type |
|---|---|
| 200 - Ok | GZipped Byte Array in the Quantized-Mesh format |
| 400 - Bad Request | text/html |
| 404 - Not Found | text/html |