Analytics Metadata Producer Configuration

Description

The Analytics Metadata Producer Configuration API is an interface for applications and users to look up information about and configure RTSP metadata producers. This includes listing available RTSP metadata producers, enabling/disabling producers on separate video channels or requesting samples of metadata to check the functionality of each individual producer. A producer in this context is a product dependent application running on your device.

Note
This API is currently only designed to be used with single- and dual channel devices. A version with support for devices with more channels might be released in the future.

Model

The API implements analyticsmetadataconfig.cgi as its communications interface and supports the following methods:

MethodDescription
listProducersLists either all or a specific number of metadata producers.
setEnabledProducersEnables/disables a specific metadata producer and their supported video channels.
getSupportedMetadataRetrieves a sample frame for either all or a specific number of metadata producers.
getSupportedVersionsRetrieves the API versions supported by your device.

Identification

API Discovery

id=analytics-metadata-config

Common examples

Configure metadata producers

These examples will showcase the steps you need to take to list all available metadata producers and configure whether they should be enabled or disabled in the RTSP metadata stream.

1. Send a request with an empty params to find available RTSP analytics producers.

//<servername>/axis-cgi/analyticsmetadataconfig.cgi#listProducers
JSON input parameters
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "listProducers",
  "params": {
  }
}

2. Parse the JSON response.

Successful response example
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "listProducers",
  "data": {
    "producers": [
      {
        "name": "producer",
        "niceName": "Producer Name",
        "videochannels": [
          {
            "channel": 1,
            "enabled": true
          },
          {
            "channel": 2,
            "enabled": false
          }
        ]
      }
    ]
  }
}
Error response example
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "listProducers",
  "error": {
    "code": 1000,
    "message": "The application failed to handle the request."
  }
}

3. Send a request containing an array of producers and which video channels they should enable/disable.

//<servername>/axis-cgi/analyticsmetadataconfig.cgi#setEnabledProducers
JSON input parameters
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "setEnabledProducers",
  "params": {
    "producers": [
      {
        "name": "producer",
        "videochannels": [
          {
            "channel": 1,
            "enabled": true
          },
          {
            "channel": 2,
            "enabled": false
          }
        ]
      }
    ]
  }
}

4. Parse the JSON response. The data parameter will be empty if the request is successful.

Successful response example
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "setEnabledProducers",
  "data": {}
}
Error response example
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "setEnabledProducers",
  "error": {
    "code": 1000,
    "message": "The application failed to handle the request."
  }
}

API references

Retrieve supported metadata

This example will showcase the steps you need to take to retrieve information regarding the RTSP metadata analytics producers and what kind of metadata they can produce. One of reasons you would want to do this is to get an idea about what kind of metadata that can be included in the RTSP stream and request a response from a select number of specific producers.

1. Send a request.

//<servername>/axis-cgi/analyticsmetadataconfig.cgi#getSupportedMetadata
JSON input parameters
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "getSupportedMetadata",
  "params": {
    "producers": [
      "producer"
    ]
  }
}

2. Parse the JSON response.

Successful response example
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "getSupportedMetadata",
  "data": {
    "producers": [
      {
        "name": "producer",
        "sampleFrameXML": "<tt:Frame></tt:Frame>"
      }
    ]
  }
}
Error response example
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "getSupportedMetadata",
  "error": {
    "code": 1000,
    "message": "The application failed to handle the request."
  }
}

API references

Retrieve supported API versions

This example will showcase the steps you need to take to retrieve all API versions supported by your device.

1. Send a request.

//<servername>/axis-cgi/analyticsmetadataconfig.cgi#getSupportedVersions
JSON input parameters
{
  "context": "my context",
  "method": "getSupportedVersions"
}

2. Parse the JSON response

Successful response example
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": ["1.0", "1.1"]
  }
}
Error response example
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "getSupportedVersions",
  "error": {
    "code": 1000,
    "message": "The application failed to handle the request."
  }
}

API references

API specifications

listProducers

This method is used when you wish to list a select number of metadata producers along with their supported video channel and status. Using this method can lead to either one of the following responses:

  • All available analytics producers will be listed in cases where the parameter producers are absent.

  • The response will be successful when the parameter producers are set even if one or more of them doesn’t exist. These producers will simply not be listed.

Request

DigestAuth

Admin, Operator, Viewer

BasicAuth

Admin, Operator, Viewer

Method

POST

Content-type

application/json

//<servername>/axis-cgi/analyticsmetadataconfig.cgi#listProducers
JSON input parameters
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "listProducers",
  "params": {
    "producers": [
      "producer"
    ]
  }
}
ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringOptional. A text string echoed back in the corresponding response.
methodStringSpecifies the method.
paramsObjectParameters sent to and included in the API call by the method.
producersArrayContainer for the producers.

Return value - Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "listProducers",
  "data": {
    "producers": [
      {
        "name": "producer",
        "niceName": "Producer Name",
        "videochannels": [
          {
            "channel": 1,
            "enabled": true
          },
          {
            "channel": 2,
            "enabled": false
          }
        ]
      }
    ]
  }
}
ParameterTypeDescription
apiVersionStringThe API version returned from the request.
contextStringOptional. The context set by the user in the request.
methodStringThe requested method.
dataObjectContains the producer information and their assigned video channels.
producersArrayContainer for the producers.
nameStringThe producer name.
niceNameStringOptional. The display friendly name.
videochannelsArrayContainer for the video channels assigned to the producer.
channelIntegerThe name of the video channel.
enabledBooleanThe status of the video channel.

Return value - Error

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "listProducers",
  "error": {
    "code": <integer>,
    "message": <string>
  }
}
ParameterTypeDescription
apiVersionStringThe API version returned from the request.
contextStringOptional. The context set by the user in the request.
methodStringThe requested method.
errorObjectThe error object.
codeIntegerAnd error code describing the kind of error.
messageStringAn error message detailing the error.

Error codes

The following error codes are specific for this method. See General error codes for a complete list of potential errors.

CodeDescription
1000The application failed to handle the request.
2000The major version number isn’t supported.
2001The request was not formatted correctly, i.e. does not follow json-schema.
2004The request has parameter that has an invalid value.
2005The method in the request is not supported.

setEnabledProducers

This method is used when you wish to enable/disable specific metadata producers and their supported video channels. Please note that not using this method correctly can lead to one of the following responses:

  • The response will be an error if a video channel that the producer does not support is specified.

  • Likewise, an error will be returned if a fault occurred on any of the producer’s channels, meaning that no updates will be applied.

Request

DigestAuth

Admin, Operator

BasicAuth

Admin, Operator

Method

POST

Content-type

application/json

//<servername>/axis-cgi/analyticsmetadataconfig.cgi#setEnabledProducers
JSON input parameters
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "setEnabledProducers",
  "params": {
    "producers": [
      {
        "name": "producer",
        "videochannels": [
          {
            "channel": 1,
            "enabled": true
          },
          {
            "channel": 2,
            "enabled": false
          }
        ]
      }
    ]
  }
}
ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringOptional. A text string echoed back in the corresponding response.
methodStringSpecifies the method.
paramsObjectParameters sent to and included in the API call by the method.
producersArrayContainer for the producers.
nameStringThe producer name.
videochannelsArrayContainer for the video channels assigned to the producer.
channelIntegerThe name of the video channel.
enabledBooleanThe status of the video channel.

Return value - Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "setEnabledProducers",
  "data": {
  }
}
ParameterTypeDescription
apiVersionStringThe API version returned from the request.
contextStringOptional. The context set by the user in the request.
methodStringThe requested method.
dataObjectContains the producer information and their assigned video channels.

Return value - Error

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "setEnabledProducers",
  "error": {
    "code": <integer>,
    "message": <string>
  }
}
ParameterTypeDescription
apiVersionStringThe API version returned from the request.
contextStringOptional. The context set by the user in the request.
methodStringThe requested method.
errorObjectThe error object.
codeIntegerAnd error code describing the kind of error.
messageStringAn error message detailing the error.

Error codes

The following error codes are specific for this method. See General error codes for a complete list of potential errors.

CodeDescription
1000The application failed to handle the request.
2000The major version number isn’t supported.
2001The request was not formatted correctly, i.e. does not follow json-schema.
2003The request has a missing mandatory parameter.
2004The request has parameter that has an invalid value.
2005The method in the request is not supported.

getSupportedMetadata

This method is used when you wish to retrieve a sample frame for a select number of metadata producers. The frame will be compatible with the ONVIF XML metadata format and have one of the following characteristics:

  • All analytics producers will be listed if the parameter producer is absent.

  • The response will be successful even if not all parameter producers are set. The missing producers will be omitted from the response.

Request

DigestAuth

Admin, Operator, Viewer

BasicAuth

Admin, Operator, Viewer

Method

POST

Content-type

application/json

//<servername>/axis-cgi/analyticsmetadataconfig.cgi#getSupportedMetadata
JSON input parameters
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "getSupportedMetadata",
  "params": {
    "producers": [
      "producer"
    ]
  }
}
ParameterTypeDescription
apiVersionStringThe API version that should be used.
contextStringOptional. A text string echoed back in the corresponding response.
methodStringSpecifies the method.
paramsObjectParameters sent to and included in the API call by the method.
producersArrayContainer for the producers.

Return value - Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "getSupportedMetadata",
  "data": {
    "producers": [
      {
        "name": "producer",
        "sampleFrameXML": "<tt:Frame></tt:Frame>"
      }
    ]
  }
}
ParameterTypeDescription
apiVersionStringThe API version returned from the request.
contextStringOptional. The context set by the user in the request.
methodStringThe requested method.
dataObjectContains the producer information and their assigned video channels.
producersArrayContainer for the producers.
nameStringThe producer name.
sampleFrameXMLStringThe sample frame associated with the producer.

Return value - Error

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "getSupportedMetadata",
  "error": {
    "code": <integer>
    "message": <string>
  }
}
ParameterTypeDescription
apiVersionStringThe API version returned from the request.
contextStringOptional. The context set by the user in the request.
methodStringThe requested method.
errorObjectThe error object.
codeIntegerAnd error code describing the kind of error.
messageStringAn error message detailing the error.

Error codes

The following error codes are specific for this method. See General error codes for a complete list of potential errors.

CodeDescription
1000The application failed to handle the request.
2000The major version number isn’t supported.
2001The request was not formatted correctly, i.e. does not follow json-schema.
2004The request has parameter that has an invalid value.
2005The method in the request is not supported.

getSupportedVersions

This method is used when you wish to retrieve a list containing the API versions supported by your device.

Request

DigestAuth

Admin, Operator, Viewer

BasicAuth

Admin, Operator, Viewer

Method

POST

Content-type

application/json

//<servername>/axis-cgi/analyticsmetadataconfig.cgi#getSupportedVersions
JSON input parameters
{
  "context": "my context",
  "method": "getSupportedVersions"
}
ParameterTypeDescription
contextStringOptional. A text string echoed back in the corresponding response.
methodStringSpecifies the method.

Return value - Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": [
      "<Major1>.<Minor1>",
      "<Major2>.<Minor2>",
    ]
  }
}
ParameterTypeDescription
apiVersionStringThe API version returned from the request.
contextStringOptional. The context set by the user in the request.
methodStringThe requested method.
dataObjectContains the producer information and their assigned video channels.
apiVersionsArrayContains the supported API versions in the format “Major.Minor”, i.e. 1.4 or 2.1.

Return value - Error

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "1.0",
  "context": "my context",
  "method": "getSupportedVersions",
  "error": {
    "code": <integer>
    "message": <string>
  }
}
ParameterTypeDescription
apiVersionStringThe API version returned from the request.
contextStringOptional. The context set by the user in the request.
methodStringThe requested method.
errorObjectThe error object.
codeIntegerAnd error code describing the kind of error.
messageStringAn error message detailing the error.

Error codes

The following error codes are specific for this method. See General error codes for a complete list of potential errors.

CodeDescription
1000The application failed to handle the request.
2001The request was not formatted correctly, i.e. does not follow json-schema.
2005The method in the request is not supported.

General error codes

CodeDescription
1000The application failed to handle the request.
2000The major version number isn’t supported.
2001The request was not formatted correctly, i.e. does not follow json-schema.
2003The request has a missing mandatory parameter.
2004The request has parameter that has an invalid value.
2005The method in the request is not supported.