1

Camlytics Service REST API

Camlytics Service provides a convenient way to access analytical events, reports, locations and channels data programmatically.

You may also be interested in webhooks for real-time metrics like current occupancy and current queue. If you plan to receive analytical events in real time, we recommend using webhooks.
If you are interested in programmatic receiving the Reports data, you may opt for report feeds.


2

API key

Authentication to the Service REST API requires a valid API Key.

Public and secret API keys can be found in API key section in the Settings.


3

Request signing

Do the following steps to sign your API request:

  • Create a SHA512 HMAC using your API Key secret and the request URI value.
  • Include the resulting hash in your request in the X-Sign request header.

Example:

Javascript

const Crypto = require('crypto');
// if you use the since or/and until parameter. You should process it with encodeURIComponent function
const since = encodeURIComponent('2020-10-13T06:12:00.000+01:00'); // 2020-10-13T06%3A12%3A00.000%2B01%3A00
const requestUri = '/service/api/v1/events?location_id=32&nonce=154&since=' + since;
const secret = 'ehsd7485746548574';
const signature = Crypto.createHmac('sha512', secret)
                  .update(requestUri)
                  .digest('hex');

PHP

<?php
// if you use the since or/and until parameter. You should process it with urlencode function
$since = urlencode('2020-10-12T14:00:00Z'); // 2020-10-12T14%3A00%3A00Z
$requestUri = '/service/api/v1/events?location_id=32&nonce=154&since=' . $since;
$secret = 'ehsd7485746548574';
$sign = hash_hmac("sha512", $requestUri, $secret)

4

Request throttling

The current request limit is 1 request per second. If you make more requests you will receive response 503 or 429 error code.


5

Request parameters

Required header parameters

X-key - public API key

X-Sign - SHA512 HMAC using your API Key secret and the request URI value

Required query string parameter

Nonce - a monotonically increasing user-generated value (we recommend a UNIX-style timestamp in epoch second format). Nonce must be more than the previous one.


Methods & Models

Camlytics Service API
More information: https://cloud.camlytics.com
Contact Info: info@camlytics.com
Version: v1
BasePath:/service/api/v1
Apache 2.0
http://www.apache.org/licenses/LICENSE-2.0.html

Access

  1. APIKey
    KeyParamName: X-Key
    KeyInQuery:false
    KeyInHeader:true
  2. Signature
    KeyParamName: X-Sign
    KeyInQuery:false
    KeyInHeader:true

Methods

[ Jump to Models ]

Table of Contents

Dictionaries

Statistic

Dictionaries

Up
get /channels
Retrieve video channels list (channelList)

Query parameters

nonce (required)
Query Parameter — monotonically increasing counter for all requests to API format: int32
location_id (optional)
Query Parameter — Include channels only for specified location. Ignored if channel_id parameter is passed. format: int32
channel_id (optional)
Query Parameter — Include only specified channel.

Return type

Example data

Content-Type: application/json
{
  "msg" : "success",
  "result" : [ {
    "name" : "Lobby",
    "paid" : 0,
    "active" : 1,
    "id" : "47576ahb-56656-45786-acb45_000015E2",
    "location_id" : 123
  }, {
    "name" : "Lobby",
    "paid" : 0,
    "active" : 1,
    "id" : "47576ahb-56656-45786-acb45_000015E2",
    "location_id" : 123
  } ],
  "code" : 0
}

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

channels list matching criteria inline_response_200_1

Up
get /locations
Retrieve locations list (locationList)

Query parameters

nonce (required)
Query Parameter — monotonically increasing counter format: int32
location_id (optional)
Query Parameter — Include only specified location. format: int32

Return type

Example data

Content-Type: application/json
{
  "msg" : "success",
  "result" : [ {
    "name" : "Manhattan store",
    "id" : 123,
    "version" : "3.2.1",
    "timezone_offset" : "+00:00",
    "hash" : "SwU8JH3ldduwsZoxzamSCNU9Xd/lCQGCUUQyJ/Fz9e0+Y+CTVKRvHsYZDBlsFMuVXps1UTFYea8wds6tiyEPSxsJUsKry3C3/1eMNs3h6y0dNYlqnMFCTR/J8NkujrBdndZyxATevYDPIidn51ZcU79DFWq1NYVnrYoY4pxCMNDNppZsCap0tAnGvyvq43MlKN1qvONBC/p5vVXf5bdfMGB3mhEhMTQ"
  }, {
    "name" : "Manhattan store",
    "id" : 123,
    "version" : "3.2.1",
    "timezone_offset" : "-04:00",
    "hash" : "SwU8JH3ldduwsZoxzamSCNU9Xd/lCQGCUUQyJ/Fz9e0+Y+CTVKRvHsYZDBlsFMuVXps1UTFYea8wds6tiyEPSxsJUsKry3C3/1eMNs3h6y0dNYlqnMFCTR/J8NkujrBdndZyxATevYDPIidn51ZcU79DFWq1NYVnrYoY4pxCMNDNppZsCap0tAnGvyvq43MlKN1qvONBC/p5vVXf5bdfMGB3mhEhMTQ"
  } ],
  "code" : 0
}

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

locations list matching criteria inline_response_200

Up
get /triggers
Retrieve triggers list (lines and zones) (triggerList)

Query parameters

nonce (required)
Query Parameter — monotonically increasing counter for all requests to API format: int32
location_id (optional)
Query Parameter — Include triggers only for specified location. Ignored if channel_id or trigger_id parameters are passed. format: int32
channel_id (optional)
Query Parameter — Include triggers only for specified channel. Ignored if trigger_id parameter is passed.
trigger_id (optional)
Query Parameter — Include only specified trigger.

Return type

Example data

Content-Type: application/json
{
  "msg" : "success",
  "result" : [ {
    "name" : "Enter",
    "active" : 1,
    "id" : "47576ahb-56656-45786-acb45_000015E2",
    "type" : "Line",
    "channel_id" : "35576ahb-56656-45781-acb45_000015E2",
    "location_id" : 123
  }, {
    "name" : "Enter",
    "active" : 1,
    "id" : "47576ahb-56656-45786-acb45_000015E2",
    "type" : "Line",
    "channel_id" : "35576ahb-56656-45781-acb45_000015E2",
    "location_id" : 123
  } ],
  "code" : 0
}

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

triggers list matching criteria inline_response_200_2

Statistic

Up
get /events
Retrieve events list (eventList)

Query parameters

nonce (required)
Query Parameter — monotonically increasing counter for all requests to API format: int32
location_id (optional)
Query Parameter — Include events only for specified location. Ignored if channel_id or trigger_id parameters are passed. format: int32
channel_id (optional)
Query Parameter — Include events only for specified channel. Ignored if trigger_id parameter is passed.
trigger_id (optional)
Query Parameter — Include events only for specified trigger.
event_type (optional)
Query Parameter — Include events only for specified event type.
origin (optional)
Query Parameter — Include events only for specified origin.
since (optional)
Query Parameter — Exclude events that occurred before since. Example: since=2018-05-20T10:30:02.5550000Z format: date-time
until (optional)
Query Parameter — Exclude events that occurred after until. Example: until=2018-05-20T10:30:02.5550000Z format: date-time
starting_after (optional)
Query Parameter — A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with 1243, your subsequent call can include starting_after=1243 in order to fetch the next page of the list. format: int32
limit (optional)
Query Parameter — A limit on the number of objects to be returned. Limit can range between 1 and 1000, and the default is 100. format: int32
order (optional)
Query Parameter — Data sort direction

Return type

Example data

Content-Type: application/json
{
  "msg" : "success",
  "result" : [ {
    "record_id" : 1635343534,
    "event_type" : "RegionJoin",
    "snapshot_id" : -235343534,
    "trigger_id" : "47576ahb-56656-45786-acb45_000015E2",
    "origin" : "Pedestrian",
    "suborigin" : "Unknown",
    "age_range" : "",
    "gender" : "",
    "id" : 34454545,
    "channel_id" : "35576ahb-56656-45781-acb45_000015E2",
    "object_id" : 6,
    "location_id" : 123,
    "event_time" : "2000-01-23T04:56:07.000+00:00"
  }, {
    "record_id" : 1635343534,
    "event_type" : "RegionJoin",
    "snapshot_id" : -235343534,
    "trigger_id" : "47576ahb-56656-45786-acb45_000015E2",
    "origin" : "Vehicle",
    "suborigin" : "Car",
    "age_range" : "",
    "gender" : "",
    "id" : 34454545,
    "channel_id" : "35576ahb-56656-45781-acb45_000015E2",
    "object_id" : 6,
    "location_id" : 123,
    "event_time" : "2000-01-23T04:56:07.000+00:00"
  }, {
    "record_id" : 1635343534,
    "event_type" : "RegionJoin",
    "snapshot_id" : -235343534,
    "trigger_id" : "47576ahb-56656-45786-acb45_000015E2",
    "origin" : "Face",
    "suborigin" : "",
    "age_range" : "26 - 35",
    "gender" : "Male",
    "id" : 34454545,
    "channel_id" : "35576ahb-56656-45781-acb45_000015E2",
    "object_id" : 6,
    "location_id" : 123,
    "event_time" : "2000-01-23T04:56:07.000+00:00"
  } ],
  "code" : 0
}

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

events list matching criteria inline_response_200_3

Up
get /totals/triggers
Retrieve events count grouped by trigger id (totalsTriggersList)

Query parameters

nonce (required)
Query Parameter — monotonically increasing counter for all requests to API format: int32
location_id (optional)
Query Parameter — Include events only for specified location. Ignored if channel_id or trigger_id parameters are passed. format: int32
channel_id (optional)
Query Parameter — Include events only for specified channel. Ignored if trigger_id parameter is passed.
trigger_id (optional)
Query Parameter — Include events only for specified trigger.
event_type (optional)
Query Parameter — Include events only for specified event type.
origin (optional)
Query Parameter — Include events only for specified origin.
since (optional)
Query Parameter — Exclude events that occurred before since. Example: since=2018-05-20T10:30:02.5550000Z format: date-time
until (optional)
Query Parameter — Exclude events that occurred after until. Example: until=2018-05-20T10:30:02.5550000Z format: date-time

Return type

Example data

Content-Type: application/json
{
  "msg" : "success",
  "result" : [ {
    "trigger_name" : "Exit",
    "trigger_id" : "35576ahb-56656-45781-acb45_000015E2",
    "count" : 3012,
    "channel_id" : "85576ahb-56656-45781-acb41_000015E2",
    "location_id" : 423
  }, {
    "trigger_name" : "Exit",
    "trigger_id" : "35576ahb-56656-45781-acb45_000015E2",
    "count" : 3012,
    "channel_id" : "85576ahb-56656-45781-acb41_000015E2",
    "location_id" : 423
  } ],
  "code" : 0
}

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

number of events matching criteria grouped by triggers inline_response_200_4

Up
get /totals/types
Retrieve events count grouped by event type, channel id (totalsTypesList)

Query parameters

nonce (required)
Query Parameter — monotonically increasing counter for all requests to API format: int32
location_id (optional)
Query Parameter — Include events only for specified location. Ignored if channel_id parameter is passed. format: int32
channel_id (optional)
Query Parameter — Include events only for specified channel.
event_type (optional)
Query Parameter — Include events only for specified event type.
origin (optional)
Query Parameter — Include events only for specified origin.
since (optional)
Query Parameter — Exclude events that occurred before since. Example: since=2018-05-20T10:30:02.5550000Z format: date-time
until (optional)
Query Parameter — Exclude events that occurred after until. Example: until=2018-05-20T10:30:02.5550000Z format: date-time

Return type

Example data

Content-Type: application/json
{
  "msg" : "success",
  "result" : [ {
    "count" : 4712,
    "type" : "TripwireCrossed",
    "channel_id" : "35576ahb-56656-45781-acb45_000015E2"
  }, {
    "count" : 4712,
    "type" : "TripwireCrossed",
    "channel_id" : "35576ahb-56656-45781-acb45_000015E2"
  } ],
  "code" : 0
}

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

number of events matching criteria grouped by types inline_response_200_5

Up
get /histograms
Retrieve histograms list (histogramList)

Query parameters

nonce (required)
Query Parameter — monotonically increasing counter for all requests to API format: int32
location_id (optional)
Query Parameter — Include events only for specified location. Ignored if channel_id or trigger_id parameters are passed. format: int32
channel_id (optional)
Query Parameter — Include events only for specified channel. Ignored if trigger_id parameter is passed.
trigger_id (optional)
Query Parameter — Include events only for specified trigger.
since (optional)
Query Parameter — Exclude events that occurred before since. Example: since=2018-05-20T10:30:02.5550000Z format: date-time
until (optional)
Query Parameter — Exclude events that occurred after until. Example: until=2018-05-20T10:30:02.5550000Z format: date-time
starting_after (optional)
Query Parameter — A cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with 1243, your subsequent call can include starting_after=1243 in order to fetch the next page of the list. format: int32
limit (optional)
Query Parameter — A limit on the number of objects to be returned. Limit can range between 1 and 1000, and the default is 100. format: int32
order (optional)
Query Parameter — Data sort direction

Return type

Example data

Content-Type: application/json
{
  "msg" : "success",
  "result" : [ {
    "trigger_id" : "47576ahb-56656-45786-acb45_000015E2",
    "id" : 34454545,
    "channel_id" : "35576ahb-56656-45781-acb45_000015E2",
    "counting_data" : [ 3400.3, 199.7 ],
    "lifetime_data" : [ 10, 4, 0, 1 ],
    "location_id" : 123,
    "histogram_time" : "2000-01-23T04:00:00+00:00"
  }, {
    "trigger_id" : "47576ahb-56656-45786-acb45_000015E2",
    "id" : 34454545,
    "channel_id" : "35576ahb-56656-45781-acb45_000015E2",
    "counting_data" : [ 3600 ],
    "lifetime_data" : [  ],
    "location_id" : 123,
    "histogram_time" : "2000-01-23T05:00:00+00:00"
  } ],
  "code" : 0
}

Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.
  • application/json

Responses

200

histograms list matching criteria inline_response_200_6

Models

[ Jump to Methods ]

Table of Contents

  1. Channel -
  2. Event -
  3. EventTotalByTrigger -
  4. EventTotalByType -
  5. Histogram -
  6. Location -
  7. Trigger -
  8. inline_response_200 -
  9. inline_response_200_1 -
  10. inline_response_200_2 -
  11. inline_response_200_3 -
  12. inline_response_200_4 -
  13. inline_response_200_5 -
  14. inline_response_200_6 -

Channel - Up

id
example: 47576ahb-56656-45786-acb45_000015E2
location_id
Integer format: int32
example: 123
name
example: Lobby
active
Integer format: int32
example: 1
paid
Integer format: int32
example: 0

Event - Up

id
Integer format: int32
example: 34454545
location_id
Integer format: int32
example: 123
channel_id
example: 35576ahb-56656-45781-acb45_000015E2
trigger_id
example: 47576ahb-56656-45786-acb45_000015E2
event_type
Enum:
TripwireCrossed
Tailgating
RegionJoin
RegionLeave
MotionInRegionOn
Loitering
CrowdOn
Sabotage
example: RegionJoin
origin
Enum:
Pedestrian
Vehicle
Unknown
suborigin
Enum:
Unknown
Car
Van
Truck
Bus
Bike
age_range
Enum:
under 25
26 - 35
36 - 45
46 - 55
56 - 65
over 65
gender
Enum:
Unknown
Male
Female
object_id
Integer format: int32 | null
event_time
Date format: date-time
snapshot_id
Integer format: int32
example: -235343534
record_id
Integer format: int32
example: 1635343534

EventTotalByTrigger - Up

trigger_id
String format: string | null
example: 35576ahb-56656-45781-acb45_000015E2
trigger_name
example: Exit
location_id
Integer format: int32
example: 423
channel_id
example: 85576ahb-56656-45781-acb41_000015E2
count
example: 3012

EventTotalByType - Up

type
Enum:
TripwireCrossed
Tailgating
RegionJoin
RegionLeave
MotionInRegionOn
Loitering
CrowdOn
Sabotage
channel_id
example: 35576ahb-56656-45781-acb45_000015E2
count
example: 4712

Histogram - Up

id
Integer format: int32
example: 34454545
location_id
Integer format: int32
example: 123
channel_id
example: 35576ahb-56656-45781-acb45_000015E2
trigger_id
example: 47576ahb-56656-45786-acb45_000015E2
counting_data
Array format: []float32
example: [ 3198.9, 201.1, 149.6, 50.4]
lifetime_data
Array format: []int32
example: [ 16, 5, 0, 0, 1]
histogram_time
Date format: date-time

Location - Up

id
Integer format: int32
example: 123
name
example: Manhattan store
hash
String format: base64
example: SwU8JH3ldduwsZoxzamSCNU9Xd/lCQGCUUQyJ/Fz9e0+Y+CTVKRvHsYZDBlsFMuVXps1UTFYea8wds6tiyEPSxsJUsKry3C3/1eMNs3h6y0dNYlqnMFCTR/J8NkujrBdndZyxATevYDPIidn51ZcU79DFWq1NYVnrYoY4pxCMNDNppZsCap0tAnGvyvq43MlKN1qvONBC/p5vVXf5bdfMGB3mhEhMTQ
version
example: 3.2.1

Trigger - Up

id
example: 47576ahb-56656-45786-acb45_000015E2
location_id
Integer format: int32
example: 123
channel_id
example: 35576ahb-56656-45781-acb45_000015E2
name
example: Enter
type
example: Line
active
Integer format: int32
example: 1

inline_response_200 - Up

code (optional)
Integer format: int32
msg (optional)
example: success
result (optional)

inline_response_200_1 - Up

code (optional)
Integer format: int32
msg (optional)
example: success
result (optional)

inline_response_200_2 - Up

code (optional)
Integer format: int32
msg (optional)
example: success
result (optional)

inline_response_200_3 - Up

code (optional)
Integer format: int32
msg (optional)
example: success
result (optional)

inline_response_200_4 - Up

code (optional)
Integer format: int32
msg (optional)
example: success
result (optional)

inline_response_200_5 - Up

code (optional)
Integer format: int32
msg (optional)
example: success
result (optional)

inline_response_200_6 - Up

code (optional)
Integer format: int32
msg (optional)
example: success
result (optional)

6

Webhooks

Webhooks are the preferred way to receive events in real-time without making any excessive requests. In order to do that, you would need a webhook receiving endpoint.

For testing purposes, you can use requestbin.com service.

In order to access the webhooks settings, in cloud portal, go to Settings > Webhooks. There, you would set up the endpoint for each of the added channels or for the whole location. If you set the webhook for the whole location you would receive all events for any of the location channels.

webhook video analytics

The JSON structure of the webhook event is very similar to the API structure. The default webhook timeout is 10 seconds. The time of the event is in UTC time zone.

[ {
    "record_id" : 1635343534,
    "event_type" : "RegionJoin",
    "snapshot_id" : -235343534,
    "trigger_id" : "47576ahb-56656-45786-acb45_000015E2",
    "origin" : "Pedestrian",
    "suborigin" : "Unknown",
    "age_range" : "",
    "gender" : "",
    "id" : null,
    "channel_id" : "35576ahb-56656-45781-acb45_000015E2",
    "object_id" : 6,
    "location_id" : 123,
    "event_time" : "2000-01-23 04:56:07.000"
  }, {
    "record_id" : 1635343534,
    "event_type" : "RegionJoin",
    "snapshot_id" : -235343534,
    "trigger_id" : "47576ahb-56656-45786-acb45_000015E2",
    "origin" : "Vehicle",
    "suborigin" : "Car",
    "age_range" : "",
    "gender" : "",
    "id" : null,
    "channel_id" : "35576ahb-56656-45781-acb45_000015E2",
    "object_id" : 6,
    "location_id" : 123,
    "event_time" : "2000-01-23 04:56:07.000"
  }, {
    "record_id" : 1635343534,
    "event_type" : "RegionJoin",
    "snapshot_id" : -235343534,
    "trigger_id" : "47576ahb-56656-45786-acb45_000015E2",
    "origin" : "Face",
    "suborigin" : "",
    "age_range" : "26 - 35",
    "gender" : "Male",
    "id" : null,
    "channel_id" : "35576ahb-56656-45781-acb45_000015E2",
    "object_id" : 6,
    "location_id" : 123,
    "event_time" : "2000-01-23 04:56:07.000"
  } ]