Time API

Description

The Time API makes it possible to get and set time, date and time zone information. There currently exist two different time zone formats:

  • The Time Zone Database is provided by IANA (Internet Assigned Numbers Authority) and offers an easy way to set the time zone. An example of such a time zone format is Europe/Stockholm and once the time zone is selected the daylight saving rules will be applied for that time zone, as the database is updated to reflect changes in the time zones. Thus, an updated version of the database will be included through the firmware upgrades and be applied without the need to change the time zone setting.

  • The POSIX format (Portable Operating System Interface). Example of such a time zone format is CET-1CEST,M3.5.0,M10.5.0/3.

The API uses the time.cgi and consists of the following methods:

MethodsDescription
getDateTimeInfoGet system date, time, time zone and local time. See for additional information.
getAllGet all properties returned from getDateTimeInfo plus a list of available time zones in the IANA format.
setDateTimeSet system date and time UTC. See for additional information.
setTimeZoneSet system time zone in the IANA format.
setPosixTimeZoneSet system time zone in the POSIX format and the DST flag.
getSupportedVersionsGet API versions supported by the product.

Model

The API consists of an authenticated CGI which should be called using the HTTP POST method, and with JSON formatted data as input. The API includes a number of methods, which makes it possible to:

  • get and set the date and time.

  • get and set the time zone.

  • list available time zones.

  • get the local date and time.

The available time zones are the ones provided by IANA, and are usually referred to as tz or zoneinfo. They are periodically updated to reflect changes made by political bodies, UTC offsets and daylight-saving rules.

Identification

API Discovery

id=time-service

Firmware

9.30 and later

For information about the API Discovery, see .

Obsoletes

This API deprecates the following methods:

  • date.cgi: This method will still be available during a transitional period.

  • Time.POSIXTimeZone and Time.DST.Enabled: Both of these methods are fully supported by the Time API, but can also be accessed through the legacy param.cgi.

Common examples

All requests made to Time API is done through a HTTP request with a proper JSON body, while all the responses to the API calls will be returned as JSON data.

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

Retrieve information

Use this example to receive the current time, date and time zone information on the device, the latter whom also includes a list of supported time zones in different formats, which is dependent on whether:

  • if the time zone has been set with the IANA format, the get operation will include the IANA format, but it can also include the POSIX format if it is available in the IANA Time Zone Database.

  • if the time zone has been set with the POSIX format, the get operation will only include the POSIX format.

The dstEnabled will be available in the response if a POSIX format string is returned.

Retrieve Date and Time information

1) Request current date and time information with the following JSON request.

{
  "apiVersion": "1.0",
  "context": "Client defined request ID",
  "method": "getDateTimeInfo"
}

2) There are three possible JSON responses, where the time zone information may differ. Possible names for the data responses are listed in the table below.

a) Parse the JSON response, which only includes time zone information in an IANA format.

{
  "apiVersion": "1.0",
  "context": "Client defined request ID",
  "method": "getDateTimeInfo",
  "data": {
    "dateTime": "2018-11-19T13:26:53Z",
    "localDateTime": "2018-11-19T14:26:53+01:00",
    "timeZone": "Europe/Stockholm"
  }
}

b) Parse the JSON response, which includes only time zone information in the POSIX format.

{
  "apiVersion": "1.0",
  "context": "Client defined request ID",
  "method": "getDateTimeInfo",
  "data": {
    "dateTime": "2018-11-19T13:26:53Z",
    "localDateTime": 2018-11-19T14:26:53+01:00",
    "posixTimeZone": "CET-1CEST,M3.5.0,M10.5.0/3",
    "dstEnabled": true
  }
}

c) Parse the JSON response, which includes time zone information in both the IANA and POSIX format.

{
  "apiVersion": "1.0",
  "context": "Client defined request ID",
  "method": "getDateTimeInfo",
  "data": {
    "dateTime": "2018-11-19T13:26:53Z",
    "localDateTime": 2018-11-19T14:26:53+01:00",
    "timeZone": "Europe/Stockholm",
    "posixTimeZone": "CET-1CEST,M3.5.0,M10.5.0/3",
    "dstEnabled": true
  }
}
ParameterDescription
dateTimeSystem date and time presented in UTC. The format is in ISO 8601.
localDateTimeLocal date and time. The format is ISO 8601.
timeZoneSystem time zone in the IANA format.
posixTimeZoneSystem time zone in the POSIX format.
dstEnabledtrue means that it will activate the DST settings of the POSIX time zone string.
false means that it will ignore the DST settings of the POSIX time zone string.
The IANA response does not contain this field, as the DST is always true.

Retrieve Date and Time Information and List of Available Time Zones

1) Request current date and time information and list of available time zones with the following JSON request.

{
  "apiVersion": "1.0",
  "context": "Client defined request ID",
  "method": "getAll"
}

2) There are three possible JSON responses, where the time zone information may differ. The names that can be included in the response data are listed in the table below.

a) Parse the JSON response which includes only time zone information in the IANA format.

{
  "apiVersion": "1.0",
  "context": "Client defined request ID",
  "method": "getAll",
  "data": {
    "dateTime": "2018-11-19T13:26:53Z",
    "localDateTime": "2018-11-19T14:26:53+01:00",
    "timeZone": "Europe/Stockholm",
    "timeZones": ["Africa/Abidjan", "Africa/Accra"]
  }
}

b) Parse the JSON response which includes only time zone information in the POSIX format.

{
  "apiVersion": "1.0",
  "context": "Client defined request ID",
  "method": "getAll",
  "data": {
    "dateTime": "2018-11-19T13:26:53Z",
    "localDateTime": "2018-11-19T14:26:53+01:00",
    "posixTimeZone": "CET-1CEST,M3.5.0,M10.5.0/3",
    "dstEnabled": true,
    "timeZones": [ "Africa/Abidjan", "Africa/Accra" ]
  }
}

c) Parse the JSON response which includes time zone information in both IANA and POSIX format.

{
  "apiVersion": "1.0",
  "context": "Client defined request ID",
  "method": "getAll",
  "data": {
    "dateTime": "2018-11-19T13:26:53Z",
    "localDateTime": "2018-11-19T14:26:53+01:00",
    "timeZone": "Europe/Stockholm",
    "posixTimeZone": "CET-1CEST,M3.5.0,M10.5.0/3",
    "dstEnabled": true,
    "timeZones": [ "Africa/Abidjan", "Africa/Accra" ]
  }
}
ParameterDescription
dateTimeSystem date and time presented in UTC. The format is in ISO 8601.
localDateTimeLocal date and time. The format is ISO 8601.
timeZoneSystem time zone in the IANA format.
posixTimeZoneSystem time zone in the POSIX format.
dstEnabledtrue means it will activate the DST settings of the POSIX time zone string.
false means it will ignore the DST settings of the POSIX time zone string.
The IANA response does not contain this field, as the DST is always true.
timeZonesList of supported time zones in the IANA format.

Set properties

Use this example to set the time, date and time zone on the device.

Set Date and Time

1) Request set date and time with the following JSON request.

{
  "apiVersion": "1.0",
  "context": "Client defined request ID",
  "method": "setDateTime",
  "params": {
    "dateTime": "2018-12-24T14:28:53Z"
  }
}

2) Parse the JSON response which echoes the value of params object in the data object if successful.

{
  "apiVersion": "1.0",
  "context": "Client defined request ID",
  "method": "setDateTime",
  "data": {
    "dateTime": "2018-12-24T14:28:53Z"
  }
}

Please note that the dateTime parameter is in the UTC format, which should be formatted as [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss]Z.

Set Time Zone

setTimeZone is the preferred way of setting the time zone on the device.

See for additional information.

1) Request set time zone with the following JSON request.

{
  "apiVersion": "1.0",
  "context": "Client defined request ID",
  "method": "setTimeZone",
  "params": {
    "timeZone": "Europe/Stockholm"
  }
}

2) Parse the JSON response which echoes the value of params object in the data object if successful.

{
  "apiVersion": "1.0",
  "context": "Client defined request ID",
  "method": "setTimeZone",
  "data": {
    "timeZone": "Europe/Stockholm"
  }
}
Note
Please note that this request will set a new IANA time zone and clear any previous POSIX time zone. The POSIX string in the Time Zone Database will not be affected.

Set POSIX Time Zone

Be aware that setPosixTimeZone is not the recommended way when setting the time zone. Instead, use the preferred method setTimeZone in the section.

1) Request set POSIX time zone with the following JSON request.

{
  "apiVersion": "1.0",
  "context": "Client defined request ID",
  "method": "setPosixTimeZone",
  "params": {
    "posixTimeZone": "CET-1CEST,M3.5.0,M10.5.0/3",
    "enableDst": true
  }
}

2) Parse the JSON response, which echoes the value of params object in the data object if successful.

{
  "apiVersion": "1.0",
  "context": "Client defined request ID",
  "method": "setPosixTimeZone",
  "data": {
    "posixTimeZone": "CET-1CEST,M3.5.0,M10.5.0/3",
    "dstEnabled": true
  }
}
Note
Please note that this request will set a new POSIX time zone and clear any previous IANA time zones.

API specification

getDateTimeInfo

getDateTimeInfo is used to retrieve all the date and time related properties provided by the Time API.

Request

Security level

Viewer

Method

POST

http://myserver/axis-cgi/time.cgi
{
  "apiVersion": "<Major>.<Minor>",
  "context": "<ID string>",
  "method": "getDateTimeInfo"
}
ParameterDescription
apiVersion=<Major>.<Minor>Required. The API version that should be used.
context=<ID string>Optional. The client sets this value, while the server echoes the date back in the response. If set, it will be present in the response regardless of whether the response was successful or not.
method=getDateTimeInfoRequired. Specifies that the getDateTimeInfo operation is performed.

Return value - Success

A successful response may contain time zone information in one of the following formats:

  • IANA: The get operation will include this format, however, it can also come with the POSIX format as long as it is available in the IANA Time Zone Database.

  • POSIX: The get operation will include this format.

HTTP code

200 OK

Content-type

application/json

IANA format

Response body syntax
{
  "apiVersion": "<Major>.<Minor>",
  "context": "<ID string>",
  "method": "getDateTimeInfo",
  "data": {
    "dateTime": "<date and time>",
    "localDateTime": "<local date and time>",
    "timeZone": "<IANA time zone id>"
  }
}
ParameterDescription
apiVersionThe API version that is used.
contextOptional. Text string echoed back if provided by the client in the corresponding request.
methodThe method that is used to produce the response.
data.dateTimeThe system date and time in UTC, presented in the ISO 8601 format.
data.localDateTimeThe local date and time in the ISO 8601 format.
data.timeZoneThe system time zone in IANA format, for example Europe/Stockholm.

POSIX format

Response body syntax
{
  "apiVersion": "<Major>.<Minor>",
  "context": "<ID string>",
  "method": "getDateTimeInfo",
  "data": {
    "dateTime": "<date and time">,
    "localDateTime": <local date and time>,
    "posixTimeZone": "<POSIX time zone string>",
    "dstEnabled": <DST flag>
  }
}
ParameterDescription
apiVersionThe API version that is used.
contextOptional. Text string echoed back if provided by the client in the corresponding request.
methodThe method that is used to produce the response.
data.dateTimeThe system date and time in UTC, presented in the ISO 8601 format.
data.localDateTimeThe local date and time, presented in the ISO 8601 format.
data.posixTimeZoneThe system time zone in the POSIX format, for example EST5EDT,M3.2.0,M11.1.0.
data.dstEnabledThe DST flag for controlling the POSIX time zone string:
true means it will activate the DST settings of the POSIX time zone string.
false means it will ignore the DST settings of the POSIX time zone string.

IANA and POSIX format

Response body syntax
{
  "apiVersion": "<Major>.<Minor>",
  "context": "<ID string>",
  "method": "getDateTimeInfo",
  "data": {
    "dateTime": "<date and time>",
    "localDateTime": "<local date and time>",
    "timeZone": "<IANA time zone id>",
    "posixTimeZone": "<POSIX time zone string>",
    "dstEnabled": <DST flag>
  }
}
ParameterDescription
apiVersionThe API version that is used.
contextText string echoed back if provided by the client in the corresponding request.
methodThe method that is used to produce the response.
data.dateTimeThe system date and time in UTC, presented in the ISO 8601 format.
data.localDateTimeThe local date and time, presented in the ISO 8601 format.
data.timeZoneThe system time zone presented in the IANA format, for example Europe/Stockholm.
data.posixTimeZoneThe system time zone presented in the POSIX format, for example EST5EDT,M3.2.0,M11.1.0.
data.dstEnabledThe DST flag for controlling the POSIX time zone string:
true means it will activate the DST settings of the POSIX time zone string.
false means it will ignore the DST settings of the POSIX time zone string.

Return value - Failure

HTTP code

200 OK

Content-type

application/json

There currently doesn’t exist any specific error response for this method.

Error codes

General errors are listed in .

getAll

getAll is used to retrieve all date and time related properties provided by the Time API, including a list of supported time zones.

Request

Security level

Viewer

Method

POST

http://myserver/axis-cgi/time.cgi
{
  "apiVersion": "<Major>.<Minor>",
  "context": "<ID string>",
  "method": "getAll"
}
ParameterDescription
apiVersion=<Major>.<Minor>Required. The API version that is used.
context=<ID string>Optional. The client sets this value and the server echoes the data back in the response. If it is set, it will be present in the response, regardless of whether the response is successful or not.
method=getAllRequired. Specifies that the getAll operation is performed.

Return value - Success

A successful response may contain time zone information in one of the following formats:

  • IANA: The get operation will include this format, however, it can also come with the POSIX format as long as it is available in the IANA Time Zone Database.

  • POSIX: The get operation will include this format.

HTTP code

200 OK

Content-type

application/json

IANA format

Response body syntax
{
  "apiVersion": "<Major>.<Minor>",
  "context": "<ID string>",
  "method": "getAll",
  "data": {
    "dateTime": "<date and time>",
    "localDateTime": "<local date and time>",
    "timeZone": "<IANA time zone id>",
    "timeZones": ["<IANA time zone id1>", "<IANA time zone id2>", ...]
  }
}
ParameterDescription
apiVersionThe API version that is used.
contextOptional. Text string echoed back if provided by the client in the corresponding request.
methodThe method that is used to produce the response.
data.dateTimeThe system date and time in UTC, presented in the ISO 8601 format.
data.localDataTimeThe local date and time in the ISO 8601 format.
data.timeZoneThe system time zone in IANA format, for example Europe/Stockholm.
data.timeZones[]Contains an array of time zones in the IANA format that is supported on the device.

POSIX format

Response body syntax
{
  "apiVersion": "<Major>.<Minor>",
  "context": "<ID string>",
  "method": "getAll",
  "data": {
    "dateTime": "<date and time>",
    "localDateTime": "<local date and time>",
    "posixTimeZone": "<POSIX time zone string>",
    "dstEnabled": <DST flag>,
    "timeZones": ["<IANA time zone id1>", "<IANA time zone id2>", ...]
  }
}
ParameterDescription
apiVersionThe API version that is used.
contextOptional. Text string echoed back if provided by the client in the corresponding request.
methodThe method that is used to produce the response.
data.dateTimeThe system date and time in UTC, presented in the ISO 8601 format.
data.localDateTimeThe local date and time, presented in the ISO 8601 format.
data.posixTimeZoneThe system time zone, presented in the POSIX format, for example EST5EDT,M3.2.0,M11.1.0.
data.dstEnabledThe DST flag for controlling the POSIX time zone string:
true means it will activate the DST settings of the POSIX time zone string.
false means it will ignore the DST settings of the POSIX time zone string.
data.timeZones[]Contains an array of time zones in the IANA format that is supported on the device.

IANA and POSIX formats

Response body syntax
{
  "apiVersion": "<Major>.<Minor>",
  "context": "<ID string>",
  "method": "getAll",
  "data": {
    "dateTime": "<date and time>",
    "localDateTime": "<local date and time>",
    "timeZone": "<IANA time zone id>",
    "posixTimeZone": "<POSIX time zone string>",
    "dstEnabled": <DST flag>,
    "timeZones": ["<IANA time zone id1>", "<IANA time zone id2>", ...]
  }
}
ParameterDescription
apiVersionThe API version that is used.
contextOptional. Text string echoed back if provided by the client in the corresponding request.
methodThe method that is used to produce the response.
data.dateTimeThe system date and time in UTC, presented in the ISO 8601 format.
data.localDateTimeThe local date and time, presented in the ISO 8601 format.
data.timeZoneThe system time zone presented in the IANA format, for example Europe/Stockholm.
data.posixTimeZoneThe system time zone presented in the POSIX format, for example EST5EDT,M3.2.0,M11.1.0.
data.dstEnabledThe DST flag for controlling the POSIX time zone string:
true means it will activate the DST settings of the POSIX time zone string.
false means it will ignore the DST settings of the POSIX time zone string.
data.timeZones[]Contains an array of the zones, presented in the IANA format that is supported on the device.

Return value - Failure

HTTP code

200 OK

Content-type

application/json

There currently doesn’t exist any specific error response for this method.

Error codes

General errors are listed in .

setDateTime

setDateTime is used to set the date and time.

Request

Security level

Operator

Method

POST

http://myserver/axis-cgi/time.cgi
{
  "apiVersion": "<Major>.<Minor>",
  "context": "<ID string>",
  "method": "setDateTime",
  "params": {
    "dateTime": "<date and time>"
  }
}
ParameterDescription
apiVersion=<Major>.<Minor>Required. The API version that is used.
context=<ID string>Optional. The client sets this value and the server echoes the data back in the response. If it is set, it will be present in the response, regardless of whether the response is successful or not.
method=setDateTimeRequired. Specifies that the setDateTime operation is performed.
params.dateTime=<date and time>Required. Specifies that the date and time are set in UTC. The dateTime should be formatted as [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss]Z. (Example: 2018-12-24T20:30:45Z).

Return value - Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "<Major>.<Minor>",
  "context": "<ID string>",
  "method": "setDateTime",
  "data": {
    "dateTime": "<date and time>"
  }
}
ParameterDescription
apiVersionThe API version that is used.
contextOptional. Text string echoed back if provided by the client in the corresponding request.
methodThe method that is used to produce the response.
data.dateTimeEchoes the date and time value that has been set.

Return value - Failure

HTTP code

200 OK

Content-type

application/json

There currently doesn’t exist any specific error response for this method.

Error codes

General errors are listed in .

setTimeZone

setTimeZone is used to set the time zone. This will set a new IANA time zone, clearing any previous POSIX time zones, although its string in the Time Zone Database will not be affected.

setTimeZone is the preferred way of setting a time zone on the device, since it uses an uniform naming convention, such as Europe/Stockholm, which is easier to understand than the POSIX style. The Time Zone Database is commonly used in Linux distributions.

Request

Security level

Operator

Method

POST

http://myserver/axis-cgi/time.cgi
{
  "apiVersion": "<Major>.<Minor>",
  "context": "<ID string>",
  "method": "setTimeZone",
  "params": {
    "timeZone": "<IANA time zone>"
  }
}
ParameterDescription
apiVersion=<Major>.<Minor>Required. The API version that is used.
context=<ID string>Optional. The client sets this value and the server echoes the data back in the response. If it is set, it will be present in the response, regardless of whether the response is successful or not.
method=setTimeZoneRequired. Specifies that the setTimeZone operation is performed.
params.timeZone=<IANA time zone>Required. Specifies which IANA time zone that should be set.

Return value - Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "<Major>.<Minor>"
  "context": "<ID string>",
  "method": "setTimeZone",
  "data": {
    "timeZone": "<IANA time zone>"
  }
}
ParameterDescription
apiVersionThe API version that is used.
contextOptional. Text string echoed back if provided by the client in the corresponding request.
methodThe method that is used to produce the response.
data.timeZoneEchoes the time zone value that has been set.

Return value - Failure

HTTP code

200 OK

Content-type

application/json

There currently doesn’t exist any specific error response for this method.

Error codes

General errors are listed in .

setPosixTimeZone

setPosixTimeZone is used to set the POSIX time zone. This will set a new POSIX time zone and clear the previous IANA time zones. This method is not the recommend way of setting the time zone, as the POSIX style format has a complex structure and the enabled DST requires manual configuration. Instead, is the preferred method.

Request

Security level

Operator

Method

POST

http://myserver/axis-cgi/time.cgi
{
  "apiVersion": "<Major>.<Minor>",
  "context": "<ID string>",
  "method": "setPosixTimeZone",
  "params": {
    "posixTimeZone": "<POSIX time zone string>",
    "enableDst": <DST flag>
  }
}
ParameterDescription
apiVersion=<Major>.<Minor>Required. The API version that is used.
context=<ID string>Optional. The client sets this value and the server echoes the data back in the response. If it is set, it will be present in the response, regardless of whether the response is successful or not.
method=setPosixTimeZoneRequired. Specifies that the setPosixTimeZone operation is performed.
params.posixTimeZone=<POSIX time zone>Required. Specifies that the POSIXtime zone should be set, for example EST5EDT,M3.2.0,M11.1.0.
params.enableDst=<DST flag>Required. Set to true to activate the DST settings of the POSIX time zone string. Set to false to ignore the DST setting of the POSIX time zone string.

Return value-Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "apiVersion": "<Major>.<Minor>",
  "context": "<ID string>",
  "method": "setPosixTimeZone",
  "data": {
    "posixTimeZone": "<POSIX time zone string>",
    "dstEnabled": <DST flag>
  }
}
ParameterDescription
apiVersionThe API version that is used.
contextOptional. Text string echoed back if provided by the client in the corresponding request.
methodThe method that is used to produce the response.
data.posixTimeZoneEchoes the set value of the time zone.
data.dstEnabledEchoes the set values of the DST flag.

Return value - Failure

HTTP code

200 OK

Content-type

application/json

There currently doesn’t exist any specific error response for this method.

Error codes

General errors are listed in .

getSupportedVersions

getSupportedVersions is used to retrieve supported API versions.

Request

Security level

Viewer

Method

POST

http://myserver/axis-cgi/time.cgi
{
  "context": "<ID string>",
  "method": "getSupportedVersions"
}
ParameterDescription
context=<ID string>Optional. The client sets this value and the server echoes the data back in the response. If it is set, it will be present in the response, regardless of whether the response is successful or not.
method="getSupportedVersions"Required. Specifies that the getSupportedVersions operation is performed.

Return value - Success

HTTP code

200 OK

Content-type

application/json

Response body syntax
{
  "context": "<ID string>",
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": [ "<Major1>.<Major1>", "<Major2>.<Minor2>" ]
  }
}
ParameterDescription
contextOptional. Text string echoed back if provided by the client in the corresponding request.
methodThe method that is used to produce the response.
data.apiVersionsContains an array of supported versions.
data.apiVersions[]=<list of versions>Contains a list of supported ”<Major>.<Minor>” versions, e.g. [“1.4”,”2.5”].

Return value - Failure

HTTP code

200 OK

Content-type

application/json

There currently doesn’t exist any specific error response for this method.

Error codes

General errors are listed in .

Error handling

The following table lists general errors that can occur for any JSON requests. As there currently doesn’t exist any specific error responses, a general JSON error response is listed below. Descriptions will only be used to describe the type of error code that appears and detailed information on the fault will be provided in the message field in the error structure.

CodeDescription
1000Internal error. Refer to message field or logs.
2000Invalid request. Only HTTP request type POST is supported.
2001Request body too large.
3000Invalid JSON data.
4000Method does not exist.
4001The specified version is not supported.
4002Authorization failed.
4003Missing parameter(s).
4004Invalid parameter(s).

All failures are returned with the following JSON response:

Error response body syntax
{
  "apiVersion": "<Major>.<Minor>",
  "context": "<ID string>",
  "method": "<method string>",
  "error": {
    "code": <integer error code>,
    "message": "<string>"
  }
}
ParameterDescription
apiVersionThe API version that is used.
contextOptional. Text string echoed back if provided by the client in the corresponding request.
methodThe method that is used to produce the response.
error.codeContains the error code. This value can be a method specific and/or a general error code.
error.messageContains a detailed message about the occurred failure.

HTTP status codes

Some HTTP requests might fail before the JSON parser can be called. These errors are returned in the JSON body when the service is executed, which means that the client must be able to handle HTTP error codes. Specifically HTTP errors 401 and 403 will be returned if the authentication fails.