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.
402 - Payment Required. Allocation is required prior to running this request.
403 - Forbidden. You are trying to modify internal assets.
404 - Not Found. You are trying to access resource which does not exist.
405 - Method Not Allowed. Used HTTP method is not allowed for this endpoint.
409 - Conflict. You are trying to modify resource which is in conflict with another.
413 - Payload Too Large. Request payload is too large.
422 - Unprocessable Content. Request payload did not pass validation.
424 - Failed Dependency. This status code is returned when a failed processing pipeline is retrieved (see Asynchronous API).
429 - Too Many Requests. Too many requests to this endpoint, please try again later.
500 - Internal Server Error.
503 - Service Unavailable. Try again later.

List of Error Codes

See API errors for details.

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.