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

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 and uses uniform URL paths with format /kraken/release/<map_type>/tiles/{initiate|release}.

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.

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 provider == 'gbdx' and dataset == 'preview':
    r_e = 15
elif 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/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.

Example response:

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

Release Imagery

Imagery maps have truecolor.png tile files.

POST /kraken/release/imagery/tiles/initiate

See generic initiate endpoint.

POST /kraken/release/imagery/tiles/retrieve

See generic retrieve endpoint.

Release Aircraft

Aircraft maps have aircraft.png and detections.geojson (with this form) tile files.

Supported Imagery:

  • gbdx / idaho-pansharpened
  • ab / pleiades
  • pl / PSOrthoTile – only images with GSD lower than 3.5
POST /kraken/release/aircraft/tiles/initiate

See generic initiate endpoint.

POST /kraken/release/aircraft/tiles/retrieve

See generic retrieve endpoint.

Release Ships

Ships maps have ships.png and detections.geojson (with this form) tile files.

Supported Imagery:

  • gbdx / idaho-pansharpened
  • ab / pleiades
  • pl / PSOrthoTile – only images with GSD lower than 3.5
POST /kraken/release/ships/tiles/initiate

See generic initiate endpoint.

POST /kraken/release/ships/tiles/retrieve

See generic retrieve endpoint.

Release WRUNC

WRUNC maps have water.png, roads.png, urban.png, nonurban.png, clouds.png and area.json (with this form) tile files.

Supported Imagery:

  • gbdx / idaho-pansharpened
  • ab / pleiades
  • pl / PSOrthoTile – only images with GSD lower than 3.5
POST /kraken/release/wrunc/tiles/initiate

See generic initiate endpoint.

POST /kraken/release/wrunc/tiles/retrieve

See generic retrieve endpoint.

Release Cars

Cars maps have cars.png, trucks.png and detections.geojson (with this form) tile files.

Supported Imagery:

  • gbdx / idaho-pansharpened – only images with GSD lower than 0.55
POST /kraken/release/cars/tiles/initiate

See generic initiate endpoint.

POST /kraken/release/cars/tiles/retrieve

See generic retrieve endpoint.

Release Containers

Cargo containers maps have containers.png and area.json (with this form) tile files.

Supported Imagery:

  • gbdx / idaho-pansharpened
  • ab / pleiades
POST /kraken/release/containers/tiles/initiate

See generic initiate endpoint.

POST /kraken/release/containers/tiles/retrieve

See generic retrieve endpoint.

Release Boats

Boats maps have boats.png and detections.geojson (with this form) tile files.

Supported Imagery:

  • gbdx / idaho-pansharpened
  • ab / pleiades
POST /kraken/release/boats/tiles/initiate

See generic initiate endpoint.

POST /kraken/release/boats/tiles/retrieve

See generic retrieve endpoint.

Release Solar Panels

Maps of solar panels have solar-panels.png and area.json (with this form) tile files.

Supported Imagery:

  • gbdx / idaho-pansharpened
POST /kraken/release/solar-panels/tiles/initiate

See generic initiate endpoint.

POST /kraken/release/solar-panels/tiles/retrieve

See generic retrieve endpoint.

Release Swimming Pools

Swimming pools maps have pools.png and detections.geojson (with this form) tile files.

Supported Imagery:

  • gbdx / idaho-pansharpened
POST /kraken/release/pools/tiles/initiate

See generic initiate endpoint.

POST /kraken/release/pools/tiles/retrieve

See generic retrieve endpoint.

Release Change Detection

Detects changes in a new image as compared to an old image. Change detection have heatmap.png and attention_regions.geojson (with this form) tile files.

Change detection can run only between provider-datasets within any of supported groups.

Supported Imagery Groups:

  • gbdx / idaho-pansharpened, ab / pleiades
  • pl / PSOrthoTile
POST /kraken/release/change/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/change/tiles/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