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
imagery.ski
metadata.json

aircraft
gbdx idaho-pansharpened
pl PSOrthoTile
aircraft.png
segmentation.ski
detections.geojson
metadata.json
ships
gbdx idaho-pansharpened
ab pleiades
pl PSOrthoTile
ships.png
segmentation.ski

detections.geojson
metadata.json

wrunc
gbdx idaho-pansharpened
ab pleiades
pl PSOrthoTile
ee COPERNICUS/S2


water.png
roads.png
urban.png
nonurban.png
clouds.png
segmentation.ski
metadata.json





wrun
ee COPERNICUS/S1_GRD




water.png
roads.png
urban.png
nonurban.png
segmentation.ski
metadata.json




cars
gbdx idaho-pansharpened [1]


cars.png
trucks.png
segmentation.ski
detections.geojson
metadata.json

containers [2]
gbdx idaho-pansharpened
ab pleiades
containers.png
segmentation.ski
metadata.json

destruction [4]
gbdx idaho-pansharpened



destruction-medium.png
destruction-heavy.png
road-destruction.png
segmentation.ski
metadata.json



boats [3]
gbdx idaho-pansharpened
ab pleiades
boats.png
segmentation.ski
detections.geojson
metadata.json
solar-panels
gbdx idaho-pansharpened

solar-panels.png
segmentation.ski
detections.geojson
metadata.json
pools
gbdx idaho-pansharpened


pools.png
segmentation.ski

detections.geojson
metadata.json

houses [5]
gbdx idaho-pansharpened



houses.png
construction-medium.png
constructions-early.png
segmentation.ski
detections.geojson
metadata.json


coal
ee COPERNICUS/S2

coal.png
segmentation.ski
metadata.json

cranes
gbdx idaho-pansharpened

cranes.png
segmentation.ski
detections.geojson
metadata.json
ips-deadwood
ee COPERNICUS/S2
pl PSOrthoTile
gbdx idaho-pansharpened
ips-deadwood.png
segmentation.ski

metadata.json
detections.geojson
detections.geojson
ips-baresoil
ee COPERNICUS/S2
pl PSOrthoTile
ips-baresoil.png
segmentation.ski
metadata.json

lithium
ee COPERNICUS/S2

lithium.png
segmentation.ski
metadata.json

cows
gbdx idaho-pansharpened


cows.png
segmentation.ski

detections.geojson
metadata.json

change [6]
gbdx idaho-pansharpened
ab pleiades
pl PSOrthoTile
ee COPERNICUS/S2 [11]
heatmap.png
heatmap.ski


attention_regions.geojson
metadata.json


sar-blobs [7]
ee COPERNICUS/S1_GRD


sar-blobs.png
segmentation.ski

detections.geojson
metadata.json

sar-diff [8]
ee COPERNICUS/S1_GRD


heatmap.png
heatmap.ski

attention_regions.geojson
metadata.json

sar-change [9]
ee COPERNICUS/S1_GRD

heatmap.png
heatmap.ski
attention_regions.geojson
metadata.json
prenormalized- sar-diff [8]
ee COPERNICUS/S1_GRD


heatmap.png
heatmap.ski

attention_regions.geojson
metadata.json

prenormalized- sar-change [9]
ee COPERNICUS/S1_GRD


heatmap.png
heatmap.ski

attention_regions.geojson
metadata.json

wrunc-change [10]
pl PSOrthoTile [11]










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
segmentation.ski
metadata.json










eme [12]
gbdx idaho-pansharpened

eme.png
segmentation.ski
detections.geojson
metadata.json
trees
gbdx idaho-pansharpened

trees.png
segmentation.ski
detections.geojson
metadata.json
ndvi [13]
gbdx idaho-pansharpened
pl PSOrthoTile
ee LANDSAT/LE07/C01/T1
ee LANDSAT/LC08/C01/T1
ee COPERNICUS/S2
heatmap.png
heatmap.ski



metadata.json




ndbi [14]
ee LANDSAT/LE07/C01/T1
ee LANDSAT/LC08/C01/T1
ee COPERNICUS/S2
heatmap.png
heatmap.ski

metadata.json


ndmi [15]
ee LANDSAT/LE07/C01/T1
ee LANDSAT/LC08/C01/T1
ee COPERNICUS/S2
heatmap.png
heatmap.ski

metadata.json


ndwi [16]
ee LANDSAT/LE07/C01/T1
ee LANDSAT/LC08/C01/T1
ee COPERNICUS/S2
heatmap.png
heatmap.ski

metadata.json


evi [17]
ee LANDSAT/LE07/C01/T1
ee LANDSAT/LC08/C01/T1
ee COPERNICUS/S2
heatmap.png
heatmap.ski

metadata.json


savi [18]
ee LANDSAT/LE07/C01/T1
ee LANDSAT/LC08/C01/T1
ee COPERNICUS/S2
heatmap.png
heatmap.ski

metadata.json


msavi2 [19]
ee LANDSAT/LE07/C01/T1
ee LANDSAT/LC08/C01/T1
ee COPERNICUS/S2
heatmap.png
heatmap.ski

metadata.json


weather [20]
pl PSOrthoTile


clouds.png
snow.png
segmentation.ski
metadata.json


nl-change-daily [21]
noaa VIIRS/Daily

nl-change.png
nl-change.ski
metadata.json

nl-change-monthly [21]
noaa VIIRS/Monthly

nl-change.png
nl-change.ski
metadata.json

oil-pads [22]
ee COPERNICUS/S2

oil-pads.png
segmentation.ski
detections.geojson
metadata.json
flare-blobs [23]
ee COPERNICUS/S2
ee LANDSAT/LC08/C01/T1
flare-blobs.png
segmentation.ski
detections.geojson
metadata.json
normalized-imagery [24]
ee COPERNICUS/S1_GRD

normalized_imagery.png
imagery.ski
metadata.json

For more information about output files, see metadata.json, detections.geojson, attention_regions.geojson and segmentation.ski.

[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 ruins of houses and infrastructure in war-zones.
[5]Detects houses and house constructions (medium and early phases).
[6]Detects changes in a new image as compared to an old image.
[7]Detects blobs at open water areas in a SAR (Synthetic-Aperture Radar) image.
[8](1, 2) Detects differences in a new SAR (Synthetic-Aperture Radar) image compared to an old SAR image.
[9](1, 2) Detects changes in a new SAR (Synthetic-Aperture Radar) image compared to an old SAR image.
[10]Detects changes in WRUNC outputs of a new and an old image.
[11](1, 2) Change detection can run only between provider-datasets within supported groups: {gbdx, ab}, {pl} and {ee}.
[12]Detects earthmoving equipment (excavators, backhoe loaders and bulldozers). Currently works only on images from WV03_VNIR satellite.
[13]Normalized Difference Vegetation Index.
[14]Normalized Difference Buildup Index.
[15]Normalized Difference Metalic Index.
[16]Normalized Difference Water Index.
[17]Enhanced Vegetation Index
[18]Soil Adjusted Vegetation Index
[19]Modified Soil Adjusted Vegetation Index
[20]Detects clouds and snow covered land.
[21](1, 2) Detects change in night-lights.
[22]Detects oil pads.
[23]Detects flare blobs.
[24]Normalized SAR imagery.

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 Grid 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.
  • 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 generate various map types. One can generate a map for a GeoJSON. Release endpoints have uniform URL paths in format: /kraken/release/<map_type>/geojson/{initiate|retrieve}.

Needed Permissions:

  • kraken.release
  • Also a set of permissions in the form <prefix>.<provider>.<dataset> is needed. <prefix> is replaced with algorithms.<name-of-algorithm> or with imagery.images.
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

Needed Permissions: kraken.release

POST /kraken/release/{map_type}/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. It is guaranteed that at most four tiles, all at equal zoom level, are returned. User is allowed to request any descendant tile, 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.

Needed Permissions: See generic initiate 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.

Grid 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 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.

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/segmentation.ski
  • https://spaceknow-kraken.appspot.com/kraken/grid/abc/-/19/83861/202628/detections.geojson
  • https://spaceknow-kraken.appspot.com/kraken/grid/abc/-/19/83861/202628/metadata.json

Error Status Codes

  • 400 – invalid request: a possible reason is invalid or expired map ID.
  • 401 – given map ID doesn’t include requested tile.
  • 404 – requested tile doesn’t exist: data are not available or the area of the tile cannot be analyzed.