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]
]]
}
Allocate Area
Use this API endpoints to allocate an area and time range for group of which requesting client is part of.
Note
The group license must not be expired in order to use this endpoint.
Needed Permissions: credits.allocate-area
- POST /credits/area/allocate-geojson
- Request JSON Object:
geojson (object) – required; GeoJSON in WGS84 coordinates enclosing area to be allocated. The GeoJSON must be within -85 to 85 degrees of latitude.
sceneIds (list) – required; list of sceneIds, obtained from e.g. Ragnar search
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\) newly allocated.
cost (float) – number of credits subtracted from account
Example response:
{ "km2": 2.5, "cost": 1.25 }
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 foreign 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.
Needed Permissions: credits.get-remaining-credit
- 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.
Needed Permissions: credits.payment
- 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 equal to spent USD.
Needed Permissions: credits.payment
- 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 }
List Group Allocations
List all allocations for the credits group of the current user.
Needed Permissions: 'admin.credits.list-group-allocations'
Note
The time
and credit
properties are fetched from transactions for
the particular allocation. The transaction records were introduced much later
after the allocation records. Thus, those values can be missing or imprecise.
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-allocations
- Response JSON Array of Objects:
id (string) – allocation ID
sceneId (string) – scene ID
tiles (array) – list of the allocated tiles in the form of
[X, Y]
, e.g.[[0, 1], [2, 13]]
(tile-based datasets only)preallocationId (float) – ID of the preallocation transaction
credit (float) – used credits
time (string) – first allocation time
Example response:
[ { "credit": 1.23, "kind": "credit.allocate", "sceneId": "scene-id", "time": "2022-11-30 03:19:59" }, { "credit": 5.23, "kind": "credit.preallocate", "sceneId": "scene-id2", "time": "2022-11-12 04:49:56" } ]
List User Allocations
List all allocations for the current user.
Note
The list of allocations is based on transactions which were introduced after the allocation entities. Hence, the list is incomplete for some users.
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-allocations
- Response JSON Array of Objects:
id (string) – allocation ID
sceneId (string) – scene ID
tiles (array) – list of the allocated tiles in the form of
[X, Y]
, e.g.[[0, 1], [2, 13]]
(tile-based datasets only)preallocationId (float) – ID of the preallocation transaction
credit (float) – used credits
time (string) – first allocation time
Example response:
[ { "credit": 1.23, "kind": "credit.allocate", "sceneId": "scene-id", "time": "2022-11-30 03:19:59" }, { "credit": 5.23, "kind": "credit.preallocate", "sceneId": "scene-id2", "time": "2022-11-12 04:49:56" } ]
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.
Needed Permissions: credits.get-remaining-credit
- 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:
{}