Kraken API (Imagery and Analyses)

Legends say that the Kraken was a giant sea creature that was bigger than the eye could see. Sometimes, one wants to get an overview of a bigger area than Ragnar API can provide. Borrowing its name from the Kraken, the sea monster, the Kraken API was born to serve this very need.

The API interfaces imagery and analyses through tiled web map interface.

Map and Tiling

Kraken map is Earth surface between -180 to +180 of longitude and -85.051129 to +85.051129 of latitude projected to a square with Web Mercator projection. The map is divided into multiple zoom levels each consisting of a grid of tiles.

A tile is unambiguously identified by \((z, x, y)\) coordinates, where \(z\) represents zoom level, \(x\) represents a horizontal coordinate and \(y\) represents a vertical coordinate. The top-left tile has coordinates \((z, 0, 0)\).

A zoom level is a number that indicates the level of tile’s fine-detail. The lowest zoom level, at which the whole map is rendered to a single tile, is 0. With each successive zoom level, the total number of map tiles quadruples. The zoom level \(z >= 0\) is a grid with \(2^z \times 2^z\) tiles.

A tile is physically represented by one or many files representing area given by the tile boundaries. The files may consist of PNG and other images with dimensions of 512x512 pixels (256x256 pixels for legacy files with version <= 372), a GeoJSON or other types of raster and vector data. See Grid Files.

Glossary

Kraken map – an individual image or analyses identified with a unique ID.
Map type – type of analysis (type of Kraken map), e.g. IMAGERY, AIRCRAFT, NDVI
Grid file – a map is divided into tiles. For every tile (i.e. some zoom, x, y coordinates) there is one or more available grid files (e.g. truecolor.png or detections.geojson).

Release The Kraken!

Kraken release endpoints serve as a preparation and/or re-computation of a map. All release endpoints generate a map ID which can be later used to access the map. A map ID expires in one year.

Generic Kraken Release Endpoints

Kraken API can execute analysis over area specified by GeoJSON. Type of analysis to execute is given by map type, e.g. AIRCRAFT.

Note

The area must be allocated using Credits API.

See Kraken Initiate. and Kraken Retrieve.

Max zoom

Max zoom is determined by the following formula:

\[z_{max} = \lceil log_2(\frac{4 \cdot 10^7 \cdot cos(\frac{l \cdot \pi}{180})}{256 \cdot r_e}) \rceil\]

where \(l\) is latitude of the scene footprint centroid and \(r_e\) is the effective resolution in meters per pixel.

Release with subGeometry

Sometimes it is useful to have kraken analyze bigger extent and then download only subset of what was analyzed. This is the case for SAR change algorithms when we want to analyze AoI buffered sufficiently so that kraken can use AoI neighborhood for data normalization.

Kraken Pairwise API

See Kraken Pairwise OpenAPI.

Kraken N-wise API

See Kraken Nwise OpenAPI.

Grid Files

See Kraken Grid OpenAPI.

.png tile can be either RGBA or grayscale+alpha PNG and requested polygon is drawn to the PNG alpha channel.

truecolor.png can be represented by:

Bands corresponding to RGB in satellite imagery if such bands are present.
Bands chosen to fill RGB channels that are not corresponding to red, green, blue. For example imagery from idaho-swir contains only data from infrared bands and 3 of them are chosen to be visualized.
One Grayscale channel if only one band is present in satellite imagery. This grayscale band can correspond to visible light band in some imagery but generally it can contain other data too.
SAR imagery is visualized as (log(S), log(O), arctan(S/O)) where S is intensity of detected radio waves with same polarisation as radio waves emitted by the satellite, O is intensity of detected radio waves with polarisation perpendicular to emitted radio waves. arctan in blue band represents measure of preservation of polarisation plane in reflected light.

Kraken Dry-Run

See Kraken Dry Run Initiate OpenAPI and Kraken Dry Run Retrieve OpenAPI.

Kraken MapType List

See Kraken Map Type List OpenAPI.

Kraken MapType by Map ID

See Kraken Map Type by ID OpenAPI.

Kraken Guardian Groups

See Kraken Guardian Group OpenAPI.

Kraken Pdf generation

See Kraken Pdf Report Initiate OpenAPI and Kraken Pdf Report Retrieve OpenAPI.