Counter API

U-Alarm'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 U-Alarm.

Prerequisites

  • Finished the Quick Start Guide and created a test Alarm to make sure that your camera is working and events are triggered. (This test Alarm can be deleted after testing.)
  • Created an API Token so that the third party software has access to U-Alarm.
  • 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 (ROIs).

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.

Each aggregation contains:

  • an object_type string, which is one of PERSON_FULL_BODY, MOTORCYCLE, CAR, TRAIN, TRUCK, BUS, BICYCLE, BOAT, AIRPLANE
  • a last integer, the number of detections in the last frame of the aggregation period
  • and an average float, the average number of detections.

The two API endpoints have the following parameters:

ParameterUsed in /counter/?ValueExample value
technical_name/batchCounter technical namefront-yard-counter
technical_names/liveArray of technical namesfirst,second,third
from_timestamp/batchUnix timestamp (ms)1625216205000
to_timestamp/batchUnix timestamp (ms) Maximum difference between to and from is 24 hours1625216275000
token/batch and /liveAPI token from U-alarm UI2eef33b9-a2ac-457b-a076-9b43a3ab6df6

Example

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

Batch Mode

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

/**
 * @param technical_name: string ;  counter technical name
 * @param token  : A base64 token issued by U-Alarm 
 * @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 obejct types, only those will be listed in the aggregations array that are selected in the UI
       "last": 0, 
        //^ last: integer, exact number of detections on the last frame in the aggregation period  
       "average": 0.0
       //^ average: float, average number of detections in the whole aggregation period  
      }, 
      {"object_type": "PERSON_FULL_BODY","last": 0, "average": 0.2}, 
      {"object_type": "CAR",             "last": 0, "average": 0.0}, 
      {"object_type": "MOTORCYCLE",      "last": 0, "average": 0.0},
      {"object_type": "AIRPLANE",        "last": 0, "average": 0.0}, 
      {"object_type": "TRAIN",           "last": 0, "average": 0.0},
      {"object_type": "TRUCK",           "last": 0, "average": 0.0}, 
      {"object_type": "BICYCLE",         "last": 0, "average": 0.0}, 
      {"object_type": "BUS",             "last": 0, "average": 0.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"}
    ]   
  }, 
    
]

Server Side Event Mode

This demo uses javascripts's EventSource API to read events.

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_names 
  {
  "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",
          "last": 0,
          "average": 0.0
        }, 
        /*... other detections*/ 
    ],
    "cameras_with_error": [{"display_name": "115", "technical_name": "115"}]
  }
}, {
   "technical_name" : "name-2", 
   "record" : { /*... same as above*/ }
}
]

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 - U-Alarm API is not running. Please try logging in to the U-Alarm User Interface, or restart the physical device.
← Custom Integration