Skip to main content
Version: 4.0.0

Multi Object Counter API

Ultinous AI Suite's measurement-based counters are designed to be used with custom third party software. This guide will cover how the data created by the counters can be read from Ultinous AI Suite.

If you wish to double-check the data produced by your counters, they can be viewed inside Ultinous AI Suite as well, in a dedicated Counters interface.

Prerequisites​

  • Finished the Quick Start Guide and created a test Solution to make sure that your camera is working and events are triggered. (This test Solution can be deleted after testing.)
  • Created an API Token so that the third party software has access to Ultinous AI Suite.
  • Created a Multi Object Counter. Please note that the technical name value will be the identifier value for the API. This is a UUID by default, but can be renamed to any unique string.

Using the API​

The output from each counter is a number indicating the number of detections in the union of all cameras' regions of interests (ROI).

The API is read-only and has two main ways of accessing the counters:

  • Batch mode, where past counter values are of interest.
  • Live Server Side Event mode for real time processing of values.

A list of available technical names can also be queried: these are unique identifiers assigned to each registered solution. Editable in the Ultinous AI Suite web interface, otherwise a default technical name is generated.

To reach the endpoints, an API token has to be generated - see the API Token section of the guide.

Each aggregation contains:​

  • an object_type string, which is one of PERSON_FULL_BODY, MOTORCYCLE, CAR, TRAIN, TRUCK, BUS, BICYCLE, BOAT, AIRPLANE
  • a first integer, the number of detections in the first frame of the aggregation period
  • a last integer, the number of detections in the last frame of the aggregation period
  • an average float, the average number of detections
  • a median float, the median of detections in the whole aggregation period
  • a min integer, the sum of detections on the last frame in the aggregation period
  • and a max integer, the sum of detections on the first frame in the aggregation period

The above is true for any output schema, regardless of the mode it is requested in.

API URL​

const url = "http://<address-of-Ultinous AI Suite>/API"; //< note the /API at the end.

Bach mode​

JSON output​

Path: /counter/batch

Parameters:

  • from_timestamp: (int64) The starting timestamp of the request interval (inclusive).
  • to_timestamp: (int64) The end timestamp of the request interval (exclusive).
  • technical_name: (string) The 'Technical name' of the solution.

Example javascript​

The following example is using javascript and its fetch function to show how these values can be read.

const url = "http://<address-of-Ultinous AI Suite>/API"; //< note the /API at the end.
/**
 * maximum time interval is three days
 * @param technical_name: string ; counter technical name
 * @param token : A base64 token issued by Ultinous AI Suite
 * @param from_timestamp : unix timestamp;  Only show counter values from given date
 * @param to_timestamp : unix timestamp;  Show values until.
 */
const params = new URLSearchParams({
    'from_timestamp':'unix-timestamp',
    'to_timestamp':'unix-timestamp',
    'token':'api-token',
    'technical_name':'counter-technical-name'
});

fetch(`${url}/counter/batch${params.toString()}`)
    .then( value => console.log(value.json()))

Example response​

[ //< Array of aggregation periods
    {
    "from_timestamp": 1625215860000,
    "to_timestamp": 1625215865000,
    //^ next aggregation periods from_timestamp is equal to this periods to_timestamp
    "status": "ERROR", //< status is OK or ERROR.
    "aggregations": [
      {
       "object_type": "BOAT",
       //^ out of the 9 main object types, only those will be listed in the aggregations array that are selected in the UI
       "first": 0,
        //^ first: integer, exact number of detections on the first frame in the aggregation period
       "last": 0,
        //^ last: integer, exact number of detections on the last frame in the aggregation period
       "median": 0.0,
        //^ median: float, median of detections in the whole aggregation period
       "average": 0.0,
       //^ average: float, average number of detections in the whole aggregation period
       "min": 0,
        //^ min: integer, exact sum of detections on the first frame in the aggregation period
       "max": 0,
        //^ max: integer, exact sum of detections on the last frame in the aggregation period
      },
      {"object_type": "PERSON_FULL_BODY","first": 0, "last": 0, "median": 0.0, "average": 0.2, "min": 0, "max": 0},
      {"object_type": "CAR",             "first": 0, "last": 0, "median": 0.0, "average": 0.0, "min": 0, "max": 0},
      {"object_type": "MOTORCYCLE",      "first": 0, "last": 0, "median": 0.0, "average": 0.1, "min": 0, "max": 0},
      {"object_type": "AIRPLANE",        "first": 0, "last": 0, "median": 0.0, "average": 0.2, "min": 0, "max": 0},
      {"object_type": "TRAIN",           "first": 0, "last": 0, "median": 0.0, "average": 0.2, "min": 0, "max": 0},
      {"object_type": "TRUCK",           "first": 0, "last": 0, "median": 0.0, "average": 0.0, "min": 0, "max": 0},
      {"object_type": "BICYCLE",         "first": 0, "last": 0, "median": 0.0, "average": 0.0, "min": 0, "max": 0},
      {"object_type": "BUS",             "first": 0, "last": 0, "median": 0.0, "average": 0.1, "min": 0, "max": 0}
    ],
    "cameras_with_error": [
    //^ If status is ERROR, cameras_with_error array will show the cameras that are unreachable
        {"display_name": "Front Yard", "technical_name": "frontyard-hd"}
    ]
  }
]

CSV output​

Path: /counter/batch/csv

Parameters:

  • from_timestamp: (int64) The starting timestamp of the request interval (inclusive).
  • to_timestamp: (int64) The end timestamp of the request interval (exclusive).
  • technical_name: (string) The UUID of the solution.
  • token: (string) The token you generated in the web interface, see above.

Example javascript​

The following example is using javascript and its fetch function to show how these values can be read.

const url = "http://<address-of-Ultinous AI Suite>/API"; //< note the /API at the end.
/**
 * maximum time interval is three days
 * @param technical_name: string ;  counter technical name
 * @param token  : A base64 token issued by Ultinous AI Suite
 * @param from_timestamp : unix timestamp;  Only show counter values from given date
 * @param to_timestamp :   unix timestamp;  Show values until.
 */
const params = new URLSearchParams({
    'from_timestamp':'unix-timestamp',
    'to_timestamp':'unix-timestamp',
    'token':'api-token',
    'technical_name':'counter-technical-name'
});

fetch(`${url}/counter/batch/csv${params.toString()}`)
    .then( value => console.log(value.json()))

Example response​

from_timestamp,to_timestamp,status,object_type,first,last,min,max,average,median,cameras_with_error
1659463120000,1659463124999,OK,CAR,0,0,0,0,0.0,0.0,
1659463120000,1659463124999,OK,PERSON_FULL_BODY,2,2,2,2,2.0,2.0,
1659463125000,1659463129999,OK,CAR,0,0,0,0,0.0,0.0,
1659463125000,1659463129999,OK,PERSON_FULL_BODY,3,3,3,3,3.0,3.0,
1659463130000,1659463134999,OK,CAR,0,0,0,0,0.0,0.0,
1659463130000,1659463134999,OK,PERSON_FULL_BODY,2,2,2,2,2.0,2.0,

Server Side Event Mode​

Path: /counter/live

Parameters:

  • technical_names: array of technical names

Time ordered merged

Example request​

const params = new URLSearchParams({
    'token':'api-token',
    'technical_names':['name-1','name2'] //< Multiple technical_names can be requested
});
const evtPath = `${url}/counter/live?${params.toString()}`
const evtSource = new EventSource(evtPath)
evtSource.onmessage = evt => console.log(evt.data)

Example response​

[ //< Array of technical_name and record pairs
  {
  "technical_name": "name-1",
  "record": { //< A record contains a single aggregation period
    "from_timestamp": 1625231670000,
    "to_timestamp": 1625231675000,
    "status": "ERROR",
    "aggregations": [
        {
          "object_type": "PERSON_FULL_BODY",
          "first": 0,
          "last": 0,
          "median": 0.0,
          "average": 0.0,
          "min": 0,
          "max": 0
        }/*,
        ... other detections*/
    ],
    "cameras_with_error": [{"display_name": "115", "technical_name": "115"}]
  }, {
     "technical_name" : "name-2",
     "record" : { /*... same as above*/ }
  }
]

List of technical names​

Path: /counter/technical_names

["name-1", "name2"]

A queryable list of available technical names.

Troubleshooting​

Error Status Codes

  • 401 Unauthorized - Wrong API Key. Make sure a valid key is set up.
  • 404 Not Found - The technical_name(s) parameter is invalid.
  • 502 Bad Gateway - Ultinous AI Suite API is not running. Please try logging in to the Ultinous AI Suite User Interface, or restart the physical device.