Albatross Tiles

View the map layers Albatross delivers to your workspace in a GIS such as QGIS or ArcGIS Pro, or in a web map. The Tiles API serves them as WMTS and map tiles, and can also return their pixel values. To add your data to a GIS, see Add your data to a GIS.

Identifiers

Every request names a collection and, for one deliverable, an item. These are the standard names map services use; in Albatross terms a collection is your workspace and an item is one of its deliverables:

In the path	Is	Example
collection_id	Your workspace_id	6603439307
item_id	A deliverable_id	019feff4-6c2a-7d51-9e6b-1f0c2b7a4e10
assets	Which map layers of it, by type	rgb, dtm

They are the same ids the Albatross web app uses: in its URLs the workspace_id follows /workspaces/, and a deliverable_id follows /deliverables/.

The data catalogue in the Albatross web app copies ready-made WMTS URLs for a workspace, a project, an area or a deliverable, and GET /collections/{collection_id}/items lists every deliverable you can read with a tile URL for each of its map layers.

The map layer types are rgb (true colour), cir (colour infrared), pms (pansharpened multispectral), pan (panchromatic), dtm (digital terrain model), dsm (digital surface model) and ras (analysis raster).

Authentication

Every collection route needs a credential, and answers only with data from the projects that credential can read.

• API key: created by a workspace admin in Albatross over the projects it should read, with the tiles:read scope. Send it as Authorization: Bearer alb_..., or as the password of HTTP Basic authentication with any user name, which is how most GIS clients send one. A key pasted as the user name with a blank password works too.
• Albatross session: the web app's own sign-in, which is how the Albatross map reads tiles.

A key never goes in a URL. The colormap, algorithm and tiling scheme routes are public.

Add your data to a GIS

One URL brings a whole workspace into a GIS:

GET /collections/{collection_id}/WMTSCapabilities.xml

It lists the workspace mosaic first, then one layer per deliverable. It lists true colour by default; add ?assets=dtm for another layer type, or ?assets=all for every one. A single deliverable has its own document at /collections/{collection_id}/items/{item_id}/WMTSCapabilities.xml.

• QGIS: Layer, Add Layer, Add WMS/WMTS Layer. Create an Authentication configuration of type "API Header" with header Authorization and value Bearer alb_... (or "Basic" with any user name and the key as password; QGIS sends nothing if the user name is empty), then add the URL above.
• ArcGIS Pro: Insert, Connections, New WMTS Server. Paste the URL and enter any user name with the key as the password, and save the login to Windows Credential Manager.

When a key is rolled, the old one stops working within a minute, and QGIS and ArcGIS Pro ask for the new one.

Tiles for web maps

XYZ tiles for one deliverable, or for the whole workspace as one mosaic:

GET /collections/{collection_id}/items/{item_id}/tiles/WebMercatorQuad/{z}/{x}/{y}.png?assets=rgb
GET /collections/{collection_id}/tiles/WebMercatorQuad/{z}/{x}/{y}.png

The matching tilejson.json describes either one for MapLibre, Leaflet or OpenLayers. Tiles are 256 pixels a side, but a tilejson.json describes 512 pixel tiles unless you add tilesize=256 (see below). WebMercatorQuad suits almost every web map; the other tiling schemes are listed under Tiling schemes.

In the mosaic every deliverable is drawn as one layer, newest capture on top. Narrow it with datetime, bbox, ids or a CQL2 filter.

512 pixel tiles

Add tilesize=512 to a tile or tilejson URL for tiles 512 pixels a side. 256 and 512 are the only sizes offered. A 512 pixel tile holds four times the pixels of a 256 pixel one, and counts as four tiles. Requested at the same zoom level it covers the same ground as a 256 pixel tile, just in more detail, so the same view costs four times as much.

To take advantage of it, request 512 pixel tiles one zoom level lower (z - 1) than you would 256 pixel ones. Each tile then covers the ground of four 256 pixel tiles at the same detail: the map makes a quarter of the requests for the same picture and the same usage, and loads faster. Tell your map library the tiles are 512 pixels so it does this for you: tileSize: 512 in MapLibre, tileSize: 512, zoomOffset: -1 in Leaflet, or a 512 pixel tile grid in OpenLayers.

A WMTS document always describes 256 pixel tiles.

Formats and styling

• Pictures (rgb, cir) come as PNG, JPEG or WebP.
• Measurements (heights and analysis values) come as a stretched PNG to look at, or as a GeoTIFF (.tif) holding the real values to analyse.
• Styling a single-band layer: name a colour ramp with colormap_name (see Colormaps), set the range with rescale=min,max, or process the pixels first with algorithm (see Algorithms). WMTS shows dtm and dsm as tinted relief (algorithm=relief) and ras through the turbo colormap by default.
• Values at a point: GET .../point/{lon},{lat} returns the pixel values under a coordinate, and statistics summarises a layer or an area.

Responses

Status	Means
200	The tile or document
204	A mosaic tile with no data under it
401	No credential, or one Albatross does not accept
403	The API key lacks the tiles:read scope, or map tiles are not enabled
404	No such workspace or deliverable among the projects you can read
422	An invalid parameter, such as a tilesize other than 256 or 512, or a buffer over 8
503	Albatross could not check the credential; nothing is served unchecked

Caching and usage

Successful responses may be cached by the client for an hour (Cache-Control: private, max-age=3600), and errors never are. Tiles served to an API key count towards your workspace's monthly usage by size: a 256 pixel tile counts as one and a 512 pixel tile as four. A buffer does not change the count. Documents, metadata and statistics are not counted. Tiles the Albatross web app shows are never counted. See Metering for how usage is counted and where to see it.