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.

Available Algorithms

Map Type Supported Imagery Raster Output Vector Output
imagery
truecolor.png
 
aircraft
gbdx idaho-pansharpened
ab pleiades
pl PSOrthoTile
aircraft.png
detections.geojson
ships
gbdx idaho-pansharpened
ab pleiades
pl PSOrthoTile
ships.png
detections.geojson
wrunc
gbdx idaho-pansharpened
ab pleiades
pl PSOrthoTile
water.png
roads.png
urban.png
nonurban.png
clouds.png
area.json
cars
gbdx idaho-pansharpened [1]
cars.png
trucks.png
detections.geojson
containers [2]
gbdx idaho-pansharpened
ab pleiades
containers.png
area.json
boats [3]
gbdx idaho-pansharpened
ab pleiades
boats.png
detections.geojson
solar-panels
gbdx idaho-pansharpened
solar-panels.png
area.json
pools
gbdx idaho-pansharpened
pools.geojson
detections.geojson
houses [4]
gbdx idaho-pansharpened
houses.png
construction-medium.png
constructions-early.png
detections.geojson
coal
ee COPERNICUS/S2
coal.png
area.json
cranes
gbdx idaho-pansharpened
cranes.png
detections.geojson
lithium
ee COPERNICUS/S2
lithium.png
area.json
cows
gbdx idaho-pansharpened
cows.png
detections.geojson
change [5]
gbdx idaho-pansharpened
ab pleiades
pl PSOrthoTile [7]
heatmap.png
attention_regions.geojson
wrunc-change [6]
pl PSOrthoTile [7]











ndvi-added-heatmap.png
ndvi-removed-heatmap.png
water-added.png
water-removed.png
roads-added.png
roads-removed.png
urban-added.png
urban-removed.png
nonurban-added.png
nonurban-removed.png
clouds-added.png
clouds-removed.png
 
eme [8]
gbdx idaho-pansharpened
eme.png
detections.geojson
trees
gbdx idaho-pansharpened
trees.png
area.json
ndvi [9]
gbdx idaho-pansharpened
pl PSOrthoTile
heatmap.png
 

For more information about vector files, see area.json, detections.geojson and attention_regions.geojson formats.

[1]Only images with GSD lower than 0.55.
[2]Detects cargo containers.
[3]Detects boats with length smaller or equal to 30 meters. Note that boats are also detected as ships in ships map type, i.e. boats class is a subset of ships class.
[4]Detects houses and house constructions (medium and early phases).
[5]Detects changes in a new image as compared to an old image.
[6]Detects changes in WRUNC outputs of a new and an old image.
[7](1, 2) Change detection can run only between provider-datasets within supported groups: {gbdx, ab} and {pl}.
[8]Detects earthmoving equipment (excavators, backhoe loaders and bulldozers).
[9]Normalized Difference Vegetation Index from the range of 0..1.

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 256x256 pixels, a GeoJSON or other types of raster and vector data. See Tile Files.

Glossary

  • Kraken map – an individual image or analyses identified with a unique ID.
  • Map type – type of a Kraken map. For example WRUNC or IMAGERY.
  • Tile file – a map is divided into tiles. For every tile (i.e. some zoom, x, y coordinates) there is one or more available files (i.e. 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.

Generic Kraken Release Endpoints

Kraken API can generate various map types. One can generate a map for a GeoJSON or a list of (zoom, x, y) tiles:

  • tile endpoints have uniform URL paths in format /kraken/release/<map_type>/tiles/{initiate|retrieve},
  • GeoJSON endpoints have uniform URL paths in format /kraken/release/<map_type>/geojson/{initiate|retrieve}.
POST /kraken/release/{map_type}/tiles/initiate
Request JSON Object:
 
  • sceneId (string) – required; ID of a scene from which the map should be generated. See Ragnar API (Search and Get Imagery).
  • tiles (list) – required; list of tiles which should be available in the map. It is a list of 3-tuples with [zoom, x, y] coordinates. Only the top-level (broadest) tiles should be specified here, all finer underlying tiles are generated automatically up to maximal zoom level. The zoom level of all requested tiles must be smaller or equal than max zoom for the map. You may specify up to 16 tiles.

Example request:

{
    "sceneId": "abc",
    "tiles": [
        [19, 83861, 202628],
        [19, 83862, 202628]
    ]
}

Example response:

See pipeline initiation.

POST /kraken/release/{map_type}/geojson/initiate
Request JSON Object:
 

Example request:

{
    "sceneId": "abc",
    "extent": {
        "type": "MultiPolygon",
        "coordinates": [
            [
                [
                    [-122.51747131348, 37.694823535365],
                    [-122.35130310059, 37.694823535365],
                    [-122.35130310059, 37.809919574016],
                    [-122.51747131348, 37.809919574016],
                    [-122.51747131348, 37.694823535365]
                ]
            ]
        ]
    }
}

Example response:

See pipeline initiation.

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.

Effective resolution for the map can be determined by the following pseudo code:

if release_type == 'imagery':
    r_e = min(r for b in bands for r in (b.approx_res_x, b.approx_res_y))
elif provider == 'pl':
    r_e = 3.125
else:
    r_e = 0.5

Note

If tile \((z, x, y)\) is generated and \(z < \mathit{max\_zoom\_level}\) then tiles \((z + 1, 2x, 2y)\), \((z + 1, 2x + 1, 2y)\), \((z + 1, 2x, 2y + 1)\) and \((z + 1, 2x + 1, 2y + 1)\) are also generated.

POST /kraken/release/{map_type}/{tiles|geojson}/retrieve

Example request:

See pipeline retrieve.

Response JSON Object:
 
  • mapId (string) – map ID to be used to access map tiles.
  • maxZoom (int) – maximum zoom available for returned mapId.
  • tiles (list) – List of tiles which were successfully created, the system may be unable to release some of the requested tiles. This is always a subset of requested tiles. Note that some child tiles of tiles may be missing.

Example response:

{
    "mapId": "xyz",
    "maxZoom": 19,
    "tiles": [
        [19, 83861, 202628]
    ]
}

Release Pairwise Map Types

General Change Detection and WRUNC Change map types use two scenes as input and are released and retrieved in the following manner.

POST /kraken/release/<map_type>/tiles/initiate
Request JSON Object:
 
  • oldSceneId (string) – required; ID of an old scene.
  • newSceneId (string) – required; ID of a scene in which changes will be detected as compared to “old scene”.
  • tiles (string) – required; list of tiles which should be available in the map. It is a list of 3-tuples with [zoom, x, y] coordinates. Only the top-level (broadest) tiles should be specified here, all finer underlying tiles are generated automatically up to maximal zoom level.
POST /kraken/release/<map_type>/tiles/retrieve

See generic retrieve endpoint.

POST /kraken/release/<map_type>/geojson/initiate
Request JSON Object:
 
  • oldSceneId (string) – required; ID of an old scene.
  • newSceneId (string) – required; ID of a scene in which changes will be detected as compared to “old scene”.
  • extent (object) – required; area of interest which must intersect with intersection of old and new scene’s footprints. The area must be allocated using Credits API if the imagery is high-resolution.
POST /kraken/release/<map_type>/geojson/retrieve

See generic retrieve endpoint.

Tile Files

A tile can be downloaded on https://spaceknow-kraken.appspot.com/kraken/grid/<map_id>/<geometry_id>/<z>/<x>/<y>/<file_name>, where map_id is an ID of a map, geometry_id is either - or an ID of a geometry from GeoJSON API, z is zoom level, x and y are horizontal and vertical coordinates of the tile.

Each map type has different set of available tiles (file_name in the URL). See the documentation of individual Kraken release endpoints above.

If geometry_id is not - then the tile is clipped to the GeoJSON.

.png tile is a RGBA PNG and polygon is drawn to the PNG alpha channel.

For example this URL https://spaceknow-kraken.appspot.com/kraken/grid/xyz/-/19/83861/202628/truecolor.png contains a PNG tile that shows the city of San Francisco (\(x = 83861, y = 202628\)) at zoom level 19. The tile is from a map with ID abc and is not clipped (geometry_id is -).

Other examples are:

  • https://spaceknow-kraken.appspot.com/kraken/grid/abc/-/19/83861/202628/aircraft.png
  • https://spaceknow-kraken.appspot.com/kraken/grid/abc/-/19/83861/202628/detections.geojson
  • https://spaceknow-kraken.appspot.com/kraken/grid/abc/-/19/83861/202628/area.json