# Introduction The Traces API is organized around REST architectural style. Our API has predictable resource-oriented URLs, JSON-encoded responses, standard HTTP response codes, and key-based authentication. If you are our current customer your version of Traces API may differ from this reference as we continuously release new versions and tailor functionality for your individual needs. Follow your cluster URL or log in to the Knowledge Сenter to see documentation customized to your version of the API, with your API keys and data. {% hint style="info" %} ### **Data migration has not finished yet!** Please refer to the Knowledge Center for the latest documentation. **TODO** * [x] Add Counting API * [x] Add FAF API * [ ] Add People Search API {% endhint %} # Development Quickstart **Get up and running with our API and start building AI-powered products today.** Working with the latest version of Traces’ AI can begin as soon as you follow these three steps: * Obtain your API keys so Traces can authenticate your API request * Familiarise yourself with the relevant documentation for your product. * Make a test API request to confirm everything is up and running. {% hint style="info" %} ### Not a developer? Talk to our Customer Success Engineer to get the most out of our technology without writing any code {% endhint %} Get in touch with the [Customer Success Engineer](https://www.traces.ai/contacts) now. ### **Obtain your API keys** Traces authenticates your API requests using your account’s API keys. If you don’t have a valid API Key contact your Traces Account Manager. ### **Read relevant documentation** We have documented the most common use cases for our API. If you are our current customer your version of Traces API may be different as we continuously release new versions and tailor functionality for your individual needs. Follow your cluster URL or log in to the Knowledge Сenter to see the latest updates. ### **Make a test API request** To check that your integration is working correctly, make a test API request using your API key. We’ve pre-filled some code examples for your convenience. `POST` `http://faf.traces.cloud/api/v1.1/filter-alarm` #### Headers | Name | Type | Description | | -------------------------------------------------- | ------ | ---------------------------------------------- | | X-Traces-API-Key\* | string | Authorization API key to access Traces FAF API | #### Request Body | Name | Type | Description | | ------------------------------------------ | ------ | ---------------------------------------------------------------------------- | | metadata\* | object | A dictionary with the following keys: "event\_id", "camera\_id", "timestamp" | | image\_0\* | object | frame #1 | | image\_1\* | object | frame #2 | | image\_2\* | object | frame #3 | | image\_3\* | object | frame #4 | | image\_4\* | object | frame #5 | {% tabs %} {% tab title="200 " %} ```javascript { "alarm_confirmed": true, "alarm_confidence": 0.7892204529672106, "triggered_by": [ { "object_type": "vehicle", "action": "moving", "bbox": [ 527, 400, 827, 569 ], "frame_id": 0, "direction": null }, { "object_type": "vehicle", "action": "moving", "bbox": [ 122, 399, 335, 536 ], "frame_id": 1, "direction": null }, { "object_type": "vehicle", "action": "moving", "bbox": [ 202, 270, 325, 337 ], "frame_id": 2, "direction": null } ] } ``` {% endtab %} {% tab title="401 " %} ``` { "code": "INVALID_API_KEY", "description": "API key was not recognized" } ``` {% endtab %} {% endtabs %} ### Example {% tabs %} {% tab title="Bash" %} ```bash curl -X POST "http://faf.traces.cloud/api/v1.1/filter-alarm" -H "accept: */*" -H "X-Traces-API-Key: YOUR_API_KEY" -H "Content-Type: multipart/form-data" -F "metadata={ "event_id": "ddf27b34-d3b5-41a5-b2a6-3873a589ec09", "camera_id": "b5271b30-aecd-4897-bc95-ff25c8466b9e", "timestamp": 1585840725 }" -F "image_0=@customer_frame0.png;type=image/png" -F "image_1=@customer_frame1.png;type=image/png" -F "image_2=@customer_frame2.png;type=image/png" -F "image_3=@customer_frame3.png;type=image/png" -F "image_4=@customer_frame4.png;type=image/png" ``` {% endtab %} {% endtabs %} # Сluster URL structure ### Cluster URL structure: [](https://k1.traces.cloud/api/v1/searchByImage) | Name | Mandatory | Info | | ------------- | --------- | --------------------------------------------------- | | k111 | | name of your cluster | | traces.cloud | | Traces domain name with top-level domain | | v1 | | a version of your API | | searchByImage | | API endpoint name | | doc | | documentation customized to your version of the API | {% hint style="info" %} ### traces.cloud VS traces.ai is the only root domain utilized to serve Traces APIs. is a corporate root domain of Traces Inc. and it can not be used interchangeably with traces.cloud {% endhint %} # API Reference ## API keys Traces authenticates your API requests using your account’s API keys. Making an API request that doesn't include your key, includes incorrect or outdated key returns an error. If you don’t have a valid API Key contact your Traces Account Manager. ### Test and Prod Keys There are separate keys for testing and production workloads. All data submitted with a Test API key is removed automatically within 5 days and can not be restored. Auto Training Pipeline is not initiated with Test API calls. Use test API keys during the development and Prod API keys from production workloads. ### Keeping your API keys safe Your API key can be used to make any API call on behalf of your account. * Keep your API key as secure as any other password. * Keep your API key out of your version control system. * Share your API key only with those who need it. * Use secret management services and password managers Should you think your API key has been compromised, contact your Traces Account Manager immediately. ## HTTP response codes Traces uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with the computation cluster. | HTTP Code | Status | Explanation | | ------------------ | ----------------- | ------------------------------------------------------------------------------------------------ | | 200 | OK | Everything worked as expected | | 400 | Bad Request | The request was unacceptable, often due to missing a required parameter. | | 401 | Unauthorized | The parameters were valid but the request failed. | | 402 | Request Failed | The API key doesn't have permission to perform the request. | | 403 | Forbidden | The API key doesn't have permission to perform the request. | | 404 | Not Found | The requested resource doesn't exist. | | 429 | Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. | | 500, 502, 503, 504 | Server Errors | Cluster encountered an unexpected condition that prevented it from fulfilling the request | # False Alarm Filtering (FAF) ## Introduction Verifies video motion alerts by getting information about the source of an alarm, coordinates of an object of interest (bounding boxes), and many more. Traces False Alarm Filtering solution accurately highlights important events while filtering out irrelevant noise caused by animals, insects, weather, etc. ## Key Features * Video and Frame-based analytics * Person Detection * Vehicle Detection * Custom Object Detection * Near real-time performance * Auto Training pipeline ## Architecture diagram ![Document image](https://archbee.imgix.net/bLFGjdFdIY6MzXs3Kd3G8/be6l6Nk42hkExiKQ8ByRA_fafv12mainwiki.png?auto=format\&ixlib=react-9.1.1\&h=1723\&w=2200) # FAF API ## Health ## health `GET` `https://faf.traces.cloud/api/v1/health` This endpoint allows to test that service is up #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ---------------------------------------------- | | x-api-key\* | string | Authorization API key to access Traces FAF API | {% tabs %} {% tab title="200 " %} ``` ALIVE ``` {% endtab %} {% tab title="404 " %} ``` ``` {% endtab %} {% endtabs %} #### Example {% tabs %} {% tab title="Bash" %} ```sh curl -X GET https://faf.traces.cloud/api/v1.1/health -H "x-api-key: YOUR_API_KEY" ``` {% endtab %} {% endtabs %} ## Operations ## filter-alarm `POST` `https://faf.traces.cloud/api/v1/filter-alarm` Performs alarm filtering and returns alarm type, confidence, and a list of objects that triggered an event with corresponding information. \ This endpoint accepts any number of frames with a minimum limit of 5 frames per event. #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ---------------------------------------------- | | x-api-key\* | string | Authorization API key to access Traces FAF API | #### Request Body | Name | Type | Description | | ------------------------------------------ | ------ | ---------------------------------------------------------------------------- | | metadata\* | object | A dictionary with the following keys: "event\_id", "camera\_id", "timestamp" | | image\_0\* | string | frame #1; image file ($binary) | | image\_1\* | string | frame #2; image file ($binary) | | image\_2\* | string | frame #3; image file ($binary) | | image\_3\* | string | frame #4; image file ($binary) | | image\_4\* | string | frame #5; image file ($binary) | {% tabs %} {% tab title="200 An example of an API response to an alarm that was triggered by a vehicle with coordinates of moving vehicle on each frame." %} ```javascript { "alarm_confirmed": true, "alarm_confidence": 0.7892204529672106, "triggered_by": [ { "object_type": "vehicle", "action": "moving", "bbox": [ 527, 400, 827, 569 ], "frame_id": 0, "direction": null }, { "object_type": "vehicle", "action": "moving", "bbox": [ 122, 399, 335, 536 ], "frame_id": 1, "direction": null }, { "object_type": "vehicle", "action": "moving", "bbox": [ 202, 270, 325, 337 ], "frame_id": 2, "direction": null } ] } ``` {% endtab %} {% tab title="401 Auth data was not provided" %} ```javascript { "code": "INVALID_API_KEY", "description": "API key was not recognized" } ``` {% endtab %} {% endtabs %} ### **Example** An example of a request with 5 frames. {% tabs %} {% tab title="Bash" %} ```bash curl -X POST "https://faf.traces.cloud/api/v1.1/filter-alarm" -H "accept: */*" -H "x-api-key: YOUR_API_KEY" -H "Content-Type: multipart/form-data" -F "metadata={ "event_id": "ddf27b34-d3b5-41a5-b2a6-3873a589ec09", "camera_id": "b5271b30-aecd-4897-bc95-ff25c8466b9e", "timestamp": 1585840725 }" -F "image_0=@customer_frame0.png;type=image/png" -F "image_1=@customer_frame1.png;type=image/png" -F "image_2=@customer_frame2.png;type=image/png" -F "image_3=@customer_frame3.png;type=image/png" -F "image_4=@customer_frame4.png;type=image/png" ``` {% endtab %} {% endtabs %} An example of a request with 12 frames. ```javascript curl -X POST "https://faf.traces.cloud/api/v1.1/filter-alarm" -H "accept: */*" -H "x-api-key: YOUR_API_KEY" -H "Content-Type: multipart/form-data" -F "metadata={ "event_id": "ddf27b34-d3b5-41a5-b2a6-3873a589ec09", "camera_id": "b5271b30-aecd-4897-bc95-ff25c8466b9e", "timestamp": 1585840725 }" -F "image_0=@customer_frame0.png;type=image/png" -F "image_1=@customer_frame1.png;type=image/png" -F "image_2=@customer_frame2.png;type=image/png" -F "image_3=@customer_frame3.png;type=image/png" -F "image_4=@customer_frame4.png;type=image/png" -F "image_5=@customer_frame5.png;type=image/png" -F "image_6=@customer_frame6.png;type=image/png" -F "image_7=@customer_frame7.png;type=image/png" -F "image_8=@customer_frame8.png;type=image/png" -F "image_9=@customer_frame9.png;type=image/png" -F "image_10=@customer_frame10.png;type=image/png" -F "image_11=@customer_frame11.png;type=image/png" ``` ## filter-video-alarm `POST` `https://faf.traces.cloud/api/v1/filter-video-alarm` Performs alarm filtering and returns alarm type, confidence, and a list of objects that triggered an event with corresponding information. \ This endpoint accepts video files. \ It is recommended to send a video 10-20 seconds long. Sending videos longer than 30 seconds may result in a prolonged response time. #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ---------------------------------------------- | | x-api-key\* | string | Authorization API key to access Traces FAF API | #### Request Body | Name | Type | Description | | ------------------------------------------ | ------ | ---------------------------------------------------------------------------- | | video\* | string | video file ($binary) | | metadata\* | object | A dictionary with the following keys: "event\_id", "camera\_id", "timestamp" | {% tabs %} {% tab title="200 An example of an API response to an alarm that was triggered by a vehicle with coordinates of moving vehicle on each frame. " %} ```javascript { "alarm_confirmed": true, "alarm_confidence": 0.7892204529672106, "triggered_by": [ { "object_type": "vehicle", "action": "moving", "bbox": [ 527, 400, 827, 569 ], "frame_id": 0, "direction": null }, { "object_type": "vehicle", "action": "moving", "bbox": [ 122, 399, 335, 536 ], "frame_id": 1, "direction": null }, { "object_type": "vehicle", "action": "moving", "bbox": [ 202, 270, 325, 337 ], "frame_id": 2, "direction": null } ] } ``` {% endtab %} {% tab title="401 " %} ```javascript { "code": "INVALID_API_KEY", "description": "API key was not recognized" } ``` {% endtab %} {% endtabs %} ## **Examples of Alarm Responses to different motion events** ### Examples of Alarm Responses for customers on a General tier. Each trigger includes the following information for each frame: '`object_type`', '`action`', '`bbox`', '`frame_id`', and '`direction`'. If more information is needed, refer to [examples of Alarm Responses on an Advanced tier](#5l-example-of-alarm-triggered-by-person-and-vehicle-1). #### **Example of False Alarm** Input data ![Click to Zoom](https://archbee.imgix.net/bLFGjdFdIY6MzXs3Kd3G8/n9SVMcTXNFMXc_b2edvPl_false-alarm.png?auto=format\&ixlib=react-9.1.1\&h=109\&w=968) FAF Response ```javascript { "alarm_confirmed": false, "alarm_confidence": null, "triggered_by": [] } ``` #### **Example of an alarm triggered by a "Person"** Input data ![Click to Zoom](https://archbee.imgix.net/bLFGjdFdIY6MzXs3Kd3G8/0EvWI1O2aL-PwLe8lcUO6_person.png?auto=format\&ixlib=react-9.1.1\&h=364\&w=3224) FAF Response ```javascript { "alarm_confirmed": true, "alarm_confidence": 0.7866996370706637, "triggered_by": [ { "object_type": "person", "action": "moving", "bbox": [ 621, 1051, 711, 1269 ], "frame_id": 0, "direction": null }, { "object_type": "person", "action": "moving", "bbox": [ 959, 1100, 1031, 1337 ], "frame_id": 0, "direction": null }, { "object_type": "person", "action": "moving", "bbox": [ 718, 1148, 815, 1368 ], "frame_id": 0, "direction": null }, { "object_type": "person", "action": "moving", "bbox": [ 769, 977, 859, 1233 ], "frame_id": 1, "direction": null }, { "object_type": "person", "action": "moving", "bbox": [ 687, 971, 771, 1189 ], "frame_id": 1, "direction": null }, { "object_type": "person", "action": "moving", "bbox": [ 940, 983, 1026, 1217 ], "frame_id": 1, "direction": null }, { "object_type": "person", "action": "moving", "bbox": [ 983, 875, 1059, 1086 ], "frame_id": 2, "direction": null }, { "object_type": "person", "action": "moving", "bbox": [ 833, 886, 894, 1121 ], "frame_id": 2, "direction": null }, { "object_type": "person", "action": "moving", "bbox": [ 738, 871, 816, 1080 ], "frame_id": 2, "direction": null } ] } ``` #### **Example of an alarm triggered by "Vehicle"** Input data ![Click to Zoom](https://archbee.imgix.net/bLFGjdFdIY6MzXs3Kd3G8/WDZ51A2rUH7tjeYT2EPLY_vehicle.png?auto=format\&ixlib=react-9.1.1\&h=361\&w=3227) FAF Response ```javascript { "alarm_confirmed": true, "alarm_confidence": 0.7540868690800507, "triggered_by": [ { "object_type": "vehicle", "action": "moving", "bbox": [ 2084, 604, 2420, 774 ], "frame_id": 0, "direction": null }, { "object_type": "vehicle", "action": "moving", "bbox": [ 1433, 456, 1723, 588 ], "frame_id": 1, "direction": null }, { "object_type": "vehicle", "action": "moving", "bbox": [ 805, 514, 1104, 699 ], "frame_id": 2, "direction": null } ] } ``` #### **Example of an alarm triggered by both "Person" and "Vehicle"** Input data ![Click to Zoom](https://archbee.imgix.net/bLFGjdFdIY6MzXs3Kd3G8/008t9UW4ZE-QOGk1Wuhsd_personandvehicle.png?auto=format\&ixlib=react-9.1.1\&h=362\&w=3224) FAF Response ```javascript { "alarm_confirmed": true, "alarm_confidence": 0.6292241402835548, "triggered_by": [ { "object_type": "vehicle", "action": "moving", "bbox": [ 677, 486, 925, 653 ], "frame_id": 0, "direction": null }, { "object_type": "person", "action": "moving", "bbox": [ 447, 195, 496, 269 ], "frame_id": 0, "direction": null }, { "object_type": "vehicle", "action": "moving", "bbox": [ 673, 466, 923, 653 ], "frame_id": 1, "direction": null }, { "object_type": "person", "action": "moving", "bbox": [ 588, 393, 624, 495 ], "frame_id": 1, "direction": null }, { "object_type": "vehicle", "action": "moving", "bbox": [ 584, 468, 814, 620 ], "frame_id": 2, "direction": null } ] } ``` ### Examples of Alarm Responses for customers on an Advanced tier. Customers on the Advanced tier will receive comprehensive alarm responses that contain all the information from the General tier, as well as additional data fields such as `object_class` and `object_color`. These fields provide additional context and insights into the alarm event, enabling customers to quickly and effectively respond to any issues with their system. > The newly introduced `object_class` field provides supplementary information regarding the specific class of a vehicle that has triggered an alarm. The supported vehicle classes within our API solution include four distinct categories: "car", "truck", "bus", and "motorbike". > The recently added `object_color` field outlines the color of a vehicle that has triggered an alarm. Our library comprises 147 distinct colors for this purpose. The `object_color` value is computed for each bounding box associated with a vehicle trigger. It is important to note that factors such as varying lighting conditions and shadows may influence the accuracy of the detected color. Below are some examples of input data and their corresponding responses with updated structure. These examples showcase the latest changes and improvements to the response format, enabling customers to better understand and utilize our API's features. #### **Examples of an alarm triggered by both "Vehicle" with extended details.** Example 1. Input data
FAF Response ```javascript { "alarm_confirmed": true, "alarm_confidence": 0.8125502391157845, "triggered_by": [ { "object_type": "vehicle", "object_class": "car", "action": "moving", "bbox": [ 520, 352, 714, 512 ], "frame_id": 0, "direction": null, "object_color": "slategray" }, { "object_type": "vehicle", "object_class": "car", "action": "moving", "bbox": [ 413, 345, 574, 472 ], "frame_id": 1, "direction": null, "object_color": "slategray" }, { "object_type": "vehicle", "object_class": "car", "action": "moving", "bbox": [ 392, 322, 511, 450 ], "frame_id": 2, "direction": null, "object_color": "slategray" } ] } ``` Example 2. Input data
FAF Response ```javascript { "alarm_confirmed": true, "alarm_confidence": 0.7021554756882509, "triggered_by": [ { "object_type": "vehicle", "object_class": "car", "action": "moving", "bbox": [ 588, 332, 672, 371 ], "frame_id": 0, "direction": null, "object_color": "darkslateblue" }, { "object_type": "vehicle", "object_class": "car", "action": "moving", "bbox": [ 628, 319, 709, 361 ], "frame_id": 1, "direction": null, "object_color": "darkslateblue" }, { "object_type": "vehicle", "object_class": "car", "action": "moving", "bbox": [ 727, 313, 826, 347 ], "frame_id": 2, "direction": null, "object_color": "darkslateblue" } ] } ``` Example 3. Input data
FAF Response ```javascript { "alarm_confirmed": true, "alarm_confidence": 0.694689647096008, "triggered_by": [ { "object_type": "vehicle", "object_class": "car", "action": "moving", "bbox": [ 1537, 77, 1627, 167 ], "frame_id": 0, "direction": null, "object_color": "darkslategray" }, { "object_type": "vehicle", "object_class": "car", "action": "moving", "bbox": [ 1475, 137, 1579, 238 ], "frame_id": 1, "direction": null, "object_color": "darkslategray" }, { "object_type": "person", "object_class": "person", "action": "moving", "bbox": [ 451, 482, 490, 585 ], "frame_id": 1, "direction": null, "object_color": null }, { "object_type": "vehicle", "object_class": "car", "action": "moving", "bbox": [ 1379, 201, 1515, 316 ], "frame_id": 2, "direction": null, "object_color": "darkslategray" }, { "object_type": "person", "object_class": "person", "action": "moving", "bbox": [ 456, 476, 497, 575 ], "frame_id": 2, "direction": null, "object_color": null } ] } ``` ## **EventMetadata**
KeyTypeExampleDescription
camera_id*str"b5271b30-aecd-4897-bc95-ff25c8466b9e"A unique ID number of the video camera. Used for AI auto training pipeline, consensus algorithm, and billing.
timestamp* int1585840725A timestamp in seconds since the epoch
event_id*str"ddf27b34-d3b5-41a5-b2a6-3873a589ec09"

A unique ID of the event.

Used for synchronization and AI auto training pipeline

motion_maskslist

[((0, 0), (900, 0),
 (900, 130), (0, 580)), 
 ((1920, 1090), (1920, 500),
 (1000, 1090))]
List of motion mask coordinates. See/pages/-McYoj-nubTXQvpJsE8G#motion-masks for more details
# Best Practices Traces FAF API accepts both videos and frames as input. Below you may find general recommendations for each data type. ## How to sample frames for a motion event? Correct frame selection is an important factor for getting the most accurate results. The advice may vary for every use-case individually, so it is best to talk to Traces Account Manager to schedule a demo. Below you may find a general recommendation for frames sampling. Traces AI FAF accepts any number of frames. Even as little as 5 frames are usually enough to receive accurate results. For motion events that are 10 - 15 seconds long, it is recommended to split a video equally into 4 chunks and take the first frame of each chuck and the last frame from the last chunk as shown on a diagram. For example, given a 10 seconds long motion event with 12 fps, it is best to sample * **frame #0,** * **frame #30,** * **frame #60,** * **frame #90, and** * **frame #120** and send it to Traces FAF as fields "image\_0", "image\_1", "image\_2", "image\_3", and "image\_4" respectively. ![frame sampling](https://archbee.imgix.net/bLFGjdFdIY6MzXs3Kd3G8/IhEbt9dMEVWym95LiozhD_group-369.png?auto=format\&ixlib=react-9.1.1\&h=244\&w=2293) ## Recommendations for videos Traces AI accepts .mp4, .m4v, .avi video formats. A general recommendation is to send a video 10-20 seconds long. It is advisable to avoid sending videos over 30 seconds long as it may cause a long response time. ## Motion Masks Motion mask is an area on a video/frame where motion triggers will be ignored. The mask indicates an insignificant area from a camera view. It is defined by a customer and unique for every camera. Each motion mask is represented by a set of coordinates that form a polygon. All coordinates should be within the image's dimension to guarantee correct results. Traces AI supports an unlimited number of motion masks per event of any shape and any size. #### Below are some examples of various motion masks (blue), given an image (gray) of 1920\*1080 resolution. {% tabs %} {% tab title="Example 1" %} Motion mask - `[((1920, 500), (1920, 1080), (1000, 1080))]` ![](/files/or33zn3ZrWtTQYgn04rM) {% endtab %} {% tab title="Example 2" %} Motion mask - `[((0, 500), (150, 800), (200, 600), (700, 400), (400, 400), (100,200))]` ![](/files/giMlqHmsr2c8jBFQwgNC) {% endtab %} {% tab title="Example 3" %} Motion mask - `[((0, 500), (150, 800), (200, 600), (700, 400), (400, 400), (100,200)), ((1920, 500), (1920, 1080), (1000, 1080))]` ![](/files/K12YAqVlp9GBeNJrPW1T) {% endtab %} {% endtabs %} ## Cameras ID & Cameras Location All motion events that are coming from the same camera should have the same scenery. Changing camera location and using the same Cameras ID will reset the AI auto training progress. # How to Connect Traces offers multiple connection interfaces that can be built on top of the same REST API. ![Document image](https://archbee.imgix.net/bLFGjdFdIY6MzXs3Kd3G8/phTrl5B_C_RpOrDWwpXKF_how-to-connect.png?auto=format\&ixlib=react-9.1.1\&h=360\&w=514) ## App Build web, mobile, backend applications and interact with our [API](/faf-api/api) using your favorite programming language. We are using predictable resource-oriented URLs, JSON-encoded responses, standard [HTTP response codes](https://docs.traces.cloud/api-reference#un-http-response-codes), and key-based authentication. ## VMS and NVR Connections are possible through custom integration, native Traces plugins, or other means provided by the VMS/NVR manufacturers. ## SMTP gateway The standard function of most cameras and NVRs is to send an email alert when certain types of events occur. Also known as SMTP push mail notification. Traces SMTP gateway receives an email alert, classify the source and forward the results to your system. ## EDGE Appliance Similar to VMS/NVR integration there are multiple means of connecting your cameras to Traces API through EDGE Appliance. {% hint style="success" %} ### What option is right for you? Talk to our Customer Success Engineers to get the most out of our technology or refer to this quick guide to learn more about every option. {% endhint %} # Advanced Event Understanding ## Introduction Welcome to the Advanced Event Understanding API, a cutting-edge solution for sophisticated event analysis and interpretation. Our API harnesses the power of advanced AI technology to provide deep, real-time insights for your security and surveillance applications. By processing multiple images and associated metadata, our system offers unparalleled event comprehension, enabling you to make informed decisions quickly and efficiently. ## Key Features * **Efficient Multi-Image Processing**: Analyze 5 or more strategic images per event, providing comprehensive understanding without the need for extensive data transfer. * **Advanced AI Interpretation**: Extract deep insights from limited visual data, offering sophisticated event analysis that rivals full video processing. * **Real-time Analysis**: Receive instant results for time-critical decision-making. * **Flexible Integration**: Seamlessly incorporate our RESTful API into your existing systems. * **Secure Communication**: Protect your data with robust API key authentication. ## Authentication All API requests require authentication using an API key. Include your API key in the `x-api-key` header for all requests. If you don't have an API key, you can obtain one by contacting our support team at . ## API Endpoints {% openapi src="/files/NL9kP5zcWoqnJpwD2lBz" path="/health" method="get" %} [swagger\_codesamples.json](https://2748832723-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-McYmA310oN--gaDwXjq%2Fuploads%2Fe9wxqsFHWfwLXzVy1Tlp%2Fswagger_codesamples.json?alt=media\&token=89667d40-8b2e-4db7-8316-78382d6b3bc6) {% endopenapi %} {% openapi src="/files/0KzCtdmBSZFx3iKCtHZT" path="/event/process" method="post" %} [swagger\_codesamples.json](https://2748832723-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-McYmA310oN--gaDwXjq%2Fuploads%2FRFsJ723mp5rtGbSZ7IHe%2Fswagger_codesamples.json?alt=media\&token=4821a9a0-7f0a-4b5e-80a5-bf4aae62e01e) {% endopenapi %} {% openapi src="/files/0KzCtdmBSZFx3iKCtHZT" path="/event/advanced\_understanding" method="get" %} [swagger\_codesamples.json](https://2748832723-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-McYmA310oN--gaDwXjq%2Fuploads%2FRFsJ723mp5rtGbSZ7IHe%2Fswagger_codesamples.json?alt=media\&token=4821a9a0-7f0a-4b5e-80a5-bf4aae62e01e) {% endopenapi %} ## Examples

Input data

{% code overflow="wrap" fullWidth="true" %} ```json { "status": "completed", "result": { "event_summary": "A person wearing a light-colored hoodie approaches a black car parked on the side of a street. The person appears to attempt to open the side door, but the car is locked. The person gains entry to the car.", "predicted_attributes": { "people_descriptions": [ "light-colored hoodie", "dark jeans" ], "people_actions": [ "trying to break in" ], "logos": [ "None" ], "vehicle_descriptions": [ "a black car" ], "vehicle_actions": [ "parked" ], "suspicion_status": "highly suspicious" } } } ``` {% endcode %} ## Advanced Features Our Advanced Event Understanding API offers a range of sophisticated capabilities: 1. **Multi-image Analysis**: Process 5 or more images per event for comprehensive understanding. 2. **Object Detection and Classification**: Identify and categorize objects, people, and vehicles in the scene. 3. **Action Recognition**: Understand and interpret the actions and behaviors of detected entities. 4. **Contextual Analysis**: Evaluate the overall situation and relationships between objects and actions. 5. **Natural Language Summaries**: Generate human-readable descriptions of events for quick comprehension. 6. **Suspicion Assessment**: Automatically evaluate the potential threat level of events. # Counting Add something ? ## Introduction Traces People Counting enables conventional IP security cameras with counting capabilities. ## Key Features * Double-counting reduction system * Gender detection * Age detection * Heatmaps * Dwelling behavior * Employees tracking ### **Double-counting reduction** Significantly reduces the number of double-counting events. Best used in scenarios where staff members or service personnel have to use the same pathway with the customers. *Example: A security guard (courier/cashier, consultant, etc) can be caught by the camera in the area of interest, and counted multiple times. A double-counting reduction system filters such false-positive events from statistics.* ### **Heatmap** Analyze customers’ flow and provide insight like information about areas of high interest that should be properly stocked and managed. Information can be split by different time ranges, days of the week, and months. ### **Dwelling behavior** Understand how long a customer spends in the area of interest. A deep analysis of this metric can lead to a better understanding of shopping behavior and an increase in customer spending. ### **Employees tracking** Monitor worker engagement with workplace-related tasks and track activities. ## Architecture diagram ![Document image](https://archbee.imgix.net/bLFGjdFdIY6MzXs3Kd3G8/P1weENoCPtLKFYqatP3-d_peoplecountingmain.png?auto=format\&ixlib=react-9.1.1\&h=1723\&w=2200) {% hint style="warning" %} ### Data migration has not finished yet Please refer to the [Knowledge Cente](https://www.traces.ai/resources/knowledge-center)r for the latest documentation. {% endhint %}  # 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 | {% tabs %} {% tab title="200 " %} ``` ALIVE ``` {% endtab %} {% endtabs %} ### Example ```javascript 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](/counting/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 `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 | {% 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 `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" }

| {% 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 `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 | {% 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 `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" }` | {% 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 `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" }` | {% 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" ``` # Best Practises ## Counting triangle Traces solution calculates the number of people that are passing by any area of interest in a camera. In order to define an area of interest, a *'counting triangle'* should be set. The *'counting triangle'* consists of a base and an apex. A base is used to calculate the number of people who pass by the line from both sides. An apex is used to define which side should be considered as an entrance. In order to send the coordinates of triangle use: * x1, y1; x2, y2 - to denote vertex of the base * x3, y3 - to denote the direction of the entrance(apex). See below in the examples: ![Examples of how to define counting triangles](/files/-McaDFnEA7oubEgtG219) # People Search {% hint style="warning" %} ### Data migration has not finished yet Please refer to the [Knowledge Center](https://www.traces.ai/resources/knowledge-center) for the latest documentation. {% endhint %} # Solutions ## Auto Training Pipeline To provide the best performance to each customer, Traces AI retrains itself based on a customer’s specific use cases. This approach automatically improves an AI model’s performance by increasing accuracy over time. ![Document image](https://archbee.imgix.net/bLFGjdFdIY6MzXs3Kd3G8/N7KoGiiSwVWH3Ft9bRlr1_autotrainingpipeline.png?auto=format\&ixlib=react-9.1.1\&h=904\&w=1910)