# Counting API

## Health

## health

<mark style="color:blue;">`GET`</mark> `https://counting.traces.cloud/api/v1/health`

This endpoint allows to test that service is up &#x20;

#### Path Parameters

| Name             | Type   | Description                                         |
| ---------------- | ------ | --------------------------------------------------- |
| X-Traces-API-Key | string | Authorization API key to access Traces Counting API |

{% tabs %}
{% tab title="200 " %}

```
ALIVE
```

{% endtab %}
{% endtabs %}

### Example

```javascript
curl -X GET "http://faf.traces.cloud.api/v1/health" -H "accept: */*"

```

## Operations <a href="#id-0g-operations" id="id-0g-operations"></a>

For a successful usage of Traces Counting API, it is required to do the following step:

* Register a camera by providing coordinates of counting triangles. It should be done only once for every unique camera. Read more about [counting triangles](https://docs.traces.cloud/best-practises#counting-triangle) here.

If the placement of a camera or areas of interest has changed, just update the coordinates of counting triangles by sending a new POST request with the same '*camera id'*.

## object-counting-settings

<mark style="color:green;">`POST`</mark> `https://counting.traces.cloud/api/v1/object-counting-settings`

Defines areas of interest (counting triangles) for a given camera. Counting triangles are used to calculate the number of objects that passed by.

#### Headers

| Name                                               | Type   | Description                                         |
| -------------------------------------------------- | ------ | --------------------------------------------------- |
| X-Traces-API-Key<mark style="color:red;">\*</mark> | string | Authorization API key to access Traces Counting API |

#### Request Body

| Name                                                | Type   | Description                                                                                                                           |
| --------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| counting\_options<mark style="color:red;">\*</mark> | object | Dictionary with a `camera_id`  key and a  list of `counting_triangles` defined for every unique camera. See example `data.json` below |

{% tabs %}
{% tab title="200 " %}

```javascript
{"status": "success"}
```

{% endtab %}

{% tab title="401 " %}

```javascript
{"code": "INVALID_API_KEY", "description": "API key was not recognized"}
```

{% endtab %}
{% endtabs %}

{% code title="data.json" %}

```javascript
{
  "camera_id": "b5271b30-aecd-4897-bc95-ff25c8466b9e",
  "counting_triangles": [
    {
      "passway_name": "2nd-floor-escalator-up",
      "coordinates": {
        "x1": 0,
        "y1": 0,
        "x2": 100,
        "y2": 100,
        "x3": 50,
        "y3": 50
      }
    },
    {
      "passway_name": "2nd-floor-escalator-down",
      "coordinates": {
        "x1": 200,
        "y1": 200,
        "x2": 400,
        "y2": 400,
        "x3": 350,
        "y3": 350
      }
    }
  ]
}
```

{% endcode %}

### Example

{% tabs %}
{% tab title="cURL" %}

```javascript
curl -X POST -H "Content-Type: application/json" -H "X-Traces-API-Key: YOUR_API_KEY" -d @data.json https://counting.traces.cloud/api/v1/object-counting-settings
```

{% endtab %}

{% tab title="cURL" %}

```javascript
curl -X POST "https://counting.traces.cloud/api/v1/object-counting-settings" -H "accept: /" -H "X-Traces-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" -d "{\"camera_id\":\"b5271b30-aecd-4897-bc95-ff25c8466b9e\",\"passways\":[{\"passway_name\":\"2nd-floor-escalator-up\",\"coordinates\":{\"x1\":0,\"y1\":0,\"x2\":100,\"y2\":100,\"x3\":50,\"y3\":50}},{\"passway_name\":\"2nd-floor-escalator-down\",\"coordinates\":{\"x1\":200,\"y1\":200,\"x2\":400,\"y2\":400,\"x3\":300,\"y3\":300}}]}"where 'data.json' looks like
```

{% endtab %}
{% endtabs %}

## object-counting

<mark style="color:green;">`POST`</mark> `https://counting.traces.cloud/api/v1/object-counting`

Calculates the number of objects that passed every area of interest in a given video. \
Returns a detailed report about how many objects of each type entered and exited every area of interest.&#x20;

#### Headers

| Name                                               | Type   | Description                                         |
| -------------------------------------------------- | ------ | --------------------------------------------------- |
| X-Traces-API-Key<mark style="color:red;">\*</mark> | string | Authorization API key to access Traces Counting API |

#### Request Body

| Name                                                | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                |
| --------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| counting\_options<mark style="color:red;">\*</mark> | object | <p>Dictionary with "<code>classes</code>" and "<code>count\_by\_frames</code>" keys. <br>Example: <code>{ "classes": \[ "people", "vehicle" ], "count\_by\_frames": false }</code>.<br><code>Classes</code> are the types of objects that will be calculated.<br><code>Count\_by\_frames</code> defines the granularity level of response. If <code>True,</code>the number of objects will be shown for every frame of an input video.</p> |
| video<mark style="color:red;">\*</mark>             | string | video file ($binary)                                                                                                                                                                                                                                                                                                                                                                                                                       |
| metadata<mark style="color:red;">\*</mark>          | object | <p>Dictionary with a "<code>camera\_id</code>" key. <br>Example: <code>{ "camera\_id": "b5271b30-aecd-4897-bc95-ff25c8466b9e" }</code></p>                                                                                                                                                                                                                                                                                                 |

{% tabs %}
{% tab title="200 An example of a response with counting\_options set as described in parameters description   " %}

```javascript
{
  "output": [
    {
      "passway_name": "2nd-floor-escalator-up",
      "counted_objects": [
        {
          "object_type": "person",
          "in": 100,
          "out": 0
        },
        {
          "object_type": "vehicle",
          "in": 0,
          "out": 0
        }
      ]
    }
  ]
}
```

{% endtab %}
{% endtabs %}

### Example

```javascript
curl -X POST "https://counting.traces.cloud/api/v1/object-counting/" -H "accept: /" -H "X-Traces-API-Key: YOUR_API_KEY" -H "Content-Type: multipart/form-data" -F "metadata={ "camera_id": "b5271b30-aecd-4897-bc95-ff25c8466b9e" }" -F "counting_options={ "classes": [ "people", "vehicle" ], "count_by_frames": false }" -F "video=@customer_video.mp4;type=video/mp4"
```

## dwell-time-settings

<mark style="color:green;">`POST`</mark> `https://counting.traces.cloud/api/v1/dwell-time-settings`

Defines spaces for dwell time calculation for a given camera.

#### Headers

| Name                                               | Type   | Description                                         |
| -------------------------------------------------- | ------ | --------------------------------------------------- |
| X-Traces-API-Key<mark style="color:red;">\*</mark> | string | Authorization API key to access Traces Counting API |

#### Request Body

| Name                                                | Type   | Description                                                                                             |
| --------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------- |
| counting\_options<mark style="color:red;">\*</mark> | object | Dictionary with a list of spaces where a dwell time should be calculated. See example `data.json` below |

{% tabs %}
{% tab title="200 " %}

```javascript
{"status": "success"}
```

{% endtab %}
{% endtabs %}

{% code title="data.json" %}

```javascript
{
  "camera_id": "b5271b30-aecd-4897-bc95-ff25c8466b9e",
  "spaces": [
    {
      "space_name": "main_entrance",
      "coordinates": {
        "x1": 0,
        "y1": 0,
        "x2": 100,
        "y2": 100
      }
  }]
}
```

{% endcode %}

### Example

```javascript
 curl -X POST -H "Content-Type: application/json" -H "X-Traces-API-Key: YOUR_API_KEY" -d @data.json https://counting.traces.cloud/api/v1/dwell-time-settings
```

## dwell-time-summary

<mark style="color:green;">`POST`</mark> `https://counting.traces.cloud/api/v1/dwell-time-summary`

Calculates statistics about customer's dwell time in the defined spaces.\
Returns the number of people who entered a perimeter of every space; average, median, total, maximum, and minimum of dwell time in the given video.

#### Path Parameters

| Name                                               | Type   | Description                                                    |
| -------------------------------------------------- | ------ | -------------------------------------------------------------- |
| X-Traces-API-Key<mark style="color:red;">\*</mark> | string | <p>Authorization API key to access Traces Counting API<br></p> |

#### Request Body

| Name                                       | Type   | Description                                                                                           |
| ------------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------- |
| video<mark style="color:red;">\*</mark>    | string | video file ($binary)                                                                                  |
| metadata<mark style="color:red;">\*</mark> | object | Dictionary with `"camera_id"` key. Example: `{ "camera_id": "b5271b30-aecd-4897-bc95-ff25c8466b9e" }` |

{% tabs %}
{% tab title="200 " %}

```javascript
[{
  "space_name": "main_entrance"
  "number_of_people": 121,
  "statistics": {
    "average": "00:05:16",
    "median":  "00:03:49",
    "minimum": "00:00:22",
    "maximum": "00:12:31",
    "total":   "04:31:33"
  }
}]
```

{% endtab %}
{% endtabs %}

### Example

```javascript
curl -X POST "https://counting.traces.cloud/api/v1/dwell-time-summary/" -H "accept: /" -H "X-Traces-API-Key: YOUR_API_KEY" -H "Content-Type: multipart/form-data" -F "metadata={ "camera_id": "b5271b30-aecd-4897-bc95-ff25c8466b9e" }" -F "video=@customer_video.mp4;type=video/mp4"
```

## dwell-time-detailed

<mark style="color:green;">`POST`</mark> `https://counting.traces.cloud/api/v1/dwell-time-detailed`

Calculates dwell-time for every customer who entered the perimeter.\
It provides detailed information about every customer who entered any space, that includes every frame where the customer appeared, their coordinates in each frame for correct localization, and a total dwell time.

#### Path Parameters

| Name                                               | Type   | Description                                         |
| -------------------------------------------------- | ------ | --------------------------------------------------- |
| X-Traces-API-Key<mark style="color:red;">\*</mark> | string | Authorization API key to access Traces Counting API |

#### Request Body

| Name                                       | Type   | Description                                                                                           |
| ------------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------- |
| video<mark style="color:red;">\*</mark>    | string | video file ($binary)                                                                                  |
| metadata<mark style="color:red;">\*</mark> | object | Dictionary with `"camera_id"` key. Example: `{ "camera_id": "b5271b30-aecd-4897-bc95-ff25c8466b9e" }` |

{% tabs %}
{% tab title="200 " %}

```javascript
[{
  "space_name": "main_entrance",
  "ids": {
    "id_0": {
      "dwell_time": "00:00:01",
      "frames": [
        {
          "frame": 5,
          "coordinates": {
            "x1": 100,
            "y1": 100,
            "x2": 220,
            "y2": 121
          }
        },
        {
          "frame": 6,
          "coordinates": {
            "x1": 102,
            "y1": 100,
            "x2": 221,
            "y2": 123
          }
        }
      ]
    }
  }
}]
```

{% endtab %}
{% endtabs %}

### Example

```javascript
curl -X POST "https://counting.traces.cloud/api/v1/dwell-time-detailed/" -H "accept: /" -H "X-Traces-API-Key: YOUR_API_KEY" -H "Content-Type: multipart/form-data" -F "metadata={ "camera_id": "b5271b30-aecd-4897-bc95-ff25c8466b9e" }" -F "video=@customer_video.mp4;type=video/mp4"
```