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.

Warning

https://spaceknow-kraken.appspot.com/ is deprecated and should not be used anymore.

Available Algorithms

Map Type Description Raster Output Vector Output Supported Imagery Global Availability [3]
imagery Represents imagery on which the algorithms are predicted.
truecolor.png
imagery.ski
analysis.geotiff
visualization.geotiff
metadata.json







aircraft General aircraft vs. non-aircraft segmentation.
aircraft.png
segmentation.ski
analysis.geotiff
visualization.geotiff

detections.geojson
metadata.json



gbdx idaho-pansharpened
Yes
pl PSOrthoTile
No
pl PSScene4Band
No
ships General ships vs non-ships segmentation.
ships.png
segmentation.ski
analysis.geotiff
visualization.geotiff



detections.geojson
metadata.json





gbdx idaho-pansharpened
Yes
pl PSOrthoTile
Yes
pl PSScene3Band
Yes
pl PSScene4Band
Yes
wrunc
Segments imagery into 5 classes:
  • Water
  • Roads
  • Urban
  • Non-urban
  • Clouds

Each pixel is exclusively assigned to one of aforementioned classes.

water.png
roads.png
urban.png
nonurban.png
clouds.png
segmentation.ski
analysis.geotiff
visualization.geotiff

metadata.json








gbdx idaho-pansharpened
Yes
pl PSOrthoTile
Yes
pl PSScene4Band
Yes
ee COPERNICUS/S2


Yes


wrun
Segments imagery into 4 classes:
  • Water
  • Roads
  • Urban
  • Clouds

Each pixel is exclusively assigned to one of aforementioned classes.

water.png
roads.png
urban.png
nonurban.png
segmentation.ski
analysis.geotiff
visualization.geotiff

metadata.json







ee COPERNICUS/S1_GRD







No







cars Segmentation of cars and trucks.
cars.png
trucks.png
segmentation.ski
analysis.geotiff
visualization.geotiff
detections.geojson
metadata.json



gbdx idaho-pansharpened



Yes




containers Segmentation of cargo containers.
containers.png
segmentation.ski
analysis.geotiff
visualization.geotiff
metadata.json



gbdx idaho-pansharpened



Yes



destruction Detects ruins of houses and infrastructure in war-zones.
destruction-medium.png
destruction-heavy.png
road-destruction.png
segmentation.ski
analysis.geotiff
visualization.geotiff
metadata.json





gbdx idaho-pansharpened





No





boats Detects boats with length smaller or equal to 30 meters. Boats are also detected as ships in ships map type, i.e. boats class is a subset of ships class.
boats.png
segmentation.ski
analysis.geotiff
visualization.geotiff
detections.geojson
metadata.json


gbdx idaho-pansharpened



Yes



solar-panels Segmentation of solar panels.
solar-panels.png
segmentation.ski
analysis.geotiff
visualization.geotiff
detections.geojson
metadata.json


gbdx idaho-pansharpened



No



pools Segmentation of swimming pools.
pools.png
segmentation.ski
analysis.geotiff
visualization.geotiff
detections.geojson
metadata.json


gbdx idaho-pansharpened



Yes



houses Detects houses and house constructions (medium and early phases).
houses.png
construction-medium.png
constructions-early.png
segmentation.ski
analysis.geotiff
visualization.geotiff
detections.geojson
metadata.json




gbdx idaho-pansharpened





No





coal Detects piles of coal.
coal.png
segmentation.ski
analysis.geotiff
visualization.geotiff
metadata.json



ee COPERNICUS/S2



No



cranes Detects individual construction cranes.
cranes.png
segmentation.ski
analysis.geotiff
visualization.geotiff
detections.geojson
metadata.json


gbdx idaho-pansharpened



No



ips-deadwood  
ips-deadwood.png
segmentation.ski
analysis.geotiff
visualization.geotiff

metadata.json
detections.geojson
detections.geojson


ee COPERNICUS/S2
No
pl PSOrthoTile
No
gbdx idaho-pansharpened
No
ips-baresoil  
ips-baresoil.png
segmentation.ski
analysis.geotiff
visualization.geotiff
metadata.json



ee COPERNICUS/S2
No
pl PSOrthoTile

No

lithium Detects piles of lithium.
lithium.png
segmentation.ski
analysis.geotiff
visualization.geotiff
metadata.json



ee COPERNICUS/S2



No



cows Detects clusters of cows.
cows.png
segmentation.ski
analysis.geotiff
visualization.geotiff
detections.geojson
metadata.json


gbdx idaho-pansharpened



No



change Detects changes in a new image as compared to an old image. Internally uses output of WRUNC.
heatmap.png
heatmap.ski
analysis.geotiff
visualization.geotiff


attention_regions.geojson
metadata.json




gbdx idaho-pansharpened
Yes
pl PSOrthoTile
Yes
ee COPERNICUS/S2
Yes

change-urban- roads Detects change in a new image compared to an old image on a union of urban and roads areas detected by WRUNC algorithm in both images.
heatmap.png
heatmap.ski
analysis.geotiff
visualization.geotiff


attention_regions.geojson
metadata.json




gbdx idaho-pansharpened
Yes
pl PSOrthoTile
Yes
ee COPERNICUS/S2
Yes

sar-blobs Detects blobs at open water areas in a SAR (Synthetic-Aperture Radar) image.
sar-blobs.png
segmentation.ski
analysis.geotiff
visualization.geotiff
detections.geojson
metadata.json


ee COPERNICUS/S1_GRD



No



sar-diff Detects differences in a new SAR (Synthetic-Aperture Radar) image compared to an old SAR image.
heatmap.png
heatmap.ski
analysis.geotiff
visualization.geotiff
attention_regions.geojson
metadata.json


ee COPERNICUS/S1_GRD



No



sar-change Detects changes in a new SAR (Synthetic-Aperture Radar) image compared to an old SAR image.
heatmap.png
heatmap.ski
analysis.geotiff
visualization.geotiff
attention_regions.geojson
metadata.json


ee COPERNICUS/S1_GRD



No



prenormalized- sar-diff Detects differences in a new SAR (Synthetic-Aperture Radar) image compared to an old SAR image.
heatmap.png
heatmap.ski
analysis.geotiff
visualization.geotiff
attention_regions.geojson
metadata.json


ee COPERNICUS/S1_GRD



No



prenormalized- sar-change Detects changes in a new SAR (Synthetic-Aperture Radar) image compared to an old SAR image.
heatmap.png
heatmap.ski
analysis.geotiff
visualization.geotiff
attention_regions.geojson
metadata.json


ee COPERNICUS/S1_GRD



No



wrunc-change Detects differences in WRUNC outputs of a new and an old image.
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
analysis.geotiff
visualization.geotiff
metadata.json
attention_regions.geojson











gbdx idaho-pansharpened
No
pl PSOrthoTile
No
ee COPERNICUS/S2







No








eme Detects earthmoving equipment (excavators, backhoe loaders and bulldozers). Currently works only on images from WV03_VNIR satellite.
eme.png
segmentation.ski
analysis.geotiff
visualization.geotiff
detections.geojson
metadata.json


gbdx idaho-pansharpened



No



trees Detects clusters of trees
trees.png
segmentation.ski
analysis.geotiff
visualization.geotiff
detections.geojson
metadata.json


gbdx idaho-pansharpened



Yes



ndvi Normalized Difference Vegetation Index.
heatmap.png
heatmap.ski
analysis.geotiff
visualization.geotiff





metadata.json








gbdx idaho-pansharpened
Yes
pl PSOrthoTile
Yes
ee LANDSAT/LE07/C01/T1
Yes
ee LANDSAT/LC08/C01/T1
Yes
ee COPERNICUS/S2
Yes
ndbi Normalized Difference Buildup Index.
heatmap.png
heatmap.ski
analysis.geotiff
visualization.geotiff

metadata.json




ee LANDSAT/LE07/C01/T1
Yes
ee LANDSAT/LC08/C01/T1
Yes
ee COPERNICUS/S2
Yes
ndmi Normalized Difference Multipurpose Index.
heatmap.png
heatmap.ski
analysis.geotiff
visualization.geotiff

metadata.json




ee LANDSAT/LE07/C01/T1
Yes
ee LANDSAT/LC08/C01/T1
Yes
ee COPERNICUS/S2
Yes
ndwi Normalized Difference Water Index.
heatmap.png
heatmap.ski
analysis.geotiff
visualization.geotiff

metadata.json




ee LANDSAT/LE07/C01/T1
Yes
ee LANDSAT/LC08/C01/T1
Yes
ee COPERNICUS/S2
Yes
evi Enhanced Vegetation Index.
heatmap.png
heatmap.ski
analysis.geotiff
visualization.geotiff

metadata.json




ee LANDSAT/LE07/C01/T1
Yes
ee LANDSAT/LC08/C01/T1
Yes
ee COPERNICUS/S2
Yes
savi Soil Adjusted Vegetation Index.
heatmap.png
heatmap.ski
analysis.geotiff
visualization.geotiff

metadata.json




ee LANDSAT/LE07/C01/T1
Yes
ee LANDSAT/LC08/C01/T1
Yes
ee COPERNICUS/S2
Yes
msavi2 Modified Soil Adjusted Vegetation Index.
heatmap.png
heatmap.ski
analysis.geotiff
visualization.geotiff

metadata.json




ee LANDSAT/LE07/C01/T1
Yes
ee LANDSAT/LC08/C01/T1
Yes
ee COPERNICUS/S2
Yes
weather Detects clouds and snow covered land.
clouds.png
snow.png
segmentation.ski
analysis.geotiff
visualization.geotiff
metadata.json




pl PSOrthoTile




No




nl-change- daily Detects change in night-light daily composites.
nl-change.png
nl-change.ski
analysis.geotiff
visualization.geotiff
metadata.json



noaa VIIRS/Daily



No



nl-change- monthly Detects change in night-light monthly composites.
nl-change.png
nl-change.ski
analysis.geotiff
visualization.geotiff
metadata.json



noaa VIIRS/Monthly



No



oil-pads Detects oil pads.
oil-pads.png
segmentation.ski
analysis.geotiff
visualization.geotiff
detections.geojson
metadata.json


ee COPERNICUS/S2



No



flare-blobs Detects flare blobs.
flare-blobs.png
segmentation.ski
analysis.geotiff
visualization.geotiff
detections.geojson
metadata.json


ee COPERNICUS/S2
No
ee LANDSAT/LC08/C01/T1

No

gas-flares Detects gas flares.
gas-flares.png
segmentation.ski
analysis.geotiff
visualization.geotiff
detections.geojson
metadata.json


ee COPERNICUS/S2



No



normalized- imagery Normalized SAR imagery.
normalized_imagery.png
imagery.ski
analysis.geotiff
visualization.geotiff
metadata.json



ee COPERNICUS/S1_GRD



Yes



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

[1]Only images with GSD lower than 0.55.
[2](1, 2, 3) Change detection can run only between provider-datasets within supported groups: {gbdx}, {pl} and {ee}.
[3]Whether the algorithm was trained on dataset which was sampled from all over the globe.

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 using the following endpoint.

GET /kraken/grid/<map_id>/<geometry_id>/<z>/<x>/<y>/<file_name>
Parameters:
  • map_id (string) – ID of a map returned by the retrieve endpoint.
  • geometry_id (string) – For internal use only, use -.
  • z (int) – Zoom level of the tile.
  • x (int) – Horizontal coordinate of the tile.
  • y (int) – Vertical coordinate of the tile.
  • file_name (string) – One of the output files available for the released map type that should be returned. See the documentation of individual Kraken map types above.
Query Parameters:
 
  • force_download (int) – Set to 1 to download chosen output file even if the file has all pixels invalid.
  • download_unclipped (int) – Set to 1 to disable clipping of tiles to requested geometry in the Grid endpoint. kraken.download-unclipped permission needed.
Status Codes:
  • 200 OK – File is present and has valid data.
  • 204 No Content – PNG/SKI does not have valid pixels in requested area, this behaviour can be overridden by setting force_download to 1.
  • 400 Bad Request – Invalid request: a possible reason is invalid or expired map ID.
  • 401 Unauthorized – Given map ID doesn’t include requested tile.
  • 404 Not Found – Requested tile doesn’t exist: data are not available or the area of the tile cannot be analyzed.

Example requests:

GET /kraken/grid/xyz/-/19/83861/202628/truecolor.png HTTP/1.1
GET /kraken/grid/abc/-/19/83861/202628/aircraft.png HTTP/1.1
GET /kraken/grid/abc/-/19/83861/202628/segmentation.ski HTTP/1.1
GET /kraken/grid/abc/-/19/83861/202628/detections.geojson HTTP/1.1
GET /kraken/grid/abc/-/19/83861/202628/metadata.json HTTP/1.1

.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

Use this endpoint to get the size of ingested imagery and analysis. Useful for predicting costs of a particular analysis before it’s run.

Needed Permissions:

  • admin.tasking.get-pipeline
POST /kraken/dry-run/initiate
Request JSON Object:
 
  • sceneIds (list) – required; IDs of scenes from which the dry-run should be generated.
  • extent (object) – required; area of interest which must intersect with scene’s footprint.
  • mapTypes (list) – required; list of Kraken map types to use.

Example request:

{
    "sceneId": "GuoBFqt3SA6Qu5Uzx5Vt0JXdqGRKROhNsnUSS0ZDjEH_bzFFqvvmQtN0aw",
    "mapTypes": ["imagery","cars","wrunc"],
    "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:

Request JSON Object:
 
  • ingested (float) – square kilometres of area that would be downloaded from the imagery provider.
  • analyzed (float) – square kilometres of area that would be analyzed.
  • kraken (float) – square kilometres of area that would be moved from Ragnar to Kraken.
{
    "ingested": 100.69,
    "kraken": 75.434,
    "analyzed": 50.23
}