Direct API requests to counter

You can use HTTP API to extract data directly from the counter component. The counter component accepts requests to http://<counter_ip>:18300/.

In this section:

Methods with Counters by ID

Get a counter by ID

GET /v1/counter/:counter_id

This method retrieves an existing counter.

Parameters in path segments:

• counter_id: ID of the counter, string.

Returns:

• JSON representation of the counter.

Example

Request

curl -i -X GET http://127.0.0.1:18300/v1/counter/test_counter

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: FC:KGNbSuJE
Date: Mon, 02 Dec 2019 13:45:59 GMT
Content-Length: 213

{
    "id": "test_counter",
    "name": "test counter name",
    "deduplication_period": 10,
    "deduplication_threshold": 0.75,
    "deduplication_only": false,
    "aggregate_by_labels": [
        "gender",
        "gate",
        "foo",
        "bar"
    ],
    "meta": "{\"meta_label\":1}"
}

Create a new counter

POST /v1/counter/:counter_id

This method creates a counter under a given name.

Parameters in path segments:

• counter_id: ID of the counter, string.

JSON parameters in request:

• name (required=false): the name of the new counter.

• deduplication_period (required=false, default=10): the lifetime of events in the inmemory queue, which is used for face deduplication.

• deduplication_threshold (required=false, default=0.75): confidence to deduplicate events.

• deduplication_only (required=false, default=False): the counter will be used only for deduplication, not to create tables with event statistics data.

• aggregate_by_labels required=false: array of strings, labels that the counter will use for counting and aggregation. A separate column with an index in the database will be created for each label.

• meta (required=false): a json string with additional parameters that are stored in the json field.

Example

Request

curl -i -X POST \
  http://127.0.0.1:18300/v1/counter/test_counter \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "test counter name",
    "deduplication_period": 10,
    "deduplication_threshold": 0.75,
    "deduplication_only": false,
    "aggregate_by_labels": ["gender", "gate", "foo", "bar"],
    "meta": "{\"meta_label\":1}"
}'

Response

HTTP/1.1 201 Created
Content-Type: application/json
X-Request-Id: FC:fQ6pYSQ3
Date: Mon, 02 Dec 2019 13:33:20 GMT
Content-Length: 213

{
    "id": "test_counter",
    "name": "test counter name",
    "deduplication_period": 10,
    "deduplication_threshold": 0.75,
    "deduplication_only": false,
    "aggregate_by_labels": [
        "gender",
        "gate",
        "foo",
        "bar"
    ],
    "meta": "{}"
}

Update an existing counter

PATCH /v1/counter/:counter_id

Parameters in path segments:

• counter_id: ID of the counter, string.

This method allows you to edit an existing counter. The editable fields are: name, deduplication_period, deduplication_threshold, meta.

Example

Request

curl -i -X PATCH \
  http://127.0.0.1:18300/v1/counter/test_counter \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "new counter name",
    "deduplication_threshold": 0.8
}'

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: FC:h9h2fhfU
Date: Mon, 02 Dec 2019 14:08:07 GMT
Content-Length: 211

{
    "id": "test_counter",
    "name": "new counter name",
    "deduplication_period": 10,
    "deduplication_threshold": 0.8,
    "deduplication_only": false,
    "aggregate_by_labels": [
        "gender",
        "gate",
        "foo",
        "bar"
    ],
    "meta": "{\"meta_label\":1}"
}

Delete a counter

DELETE /v1/counter/:counter_id

This method deletes the counter.

Parameters in path segments:

• counter_id: ID of the counter, string.

Example

Request

curl -i -X DELETE http://127.0.0.1:18300/v1/counter/test_counter

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: FC:VuS9jZ8u
Date: Mon, 02 Dec 2019 14:09:36 GMT
Content-Length: 211

{
    "id": "test_counter",
    "name": "test counter name",
    "deduplication_period": 10,
    "deduplication_threshold": 0.75,
    "deduplication_only": false,
    "aggregate_by_labels": [
        "gender",
        "gate",
        "foo",
        "bar"
    ],
    "meta": "{\"meta_label\":1}"
}

List counters

GET /v1/counter/

This method returns a list of all counters.

Example

Request

curl -i -X GET http://127.0.0.1:18300/v1/counter/

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: FC:KGNbSuJE
Date: Mon, 02 Dec 2019 14:12:18 GMT
Content-Length: 413

{
    "counters": [
        {
            "id": "test_counter_1",
            "name": "test_counter",
            "deduplication_period": 5,
            "deduplication_threshold": 2,
            "deduplication_only": false,
            "aggregate_by_labels": [
                "foo",
                "gate",
                "gender",
                "age",
                "bar"
            ],
            "meta": "{}"
        },
        {
            "id": "test_counter",
            "name": "test counter name",
            "deduplication_period": 10,
            "deduplication_threshold": 0.75,
            "deduplication_only": false,
            "aggregate_by_labels": [
                "gender",
                "gate",
                "foo",
                "bar"
            ],
            "meta": "{\"meta_label\":1}"
        }
    ]
}

Clear the queues of the counter

POST /v1/counter/:counter_id/clean-queue

This method clears the queues of the counter.

There are no parameters, returns 200 OK.

Example

Request

curl -i -X POST http://127.0.0.1:18300/v1/counter/test_counter/clean-queue

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: FC:VbhV3vC5
Date: Mon, 01 Aug 2022 19:53:29 GMT
Content-Length: 0

Post a face to a counter

POST /v1/counter/test_counter/add

This method posts a face to a counter.

JSON parameters in request:

• face_id (required=true): integer, ID of the face.

• facen (required=true): base64-encoded feature vector. If it is empty or not specified, the row in the statistics is saved without deduplication by face.

• timestamp (required=true): the date of the event in RFC 3339 format (always UTC, regardless of the host timezone and transmitted in the request).

• labels (required=false): a dictionary of string labels that correspond to the event.

• weight (required=false): a weight of the face. If it exceeds 1, this face will be counted not as one, but as a weight of faces in the count output.

• topic (required=false, default="default"): a label for distinguishing deduplications within a single counter. If specified, it indicates a separate named queue.

Example

Request

curl -X POST \
  http://127.0.0.1:18300/v1/counter/test_counter/add \
  -H 'Content-Type: application/json' \
  -d '{
    "face_id": 422631005607475734,
    "facen": "5nWCPZwO9Lxl5zC9+6O3PG8U47twtQS9qwnVvJXo1zw/c ...",
    "timestamp": "2019-11-22T14:50:36+03:00",
    "labels": {"gender": "female", "gate": null, "foo": "f", "bar": null}
}'

Returns

JSON field:

• unique: whether this face is unique or not. The search for duplicates takes place in the inmemory queue with the deduplication_threshold confidence, where the lifetime of the event in queue is the deduplication_period.

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: FC:AAwdCxmM
Date: Mon, 02 Dec 2019 14:15:13 GMT
Content-Length: 16

{
    "unique": true
}

Count faces with a given grouping

GET /v1/counter/test_counter/count

This method counts faces with a given grouping.

Query string parameters:

• from (required=false): the start time of counting in RFC 3339 format.

• till (required=false): the end time of counting in RFC 3339 format.

• labels (required=true): a list of labels (separated by commas &labels=gender,age) by which the results are grouped. The available labels are set in the theaggregate_by_labels field of the counter. It is not necessary to pass the full list of aggregate_by_labels every time. Labels that are missing in aggregate_by_labels will be ignored.

Example

Request

curl -i -X GET \
 'http://127.0.0.1:18300/v1/counter/test_counter/count?from=2019-11-20T00%3A57%3A21.751812%2B03%3A00&labels=gender%2Cage'

The response contains a list of results for different combinations of the requested labels. The fields with "" mean that the event doesn’t have such label.

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: FC:wRC5UHK2
Date: Mon, 02 Dec 2019 14:46:45 GMT
Content-Length: 257

{
    "count": [
        {
            "count": 37,
            "labels": {
                "age": "",
                "gender": ""
            }
        },
        {
            "count": 2,
            "labels": {
                "age": "27",
                "gender": "male"
            }
        },
        {
            "count": 2,
            "labels": {
                "age": "29",
                "gender": "male"
            }
        },
        {
            "count": 1,
            "labels": {
                "age": "30",
                "gender": "male"
            }
        },
        {
            "count": 1,
            "labels": {
                "age": "31",
                "gender": "male"
            }
        }
    ]
}

Count faces with a given aggregation time interval

GET /v1/counter/test_counter/aggregate

This method counts faces with a given aggregation time interval.

Query string parameters:

• aggregate_interval: a time interval in h m format (for example: 10h30m, 1h, 30m) for which the results should be grouped.

• from (required=false): the start time of counting in RFC 3339 format.

• till (required=false): the end time of counting in RFC 3339 format.

• labels (required=true): a list of labels (separated by commas &labels=gender,age) by which the results are grouped.

Example

Request

curl -i -X GET \
  'http://127.0.0.1:18300/v1/counter/test_counter_1/aggregate?from=2019-11-20T00%3A57%3A21.751812%2B03%3A00&aggregate_interval=24h&labels=gender'

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: FC:0P7OPmmS
Date: Mon, 02 Dec 2019 14:54:14 GMT
Content-Length: 161

{
    "aggregate": [
        {
            "count": 6,
            "from": "2019-12-02T03:00:00+03:00",
            "labels": {
                "gender": "male"
            }
        },
        {
            "count": 37,
            "from": "2019-12-02T03:00:00+03:00",
            "labels": {
                "gender": ""
            }
        }
    ]
}