Paths

GET/<ownerID>/layer/

This endpoint returns information about all current Cloudburst layers that can be requested, and metadata about map layers, including bounding boxes and the unit system (metric, USCS, etc.) that is used when rendering map tiles.

tags

Filter layers by tags, separated by commas. Using multiple tags parameters is equivalent to an AND operation. For example, tags=x,y is x OR y; tags=x&tags=y is x AND y; and tags=x,y&tags=z is (x OR y) AND z

GET/<ownerID>/layer/<layerID>/

This endpoint provides information about a specific Cloudburst layer that can be requested as map tiles, and its metadata, including bounding boxes and the unit system (metric, USCS, etc.) that is used when rendering map tiles.application/json

GET/<ownerID>/layer/<layerID>/<instanceID>/

This endpoint provides information about an instance of a specific Cloudburst layer that can be requested as map tiles. Instances are typically added and removed as the data underlying a dataset changes with time (e.g. forecasts expire, and forecast horizons continuously move forward). Therefore a particular instance of a layer may not be persistant.application/json

GET/<ownerID>/layer/<layerID>/<instanceID>/levels/

This endpoint exposes the array of vertical positions that data exists for a particular instance. Each element can be used to substitute the part of a tile URL. Not all layer instances have a vertical (e.g. it may be surface wave height and therefore only apply at sea level). If a layer has no vertical dimension, the array will be empty.application/json

GET/<ownerID>/layer/<layerID>/<instanceID>/times/

This endpoint exposes the array of moments that data exists for a particular instance. Each element can be used to substitute the part of a tile URL. Not all layer instances have a temporal dimension (e.g. it may be static bathymetry, or an observational dataset with no forecast or hindcast). If a layer has no temporal dimension, the array will be empty.application/json

GET/<ownerID>/legend/<size>/<orientation>/<layerID>/<instanceID>.json

Legends are inferred from plot configurations for each layer. When a legend is disabled on a per-layer basis (or if a legend cannot be rendered due to the plot type), then this endpoint will return a 204 No Content response. Cloudburst internally uses this JSON representation to render the PNG version of the legend, and this endpoint is exposed to support client-side legend rendering and the interaction that implies. The size must be substituted by either small or large. The orientation must be substituted by either horizontal or vertical.application/json

GET/<ownerID>/legend/<size>/<orientation>/<layerID>/<instanceID>.png

Legends are inferred from plot configurations for each layer. When a legend is disabled on a per-layer basis (or if a legend cannot be rendered due to the plot type), then this endpoint will return a 204 No Content response. The size must be substituted by either small or large. The orientation must be substituted by either horizontal or vertical.image/png

200 OK

A rendered map legend as a PNG

204 No Content

No Content: The layer/instance being requested does not have a legend.

Cloudburst produces map tiles, and PNG map tiles are the traditional format for representing these. Other possibilities include protocol-buffer vector tiles in the Mapbox vector tile specification, and others. This endpoint will most often be used by map clients (such as Leaflet, Mapbox GL JS, OpenLayers, and Google Maps), which know exactly which tiles to request for a given geographical map view and zoom level. The Cloudburst Javascript API is responsible for completing the resource URI via these client libraries, based on what a user is authenticated to request, and what these layers support, via requests to other endpoints. Manual requests are possible but are not recommended. The resources for a particular layer can be discovered through a GET request to /layer/<layerId>/ and inspecting the response’s resources property. The /layer/<layerId>/<instanceID>/times/ endpoints can be used to request the times that are valid (many layer instances have only one time and/or vertical level).image/png

Layer:object

Layers:object[]

All layers meeting your query, that that you are authenticated for, and which are currently availableLayer

Legend:object

Legend configuration for the given plotID (a unique identifier for a plot), derived from the respective plot configuration. A plot can consist of multiple sub-plots (e.g. a map of precipitation with a pressure overlay), only one of which will have a value associated with its key.

LegendItem:object

cmap:string

The named colourmap used by the plot. Possibly represents one of the default Matplotlib colourmaps, a cmocean Matplotlib colourmap, or a user-defined colourmap.

cmap_discrete:string[]

A sorted array of discrete values in the colourmap. If the plot uses levels (e.g. contours), then the array will include the actual class colour. Otherwise, if the plot uses a continuous colour ramp (e.g. a pcolormesh), the array includes ten values sampled evenly between the low and the high value.

string

Hex value of colour

colors:string[]

A sorted array of values referencing named colours for the lines in the plot (contour-style plots only). If the value is a string (rather than an array), that value applies to all lines.

string

Named colour (HTML convention) or hex value.

extend:string, x ∈ {neither
,both
,min
,max
,}

Indicates whether the upper- or lower-boundary of the colourmap should be extended. Unless this is ‘neither’ or null, contour levels are automatically added to one or both ends of the range so that all data are included. These added ranges are then mapped to the special colormap values which default to the ends of the colormap range.

Level:string

Levels:object[]

Metadata:object

Metadata for a layer. Cloudburst supports an arbitrary metadata document, but these specified keys are useful and will tend to exist, but none of them is mandatory, and a property may exist but have a null value.

name:string

A short, human-readable description of a layer that is suitable for inclusion in a list of available layers.

description:string

A long description of a layer, possibly including HTML tags to navigate users to glossaries or other sources of additional information.

organisation:string

Organisation responsible for publishing the data used in the layer.

source:string

The source of the data (such as a model).

regions:string[]

string

A three-digit numerical code used by the Statistics Division of the United Nations Secretariat. Represents geographical regions where the layer is considered applicable, from the global scale (‘001’), to continental, sub-continental, and country scales. See http://unstats.un.org/unsd/methods/m49/m49.htm for the list of values in current use.

unit_system:string

The system of units that the layer renders quantitative values in. Examples include “metric” and “uscs”, for layers that render with metric and United States customary system (USCS) units, respectively. A null value indicates that the unit system is unspecified or does not fit into a category (e.g. knots). This does not indicate exactly which units a plot will render, only a broad classification. This can be used to filter duplicate layers that only differ in whether they render the same physical phenomenon as, for example, millimetres or inches. There is no restriction on what value this string may take.

MplKwargs:object

See “extend” for the LegendItem; indicates if the extend method of the legend has been set independently to the plot.

spacing:string, x ∈ {proportional
,uniform
,}

Indicates whether class breaks are separated uniformly, or in proportion to their actual value between the highest and the lowest breaks.

alpha:number(float)

Transparency of the legend, from 0 (opaque) to 1 (transparent). Absence of this property implies full opacity.

format:string

Python string formatter (e.g. “%.3f”) indicating how values in the levels should be translated into ticks. This can be used to round values for display on a legend.

drawedges:boolean

Whether edges should be drawn at colour boundaries within the legend.

Norm:object

Normalisation technique and parameters for mapping values to colours. Corresponds to valid Matplotlib colorbar normalisation methods. If not null, the only required property is “method”, with the rest depending on the normalisation technique.

Normalisation technique, corresponding to one of the Matplotlib colorbar normalisation methods.

vmin:number(integer)

vmax:number(integer)

clip:boolean

gamma:number(float)

linthresh:number(float)

linscale:number(float)

Resources:object

Template URLs for requesting tiles and other resources for this layer instance. Note that the tile coordinates (z, x, and y) must be given in OGC TMS, rather than the XYZ specification (see https://gist.github.com/tmcw/4954720 for the difference, which only affects the y coordinate). Not all given properties exist for all layers. The literal text “instance” (enclosed in angle brackets) must be substituted by a valid instance ID.

tile:string

Template URL for requesting styled, PNG image tiles. Elements of the path enclosed in angle brackets need to be appropriately substituted when making requests.

vtile:string

Template URL for requesting vector tiles in the Mapbox vector tile (MVT) specification, as protocol buffers. Elements of the path enclosed in angle brackets need to be appropriately substituted when making requests.

gtile:string

Template URL for requesting UTFGrid tiles in the Mapbox UTFGrid specification, as JSON (a format for rasterised interaction data). Elements of the path enclosed in angle brackets need to be appropriately substituted when making requests.

rtile:string

Template URL for requesting raw data tiles. Elements of the path enclosed in angle brackets need to be appropriately substituted when making requests.

legend:string

URL for requesting legends as PNG images that correspond to the PNG image tiles. The “size” and “orientation” elements in the path (enclosed in angle brackets) need to be substituted. Valid values for size are “small” and “large”. Valid values for orientation are “horizontal” and “vertical”.

jsonlegend:string

URL for requesting legends as JSON representations. These JSON representations are used internally to construct the image versions of the legend, and can be used to render custom legends client-side. The “size” and “orientation” elements in the path (enclosed in angle brackets) need to be substituted.

Time:string

ISO 8601 string representing a datetime, a possible value of the temporal dimension of an instance. The index of a chosen time in this array is used to ubstitute “time” in a tile URL. This index is 0-based.