Credits API (Billing, Payments and Credits)

Credits API is a system for administration of credits and payments for them.

Concept

Some actions available through SpaceKnow APIs may be performed only within allocated areas and scenes. Users are grouped into groups where each group has credits. These credits can be exchanged for an area allocation.

For example:

Olivia and William are part of group called Smiths. Olivia wants to perform an analysis on multiple satellite images from San Francisco acquired between 4th May 2016 and 20th June 2017. Before she can do any analysis, she has to allocate scenes and location via Credits API. She does that with an API call.

There are 7 scenes found for provider GBDX and dataset IDAHO-PANSHARPENED between May 2016 and June 2017 and San Francisco has 121 \(km^2\). Mentioned dataset uses 0.1 credits per \(km^2\). This means that \(7 \cdot 121 \cdot 0.1 = 84.7\) credits is subtracted from group Smiths in exchange for that area. From now on all users from group Smiths (Olivia and William) can perform unlimited analysis of satellite images of San Francisco from dates between May 2016 and June 2017.

Credits usage is also recorded for each user and there can be a limit set how many credits given user can allocate.

Selected imagery only

The Credits API currently applies to selected imagery only. To access other types of imagery, a special permission is required instead.

Free Area

The API offers one free area suitable for testing purposes. This gives customers a chance to evaluate the product without any commitment. Free area is enclosed by web map tiles (17, 121253, 75886) to (17, 121326, 75960), which correspond to the following GeoJSON. You can inspect the area here.

{
    "type": "Polygon",
        "coordinates": [[
            [153.03131103515622, -27.510707451811598],
            [153.23455810546878, -27.510707451811598],
            [153.23455810546878, -27.327855149448382],
            [153.03131103515622, -27.327855149448382],
            [153.03131103515622, -27.510707451811598]
        ]]
}

Check Area

This API endpoints can be used to check whether a client (the group (s)he is part of) has allocation for an area in given scenes.

Note

The group license must not be expired in order to use this endpoint.

Needed Permissions: credits.check-area

POST /credits/area/check-geojson
Request JSON Object:

  • geojson (object) – required; GeoJSON in WGS84 coordinates enclosing area to be checked. The GeoJSON must be within -85 to 85 degrees of latitude.

  • sceneIds (list) – required; list of sceneIds, obtained from e.g. Ragnar search

  • userId (string) – optional; check area for this user. If not provided ID of the user making the request is used. Specifying other user ID requires special permissions.

Example request:

{
    "sceneIds": ["DXc_fDD2aRjkHXMur6NSw1Fz4vmD80bGJLtK1gfSGjMR77E2b-DOrvsQzfYeJA"],
    "geojson": {
        "type": "MultiPolygon",
        "coordinates": [
            [
                [
                    [-122.51747131348, 37.694823535365],
                    [-122.35130310059, 37.694823535365],
                    [-122.35130310059, 37.809919574016],
                    [-122.51747131348, 37.809919574016],
                    [-122.51747131348, 37.694823535365]
                ]
            ]
        ]
    }
}
Response JSON Object:

  • km2 (float) – number of \(km^2\) requiring allocation.

  • cost (float) – number of credits required for allocation

Example response:

{
    "km2": 2.5,
    "cost": 1.25
}

Get Remaining Credit

Get remaining and used credit for the group the calling user is bind in. Deprecated in favor of /credits/user/get

Needed Permissions: credits.user-info

Deprecated!

This API endpoint(s) is deprecated and will be removed soon.

POST /credits/get-remaining-credit

Example request:

{}
Response JSON Object:

  • remainingCredit (float) – amount of remaining credit of the users group

Example response:

{
    "remainingCredit": 101.1,
}

List Group Allocations

List all allocations for the group.

Needed Permissions: 'admin.credits.list-group-allocations'

POST /credits/group/list-allocations
Request JSON Object:

  • cursor (str) – optional; Use to retrieve more data if the results do not fit into response of one endpoint call.

Example request:

{"cursor": "MQ=="}
Response JSON Object:

  • results (list) – list of allocations

  • results[i].id (string) – allocation ID

  • results[i].groupId (string) – group ID

  • results[i].sceneId (string) – scene ID

  • results[i].tiles (array) – (optional) coordinates of the allocated tiles. Origin is in the top left corner of the scene. Returned only for tiled datasets.

  • cursor (string) – optional; If a cursor is present in the response, it signifies that there is more data available. Use this cursor value as a parameter in the next API call to retrieve additional data.

Example response:

{
    "results": [
        {
            "id": "transaction_id1234",
            "groupId": "groupId",
            "sceneId": "scene1",
            "tiles": [[1, 1], [5, 7]]
        },
        {
            "id": "transaction_id1235",
            "groupId": "groupId",
            "sceneId": "scene3"
        }
    ],
    "cursor": null
}

List Group Transactions

List all transactions for a group that user belongs to.

Needed Permissions: admin.credits.list-group-transactions

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.

POST /credits/group/list-transactions
Request JSON Object:

  • cursor (str) – optional; Use to retrieve more data if the results do not fit into response of one endpoint call.

Example request:

{"cursor": "MQ=="}
Response JSON Object:

  • results (list) – list of transactions

  • results[i].id (string) – ID of the transaction

  • results[i].credit (float) – used credits

  • results[i].groupId (string) – group ID

  • results[i].time (string) – time of the transaction

  • results[i].kind (string) – type of transaction. Can be either credit.allocate, credit.preallocate, credit.return or credit.update

  • results[i].allocations (array) – List of related allocations (credit.preallocate only)

  • results[i].userId (string) – Auth0 ID of the user

  • results[i].sceneId (string) – (optional) sceneId of allocated scene (credit.allocate only)

  • results[i].provider (string) – (optional) provider of allocated scene (credit.allocate and credit.preallocate only)

  • results[i].dataset (string) – (optional) dataset of allocated scene (credit.allocate and credit.preallocate only)

  • results[i].tiles (list) – (optional) allocated tiles (credit.allocate only)

  • results[i].orderReferenceId (list) – (optional) allocated tiles (credit.preallocate, credit.return only)

  • cursor (string) – next page cursor

Example response:

{
    "results": [
        {
            "id": "transaction_id1234",
            "credit": 1.23,
            "areaKm2": 2.0,
            "groupId": "groupId",
            "time": "2022-11-30 03:19:59",
            "kind": "credit.allocate",
            "sceneId": "scene1",
            "provider": "a",
            "dataset": "b",
            "tiles": [[1, 1], [1, 2]],
            "userId": "user1",
        },
        {
            "id": "transaction_id1235",
            "credit": 5.23,
            "areaKm2": 6.0,
            "groupId": "groupId",
            "time": "2022-11-12 04:49:56",
            "kind": "credit.preallocate",
            "orderReferenceId": "abc",
            "allocations": ["allocation-id1", "allocation-id2"],
            "userId": "user1"
        },
        {
            "id": "transaction_id1236",
            "kind": "credit.return",
            "orderReferenceId": "orderReferenceId",
            "credit": 5.23,
            "areaKm2": 6.0,
            "time": "2022-11-13 05:39:51",
            "userId": "user1"
        },
        {
            "id": "transaction_id1236",
            "credit": 100.0,
            "areaKm2": 0.0,
            "groupId": "groupId",
            "time": "2022-12-01 12:45:22",
            "kind": "credit.update",
            "userId": "user2"
        }
    ],
    "cursor": "MQ=="
}

List User Transactions

List all transactions for the current user.

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.

POST /credits/user/list-transactions
Request JSON Object:

  • cursor (str) – optional; Use to retrieve more data if the results do not fit into response of one endpoint call.

Example request:

{"cursor": "MQ=="}

Response is the same format as List Group Transactions endpoint

Example response:

{
    "results": [
        {
            "id": "transaction_id1234",
            "credit": 1.23,
            "areaKm2": 2.0,
            "groupId": "groupId",
            "time": "2022-11-30 03:19:59",
            "kind": "credit.allocate",
            "sceneId": "scene1",
            "provider": "a",
            "dataset": "b",
            "tiles": [[1, 1], [1, 2]],
            "userId": "user1",
        },
        {
            "id": "transaction_id1235",
            "credit": 5.23,
            "areaKm2": 6.0,
            "groupId": "groupId",
            "time": "2022-11-12 04:49:56",
            "kind": "credit.preallocate",
            "orderReferenceId": "abc",
            "allocations": ["allocation-id1", "allocation-id2"],
            "userId": "user1"
        },
        {
            "id": "transaction_id1236",
            "kind": "credit.return",
            "orderReferenceId": "orderReferenceId",
            "credit": 5.23,
            "areaKm2": 6.0,
            "time": "2022-11-13 05:39:51",
            "userId": "user1"
        },
    ],
    "cursor": null
}

Set User Credit Limit

Set user credit limit. Requires either admin.users.manage permission or admin.credits.set-user-credit-limit permission if the changed user is member of the same group as the user changing the limit.

POST /credits/user/set-credit-limit
Response JSON Object:

  • userId (string) – Id of the user

  • creditLimit (float) – Credit limit to be set for given user. Use null to unset the credit limit.

Example request:

{
    "userId": "user-id",
    "creditLimit": 123.4
}

Example response:

{}

Get Credits User

Needed Permissions: credits.get-remaining-credit

Get credits information for a given user.

POST /credits/user/get
Request JSON Object:

  • userId (string) – Optional. Get credits information for this user. If not provided, credits information for the current user will be returned. Requires special permissions.

Example request:

{
    "userId": "auth0|8e9c9d314376cb2319e14606"
}
Response JSON Object:

  • id (string) – The user ID.

  • email (string) – The user’s email address.

  • name (string) – The user’s name.

  • usedCredit (float) – The amount of credit used by the specific user.

  • remainingCredit (float) – The remaining credit available to the user, considering both user and group limits.

  • groupId (string) – The ID of the group the user belongs to.

  • creditsTier (string) – The credits tier of the user’s group.

Example response:

{
    "id": "auth0|8e9c9d314376cb2319e14606",
    "email": "user@example.com",
    "name": "John Doe",
    "usedCredit": 100.0,
    "remainingCredit": 900.0,
    "groupId": "group_123",
    "creditsTier": "basic"
}