API docs by Redocly

SpaceKnow API (1.0)

Download OpenAPI specification:Download

API Support: support@spaceknow.com

Credits

Area Check Geojson

This API endpoint can be used to check whether a client (the group (s)he is part of) has allocation for an area in given scenes. The group license must not be expired in order to use this endpoint.

Needed permissions: credits.check-area

Request Body schema: application/json
required
sceneIds
required
Array of strings (Sceneids) non-empty

List of sceneIds, obtained from e.g. Ragnar search.

required
any (Geojson)

GeoJSON in WGS84 coordinates enclosing area to be checked. The GeoJSON must be within -85 to 85 degrees of latitude.

Userid (string) or Userid (null) (Userid)

Check area for this user. If not provided ID of the user making the request is used. Specifying other user ID requires special permissions.

Creditstier (string) or Creditstier (null) (Creditstier)

Responses

Request samples

Content type
application/json
{
  • "costFreeAllocation": false,
  • "geojson": {
    },
  • "sceneIds": [
    ]
}

Response samples

Content type
application/json
{
  • "cost": 1.25,
  • "km2": 2.5
}

Group List Transactions

List all transactions for a group that user belongs to. Note: Transactions were introduced 2022-11. Note: There can be several allocations with a single preallocationId. In such cases, the amount of credit is shared among those allocations. I.e. given there are three allocations with 10 credits each. It means that there were 10 credits spent in total for all of those 3 allocations.

This endpoint supports only user authentication.

Dynamically needed permissions: Requires admin.credits.list-group-transactions if groupId is set. Requires credits.list-group-transactions otherwise.

Request Body schema: application/json
required
Groupid (string) or Groupid (null) (Groupid)

ID of the group to get.

Cursor (string) or Cursor (null) (Cursor)

Use to retrieve more data if the results do not fit into response of one endpoint call.

Responses

Request samples

Content type
application/json
{
  • "cursor": "MQ=="
}

Response samples

Content type
application/json
{
  • "cursor": "MQ==",
  • "results": [
    ]
}

Group List Allocations

List all allocations for the group. This endpoint supports only user authentication.

Dynamically needed permissions: Requires admin.credits.list-group-allocations if groupId is set. Requires ``credits.list-group-allocations` otherwise.

Request Body schema: application/json
required
Groupid (string) or Groupid (null) (Groupid)

ID of the group to get.

Cursor (string) or Cursor (null) (Cursor)

Use to retrieve more data if the results do not fit into response of one endpoint call.

Responses

Request samples

Content type
application/json
{
  • "cursor": "MQ=="
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

User Set Credit Limit

Set user credit limit. Also requires admin.users.manage permission if the changed user is not a member of the same group as the user changing the limit.

This endpoint supports only user authentication. Needed permissions: admin.credits.set-user-credit-limit

Request Body schema: application/json
required
userId
required
string (Userid) non-empty

User Auth0 ID to set the limit to.

Creditlimit (number) or Creditlimit (null) (Creditlimit)

Credit limit to be set for given user. Omit or set to None to unset the limit.

Responses

Request samples

Content type
application/json
{
  • "creditLimit": 123.4,
  • "userId": "user-id"
}

Response samples

Content type
application/json
{ }

User Get

Get credits information for a given user. Needed permissions: credits.user-info

Request Body schema: application/json
required
Userid (string) or Userid (null) (Userid)

Get credits information for this user. If not provided, credits information for the current user will be returned. Requires special permissions.

Responses

Request samples

Content type
application/json
{
  • "userId": "auth0|8e9c9d314376cb2319e14606"
}

Response samples

Content type
application/json
{
  • "creditsTier": "basic",
  • "email": "user@example.com",
  • "groupId": "group_123",
  • "id": "auth0|8e9c9d314376cb2319e14606",
  • "name": "John Doe",
  • "remainingCredit": 900,
  • "usedCredit": 100
}

Datacube

Aois Get

This endpoint lists all AoIs available for filtering of data-points in Datacube. You may be limited to a subset of these AoIs, please contact SpaceKnow representatives to get access to more.

Needed permissions: datacube.get

Request Body schema: application/json
required
object (EmptyParams)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    }
]

Catalogue Get

This endpoint lists catalogue of data-points available in Datacube. Different algorithms are available for different regions, date ranges, and their inputs come from different sources.

This endpoint supports only user authentication. Needed permissions: datacube.get

Request Body schema: application/json
required
Version (string) or Version (null) (Version)

Search for specific version.

Project (string) or Project (null) (Project)

Search for specific project.

Source (string) or Source (null) (Source)

Search for specific source.

Algorithm (string) or Algorithm (null) (Algorithm)

Search for specific algorithm.

Aoiname (string) or "" (string) or Aoiname (null) (Aoiname)

Search for specific aoi name.

Aoilabel (string) or "" (string) or Aoilabel (null) (Aoilabel)

Search for specific aoi label.

Responses

Request samples

Content type
application/json
{
  • "algorithm": "ndmi_mean",
  • "aoiLabel": "cz",
  • "aoiName": "Czech Republic",
  • "project": "coal",
  • "source": "LANDSAT/LC08/C01/T1",
  • "version": "160"
}

Response samples

Content type
application/json
{
  • "ndmi_mean": [
    ],
  • "radiance_mean": [
    ]
}

Datapoints Get

Use this endpoint to get Datacube datapoints by filter. Needed permissions: datacube.get

Dynamically needed permissions: Requires datacube.get-aoi-positions if showAoiPositions is set. Requires datacube.get-aoi-tags if showAoiTags is set.

Request Body schema: application/json
required
filters
required
Array of objects (Filters)

Filter on single project and single algorithm is required; list of filters of data. Only data-points matching all filters are returned. See Filters.

Aggregator (string) or null
showAoiPositions
boolean (Showaoipositions)
Default: false

Set to true to include AoI midpoint positions in resulting CSV. Requires datacube.get-aoi-positions permission.

showAoiTags
boolean (Showaoitags)
Default: false

Set to true to include AoI tags i.e. industry, type, sub_type in resulting CSV. Requires datacube.get-aoi-tags permission.

PostprocessType (string) or null
Resample (string) or Resample (null) (Resample)

Resampling method for datapoints - weekly, monthly or yearly.

Array of Columns (strings) or Columns (null) (Columns)

Fetch only some of the columns.

keepDuplicates
boolean (Keepduplicates)
Default: false
keepAllVersions
boolean (Keepallversions)
Default: false

By default datacube results are filtered to only contain latest version that was matched by the query. By setting keepAllVersions to true this post-filter is removed.

Responses

Request samples

Content type
application/json
{
  • "filters": [
    ]
}

Response samples

Datapoints Get Initiate

Some queries to Datacube API can match a larger number of data-points than it is possible to query and return in time span of one HTTP request. Pass the same payload as to /datacube/datapoints/get to the asynchronous endpoint to initiate the query.

Needed permissions: datacube.get

Dynamically needed permissions: Requires datacube.get-aoi-positions if showAoiPositions is set. Requires datacube.get-aoi-tags if showAoiTags is set.

Request Body schema: application/json
required
filters
required
Array of objects (Filters)

Filter on single project and single algorithm is required; list of filters of data. Only data-points matching all filters are returned. See Filters.

Aggregator (string) or null
showAoiPositions
boolean (Showaoipositions)
Default: false

Set to true to include AoI midpoint positions in resulting CSV. Requires datacube.get-aoi-positions permission.

showAoiTags
boolean (Showaoitags)
Default: false

Set to true to include AoI tags i.e. industry, type, sub_type in resulting CSV. Requires datacube.get-aoi-tags permission.

PostprocessType (string) or null
Resample (string) or Resample (null) (Resample)

Resampling method for datapoints - weekly, monthly or yearly.

Array of Columns (strings) or Columns (null) (Columns)

Fetch only some of the columns.

keepDuplicates
boolean (Keepduplicates)
Default: false
keepAllVersions
boolean (Keepallversions)
Default: false

By default datacube results are filtered to only contain latest version that was matched by the query. By setting keepAllVersions to true this post-filter is removed.

Responses

Request samples

Content type
application/json
{
  • "filters": [
    ]
}

Response samples

Content type
application/json
{
  • "nextTry": 14,
  • "pipelineId": "abcdefabcdefabcdefab",
  • "status": "NEW"
}

Datapoints Get Retrieve

Retrieves result of calling asynchronous endpoint /datacube/datapoints/get/initiate.

Request Body schema: application/json
required
pipelineId
required
string (Pipelineid) = 20 characters

ID of the pipeline.

Responses

Request samples

Content type
application/json
{
  • "pipelineId": "abcdefabcdefabcdefab"
}

Response samples

Product Catalogue Get

This endpoint lists SpaceKnow products available in Datacube or gets particular product by its id. downloadable flag signals whether user have the ability to download listed product. User can filter out to only downloadable products by specifying downloadableOnly flag in request.

Needed permissions: datacube.get

Request Body schema: application/json
required
Productid (string) or Productid (null) (Productid)

Specific productId for which metadata should be shown.

downloadableOnly
boolean (Downloadableonly)
Default: false

Show only downloadable products.

Responses

Request samples

Content type
application/json
{
  • "downloadableOnly": true,
  • "productId": "SK_PI_C_CN_W"
}

Response samples

Content type
application/json
[
  • {
    }
]

Product Get

This API endpoint returns CSV containing the requested SpaceKnow Datacube product. See Get product doc.

Needed permissions: datacube.get

Request Body schema: application/json
required
productId
required
string (Productid) [ 1 .. 140 ] characters

Product ID of the requested product.

Pitdt (string) or Pitdt (null) (Pitdt)

Date in format 'YYYY-MM-DD'. Specify if you want to receive data as of the given date.

csvFormat
string (ApiCsvFormat)
Default: "simple"
Enum: "simple" "rich"

Choose between 'simple' and 'rich'. 'rich' is a superset of the 'simple' format adding more information and clarity for every product row.

Responses

Request samples

Content type
application/json
{
  • "csvFormat": "simple",
  • "pitDt": "2020-10-10",
  • "productId": "SK_PI_C_CN_W"
}

Response samples

Content type
application/json
"value_dt,delivery_dt,col A,col B\n 2020-09-17 08:41:17 UTC,2020-09-18 08:41:44 UTC,0.3,0.2\n 2020-09-17 08:43:24 UTC,2020-09-18 08:43:25 UTC,,0.3"

Product Sales Info Get

This endpoint serves a detailed data dictionary (sales information) for a given product ID in CSV format.

Needed permissions: datacube.get

Request Body schema: application/json
required
productId
required
string (Productid) [ 1 .. 140 ] characters

Product ID of the requested product.

Responses

Request samples

Content type
application/json
{
  • "productId": "SK_TRA_DIS_CON_LOG_ASI_US_D"
}

Response samples

Content type
application/json
"\n \"column_id\", \"topic\", \"type_of_index\", \"region\", \"frequency\", \"rolling\", \"value_type\", \"units\"\n \"SK_TRA_DIS_CON_LOG_ASI_US_D_30d_normal_activity_level\", \"Transport\", \"ASI - normal\", \"United States\", \"weekly\", \"30d\", \"activity\", \"%\"\n \"SK_TRA_DIS_CON_LOG_ASI_US_D_30d_high_activity_level\", \"Transport\", \"ASI - high\", \"United States\", \"weekly\", \"30d\", \"activity\", \"%\"\n \"SK_TRA_DIS_CON_LOG_ASI_US_D_30d_low_activity_level\", \"Transport\", \"ASI - low\", \"United States\", \"weekly\", \"30d\", \"activity\", \"%\"\n "

Kraken

Grid

A tile can be downloaded using the following endpoint. This endpoint is publicly accessible.

Dynamically needed permissions: Requires kraken.download-unclipped if download_unclipped is set.

path Parameters
signed_map_id
required
string (Signed Map Id)
Examples: abc

ID of a map returned by the /kraken/release/retrieve.

request_geometry_id
required
string (Request Geometry Id)
Examples: -

For internal use only, use -.

zoom
required
integer (Zoom)
Examples: 19

Zoom level of the tile.

x
required
integer (X)
Examples: 83861

Horizontal coordinate of the tile.

y
required
integer (Y)
Examples: 202628

Vertical coordinate of the tile.

file_name
required
string (File Name)
Examples: truecolor.png

One of the output files available for the released map type that should be returned. See grid files doc.

query Parameters
User Threshold (number) or User Threshold (null) (User Threshold)
Examples: user_threshold=0.5

If given binarize grid files according to the user threshold. The value must be in [-1, 1] interval. Only available for pixel index algorithms. Only available for metadata.json and PNG grid files.

download_unclipped
integer (_GridFlag)
Default: 0
Enum: 1 0
Examples: download_unclipped=1

Set to 1 to disable clipping of tiles to requested geometry in the Grid endpoint. kraken.download-unclipped permission needed.

force_download
integer (_GridFlag)
Default: 0
Enum: 1 0
Examples: force_download=1

Set to 1 to download chosen output file even if the file has all pixels invalid.

Classification (string) or Classification (null) (Classification)
Examples: classification=default

If given custom classification can be applied to detections.geojson grid files. This can filter out or rename detections and/or add additional context. Only available for detections.geojson grid files.

Detection Filters (string) or Detection Filters (null) (Detection Filters)
Examples: detection_filters=area gt 1000 width lt 100

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. Only available for detections.geojson grid files.

percentile_stretch
integer (_GridFlag)
Default: 0
Enum: 1 0
Examples: percentile_stretch=1

If set to true then stretch the imagery visualization between 0.5 and 99.5 percentile of pixel values for the whole scene. Fails with if percentiles are not available. Only available for truecolor.png and visualization.geotiff grid files.

Responses

Response samples

Content type
application/json
"string"

Grid

A tile can be downloaded using the following endpoint. This endpoint is publicly accessible.

Dynamically needed permissions: Requires kraken.download-unclipped if download_unclipped is set.

path Parameters
signed_map_id
required
string (Signed Map Id)
Examples: abc

ID of a map returned by the /kraken/release/retrieve.

request_geometry_id
required
string (Request Geometry Id)
Examples: -

For internal use only, use -.

zoom
required
integer (Zoom)
Examples: 19

Zoom level of the tile.

x
required
integer (X)
Examples: 83861

Horizontal coordinate of the tile.

y
required
integer (Y)
Examples: 202628

Vertical coordinate of the tile.

file_name
required
string (File Name)
Examples: truecolor.png

One of the output files available for the released map type that should be returned. See grid files doc.

query Parameters
User Threshold (number) or User Threshold (null) (User Threshold)
Examples: user_threshold=0.5

If given binarize grid files according to the user threshold. The value must be in [-1, 1] interval. Only available for pixel index algorithms. Only available for metadata.json and PNG grid files.

download_unclipped
integer (_GridFlag)
Default: 0
Enum: 1 0
Examples: download_unclipped=1

Set to 1 to disable clipping of tiles to requested geometry in the Grid endpoint. kraken.download-unclipped permission needed.

force_download
integer (_GridFlag)
Default: 0
Enum: 1 0
Examples: force_download=1

Set to 1 to download chosen output file even if the file has all pixels invalid.

Classification (string) or Classification (null) (Classification)
Examples: classification=default

If given custom classification can be applied to detections.geojson grid files. This can filter out or rename detections and/or add additional context. Only available for detections.geojson grid files.

Detection Filters (string) or Detection Filters (null) (Detection Filters)
Examples: detection_filters=area gt 1000 width lt 100

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. Only available for detections.geojson grid files.

percentile_stretch
integer (_GridFlag)
Default: 0
Enum: 1 0
Examples: percentile_stretch=1

If set to true then stretch the imagery visualization between 0.5 and 99.5 percentile of pixel values for the whole scene. Fails with if percentiles are not available. Only available for truecolor.png and visualization.geotiff grid files.

Responses

Response samples

Content type
application/json
"string"

Release Initiate

Use this API to trigger analysis over area specified by GeoJSON. Needed permissions: kraken.release

Dynamically needed permissions: Requires a set of permissions in the form <prefix>.<provider>.<dataset>. <prefix> is replaced with algorithms.<name-of-algorithm> or with imagery.images.

Request Body schema: application/json
required
mapTypes
required
Array of any (Maptypes)

Map types to be analyzed.

required
any (Extent)

Area of interest which must intersect with scene's footprint, see extent doc.

sceneIds
required
Array of strings (Sceneids)

ID of scene(s) from which the map should be generated. See Ragnar doc. 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.

Subgeometry (any) or Subgeometry (null) (Subgeometry)

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 sub geometry release doc.

Responses

Request samples

Content type
application/json
{
  • "extent": {
    },
  • "mapTypes": [
    ],
  • "onlyIngested": false,
  • "sceneIds": [
    ],
  • "subGeometry": {
    }
}

Response samples

Content type
application/json
{
  • "nextTry": 14,
  • "pipelineId": "abcdefabcdefabcdefab",
  • "status": "NEW"
}

Release Retrieve

Needed permissions: kraken.release

Request Body schema: application/json
required
pipelineId
required
string (Pipelineid) = 20 characters

ID of the pipeline.

Responses

Request samples

Content type
application/json
{
  • "pipelineId": "abcdefabcdefabcdefab"
}

Response samples

Content type
application/json
Example
{
  • "mapId": "xyz",
  • "maxZoom": 19,
  • "status": "succeeded",
  • "subGeometryId": "-",
  • "tiles": [
    ]
}

Dry Run Initiate

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

Request Body schema: application/json
required
required
Array of objects (Dryruns)

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

required
any (Extent)

Area of interest which must intersect with scene's footprint.

Responses

Request samples

Content type
application/json
{
  • "allocate": false,
  • "dryRuns": [
    ],
  • "extent": {
    },
  • "ignoreCache": false,
  • "onlyIngested": false
}

Response samples

Content type
application/json
{
  • "nextTry": 14,
  • "pipelineId": "abcdefabcdefabcdefab",
  • "status": "NEW"
}

Dry Run Retrieve

Use this endpoint to get retrieve results of dry run initiated by calling /kraken/dry-run/initiate.

Needed permissions: kraken.dry-run

Request Body schema: application/json
required
pipelineId
required
string (Pipelineid) = 20 characters

ID of the pipeline.

Responses

Request samples

Content type
application/json
{
  • "pipelineId": "abcdefabcdefabcdefab"
}

Response samples

Content type
application/json
{
  • "allocatedCredits": 1.06,
  • "allocatedKm2": 100.69,
  • "analyzedKm2": 50.23,
  • "ingestedKm2": 100.69,
  • "krakenKm2": 75.434,
  • "scenes": [
    ]
}

Pairwise Initiate

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

Needed permissions: imagery.availability

Request Body schema: application/json
required
sceneIds
required
Array of strings (Sceneids)

IDs of scenes from which the pairs should be generated.

required
any (Extent)

Area of interest which must intersect with footprints of both scenes.

Minintersection (number) or Minintersection (null) (Minintersection)

Minimum required intersection of the scenes in km^2. Defaults to 0.

PairingType (string) or null

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.
Periodicity (string) or null

Periodicity used to generate slots.

Mindaydelta (number) or Mindaydelta (null) (Mindaydelta)

SAR specific. Minimum span between paired scenes in days. Defaults to 0.0.

Maxdaydelta (number) or Maxdaydelta (null) (Maxdaydelta)

SAR specific. Maximum span between paired scenes in days. Defaults to unlimited day difference.

onlyTopOrbitNumber
boolean (Onlytoporbitnumber)
Default: false

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.

Maxyoydelta (number) or Maxyoydelta (null) (Maxyoydelta)

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.

Responses

Request samples

Content type
application/json
{
  • "extent": {
    },
  • "onlyTopOrbitNumber": false,
  • "periodicity": "daily",
  • "sceneIds": [
    ]
}

Response samples

Content type
application/json
{
  • "nextTry": 14,
  • "pipelineId": "abcdefabcdefabcdefab",
  • "status": "NEW"
}

Pairwise Retrieve

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

Needed permissions: imagery.availability

Request Body schema: application/json
required
pipelineId
required
string (Pipelineid) = 20 characters

ID of the pipeline.

Responses

Request samples

Content type
application/json
{
  • "pipelineId": "abcdefabcdefabcdefab"
}

Response samples

Content type
application/json
{
  • "pairwise": [
    ]
}

Nwise Initiate

Use this endpoint to generate groups from a list of scenes according to chosen parameters. Each group can be afterward analyzed with N-wise map types through /kraken/release/initiate. 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

Request Body schema: application/json
required
Any of
groupingType
required
string (Groupingtype)
Value: "cumulated"
sceneIds
required
Array of strings (Sceneids) >= 3 items

IDs of scenes from which the pairs should be generated.

required
any (Extent)

"Area of interest which must intersect with footprints of all scenes.

minScenes
integer (Minscenes) >= 3
Default: 3

Minimum number of scenes within returned group.

Responses

Request samples

Content type
application/json
Example
{
  • "extent": {
    },
  • "groupingType": "cumulated",
  • "minScenes": 3,
  • "sceneIds": [
    ]
}

Response samples

Content type
application/json
{
  • "nextTry": 14,
  • "pipelineId": "abcdefabcdefabcdefab",
  • "status": "NEW"
}

Nwise Retrieve

Needed permissions: imagery.availability

Request Body schema: application/json
required
pipelineId
required
string (Pipelineid) = 20 characters

ID of the pipeline.

Responses

Request samples

Content type
application/json
{
  • "pipelineId": "abcdefabcdefabcdefab"
}

Response samples

Content type
application/json
{
  • "nwise": [
    ]
}

Map Types

Use this endpoint to get classes with colors which were used by algorithm applied for map with given ID. Useful for obtaining colors based on map ID for anonymous users (as this endpoint does not require authentication).

This endpoint is publicly accessible.

path Parameters
signed_map_id
required
string (Signed Map Id)
Examples: abc

ID of a map returned by the /kraken/release/retrieve.

Responses

Response samples

Content type
application/json
{
  • "deprecatedClasses": {
    },
  • "mapType": "aircraft",
  • "segmentationClassification": {
    },
  • "segmentationMetadata": {
    }
}

Map Types

Use this endpoint to see which algorithms you can access. Useful to determine the name of the algorithm to run. Only map types that user has permissions for are listed.

This endpoint supports only user authentication. Needed permissions: kraken.release

Request Body schema: application/json
required
object (EmptyParams)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Imagery

Ingest Scene

A synchronous endpoint that ingests a single scene into Phoenix. The scene is immediately searchable and downloadable. Users with permission ingest-scene can ingest scene directly on frontend by clicking on Upload images(s) for creating analysis from main menu. The synchronous nature of the endpoint makes it unsuitable for ingesting large scenes on a non-local network. It is meant to work in on-prem deployments.

This endpoint supports only user authentication. Needed permissions: ingest-scene

path Parameters
provider
required
any (Provider-Input)
Examples: pl

Name of the provider.

Request Body schema: application/json
required
string <binary> (Stream) 
        Streamed binary file. Currently supported:
          * Airbus, Planet or Iceye ZIP files containing XML metadata and
            GeoTIFF/JPEG2000 image
          * GeoTIFFs/JPEG2000 created from our SKIs, e.g. exported using the
            ``/imagery/get-image/retrieve`` endpoint.

Responses

Request samples

Content type
application/json
"string"

Response samples

Content type
application/json
{
  • "ingestedScenes": [
    ]
}

Search Initiate

Initiates imagery search pipeline.

Dynamically needed permissions: Requires imagery.images.<provider>.<dataset> for each dataset provided. Requires phoenix.ingested if onlyIngested is set to True.

query Parameters
required
object (BaseRagnarSearchRequest)
Examples:

Responses

Response samples

Content type
application/json
{
  • "nextTry": 14,
  • "pipelineId": "abcdefabcdefabcdefab",
  • "status": "NEW"
}

Search Retrieve

Use this endpoint to retrieve imagery asynchronously searched for by calling /imagery/search/initiate.

Needed permissions: imagery.availability

Request Body schema: application/json
required
pipelineId
required
string (Pipelineid) = 20 characters

ID of the pipeline.

Responses

Request samples

Content type
application/json
{
  • "pipelineId": "abcdefabcdefabcdefab"
}

Response samples

Content type
application/json
{
  • "results": [
    ]
}

Scene Info

This API endpoint returns metadata of a single scene. Needed permissions: imagery.scene-info

Request Body schema: application/json
required
sceneId
required
string (Sceneid)

ID of a scene.

Array of Tiles (items) or Tiles (null) (Tiles)

List of tiles. Returned scene footprint will contain intersection between scene and provided tiles.

Responses

Request samples

Content type
application/json
{
  • "forceOffline": false,
  • "sceneId": "DXc_f1UsDLmqr3aA2rC9Dg",
  • "tiles": [
    ]
}

Response samples

Content type
application/json
{
  • "bands": [
    ],
  • "crsEpsg": 4326,
  • "dataset": "SkySatScene",
  • "datetime": "2015-11-13 02:34:12",
  • "footprint": {
    },
  • "foreignId": "1",
  • "offNadir": 23.135675,
  • "provider": "pl",
  • "satellite": "WV02",
  • "satelliteAzimuth": 104.794,
  • "sceneId": "DXc_f1UsDLmqr3aA2rC9Dg",
  • "sunAzimuth": 59.614758,
  • "sunElevation": 65.935
}

Datasets List

Use this endpoint to see which providers you can access. Useful to determine the name of the provider and dataset to search for.

Needed permissions: imagery.availability

Request Body schema: application/json
required
object (EmptyParams)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Get Image Initiate

Use this endpoint to initiate exporting a rectangular SKI from a source imagery of given extent. The maximum size of an image retrieved is 3MPx. When a specific scale (resolution) is given both original and scaled images have to be smaller than 3MPx.

Algorithm that determines the exact area covered by the image is as follows:
 - All vertices of requested extent GeoJSON are projected into coordinate
   system (CRS) of the scene.
 - Vertices in the scene's CRS are further projected to pixel coordinates.
   This step is done with the help of
   [pixel size and CRS origin metadata](https://docs.spaceknow.com/api/ragnar.html#api-ragnar-image-metadata-crs-epsg).
 - Minimum bounding rectangle (MBR) of pixel coordinates is calculated
   and its values are rounded to integers.
 - The image is a raster image that consists of pixels based on the
   calculated MBR.

Dynamically needed permissions: imagery.images.<provider>.<dataset>

Request Body schema: application/json
required
sceneId
required
string (Sceneid)

ID of the scene from which to construct an image. Scene IDs are returned by imagery search.

required
any (Extent)

Area of interest which must intersect with scene's footprint, see extent doc.

Resolution (number) or Resolution (null) (Resolution)

If given the image is re-scaled so its ground sampling distance approximately corresponds to the value. Units of this parameter are meters. All bands are scaled to the given resolution regardless their original sizes.

Exportraster (string) or Exportraster (null) (Exportraster)

If specified, a raster (depending on the chosen type) is returned instead of an SKI. The raster includes only Phoenix tiles that intersect with the given extent. When this flag is used, imagery cannot be rescaled to different resolution (i.e. option resolution cannot be specified). Exported raster can be up to 1GPx in size. Raster'ssceneId is generated by adding its footprint hash to foreignId - this is done to support ingestion of several rasters from different parts of the same (platform) scene.

Responses

Request samples

Content type
application/json
{
  • "extent": {
    },
  • "onlyIngested": false,
  • "sceneId": "DXc_f1UsDLmqr3aA2rC9Dg"
}

Response samples

Content type
application/json
{
  • "nextTry": 14,
  • "pipelineId": "abcdefabcdefabcdefab",
  • "status": "NEW"
}

Get Image Retrieve

Use this endpoint to retrieve SKI exported by calling asynchronous endpoint /imagery/get-image/initiate.

Needed permissions: imagery.images

Request Body schema: application/json
required
pipelineId
required
string (Pipelineid) = 20 characters

ID of the pipeline.

Responses

Request samples

Content type
application/json
{
  • "pipelineId": "abcdefabcdefabcdefab"
}

Response samples

Content type
application/json
{}

Tasking

Get Status

Get status of an asynchronous pipeline, see doc.

Request Body schema: application/json
required
pipelineId
required
string (Pipelineid) = 20 characters

ID of the pipeline to get the status for.

getProgress
boolean (Getprogress)
Default: false

Whether to retrieve progress of the pipeline.

Responses

Request samples

Content type
application/json
{
  • "getProgress": true,
  • "pipelineId": "3g4PovfhGxmymQolpgvv"
}

Response samples

Content type
application/json
{
  • "nextTry": 14,
  • "progress": {
    },
  • "status": "PROCESSING"
}

User

Info

This API endpoint accepts a “Bearer” access token of a user. It returns claims related to the user.

Dynamically needed permissions: Requires admin.users.manage if userId is set.

Request Body schema: application/json
required
Userid (string) or Userid (null) (Userid)

ID of the user to get info for. Requires admin.users.manage permissions.

Responses

Request samples

Content type
application/json
{
  • "userId": "auth0|8e9c9d314376cb2319e14606"
}

Response samples

Content type
application/json
{
  • "accounting": "development",
  • "email": "john-smith@example.com",
  • "id": "auth0|mGochhH3Pz5SiCWo8m44",
  • "name": "John Smith",
  • "permissions": [
    ]
}

Guardian User Create

This API endpoint allows Guardian managers to create accounts. This endpoint supports only user authentication. Needed permissions: admin.users.create-guardian-user

Request Body schema: application/json
required
email
required
string (Email) [^@ \t\r\n]+@[^@ \t\r\n]+\.[^@ \t\r\n]+

User's e-mail.

password
required
string (Password) non-empty

User's initial password.

name
required
string (Name) non-empty

User's full name.

Responses

Request samples

Content type
application/json
{
  • "email": "john-smith@example.com",
  • "name": "John Smith",
  • "password": "secret"
}

Response samples

Content type
application/json
{ }

Guardian User Delete

Allows Guardian managers to delete accounts from their group. This endpoint supports only user authentication. Needed permissions: admin.users.delete-guardian-user

Request Body schema: application/json
required
email
required
string (Email) [^@ \t\r\n]+@[^@ \t\r\n]+\.[^@ \t\r\n]+

User's e-mail.

Responses

Request samples

Content type
application/json
{
  • "email": "example@google.com"
}

Response samples

Content type
application/json
{ }

Authentication (Get Bearer Token)

Get the bearer token as a response to this authentication request. The token is valid for 10 hours. Once the time elapses you need to get a new token via this authentication request again.

Request Body schema: application/json
required

Use the predefined body below, only change the username and password attributes with your own values.

client_id
required
string

Use the value hmWJcfhRouDOaJK2L8asREMlMrv3jFE1.

username
required
string

Please fill in your email.

password
required
string

Please fill in your password.

connection
required
string

Use the value Username-Password-Authentication.

grant_type
required
string

Use the value password.

scope
required
string

Use the value openid.

Responses

Request samples

Content type
application/json
{
  • "client_id": "hmWJcfhRouDOaJK2L8asREMlMrv3jFE1",
  • "username": "example@email.com",
  • "password": "mypassword123",
  • "connection": "Username-Password-Authentication",
  • "grant_type": "password",
  • "scope": "openid"
}

Response samples

Content type
application/json
{
  • "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Ik1URkdRVVZFUWpOQk1rUTRRamczT1RreFFqWXdSa016UmpWQ05FVTNOa1pHTmpnM05ESTRRdyJ9.eyJpc3MiOiJodHRwczovL3NwYWNla25vdy5hdXRoMC5jb20vIiwic3ViIjoiYXV0aDB8NWY1Zjg2YWUwYmI3N2EwMDcwNmFlOWU4IiwiYXVkIjoiaG1XSmNmaFJvdURPYUpLMkw4YXNSRU1sTXJ2M2pGRTEiLCJpYXQiOjE2MDAxNzMyMjUsImV4cCI6MTYwMDIwOTIyNX0.g-b8dOwo46CIDL9vMId8Iojv0zvr96nWyYkRgtVEezm4c5Cj7e1e3761MP3S9I2gosQyBOxf-L5kP_AQ_IpGs3tFbA0WhLuOCjMTNueA1F3gFYyepG4rfiXCuWRKJ4FSXUATDQWgcELH5YDVD5WRO7xA2vfPmGttT4sCQkUSYMD9yFoJIQJc4eXCHUJQp9l3yHlC-DxRmjZF50Mv2ZZ_gDcy1CQsfi4bRRUDPV2vfuNDG7px_C51tt17iVf-GFGzkm-WllOYu6L3C-sLjjZZQyTgoPXHuEXMWiZc75-B1Q3BNKPDpsMGuOh7yGcSsNeY27sMNKQbnvYWDcJFXEHemw",
  • "scope": "openid",
  • "access_token": "BeKlKSgAJD70NQeJpVPt2WKTIEIRsj2e",
  • "token_type": "bearer"
}