Counting API

Health

health

GET https://counting.traces.cloud/api/v1/health

This endpoint allows to test that service is up

Path Parameters

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

200

ALIVE

Example

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

Operations

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

POST 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*	string	Authorization API key to access Traces Counting API

Request Body

Name	Type	Description
counting_options*	object	Dictionary with a camera_id key and a list of counting_triangles defined for every unique camera. See example data.json below

200

{"status": "success"}

401

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

data.json

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

Example

cURL

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

cURL

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

object-counting

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

Headers

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

Request Body

Name	Type	Description
counting_options*	object	Dictionary with "classes" and "count_by_frames" keys. Example: { "classes": [ "people", "vehicle" ], "count_by_frames": false }. Classes are the types of objects that will be calculated. Count_by_frames defines the granularity level of response. If True,the number of objects will be shown for every frame of an input video.
video*	string	video file ($binary)
metadata*	object	Dictionary with a "camera_id" key. Example: { "camera_id": "b5271b30-aecd-4897-bc95-ff25c8466b9e" }

200 An example of a response with counting_options set as described in parameters description

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

Example

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

POST 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*	string	Authorization API key to access Traces Counting API

Request Body

Name	Type	Description
counting_options*	object	Dictionary with a list of spaces where a dwell time should be calculated. See example data.json below

200

{"status": "success"}

data.json

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

Example

 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

POST 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*	string	Authorization API key to access Traces Counting API

Request Body

Name	Type	Description
video*	string	video file ($binary)
metadata*	object	Dictionary with "camera_id" key. Example: { "camera_id": "b5271b30-aecd-4897-bc95-ff25c8466b9e" }

200

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

Example

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

POST 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*	string	Authorization API key to access Traces Counting API

Request Body

Name	Type	Description
video*	string	video file ($binary)
metadata*	object	Dictionary with "camera_id" key. Example: { "camera_id": "b5271b30-aecd-4897-bc95-ff25c8466b9e" }

200

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

Example

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"