Skip to main content

Analytics MQTT API

This API is based on the Device Configuration API framework. For guidance on how to use these APIs, please refer to Device Configuration APIs.

Overview​

There are internal producers of analytics data on the camera, known as "analytics data sources". The Analytics MQTT API allows you to create publishers to send analytics data from these sources to the specified MQTT (Message Queuing Telemetry Transport) topics.

Authentication​

For detailed information on how to authenticate requests to this API, please refer to Authentication.

Use cases​

Get available analytics data sources​

This example shows how to get all analytics data sources available for sending data over MQTT.

JSON request:

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  "http://<servername>/config/rest/analytics-mqtt/v1/data_sources"

JSON response:

200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "data_sources": [
            {
                "key": "com.axis.analytics_scene_description.v0.beta#1"
            },
            {
                "key": "com.axis.consolidated_track.v1.beta#1"
            },
            {
                "key": "some_other_structure#other_information=value1"
            }
        ]
    }
}

Add a publisher​

This example shows how to add a publisher that sends data from the analytics data source over MQTT.

JSON request:

curl --request POST \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  "http://<servername>/config/rest/analytics-mqtt/v1/publishers" \
  --data '{
    "data": {
        "id": "my_publisher",
        "data_source_key": "com.axis.analytics_scene_description.v0.beta#1",
        "mqtt_topic": "my_mqtt_topic",
        "qos": 0,
        "retain": false,
        "use_topic_prefix": false
    }
}'

JSON response:

200 OK
Content-Type: application/json

{
    "status": "success"
}

Get existing publishers​

This example shows how to get the existing publishers.

JSON request:

curl --request GET \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  "http://<servername>/config/rest/analytics-mqtt/v1/publishers"

JSON response:

200 OK
Content-Type: application/json

{
    "status": "success",
    "data": [
        {
            "id": "my_publisher",
            "key": "com.axis.analytics_scene_description.v0.beta#1",
            "mqtt_topic": "my_mqtt_topic",
            "qos": 0,
            "retain": false,
            "use_topic_prefix": false
        },
        {
            "id": "another_publisher",
            "key": "com.axis.analytics_scene_description.v0.beta#1",
            "mqtt_topic": "my_other_mqtt_topic",
            "qos": 1,
            "retain": true,
            "use_topic_prefix": false
        }
    ]
}

Delete a publisher​

This example shows how to delete a specified publisher to stop it from sending data over MQTT.

JSON request:

curl --request DELETE \
  --anyauth \
  --user "<username>:<password>" \
  --header "Content-Type: application/json" \
  "http://<servername>/config/rest/analytics-mqtt/v1/publishers/my_publisher"

JSON response:

200 OK
Content-Type: application/json

{
    "status": "success"
}

API definition​

Structure​

analytics-mqtt.v1 (Root Entity)
    ├── data_sources (Entity Collection)
        ├── key (Property)
    ├── publishers (Entity Collection)
        ├── data_source_key (Property)
        ├── id (Property)
        ├── mqtt_topic (Property)
        ├── qos (Property)
        ├── retain (Property)
        ├── use_topic_prefix (Property)

Entities​

analytics-mqtt.v1​

  • Description: Root entity
  • Type: Singleton
  • Operations:
    • Get

analytics-mqtt.v1.data_sources​

  • Description: The data sources
  • Type: Collection (Key property: key)
  • Operations:
    • Get
Properties​
analytics-mqtt.v1.data_sources.key​
  • Description: A key to reference an analytics data source
  • Data Type: data_source_key
  • Operations:
    • Get
      • Permissions: admin

analytics-mqtt.v1.publishers​

  • Description: The created publishers
  • Type: Collection (Key property: id)
  • Operations:
    • Get
    • Add
      • Permissions: admin
      • Required properties: id, data_source_key, mqtt_topic
      • Optional properties: qos, retain, use_topic_prefix
    • Remove
      • Permissions: admin
Properties​
analytics-mqtt.v1.publishers.data_source_key​
  • Description: An analytics datasource key
  • Data Type: data_source_key
  • Operations:
    • Get
      • Permissions: admin
analytics-mqtt.v1.publishers.id​
  • Description: Publisher identifier
  • Data Type: id
  • Operations:
    • Get
      • Permissions: admin
analytics-mqtt.v1.publishers.mqtt_topic​
  • Description: The MQTT topic
  • Data Type: mqtt_topic
  • Operations:
    • Get
      • Permissions: admin
analytics-mqtt.v1.publishers.qos​
  • Description: The quality of service level
  • Data Type: qos
  • Operations:
    • Get
      • Permissions: admin
analytics-mqtt.v1.publishers.retain​
  • Description: The retain policy
  • Data Type: Boolean
  • Operations:
    • Get
      • Permissions: admin
analytics-mqtt.v1.publishers.use_topic_prefix​
  • Description: Use topic prefix, configured in MQTT client
  • Data Type: Boolean
  • Operations:
    • Get
      • Permissions: admin

Data types​

data_source_key​

{
    "description": "An analytics datasource key.",
    "maxLength": 128,
    "minLength": 3,
    "type": "string"
}

id​

{
    "description": "Publisher identifier.",
    "maxLength": 128,
    "minLength": 1,
    "type": "string"
}

mqtt_topic​

{
    "description": "The mqtt topic",
    "maxLength": 128,
    "minLength": 1,
    "pattern": "^([a-zA-Z0-9_-]+)(/[a-zA-Z0-9_-]+)*$",
    "type": "string"
}

qos​

{
    "description": "The quality of service level of a publisher",
    "enum": [0, 1, 2],
    "type": "integer"
}