Regional settings

Description

The Regional settings API makes it possible to store regional settings in the camera, such as different units for length. This information can then be used to determine how these units should be presented. This API does not have any methods that lets you convert the units directly.

Model

The API consists of the CGI regionalsettings.cgi and the following methods:

Method	Description
`setRegionalSettings`	Set the regional settings.
`getRegionalSettings`	Receive the current regional settings.
`getSupportedVersions`	Receive a list of supported API versions.

Identification

Property: root.Properties.RegionalSettings.RegionalSettings="yes"
Firmware: 9.20 and later
API Discovery: id=regional-settings

An alternative way to identify the API is to check for the existence of the regionalsettings.cgi.

Common examples

Get supported versions

Use this example to view a list of API versions supported by the device.

1. Request a list of supported API versions:

http://myserver/axis-cgi/regionalsettings.cgi

JSON input parameters

{
  "context": "abc",
  "method": "getSupportedVersions"
}

2. Parse the JSON response.

a) Successful response example listing supported API versions.

{
  "apiVersion": "1.1",
  "context": "abc",
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": ["1.0","1.1"]
  }
}

b) Failed response example.

{
  "apiVersion": "1.1",
  "context": "abc",
  "method": "getSupportedVersions",
  "error": {
    "code": 1000,
    "message": "Internal error"
  }
}

For further instructions, see getSupportedVersions .

Get regional settings

Use this example to request information on how to present length in either meters or US customary feet.

1. Request the current regional settings.

http://myserver/axis-cgi/regionalsettings.cgi

JSON input parameters

{
  "apiVersion": "1.0",
  "method": "getRegionalSettings",
  "context": "abc"
}

2. Parse the JSON response.

a) Successful response example indicating that metric units have been selected.

{
  "apiVersion": "1.0",
  "method": "getRegionalSettings",
  "context": "abc",
  "data": {
    "units": {
      "length": "metric"
    }
  }
}

b) Failed response example indicating when an unsupported method has been called.

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "unknownMethod",
  "error": {
    "code": 1002,
    "message": "Unknown method"
  }
}

For further instructions, see getRegionalSettings.

Set regional settings

Use this example to apply a regional setting.

1. Update the regional length settings. In this example we will use the US customary units.

http://myserver/axis-cgi/regionalsettings.cgi

JSON input parameters

{
  "apiVersion": "1.0",
  "method": "setRegionalSettings",
  "context": "abc",
  "params": {
    "units": {
      "length": "us_customary"
    }
  }
}

2. Parse the JSON response.

a) Successful response example.

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setRegionalSettings"
}

b) Failed response example that appears when the request doesn’t contain any parameters, or an invalid value.

{
  "apiVersion": "1.0",
  "context": "abc",
  "method": "setRegionalSettings",
  "error": {
    "code": 1003,
    "message": "Invalid argument"
  }
}

For further instructions, see setRegionalSettings.

API specification

getSupportedVersions

This CGI method can be used to retrieve a list of supported API versions.

Request

Security level: Admin, operator
Method: POST

http://myserver/axis-cgi/regionalsettings.cgi

JSON input parameters

{
  "context": <string>,
  "method": "getSupportedVersions"
}

Parameter	Description
`context=<string>`	The client sets this value and the application echoes it back in the response (optional).
`method="getSupportedVersions"`	Specifies that the `getSupportedVersions` method is performed.

Return value - Success

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "context": <string>,
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": ["<Major1>.<Minor1>", "<Major2>.<Minor2>"]
  }
}

Parameter	Description
`context=<string>`	A text string that is echoed back if it was provided by the client in the corresponding request.
`method="getSupportedVersions"`	The performed method.
`data.apiVersions[]=<list of versions>`	Lists all supported major versions along with their highest supported minor version.
`<list of versions>`	List of ”<Major>.<Minor>” versions, e.g. [”1.4”, “2.5”]

Return value - Failure

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>,
  "context": <string>,
  "method": "getSupportedVersions",
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

Error codes

See General error codes for a list of potential errors.

getRegionalSettings

This CGI method that can be used to retrieve the current regional settings, which is useful when you wish to determine the length unit in the GUI.

Request

Security level: Admin, operator
Method: POST

http://myserver/axis-cgi/regionalsettings.cgi

JSON input parameters

{
  "apiVersions": "<Major>.<Minor>",
  "context": <string>,
  "method": "getRegionalSettings"
}

Parameter	Description
`apiVersion`	The API version that should be used.
`context=<string>`	The client sets this value and the server echoes the data back in the response (optional).
`method="getRegionalSettings"`	Specifies that the `getRegionalSettings` method is performed.

Return value - Success

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion":"<Major>.<Minor>",
  "method": "getRegionalSettings",
  "context": <string>,
  "data": {
    "units": {
      "length": [metric|us_customary]
    }
  }
}

Parameter	Description
`apiVersion`	The API version that should be used.
`context=<string>`	A text string that is echoed back if it was provided by the client in the corresponding request.
`method="getRegionalSettings"`	Specifies that the `getRegionalSettings` method is performed.
`data.units.length=<metric\|us_customary>`	Specifies what unit that should be used for length values. Default unit is metric.

Return value - Failure

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "method": "getRegionalSettings",
  "context": <string>,
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

Error codes

See General error codes for a list of potential errors.

setRegionalSettings

This CGI method can be used to set the regional settings used in the GUI.

Request

Security level: Admin, operator
Method: POST

http://myserver/axis-cgi/regionalsettings.cgi

JSON input parameters

{
  "apiVersions": "<Major>.<Minor>",
  "context": <string>,
  "method": "setRegionalSettings",
  "params": {
    "units": {
      "length": [metric|us_customary]
    }
  }
}

Parameter	Description
`apiVersion`	The API version that should be used.
`context=<string>`	The client sets this value and the application echoes it back in the response (optional).
`method="setRegionalSettings"`	Specifies that the `setRegionalSettings` method is performed.
`params.units.length=<metric\|us_customary>`	Specifies what unit to use for length values.

Return value - Success

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "setRegionalSettings"
}

Parameter	Description
`apiVersion`	The API version that should be used.
`context=<string>`	A text string that is echoed back if it was provided by the client in the corresponding request.
`method="setRegionalSettings"`	Specifies that the `setRegionalSettings` method is performed.

Return value - Failure

HTTP code: 200 OK
Content-type: application/json

Response body syntax

{
  "apiVersion": "<Major>.<Minor>",
  "method": "setRegionalSettings",
  "context": <string>,
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

Error codes

See General error codes for a list of potential errors.

General error codes

The table lists the general errors that can occur for any CGI method. Specific errors are listed in the API specifications.

Code	Description
`1000`	Internal error.
`1001`	The requested API version is not supported.
`1002`	Unknown method.
`1003`	Invalid argument.
`1004`	Invalid request.