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, CARS

  • 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. CARS.

Note

The area must be allocated using Credits API.

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/initiate
Request JSON Object:

  • mapType (string) – optional; Map type to be analyzed. This parameter is exclusive with mapTypes parameter. This parameter is deprecated and will be removed on 2023-04-01.

  • mapTypes (list) – optional; Map types to be analyzed.

  • sceneIds (list) – required; ID of scene(s) from which the map should be generated. See Ragnar API (Search Imagery). Number of input scenes depends on given map type, single input map types require 1 sceneIds, pairwise map types require 2 sceneIds and N-wise map types require k or more sceneIds. Value of k is dependent on exact N-wise map type used but it is always at least 2.

  • extent (object) – required; area of interest which must intersect with scene’s footprint, see Extent.

  • subGeometry (object) – optional; Subset of extent of interest. If provided the response contains subGeometryId which can later be used in Kraken Grid endpoint to crop result of analysis. See Release with subGeometry.

  • clippedImagery (bool) – optional; Only scene clipped to the requested extent is downloaded from the provider. This effectively hashes scene per geometry and creates new scene_id. Usable only with tiled Planet datasets and extents that contains less than 15 MPix of imagery.

Example request:

{
    "mapTypes": ["imagery", "cars"],
    "sceneIds": ["abc"],
    "extent": {
        "type": "MultiPolygon",
        "coordinates": [
            [
                [
                    [-122.51, 37.69],
                    [-122.35, 37.69],
                    [-122.35, 37.80],
                    [-122.51, 37.80],
                    [-122.51, 37.69]
                ]
            ]
        ]
    },
    "subGeometry": {
        "type": "Polygon",
        "coordinates": [
            [
                [-122.49, 37.71],
                [-122.44, 37.71],
                [-122.44, 37.77],
                [-122.49, 37.77],
                [-122.49, 37.71]
            ]
        ]
    }
}

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/retrieve

Example request:

See pipeline retrieve.

Response JSON Object:

  • maps (list) – list of successfully analyzed maps

  • failedMapTypes (list) – list of map types for which the analysis failed

  • maps[i].mapId (string) – map ID to be used to access map tiles

  • maps[i].mapType (string) – map type of the result

  • maps[i].maxZoom (int) – maximum zoom available for returned mapId

  • maps[i].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:

{
    "imagery": {
        "mapId": "xyz",
        "maxZoom": 19,
        "status": "succeeded",
        "tiles": [
            [19, 83861, 202628]
        ]
    },
    "cars": {
        "mapId": "xyz",
        "maxZoom": 19,
        "status": "succeeded",
        "tiles": [
            [19, 83861, 202628]
        ]
    },
    "aircraft": {
        "errorCode": "ZERO-TILES-AVAILABLE",
        "errorMessage": "No tile has been successfully generated.",
        "status": "failed"
    }
}

Deprecated version of this endpoint when mapType parameter was supplied to initiate endpoint (will be removed on 2023-04-01):

Example request:

See pipeline retrieve.

>json string mapId:

map ID to be used to access map tiles.

>json int maxZoom:

maximum zoom available for returned mapId.

>json list tiles:

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

Use this endpoint to generate pairs from a list of scenes according to chosen pairing type and other options. Each pair can be afterwards analyzed with pairwise map types through Kraken release.

Needed Permissions:

  • imagery.availability

POST /kraken/pairwise/initiate
Request JSON Object:

  • sceneIds (list) – required; IDs of scenes from which the pairs should be generated.

  • extent (object) – required; area of interest which must intersect with footprints of both scenes.

  • periodicity (string) – optional; Periodicity used to generate slots. Supported periodicities are none, daily, weekly, amweekly, semi-monthly (two samples per each month 1-14, 15+), monthly, quarterly and yearly.

  • minIntersection (float) – optional; Minimum required intersection of the scenes in sq km. Defaults to 0.

  • pairingType (float) –

    optional; Possible options:

    • continuous create pairs from all successive records. Default value.

    • first pairs the first record (sorted by time of the occurrence) in the input to the rest of the records.

    • yoy pairs records with one year of time between them with some leeway to mitigate seasonality, see –max-yoy-delta.

  • maxYoyDelta (float) – optional; Maximum deviation from exact year over year pairing in days. Use decimal number for more accuracy. Only applicable for yoy pairing. Defaults to 15.0.

  • minDayDelta (float) – optional; SAR specific. Minimum span between paired scenes in days. Defaults to 0.0.

  • maxDayDelta (float) – optional; SAR specific. Maximum span between paired scenes in days. Defaults to unlimited day difference.

  • onlyTopOrbitNumber (bool) – optional; SAR specific. Whether to include only scene set with same relative orbit number and orbit pass that has most occurrences in input. Defaults to False.

Example request:

{
    "sceneIds": ["scene_id1","scene_id2","scene_id3"],
    "periodicity": "daily",
    "extent": {
        "type": "Polygon",
        "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:

  • pairwise (list) – list of paired scenes. Dictionary contains oldSceneId and newSceneId.

{
    "pairwise": [
        {"oldSceneId": "scene_id1", "oldSceneId": "scene_id2"},
        {"oldSceneId": "scene_id2", "oldSceneId": "scene_id3"}
    ]
}

Kraken N-wise API

Use this endpoint to generate groups from a list of scenes according to chosen parameters. Each group can be afterwards analyzed with N-wise map types through Kraken release.

The endpoint fails with SCENES-WITH-SAME-DATETIME error if two scenes within one relative orbit number group have identical datetimes. Scenes must be deduplicated on datetime before sending them to the endpoint.

Needed Permissions:

  • imagery.availability

POST /kraken/nwise/initiate
Request JSON Object:

  • groupingType (string) – required; grouping type, either windowed or cumulated or cumulated-yoy

  • sceneIds (list) – required; IDs of scenes from which the pairs should be generated.

  • extent (object) – required; area of interest which must intersect with footprints of both scenes.

  • windowStart (string) – optional; date from which to start calculating group windows. Required in windowed groupingType.

  • windowSizeDays (int) – optional; length of the window for one group to fit in. Required in windowed groupingType.

  • windowStepDays (float) – optional; spacing between windows for grouping. Required in windowed groupingType.

  • startDate (string) – optional; start date of window of interest. Required in cumulated-yoy groupingType.

  • endDate (string) – optional; end date of window of interest. Required in cumulated-yoy groupingType.

  • yoyPairMinIntersectionKm2 (float) – optional; minimum intersection area for the scene pair to be considered for YoY pairing. Required in cumulated-yoy groupingType.

  • minScenes (int) – optional; minimum number of scenes within returned group. Only usable in cumulated groupingType. Defaults to 3.

Example request:

{
    "groupingType": "windowed",
    "sceneIds": ["scene_id1","scene_id2","scene_id3","scene_id4"],
    "extent": {
        "type": "Polygon",
        "coordinates": [
            [
                [
                    [-122.51747131348, 37.694823535365],
                    [-122.35130310059, 37.694823535365],
                    [-122.35130310059, 37.809919574016],
                    [-122.51747131348, 37.809919574016],
                    [-122.51747131348, 37.694823535365]
                ]
            ]
        ]
    },
    "windowSizeDays": 20,
    "windowStart": "2021-01-10",
    "windowStepDays": 10
}

Example response:

Request JSON Object:

  • nwise (list) – list of groups of scene IDs.

{
    "nwise": [
        ["scene_id1", "scene_id2", "scene_id3"],
        ["scene_id2", "scene_id3", "scene_id4"],
    ]
}

Example request:

{
    "groupingType": "cumulated",
    "sceneIds": ["scene_id1","scene_id2","scene_id3","scene_id4"],
    "extent": {
        "type": "Polygon",
        "coordinates": [
            [
                [
                    [-122.51747131348, 37.694823535365],
                    [-122.35130310059, 37.694823535365],
                    [-122.35130310059, 37.809919574016],
                    [-122.51747131348, 37.809919574016],
                    [-122.51747131348, 37.694823535365]
                ]
            ]
        ]
    },
    "minScenes": 3
}

Example response:

{
    "nwise": [
        ["scene_id1", "scene_id2", "scene_id3"],
        ["scene_id1", "scene_id2", "scene_id3", "scene_id4"],
    ]
}

Example request:

{
    "groupingType": "cumulated",
    "sceneIds": ["scene_id1", "scene_id2", "scene_id3", "scene_id4", "scene_id5", "scene_id6"],
    "extent": {
        "type": "Polygon",
        "coordinates": [
            [
                [
                    [-122.51747131348, 37.694823535365],
                    [-122.35130310059, 37.694823535365],
                    [-122.35130310059, 37.809919574016],
                    [-122.51747131348, 37.809919574016],
                    [-122.51747131348, 37.694823535365]
                ]
            ]
        ]
    },
    "startDate": "2021-05-01",
    "endDate": "2021-10-01",
    "yoyPairMinIntersectionKm2": 0,
}

Example response:

{
    "nwise": [
        ["scene_id1", "scene_id2", "scene_id3", "scene_id4", "scene_id5", "scene_id6"],
    ]
}

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) – Optional; Set to 1 to download chosen output file even if the file has all pixels invalid.

  • download_unclipped (int) – Optional; Set to 1 to disable clipping of tiles to requested geometry in the Grid endpoint. kraken.download-unclipped permission needed.

  • user_threshold (float) – Optional; If given binarize grid files according to the user threshold. The value must be in [0, 1] interval. Only available for pixel index algorithms. Only available for metadata.json and PNG grid files.

  • detection_filters (string) – Optional; If given filter features in vector grid file according to detection filters. The value is set of lines (conditions) which consists of three space-separated items: property, condition, value. Example area gt 1000nwidth lt 100 Only available for detections.geojson grid files.

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:

  • kraken.dry-run

POST /kraken/dry-run/initiate
Request JSON Object:

  • extent (object) – required; area of interest which must intersect with scene’s footprint.

  • dryRuns (list) – required; list of dry run dictionaries. Contains a list of Kraken map types to use. Also contains list of lists with sceneIds. Scene list can contain single scene_id for single algorithms or multiple scenes for change or n-wise algorithm.

  • ignoreCache (bool) – optional; true value skips checking previously cached results.

  • allocate (bool) – optional; if set to true allocate requested scenes and tiles for group of which userId client is part of. If not present or set to false it only checks credits and area required for allocation.

Example request:

{
  "dryRuns": [
    {
      "scenes": [["DXc_fDD2aRjkHVOJ4elbKQ"],["DXc_fDD2aRjkHVOJ4elbKg"]]
      ],
      "mapTypes": ["imagery", "cars", "wrunc"]
    },
    {
      "scenes": [["DXc_fDD2aRjkHVOJ4elbKQ", "DXc_fDD2aRjkHVOJ4elbKg"]}
      ],
      "mapTypes": ["wrunc-change", "change" ]
    }
  ],
  "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:

Response JSON Object:

  • ingestedKm2 (float) – square kilometres of area that would be downloaded from the imagery provider.

  • analyzedKm2 (float) – square kilometres of area that would be analyzed.

  • krakenKm2 (float) – square kilometres of area that would be moved from Ragnar to Kraken.

  • allocatedKm2 (float) – number of \(km^2\) required/allocated.

  • allocatedCredits (float) – number of credits required/allocated.

{
    "ingestedKm2": 100.69,
    "krakenKm2": 75.434,
    "analyzedKm2": 50.23,
    "allocatedKm2": 100.69,
    "allocatedCredits":1.06
}

Kraken MapType

Use this endpoint to see which algorithms you can access. Useful to determine the name of the algorithm to run.

Needed Permissions:

  • kraken.release

POST /kraken/map-types/list

Example request:

{}

Example response:

Response JSON Object:

  • mapType (str) – the name of the algorithm.

  • description (str) – the short description of the algorithm

  • gridFiles (dict) – available grid files for given mapType per suffix

  • availableDatasets (dict) – available datasets grouped per provider

[
    {
        "mapType": "cars",
        "description": "Car detection algorithm",
        "gridFiles": {
            "png": ["cars.png", "trucks.png"],
            "ski": ["segmentation.ski"],
            "geojson": ["detections.geojson"],
            "json": ["metadata.json"],
            "geotiff": ["analysis.geotiff", "visualization.geotiff"]},
        "availableDatasets": {
            "gbdx": [["idaho-pansharpened", {
                        "version": "some-number",
                        "is_global": true,
                        "max_gsd": null,
                        "margin_m": 0,
                        "margin_px": 80,
                        "min_size_px": 0,
                        "resolution": null
                    }]],
            "pl": [["PSOrthoTile", {
                        "version": "some-number2",
                        "is_global": false,
                        "max_gsd": 4.5,
                        "margin_m": 0,
                        "margin_px": 80,
                        "min_size_px": 0,
                        "resolution": 3.125
                    }]]}
    },
    {
        "mapType": "ships",
        "description": "Ship detection algorithm",
        "gridFiles": {
            "png": ["aircraft.png"],
            "ski": ["segmentation.ski"],
            "geojson": ["detections.geojson"],
            "json": ["metadata.json"],
            "geotiff": ["analysis.geotiff", "visualization.geotiff"]},
        "availableDatasets": {
            "gbdx": [["idaho-pansharpened", {
                        "version": "some-number3",
                        "is_global": true,
                        "max_gsd": null,
                        "margin_m": 100,
                        "margin_px": 0,
                        "min_size_px": 0,
                        "resolution": 0.3
                    }]],
            "pl": [["PSOrthoTile", {
                        "version": "some-number4",
                        "is_global": true,
                        "max_gsd": 4.5,
                        "margin_m": 100,
                        "margin_px": 80,
                        "min_size_px": 0,
                        "resolution": 3.125
                    }]]}
    }
]