API Mechanics

Authorization

Please contact SpaceKnow team to obtain an account.

Making Authorized Request

JWT (JSON Web Tokens) is used for authorization of every request against SpaceKnow APIs. JWT is sent in Authorization header after Bearer keyword (i.e. Authorization: Bearer JWT-TOKEN).

Example of an authorized request:

POST /imagery/search/initiate

POST /imagery/search/initiate HTTP/1.1
Host: api.spaceknow.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.t-IDcSemACt8x4iTMCda8Yhe3iZaWbvV5XKSTbuAn0M

{
    "provider": "gbdx",
    "dataset": "idaho-pansharpened",
    "extent": {
                "type": "Polygon",
                "coordinates": [[
                        [115.84512233734131, -31.96024562403475],
                        [115.84490776062012, -31.96559774488045],
                        [115.84851264953612, -31.965452113067933],
                        [115.84842681884766, -31.96053690394404],
                        [115.84512233734131, -31.96024562403475]
            ]]
    }
}

Get JWT

Obtaining JWT tokens by clients is currently only supported for Auth0 OIDC provider.

Use Auth0 Authentication API to get a JWT. Tokens are valid for 10 hours.

SpaceKnow client ID: hmWJcfhRouDOaJK2L8asREMlMrv3jFE1
SpaceKnow Auth0 domain: spaceknow.auth0.com

For example request for JWT in exchange for email and password looks like this:

POST https://spaceknow.auth0.com/oauth/ro

Example request:

POST /oauth/ro HTTP/1.1
Content-Type: application/json

{
    "client_id": "hmWJcfhRouDOaJK2L8asREMlMrv3jFE1",
    "username": "your_spaceknow_email@example.com",
    "password": "your_spaceknow_password",
    "connection": "Username-Password-Authentication",
    "grant_type": "password",
    "scope": "openid"
}

Response JSON Object:

id_token (string) – JWT to be later used in authorized API requests.

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.t-IDcSemACt8x4iTMCda8Yhe3iZaWbvV5XKSTbuAn0M",
    "access_token": "some-token",
    "token_type": "bearer"
}

To acquire a token in devel environment, fire the request above but change the following:

SpaceKnow client ID: UWBUvt919N0sUXjG1CepGhiR0DJuazSY
SpaceKnow Auth0 domain: https://spaceknow-test.auth0.com

Permissions

Most SpaceKnow API endpoints have a set of permissions required to access them. A permission is a string with . as a namespace separator, for example imagery.availability.

The following Python code snipped shows how permissions are tested.

user_permission = user_permission_str.split('.')
required_permission = required_permission_str.split('.')

test_len = min(len(user_permission), len(required_permission))
user_permission_part = user_permission[:test_len]
required_permission_part = required_permission[:test_len]
return user_permission_part == required_permission_part

See the following example, where columns are permissions of a user and rows required permission.

	`imagery.availability`	`imagery.availability.gbdx`	`kraken`	`imagery`
`imagery.availability`	true	true	false	true
`imagery.availability.gbdx.idaho-pansharpened`	true	true	false	true
`imagery.availability.pl`	true	false	false	true
`imagery.images`	false	false	false	true
`imagery`	true	true	false	true

API Errors

The HTTP status code of 5XX is returned if a server-side error occurs. The status code of 4XX is returned if a client-side error occurs.

Error Response body:

{
    "error": "MACHINE-READABLE-ERROR-CODE",
    "errorMessage": "A human readable error description."
}

List of HTTP Status Codes

400 - Bad Request. Make sure that the request body and headers are correct.
401 - Unauthorized. You do not have sufficient rights or credits to perform this action.
403 - Forbidden. You are trying to modify internal assets.
424 - Failed Dependency. This status code is returned when a failed processing pipeline is retrieved (see Asynchronous API).
500 - Internal Server Error.
503 - Service Unavailable. Try again later.

List of Error Codes

General API Error Codes

NOT-AUTHORIZED – the request is either not properly authorized or you do not have sufficient permissions.
PAYLOAD-TOO-LARGE – request payload was too large. Request payload of majority API endpoints must be at most 64 KiB large.
NON-EXISTENT-ENDPOINT – requested path does not correspond to any API endpoint.
EXTENT-TOO-LARGE – the requested extent was too large to be processed by the API. Try again with a smaller extent.
EXTENT-TOO-SMALL – requested extent is too small.
NO-VALID-PIXELS – requested scene has no valid pixels inside requested extent.
NO-DATA-AVAILABLE – there are no data available for requested scene.
NON-EXISTING-SCENE – scene with given ID was not found when processing your request.
NON-EXISTENT-GEOMETRY – GeoJSON geometry does not exist.
UNSUPPORTED-IMAGERY – provided imagery is not supported by the algorithm.
GSD-TOO-COARSE – scene GSD (ground sample distance) is bigger than the maximum supported for given map type.
ACCESS-DENIED – requesting client is not permitted to do perform an operation or access the resource.
API-KEY-AUTHORIZATION-NOT-PERMITTED – other than user authentications are not available for the endpoint. See Authorization.
AUTHORIZATION-WITHOUT-CONTEXT-NOT-PERMITTED – endpoint requires proper user authentication or request context containing user_id and accounting for API key.
INTERFEROGRAM-BASELINE-TOO-SMALL – This error may occur in SLC data analysis when analyzed tile is too close to the edge of scene and algorithm is not able to extract useful results.
METHOD-NOT-ALLOWED – chosen HTTP method is not supported by this endpoint, refer to the documentation or use HTTP OPTIONS to find the supported methods
INVALID-JWT – provided authorization token is not valid
INVALID-QUERY-PARAMETER – provided query parameter is not valid.
FORBIDDEN – requested change of internal assets.
UNSUPPORTED-ENVIRONMENT – endpoint is not supported for the environment (e.g. some on-prem deployment)

CREDITS-ERROR – imagery or analysis was requested for an area or time range that was not yet fully allocated. See Credits API (Billing, Payments and Credits) for more information.

Tasking API Error Codes

NON-EXISTENT-PIPELINE – pipeline with given ID was not found when processing your request.
PIPELINE-NOT-PROCESSED – pipeline has not been resolved yet.

Ragnar API Error Codes

ORDER-TOOK-TOO-LONG – this error occurs if a scene’s order takes too long on provider’s side.
EXTENT-HAS-NO-INTERSECTION – extent doesn’t intersect scene.
PROVIDER-ERROR – a request to imagery provider resulted in an unrecoverable error.
PROVIDER-RESTRICTION – imagery provider refused to serve given scene for given account. This may be to licensing or geo-spatial restrictions.
PROVIDER-UNAVAILABILITY – imagery provider indicated that required data are not readily available in their systems.
SEARCH-TOO-COARSE – search parameters are too coarse please narrow down the search parameters.
OUTDATED-METADATA – requested scene has outdated metadata and cannot be used.
OUTDATED-METADATA-SEARCH-AGAIN – requested scene has outdated metadata. Run search again.
IMAGERY-FETCH-TIMEOUT – fetching imagery from provider’s system took too long.
NO-VALID-PROVIDER-DATA – no valid imagery was available for the selected area in scene. This can happen only when requesting clipped imagery.
NO-THUMBNAIL-AVAILABLE – no valid thumbnail was available for the selected scene.
NO-BASEMAP-AVAILABLE – no valid basemap was available for selected path.

Kraken API Error Codes

TOO-BIG-TILE-AREA – requested web map tile(s) covers too broad area.
TILE-OUTSIDE-SCENE – requested web map tile is outside specified scene.
ZERO-TILES-AVAILABLE – none of requested web map tile(s) succeeded. See Kraken API (Imagery and Analyses).
SCENES-HAVE-NO-INTERSECTION – footprints of provided scenes don’t intersect.
VERSION-MISMATCH – versions changed during analysis. Run the analysis again later.
UNSUPPORTED-FILE-NAME – requested file is not supported.
INVALID-TILE-COORDINATES – provided tile coordinates are not valid.
TILE-DOES-NOT-EXIST – requested tile does not exist.
NOT-PERMITTED-COORDINATES – user does not have permission to request scene with these coordinates as the tile is outside the region analyzed by the user.
INVALID-MAP-ID – provided map ID is invalid.
SCENES-WITH-SAME-DATETIME – Scenes provided for grouping have identical datetimes, which is forbidden.

Credits API Error Codes

INVALID-GEOJSON – requested GeoJSON doesn’t fit requirements of the API.
NO-VALID-BINDING – affected user is not bound to any company. See Credits API (Billing, Payments and Credits).
NOT-ENOUGH-CREDITS – user’s group does not have enough credits to perform requested operation.
NON-EXISTENT-GROUP – accessed group does not exist. See Credits API (Billing, Payments and Credits).
NON-EXISTENT-USER – accessed user does not exist.
PROCESSOR-DECLINED – customer’s bank has refused the transaction request.
GATEWAY-REJECTED – transaction did not pass gateway rules.
INVALID-NONCE – transaction did not pass gateway rules.
PAYMENT-ERROR – unspecified payment error.

GeoJSON DB API Error Codes

NON-EXISTENT-FEATURE – GeoJSON feature does not exist.
MALFORMED-QUERY – query cannot be parsed.

Datacube API Error Codes

TOO-MANY-DATAPOINTS – query matched too many data-points. You may
further limit amount of returned data by for example limiting data-range.
NO-MATCHING-PACKAGE – none of permission packages assigned to calling
user matches request filters.
NON-EXISTENT-PACKAGE – requested package does not exist.
NON-EXISTENT-PRODUCT – requested product does not exist.
DUPLICATE-DATAPOINTS – some of the supplied data-points are already in
Datacube API. You may remove these and re-run the request.
UNSUPPORTED-POSTPROCESS – Your query contains unsupported postprocess
operation.
NON-EXISTENT-TABLE – requested table does not exist.
PRODUCT-HAS-NO-DATA – there are no data for given product.

Asynchronous APIs

Processes, that can take from minutes to hours, are handled asynchronously in the “pipeline”. All APIs that work asynchronously have ../initiate and ../retrieve endpoints. To trigger a new pipeline, use ../initiate. To check whether a pipeline is finished, request /check-status endpoint of Tasking API. To get a finished pipeline result, request ../retrieve.

POST /.../initiate

Response JSON Object:

pipelineId (string) – ID of the processing pipeline. It will be used later to check pipeline status and to retrieve pipeline result.
status (string) – status of the pipeline at the time the response was generated. See Tasking API to learn more about pipeline statuses.
nextTry (int) – recommended delay in seconds before first status check. See Tasking API
subGeometryId (str) – This is only provided in Kraken Release initiate endpoint if subGeometry was present in the request. See Release with subGeometry.

Example response:

{
    "nextTry": 5,
    "pipelineId": "3g4PovfhGxmymQolpgvv",
    "status": "NEW"
}

Example with subGeometryId response:

{
    "nextTry": 5,
    "pipelineId": "3g4PovfhGxmymQolpgvv",
    "status": "NEW",
    "subGeometryId": "0123456789abcdef"
}

Pipeline is stopped and set to the FAILED status if an error occurred during pipeline processing. Request on ../retrieve for the failed pipeline is responded with a status code 424, and with a specific error code and message. See API Errors.

POST /.../retrieve

Request JSON Object:

pipelineId (string) – required; ID of the pipeline whose result should be retrieved.

Example request:

{
    "pipelineId": "3g4PovfhGxmymQolpgvv"
}

Extent

Extent is a GeoJSON whose minimum bounding rectangle (MBR) is non-empty. All coordinates are considered to be expressed in WGS84 coordinate reference system.

Example extent:

{
    "type": "GeometryCollection",
    "geometries": [
        {
            "type": "Polygon",
            "coordinates": [
                [
                    [
                        14.452436864376,
                        50.092111002982
                    ],
                    [
                        14.451779723167,
                        50.092107561411
                    ],
                    [
                        14.452233016491,
                        50.091543140472
                    ],
                    [
                        14.452436864376,
                        50.092111002982
                    ]
                ]
            ]
        }
    ]
}

Extent Decomposition

Extent can be too large to be used with a particular API / system. We recommend to use Kraken API (Imagery and Analyses) in such cases.

This problem can be also solved on client side by decomposing the extent into a grid of smaller tiles (squares).

A simple decomposition determines the smallest bounding rectangle of the extent, whose side lengths are multiples of a desired tile size.

The bounding rectangle is then “cut” into square tiles. Tiles that do not intersect requested area could be omitted if desired.

Single tile has these properties:

square
intersection of the square with original polygon

The decomposition described above is “naive” as it uses a planar solution to the problem. It is recommended to use a CRS, which is a planar approximation of the earth in the area of the original extent.

API Response Headers

Following headers might be contained in API response:

SpaceKnow-Api-Version
SpaceKnow-Request-Id - unique identifier of the request. You may use it when contacting SpaceKnow engineering team about any technical issues.

Example response header:

HTTP/1.1 200 OK
server: nginx
date: Wed, 03 Jan 2018 15:47:16 GMT
content-type: application/json; charset=utf-8
content-length: 55
vary: Accept-Encoding
cache-control: no-cache
access-control-allow-origin: *
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
strict-transport-security: max-age=2592000; includeSubDomains
via: 1.1 google
alt-svc: hq=":443"; ma=2592000; quic=51303431; quic=51303339; quic=51303338; quic=51303337; quic=51303335,quic=":443"; ma=2592000; v="41,39,38,37,35"
spaceknow-api-version: 106
spaceknow-request-id: QyhRiSw87c

Paging

Some APIs may return a big number of results. To avoid large JSON responses, the results are paginated using cursor as a pointer to a specific page.

Put parameter cursor to request an object to obtain a specific page.

Example of a specific page request:

{
    "search": "*",
    "cursor": "Pu9ZyvlVXxkm0XNr2FLr"
}

If the cursor is omitted, then the first page is returned.

Example of the first page request:

{
    "search": "*"
}

Paginated APIs return cursor which is a pointer to the next page and results which is a list of entities of the returned page.

Example of the paginated response:

{
    "results": [
        {
            "name": "Enterprise 1"
        },
        {
            "name": "Enterprise 2"
        },
        {
            "name": "Enterprise 3"
        },
        {
            "name": "Enterprise 4"
        },
        {
            "name": "Enterprise 5"
        }
    ],
    "cursor": "Pu9ZyvlVXxkm0XNr2FLr"
}

cursor is null if the last page was returned.

Example of the last page response:

{
    "results": [
        {
            "name": "Enterprise 6"
        }
    ],
    "cursor": null
}

Both normal and asynchronous APIs may be paginated. In the case of asynchronous APIs a new pipeline is started for every new requested page.