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.

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

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

/**
 * maximum time interval is three days
 * @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 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"}
    ]
  },

]

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,
          "median": 0.0,
          "average": 0.0,
          "max": 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