.. Copyright (C) 2017-2024 SpaceKnow, Inc.

.. _api.credits:

*******************************************
Credits API (Billing, Payments and Credits)
*******************************************

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

* URL: https://api.spaceknow.com/credits

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 :math:`km^2`.
Mentioned dataset uses 0.1 credits per :math:`km^2`.
This means that :math:`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.

.. _GeoJSON: https://tools.ietf.org/html/rfc7946

.. admonition:: Selected imagery only

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

.. _api.credits.free-area:

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_.

.. _here: https://bl.ocks.org/anonymous/raw/7827ed6eb29ecd5226575b5efd91b880/

.. sourcecode:: json

    {
        "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``

.. http:post:: /credits/area/check-geojson

    :<json object geojson: required; `GeoJSON`_ in WGS84 coordinates enclosing
        area to be checked. The GeoJSON must be within -85 to 85 degrees of
        latitude.
    :<json list sceneIds: required; list of sceneIds, obtained from e.g. Ragnar
        search
    :<json string userId: 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**:

    .. sourcecode:: json

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

    :>json float km2: number of :math:`km^2` requiring allocation.

    :>json float cost: number of credits required for allocation

    **Example response**:

    .. sourcecode:: json

        {
            "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``

.. include:: _deprecated.rst

.. http:post:: /credits/get-remaining-credit

    **Example request**:

    .. sourcecode:: json

        {}

    :>json float remainingCredit: amount of remaining credit of the users group

    **Example response**:

    .. sourcecode:: json

        {
            "remainingCredit": 101.1,
        }

List Group Allocations
======================

List all allocations for the group.

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

.. http:post:: /credits/group/list-allocations

    :<json str cursor: optional; Use to retrieve more data if the results do
        not fit into response of one endpoint call.

    **Example request**:

    .. sourcecode:: json

        {"cursor": "MQ=="}

    :>json list results: list of allocations
    :>json string results[i].id: allocation ID
    :>json string results[i].groupId: group ID
    :>json string results[i].sceneId: scene ID
    :>json array results[i].tiles: (optional) coordinates of the allocated tiles.
        Origin is in the top left corner of the scene. Returned only for
        tiled datasets.
    :>json string cursor: 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**:

    .. sourcecode:: json

        {
            "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.

.. http:post:: /credits/group/list-transactions

    :<json str cursor: optional; Use to retrieve more data if the results do
        not fit into response of one endpoint call.

    **Example request**:

    .. sourcecode:: json

        {"cursor": "MQ=="}

    :>json list results: list of transactions
    :>json string results[i].id: ID of the transaction
    :>json float results[i].credit: used credits
    :>json string results[i].groupId: group ID
    :>json string results[i].time: time of the transaction
    :>json string results[i].kind: type of transaction. Can be either
        ``credit.allocate``, ``credit.preallocate``, ``credit.return`` or
        ``credit.update``
    :>json array results[i].allocations: List of related allocations (``credit.preallocate`` only)
    :>json string results[i].userId: Auth0 ID of the user
    :>json string results[i].sceneId: (optional) sceneId of allocated scene (``credit.allocate`` only)
    :>json string results[i].provider: (optional) provider of allocated scene (``credit.allocate`` and ``credit.preallocate`` only)
    :>json string results[i].dataset: (optional) dataset of allocated scene (``credit.allocate`` and ``credit.preallocate`` only)
    :>json list results[i].tiles: (optional) allocated tiles (``credit.allocate`` only)
    :>json list results[i].orderReferenceId: (optional) allocated tiles (``credit.preallocate``, ``credit.return`` only)
    :>json string cursor: next page cursor

    **Example response**:

    .. sourcecode:: json

        {
            "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.


.. http:post:: /credits/user/list-transactions

    :<json str cursor: optional; Use to retrieve more data if the results do
        not fit into response of one endpoint call.

    **Example request**:

    .. sourcecode:: json

        {"cursor": "MQ=="}


    Response is the same format as List Group Transactions endpoint

    **Example response**:

    .. sourcecode:: json

        {
            "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.

.. http:post:: /credits/user/set-credit-limit

    :>json string userId: Id of the user
    :>json float creditLimit: Credit limit to be set for given user. Use
        ``null`` to unset the credit limit.

    **Example request**:

    .. sourcecode:: json

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

    **Example response**:

    .. sourcecode:: json

        {}

.. _api.credits.user.get:

Get Credits User
================

**Needed Permissions**: ``credits.get-remaining-credit``

Get credits information for a given user.

.. http:post:: /credits/user/get

    :<json string userId: Optional. Get credits information for this user. If not provided,
        credits information for the current user will be returned. Requires special permissions.

    **Example request**:

    .. sourcecode:: json

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

    :>json string id: The user ID.
    :>json string email: The user's email address.
    :>json string name: The user's name.
    :>json float usedCredit: The amount of credit used by the specific user.
    :>json float remainingCredit: The remaining credit available to the user, considering both user and group limits.
    :>json string groupId: The ID of the group the user belongs to.
    :>json string creditsTier: The credits tier of the user's group.

    **Example response**:

    .. sourcecode:: json

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