Metadata Output API

Ultinous AI Suite's analytics can be utilised as either alarm-producing solutions for live event monitoring or as Metadata Output solutions, to be used with custom third party software. This guide will cover how the data created by Metadata Output can be read from Ultinous AI Suite.

If you wish to double-check the data produced by your solution, they can be downloaded directly, in .csv format as well, under the Events screen.

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 Metadata Output solution. 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 Video Output is a number indicating the number of detections with all relevant metadata.

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

• Batch mode, where past data 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. Such a value has to be entered in the Ultinous AI Suite web interface during solution creation.

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

API URL

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

Bach mode

JSON output

Path: /metadata_output/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 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 one hour
 * @param technical_name: string ;  Metadata Output technical name
 * @param token  : A base64 token issued by Ultinous AI Suite
 * @param from_timestamp : unix timestamp;  Only show data from given date
 * @param to_timestamp :   unix timestamp;  Show data until.
 */
const params = new URLSearchParams({
    'from_timestamp':'unix-timestamp',
    'to_timestamp':'unix-timestamp',
    'token':'api-token',
    'technical_name':'metadata-technical-name'
});

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

Example response

[
  {
    "frame_timestamp": 1675249200026,
    "technical_name": "parkinglot_data",
    "detections": [
      {
        "type": "PERSON_FULL_BODY",
        "bounding_box": {
          "x": 795,
          "y": 368,
          "width": 81,
          "height": 260
        },
        "detection_confidence": 0.9042969,
        "track_id": "67e56a5e-df88-4aa4-9817-aeb56d471433",
        "predicted": false
      },
      {
        "type": "PERSON_FULL_BODY",
        "bounding_box": {
          "x": 449,
          "y": 275,
          "width": 96,
          "height": 241
        },
        "detection_confidence": 0.8955078,
        "track_id": "9dd41864-183f-44e9-8105-7d3894124e0b",
        "predicted": false
      },
      {
        "type": "CAR",
        "bounding_box": {
          "x": 0,
          "y": 302,
          "width": 260,
          "height": 216
        },
        "detection_confidence": 0.88720703,
        "track_id": "0020538e-138a-4cd9-8e3a-3eb9361cfe1a",
        "predicted": false
      }
    ],
    "end_of_tracks": [],
    "camera": {
      "display_name": "ppe",
      "technical_name": "autogen-cam-293f631f-f6ed-4a22-9c22-1958e1785fac",
      "site_name": "default",
      "geo_coordinate": {
        "latitude": 40.78498,
        "longitude": -39.09988
      }
    },
    "resolution": {
      "width": 1920,
      "height": 1080
    }
  }
]

CSV output

Path: /metadata_output/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 one hour
 * @param technical_name: string ;  Metadata Output technical name
 * @param token  : A base64 token issued by Ultinous AI Suite
 * @param from_timestamp : unix timestamp;  Only show data from given date
 * @param to_timestamp :   unix timestamp;  Show data until.
 */
const params = new URLSearchParams({
    'from_timestamp':'unix-timestamp',
    'to_timestamp':'unix-timestamp',
    'token':'api-token',
    'technical_name':'metadata-technical-name'
});

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

Example response

frame_timestamp,technical_name,camera_display_name,camera_technical_name,camera_site_name,geo_coordinate_latitude,geo_coordinate_longitude,type,x,y,width,height,detection_confidence,track_id,predicted,end_of_track,width,height
1675245136529,parkinglot_data,ppe,autogen-cam-293f631f-f6ed-4a22-9c22-1958e1785fac,default,40.78498,-39.09988,CAR,0,307,258,206,0.9091797,17066f9a-556d-4bcd-9f07-ccc0691dbd77,false,false,1920,1080
1675245136529,parkinglot_data,ppe,autogen-cam-293f631f-f6ed-4a22-9c22-1958e1785fac,default,40.78498,-39.09988,PERSON_FULL_BODY,1102,363,88,277,0.8901367,add8e309-c18e-4edb-ae0f-b9c15f87401a,false,false,1920,1080
1675245136529,parkinglot_data,ppe,autogen-cam-293f631f-f6ed-4a22-9c22-1958e1785fac,default,40.78498,-39.09988,PERSON_FULL_BODY,1321,272,79,226,0.87939453,3ff5b714-360b-4c88-a668-bd39647b0615,false,false,1920,1080
1675245136529,parkinglot_data,ppe,autogen-cam-293f631f-f6ed-4a22-9c22-1958e1785fac,default,40.78498,-39.09988,PERSON_FULL_BODY,550,248,79,241,0.86035156,51b86b8f-9ff5-4fc2-a2c3-6bfcad84ada7,false,false,1920,1080
1675245136529,parkinglot_data,ppe,autogen-cam-293f631f-f6ed-4a22-9c22-1958e1785fac,default,40.78498,-39.09988,PERSON_FULL_BODY,1338,493,140,118,0.56689453,7a2baee2-fd47-44ad-91ae-f7e5cb87c0fe,true,false,1920,1080
1675245136529,parkinglot_data,ppe,autogen-cam-293f631f-f6ed-4a22-9c22-1958e1785fac,default,40.78498,-39.09988,PERSON_FULL_BODY,687,410,98,140,0.8261719,7615369f-f785-4570-b99c-4bccfea6a4a7,true,false,1920,1080
1675245136696,parkinglot_data,ppe,autogen-cam-293f631f-f6ed-4a22-9c22-1958e1785fac,default,40.78498,-39.09988,CAR,0,307,260,209,0.9067383,17066f9a-556d-4bcd-9f07-ccc0691dbd77,false,false,1920,1080
1675245136696,parkinglot_data,ppe,autogen-cam-293f631f-f6ed-4a22-9c22-1958e1785fac,default,40.78498,-39.09988,PERSON_FULL_BODY,1107,358,81,282,0.88964844,add8e309-c18e-4edb-ae0f-b9c15f87401a,false,false,1920,1080
1675245136696,parkinglot_data,ppe,autogen-cam-293f631f-f6ed-4a22-9c22-1958e1785fac,default,40.78498,-39.09988,PERSON_FULL_BODY,1336,272,69,226,0.8779297,3ff5b714-360b-4c88-a668-bd39647b0615,false,false,1920,1080
1675245136696,parkinglot_data,ppe,autogen-cam-293f631f-f6ed-4a22-9c22-1958e1785fac,default,40.78498,-39.09988,PERSON_FULL_BODY,550,245,79,243,0.8720703,51b86b8f-9ff5-4fc2-a2c3-6bfcad84ada7,false,false,1920,1080

Server Side Event Mode

Path: /metadata_output/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}/metadata_output/live?${params.toString()}`
const evtSource = new EventSource(evtPath)
evtSource.onmessage = evt => console.log(evt.data)

Example response

[
  {
    "frame_timestamp": 1675249200026,
    "technical_name": "parkinglot_data",
    "detections": [
      {
        "type": "PERSON_FULL_BODY",
        "bounding_box": {
          "x": 795,
          "y": 368,
          "width": 81,
          "height": 260
        },
        "detection_confidence": 0.9042969,
        "track_id": "67e56a5e-df88-4aa4-9817-aeb56d471433",
        "predicted": false
      },
      {
        "type": "PERSON_FULL_BODY",
        "bounding_box": {
          "x": 449,
          "y": 275,
          "width": 96,
          "height": 241
        },
        "detection_confidence": 0.8955078,
        "track_id": "9dd41864-183f-44e9-8105-7d3894124e0b",
        "predicted": false
      },
      {
        "type": "CAR",
        "bounding_box": {
          "x": 0,
          "y": 302,
          "width": 260,
          "height": 216
        },
        "detection_confidence": 0.88720703,
        "track_id": "0020538e-138a-4cd9-8e3a-3eb9361cfe1a",
        "predicted": false
      }
    ],
    "end_of_tracks": [],
    "camera": {
      "display_name": "ppe",
      "technical_name": "autogen-cam-293f631f-f6ed-4a22-9c22-1958e1785fac",
      "site_name": "default",
      "geo_coordinate": {
        "latitude": 40.78498,
        "longitude": -39.09988
      }
    },
    "resolution": {
      "width": 1920,
      "height": 1080
    }
  }
]

List of technical names

Path: /metadata_output/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.