Cloudburst API

Version: 1.0.1

Make and explore beautiful, rapidly-refreshed weather maps with the Cloudburst API

Default response content-types:
application/json, application/x-protobuf, image/png
Schemes:
http

Summary

Tag: Layer

Operation Description
GET /<ownerID>/layer/ Information about available Cloudburst layers
GET /<ownerID>/layer/<layerID>/ Information about a specific layer
GET /<ownerID>/layer/<layerID>/<instanceID>/ Information about a particular (potentially non-persistant) instance of a layer
GET /<ownerID>/layer/<layerID>/<instanceID>/times/ A collection of moments in time for which data exists and can be requested (as tiles) for an instance of a layer.
GET /<ownerID>/layer/<layerID>/<instanceID>/levels/ A collection of vertical levels for which data exists and can be requested (as tiles) for an instance of a layer.
GET /<ownerID>/tile/<layerID>/<instanceID>/<time>/<level>/<z>/<x>/<y>.<extension> A tiled map image, for use by map clients capable of consuming PNG map images in OGC TMS coordinate notation.
GET /<ownerID>/legend/<size>/<orientation>/<layerID>/<instanceID>.png A legend for PNG map tiles
GET /<ownerID>/legend/<size>/<orientation>/<layerID>/<instanceID>.json A JSON representation of the legend for PNG map tiles

Tag: Instance

Operation Description
GET /<ownerID>/layer/ Information about available Cloudburst layers
GET /<ownerID>/layer/<layerID>/ Information about a specific layer
GET /<ownerID>/layer/<layerID>/<instanceID>/ Information about a particular (potentially non-persistant) instance of a layer
GET /<ownerID>/layer/<layerID>/<instanceID>/times/ A collection of moments in time for which data exists and can be requested (as tiles) for an instance of a layer.
GET /<ownerID>/layer/<layerID>/<instanceID>/levels/ A collection of vertical levels for which data exists and can be requested (as tiles) for an instance of a layer.
GET /<ownerID>/tile/<layerID>/<instanceID>/<time>/<level>/<z>/<x>/<y>.<extension> A tiled map image, for use by map clients capable of consuming PNG map images in OGC TMS coordinate notation.
GET /<ownerID>/legend/<size>/<orientation>/<layerID>/<instanceID>.png A legend for PNG map tiles
GET /<ownerID>/legend/<size>/<orientation>/<layerID>/<instanceID>.json A JSON representation of the legend for PNG map tiles

Tag: Metadata

Operation Description
GET /<ownerID>/layer/ Information about available Cloudburst layers
GET /<ownerID>/layer/<layerID>/ Information about a specific layer

Tag: Time

Operation Description
GET /<ownerID>/layer/<layerID>/<instanceID>/times/ A collection of moments in time for which data exists and can be requested (as tiles) for an instance of a layer.
GET /<ownerID>/tile/<layerID>/<instanceID>/<time>/<level>/<z>/<x>/<y>.<extension> A tiled map image, for use by map clients capable of consuming PNG map images in OGC TMS coordinate notation.

Tag: Level

Operation Description
GET /<ownerID>/layer/<layerID>/<instanceID>/levels/ A collection of vertical levels for which data exists and can be requested (as tiles) for an instance of a layer.
GET /<ownerID>/tile/<layerID>/<instanceID>/<time>/<level>/<z>/<x>/<y>.<extension> A tiled map image, for use by map clients capable of consuming PNG map images in OGC TMS coordinate notation.

Tag: Tile

Operation Description
GET /<ownerID>/tile/<layerID>/<instanceID>/<time>/<level>/<z>/<x>/<y>.<extension> A tiled map image, for use by map clients capable of consuming PNG map images in OGC TMS coordinate notation.

Tag: Legend

Operation Description
GET /<ownerID>/legend/<size>/<orientation>/<layerID>/<instanceID>.png A legend for PNG map tiles
GET /<ownerID>/legend/<size>/<orientation>/<layerID>/<instanceID>.json A JSON representation of the legend for PNG map tiles

Paths

 

Information about available Cloudburst layers

GET /<ownerID>/layer/

Tags:
Layer,
Instance,
Metadata

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 query string (string)
,
comma separated (tags=aaa,bbb)
application/json

200 OK

Matched layers’ configurations

404 Not Found

Not Found: the owner does not exist

default

Unexpected error

 

Information about a specific layer

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

Tags:
Layer,
Instance,
Metadata

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

200 OK

Matched layers’ configurations

404 Not Found

Not Found: the owner or layer does not exist

default

Unexpected error

 

Information about a particular (potentially non-persistant) instance of a layer

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

Tags:
Layer,
Instance

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

200 OK

Matched layers’ configurations

404 Not Found

Not Found: the owner, layer or instance does not exist

default

Unexpected error

 

A collection of vertical levels for which data exists and can be requested (as tiles) for an instance of a layer.

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

Tags:
Layer,
Instance,
Level

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

200 OK

Matched layers’ configurations

204 No Content

No Content: the request was successful, but the layer instance has no vertical dimension so there is nothing to return.

404 Not Found

Not Found: the owner, layer or instance does not exist

default

Unexpected error

 

A collection of moments in time for which data exists and can be requested (as tiles) for an instance of a layer.

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

Tags:
Layer,
Instance,
Time

This endpoint exposes the array of moments that data exists for a particular instance. Each element can be used to substitute the
application/json

200 OK

Matched layers’ configurations

204 No Content

No Content: the request was successful, but the layer instance has no temporal dimension so there is nothing to return.

404 Not Found

Not Found: the owner, layer or instance does not exist

default

Unexpected error

 

A JSON representation of the legend for PNG map tiles

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

Tags:
Legend,
Layer,
Instance

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

200 OK

JSON representation of the legend (Cloudburst uses thus to render the PNG legend server-side)

204 No Content

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

default

Unexpected error

 

A legend for PNG map tiles

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

Tags:
Legend,
Layer,
Instance

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.

default

Unexpected error

 

A tiled map image, for use by map clients capable of consuming PNG map images in OGC TMS coordinate notation.

GET /<ownerID>/tile/<layerID>/<instanceID>/<time>/<level>/<z>/<x>/<y>.<extension>

Tags:
Tile,
Layer,
Instance,
Time,
Level

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

200 OK

A rendered map tile as a PNG

default

Unexpected error

Schema definitions

Bounds:
object

 

An object representing the layer instance’s bounding box (derived from the dataset)
west:
number (float)
The western extent of the instance’s dataset (degrees longitude)

east:
number (float)
The eastern extent of the instance’s dataset (degrees longitude)

north:
number (float)
The northern extent of the instance’s dataset (degrees latitude)

south:
number (float)
The southern extent of the instance’s dataset (degrees longitude)

Error:
object

 

http-code:
number (integer)
HTTP status code

incident-number:
string
Incident number that has been recorded.

message:
string
Explanation why the request has caused an error

Instance:
object

 

A named instance of a dataset, typically used to represent a forecast model cycle
id:
string
Instance ID

created:
string
ISO 8601 datetime string representing when the instance configuration was created

start_time:
string
ISO 8601 datetime string representing the earliest retrievable time-step for an instance

end_time:
string
ISO 8601 datetime string representing the latest retrievable time-step for an instance

Layer:
object

 

A layer representing a spatial dataset that can be rendered by Cloudburst
id:
string
Layer ID

instances:
Instance
bounds:
Bounds
meta:
Metadata
resources:
Resources

Layers:
object[]

 

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

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.
plotID:
LegendPlot

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.

hatches:
string[]
Sorted array of hatch styles for the plot’s levels

string , x ∈ {
/
,
//
,
///
,
\
,
\\
,
\\\
,
|
,
||
,
|||
,

,

,

,
+
,
++
,
+++
,
x
,
xx
,
xxx
,
o
,
oo
,
ooo
,
O
,
OO
,
OOO
,
.
,
..
,

,
*
,
**
,
***
}

The hatch style for the sub-plot
levels:
number[]
A sorted array of values in the dataset where breaks are to be drawn (e.g. contour lines)

number (float)

ticks:
number[]
A sorted array of values where “ticks” (small leader lines) are to be drawn on the legend. With this property, some levels can be left without a tick, or ticks added between class breaks.

number (real)

tick_labels:
string[]
A sorted array of values for the legend’s ticks. With this property, ticks can be given non-default labels (such as human interpretations of critical numerical values).

string

linestyles:
string[]
A sorted array of linestyles for the plot levels

string , x ∈ {
solid
,
dashed
,
dashdot
,
dotted
,

,

,
-.
,
:
,
,

,

}

The linestyle for the sub-plot
linewidths:
number[]
A sorted array of linewidths for the plot levels

number (float)

norm:
Norm
unit:
string
Text that is used to indicate the units on the scale; may include additional text beyond a representation of a unit (e.g. “Low-level azimuthal shear (0.001/s)”)

vmax:
number (float)
If present, indicates the upper colour boundary of a continuous plot (such as a pcolormesh).

vmin:
number (float)
If present, indicates the lower colour boundary of a continuous plot (such as a pcolormesh).

mplkwargs:
MplKwargs

LegendPlot:
object

 

A Matplotlib plot type (e.g. ‘pcolormesh’, ‘contourf’) as key, with the value representing the information for the legend for that particular sub-plot.
plotType:
LegendItem

Level:
string

 

A potential value of a vertical dimension of an instance. The index of a chosen level in this array is used to substitute “level” in a tile URL. This index is 0-based.

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

 

Additional, arbitrary Matplotlib keyword arguments. All are optional. Additional properties are possible.
extend:
string , x ∈ {
neither
,
both
,
min
,
max
,
}
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.
method:
string , x ∈ {
LogNorm
,
SymLogNorm
,
PowerNorm
,
BoundaryNorm
,
OffsetNorm
}
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.

Times:
object[]