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 time ranges. Users are grouped into groups where each group has credits. These credits can be exchanged for an area and time range 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 that time range and location via Credits API. She does that with an API call.

There is 14 months between May 2016 and June 2017 and San Francisco has 121 \(km^2\). This means that \(14 \cdot 121 = 1694\) 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.

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

Allocate Area

Use this API endpoints to allocate an area and time range for group of which requesting client is part of.

This API have GeoJSON and web map tiles alternatives. See Kraken API (Imagery and Analyses) for more information about web map tiles.

POST /credits/area/allocate-geojson
Request JSON Object:
 
  • geojson (object) – required; GeoJSON in WGS84 coordinates enclosing area to be allocated. The API may enlarge the area by fitting it to a grid of \(0.1 km^2\) tiles. The GeoJSON must be within -85 to 85 degrees of latitude.
  • ranges (list) – required; list of ranges. Must contain at least one range.
  • ranges[i].from (string) – required; inclusive UTC date-time in format YYYY-MM.
  • ranges[i].to (string) – required; inclusive UTC date-time in format YYYY-MM.

Example request:

{
    "ranges": [
        {
            "from": "2016-05",
            "to": "2017-06"
        }
    ],
    "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:
 
  • allocatedKm2Months (float) – number of \(km^2 \cdot month\) newly allocated. This number is equal to number of credits subtracted for the allocation.

Example response:

{
    "allocatedKm2Months": 0.025
}
POST /credits/area/allocate-tiles
Request JSON Object:
 
  • tiles (list) – required; list of tiles. You may specify up to 16 tiles and they must be between zoom levels 10 and 17.
  • tiles[i] (list) – zoom, x, y coordinates of a single tile.
  • ranges (list) – required; list of ranges. Must contain at least one range.
  • ranges[i].from (string) – required; inclusive UTC date-time in format YYYY-MM.
  • ranges[i].to (string) – required; inclusive UTC date-time in format YYYY-MM.

Example request:

{
    "ranges": [
        {
            "from": "2016-05",
            "to": "2017-06"
        }
    ],
    "tiles": [
        [15, 17695, 11099],
        [15, 17695, 11100]
    ]
}

Response is equal to response of /credits/area/allocate-geojson.

Check Area

This API endpoints can be used to check whether a client (the group she is part of) has allocation for and area within a time range or how much area has not been allocated yet.

This API have GeoJSON and web map tiles alternatives. See Kraken API (Imagery and Analyses) for more information about web map tiles.

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.
  • ranges (list) – required; list of ranges. Must contain at least one range.
  • ranges[i].from (string) – required; inclusive UTC date-time in format YYYY-MM.
  • ranges[i].to (string) – required; inclusive UTC date-time in format YYYY-MM.
  • userId (string) – optional; check area for this user. If not provided ID of the user making the request is used. Specifying foreign user ID requires special permissions.

Example request:

{
    "ranges": [
        {
            "from": "2016-05",
            "to": "2016-05"
        }
    ],
    "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:
 
  • allocatedKm2Months (float) – number of \(km^2 \cdot month\) already allocated in the given area in the month.
  • complementKm2Months (float) – number of \(km^2 \cdot month\) not yet allocated in the given area in the month. If this is zero then whole area is already allocated.

Example response:

{
    "allocatedKm2Months": 0.0,
    "complementKm2Months": 2.49
}
POST /credits/area/check-tiles
Request JSON Object:
 
  • tiles (list) – required; see Allocate Area.
  • ranges (list) – required; list of ranges. Must contain at least one range.
  • ranges[i].from (string) – required; inclusive UTC date-time in format YYYY-MM.
  • ranges[i].to (string) – required; inclusive UTC date-time in format YYYY-MM.
  • userId (string) – optional; check area for this user. If not provided ID of the user making the request is used. Specifying foreign user ID requires special permissions.

Example request:

{
    "ranges": [
        {
            "from": "2016-05",
            "to": "2016-05"
        }
    ],
    "tiles": [
        [15, 17695, 11099],
        [15, 17695, 11100]
    ]
}

Response is equal to response of /credits/area/check-geojson.

Add User to a Group

POST /credits/user/bind
Request JSON Object:
 
  • userId (string) – required; ID of the user to be added to a group
  • groupId (string) – required; ID of the group to which the user shall be added

Example request:

{
    "userId": "auth0|8e9c9d314376cb2319e14606",
    "groupId": "vCBzdovXPFezKDASAsuOgHUrb"
}

Example response:

{}

Remove User from its Group

POST /credits/user/unbind
Request JSON Object:
 
  • userId (string) – required; ID of the user to be affected

Example request:

{
    "userId": "auth0|8e9c9d314376cb2319e14606"
}

Example response:

{}

Search Group

POST /credits/group/search
Request JSON Object:
 
  • groupName (string) – required; name to search. Search is case-insensitive.

Example request:

{
    "groupName": "Example Company"
}
Response JSON Object:
 
  • groups (list) – list of first 10 found groups
  • groups[i].groupId (string) – a unique ID of the group
  • groups[i].name (string) – name of the group
  • groups[i].credit (float) – amount of credit assigned to the group
  • groups[i].usedCredit (float) – amount of credit already used. Remaining credit can be calculated as credit - usedCredit.

Example response:

{
    "groups": [
        {
            "groupId": "ccffeeddss",
            "name": "Example Company",
            "credit": 125,
            "usedCredit": 22.32
        }
    ]
}

Create Group

POST /credits/group/create
Request JSON Object:
 
  • name (string) – required; name of the group to be created. Group name does uniquely identify the group, always use group ID for that purpose.
  • credit (float) – required; number of credit to be assigned to the group

Example request:

{
    "name": "Example Company v2",
    "credit": 15
}
Response JSON Object:
 
  • groupId (string) – a unique ID of the created group

Example response:

{
    "groupId": "xxeeffdd"
}

Change Group Credit

POST /credits/group/change-credit
Request JSON Object:
 
  • groupId (string) – required; ID of the group to be changed
  • creditDelta (float) – amount of credit to add. This value may be negative.

Example request:

{
    "groupId": "ccffeeddss",
    "creditDelta": 150
}
Response JSON Object:
 
  • credit (float) – amount of credit the company have after the addition

Example response:

{
    "credit": 155.2
}

Get Group

POST /credits/group/get
Request JSON Object:
 
  • groupId (string) – required; ID of the group to get

Example request:

{
    "groupId": "ccffeeddss"
}
Response JSON Object:
 
  • groupId (string) – a unique ID of the group
  • name (string) – name of the group
  • credit (float) – amount of credit assigned to the group
  • usedCredit (float) – amount of credit already used.
  • boundUserIds (list) – list of users bind to the group
  • boundUserIds[i] (string) – ID of a user

Example response:

{
    "groupId": "ccffeeddss",
    "name": "Example Company",
    "credit": 125,
    "usedCredit": 22.32,
    "boundUserIds": [
        "auth0|8e9c9d314376cb2319e14606"
    ]
}

Get Remaining Credit

Get remaining and used credit for the group the calling user is bind in.

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

Create payment token

Generates Braintree client token which is needed to initiate new transaction.

POST /credits/payment/new

Example request:

{}
Response JSON Object:
 
  • clientToken (string) – Braintree client token

Example response:

{
    "clientToken": "eyJ2ZXJzaW9u..."
}

Buy credit

Buy credit using Braintree payment method nonce. Nonce is generated by Braintree Drop-in UI on frontend using client token and it is one-time-use reference to payment information.

Number of credits to be added is calculated as one tenth (1 / 10) of spent USD.

POST /credits/payment/buy-credit
Request JSON Object:
 
  • paymentMethodNonce (string) – Braintree payment method nonce
  • amountToSpend (int) – amount in USD to spend for credits, minimum is 10 USD

Example request:

{
    "paymentMethodNonce": "BlGmvLOYUHQ...",
    "amountToSpend": 15
}
Response JSON Object:
 
  • purchasedCredit (float) – amount of credit added to user’s group
  • remainingCredit (float) – amount of remaining credit of the users group

Example response:

{
    "purchasedCredit": 1.5,
    "remainingCredit": 101.1
}