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:
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
Obsoletes
This API deprecates the following methods:
date.cgi
: This method will still be available during a transitional period.Time.POSIXTimeZone
andTime.DST.Enabled
: Both of these methods are fully supported by the Time API, but can also be accessed through the legacyparam.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
}
}
Parameter | Description |
dateTime | System date and time presented in UTC. The format is in ISO 8601. |
localDateTime | Local date and time. The format is ISO 8601. |
timeZone | System time zone in the IANA format. |
posixTimeZone | System time zone in the POSIX format. |
dstEnabled | true 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" ]
}
}
Parameter | Description |
dateTime | System date and time presented in UTC. The format is in ISO 8601. |
localDateTime | Local date and time. The format is ISO 8601. |
timeZone | System time zone in the IANA format. |
posixTimeZone | System time zone in the POSIX format. |
dstEnabled | 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.The IANA response does not contain this field, as the DST is always true . |
timeZones | List 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"
}
}
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
}
}
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"
}
Parameter | Description |
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=getDateTimeInfo | Required. 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
{
"apiVersion": "<Major>.<Minor>",
"context": "<ID string>",
"method": "getDateTimeInfo",
"data": {
"dateTime": "<date and time>",
"localDateTime": "<local date and time>",
"timeZone": "<IANA time zone id>"
}
}
Parameter | Description |
apiVersion | The API version that is used. |
context | Optional. Text string echoed back if provided by the client in the corresponding request. |
method | The method that is used to produce the response. |
data.dateTime | The system date and time in UTC, presented in the ISO 8601 format. |
data.localDateTime | The local date and time in the ISO 8601 format. |
data.timeZone | The system time zone in IANA format, for example Europe/Stockholm . |
POSIX format
{
"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>
}
}
Parameter | Description |
apiVersion | The API version that is used. |
context | Optional. Text string echoed back if provided by the client in the corresponding request. |
method | The method that is used to produce the response. |
data.dateTime | The system date and time in UTC, presented in the ISO 8601 format. |
data.localDateTime | The local date and time, presented in the ISO 8601 format. |
data.posixTimeZone | The system time zone in the POSIX format, for example EST5EDT,M3.2.0,M11.1.0 . |
data.dstEnabled | The 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
{
"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>
}
}
Parameter | Description |
apiVersion | The API version that is used. |
context | Text string echoed back if provided by the client in the corresponding request. |
method | The method that is used to produce the response. |
data.dateTime | The system date and time in UTC, presented in the ISO 8601 format. |
data.localDateTime | The local date and time, presented in the ISO 8601 format. |
data.timeZone | The system time zone presented in the IANA format, for example Europe/Stockholm . |
data.posixTimeZone | The system time zone presented in the POSIX format, for example EST5EDT,M3.2.0,M11.1.0 . |
data.dstEnabled | The 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
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"
}
Parameter | Description |
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=getAll | Required. 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
{
"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>", ...]
}
}
Parameter | Description |
apiVersion | The API version that is used. |
context | Optional. Text string echoed back if provided by the client in the corresponding request. |
method | The method that is used to produce the response. |
data.dateTime | The system date and time in UTC, presented in the ISO 8601 format. |
data.localDataTime | The local date and time in the ISO 8601 format. |
data.timeZone | The 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
{
"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>", ...]
}
}
Parameter | Description |
apiVersion | The API version that is used. |
context | Optional. Text string echoed back if provided by the client in the corresponding request. |
method | The method that is used to produce the response. |
data.dateTime | The system date and time in UTC, presented in the ISO 8601 format. |
data.localDateTime | The local date and time, presented in the ISO 8601 format. |
data.posixTimeZone | The system time zone, presented in the POSIX format, for example EST5EDT,M3.2.0,M11.1.0 . |
data.dstEnabled | The 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
{
"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>", ...]
}
}
Parameter | Description |
apiVersion | The API version that is used. |
context | Optional. Text string echoed back if provided by the client in the corresponding request. |
method | The method that is used to produce the response. |
data.dateTime | The system date and time in UTC, presented in the ISO 8601 format. |
data.localDateTime | The local date and time, presented in the ISO 8601 format. |
data.timeZone | The system time zone presented in the IANA format, for example Europe/Stockholm . |
data.posixTimeZone | The system time zone presented in the POSIX format, for example EST5EDT,M3.2.0,M11.1.0 . |
data.dstEnabled | The 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
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>"
}
}
Parameter | Description |
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=setDateTime | Required. 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
{
"apiVersion": "<Major>.<Minor>",
"context": "<ID string>",
"method": "setDateTime",
"data": {
"dateTime": "<date and time>"
}
}
Parameter | Description |
apiVersion | The API version that is used. |
context | Optional. Text string echoed back if provided by the client in the corresponding request. |
method | The method that is used to produce the response. |
data.dateTime | Echoes 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
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>"
}
}
Parameter | Description |
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=setTimeZone | Required. 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
{
"apiVersion": "<Major>.<Minor>"
"context": "<ID string>",
"method": "setTimeZone",
"data": {
"timeZone": "<IANA time zone>"
}
}
Parameter | Description |
apiVersion | The API version that is used. |
context | Optional. Text string echoed back if provided by the client in the corresponding request. |
method | The method that is used to produce the response. |
data.timeZone | Echoes 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
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>
}
}
Parameter | Description |
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=setPosixTimeZone | Required. 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
{
"apiVersion": "<Major>.<Minor>",
"context": "<ID string>",
"method": "setPosixTimeZone",
"data": {
"posixTimeZone": "<POSIX time zone string>",
"dstEnabled": <DST flag>
}
}
Parameter | Description |
apiVersion | The API version that is used. |
context | Optional. Text string echoed back if provided by the client in the corresponding request. |
method | The method that is used to produce the response. |
data.posixTimeZone | Echoes the set value of the time zone. |
data.dstEnabled | Echoes 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
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"
}
Parameter | Description |
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
{
"context": "<ID string>",
"method": "getSupportedVersions",
"data": {
"apiVersions": [ "<Major1>.<Major1>", "<Major2>.<Minor2>" ]
}
}
Parameter | Description |
context | Optional. Text string echoed back if provided by the client in the corresponding request. |
method | The method that is used to produce the response. |
data.apiVersions | Contains 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
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.
Code | Description |
1000 | Internal error. Refer to message field or logs. |
2000 | Invalid request. Only HTTP request type POST is supported. |
2001 | Request body too large. |
3000 | Invalid JSON data. |
4000 | Method does not exist. |
4001 | The specified version is not supported. |
4002 | Authorization failed. |
4003 | Missing parameter(s). |
4004 | Invalid parameter(s). |
All failures are returned with the following JSON response:
{
"apiVersion": "<Major>.<Minor>",
"context": "<ID string>",
"method": "<method string>",
"error": {
"code": <integer error code>,
"message": "<string>"
}
}
Parameter | Description |
apiVersion | The API version that is used. |
context | Optional. Text string echoed back if provided by the client in the corresponding request. |
method | The method that is used to produce the response. |
error.code | Contains the error code. This value can be a method specific and/or a general error code. |
error.message | Contains 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.