Date formats
The platform allows some flexibility in the use of date/time fields in the HTTP and MQTT APIs. Fields are always of type string, but the content can be specified using the formats described here. This section also describes characteristics related to UTC handling, time zone conversion, and other details.
Separators
Date separator
The characters "/" and "-" are accepted interchangeably as date separators.
Time separator
The time separator must always be ":".
Date and time separator
Optionally, a "T" character can be used to separate the date and time. The following two dates, for example, are equivalent:
2020-02-25 14:35:18
2020-02-25T14:35:18Formats
Date formats (without time)
The platform supports the following formats for specifying a date.
| Format | Comments |
|---|---|
| yyyy/M/d | Specifies the 4-digit year, followed by month and day, without using zeros to pad month and day. The date separator can be any of the supported ones. |
| yyyy/MM/dd | Specifies the 4-digit year, followed by month and day, using zeros to pad month and day. The date separator can be any of the supported ones. |
Time formats
The platform supports the following formats for time.
| Format | Comments |
|---|---|
| H:m | Time is specified in 24-hour format, providing hours and minutes, without zero-padding, using the time separator. |
| H:m:s | Time is specified in 24-hour format, providing hours, minutes, and seconds, without zero-padding, using the time separator. |
| HH:mm | Time is specified in 24-hour format, providing hours and minutes, with zero-padding, using the time separator. |
| HH:mm:ss | Time is specified in 24-hour format, providing hours, minutes, and seconds, with zero-padding, using the time separator. |
Epoch format
It is possible to specify a date and time in epoch format, that is, as the number of seconds since midnight on January 1, 1970, UTC. The epoch format is always expressed in UTC, and therefore does not allow time zone indication.
| Format | Comments |
|---|---|
| nnnnnnnnnn | Epoch format. In this format, the date and time are reported as a number of seconds from midnight on January 1, 1970, UTC. For example, the date "2010/10/23 02:47:25" corresponds to the value 1287802045. |
Time zone indication (optional)
All APIs require the use of UTC dates and times. However, local times are allowed as long as they contain the time zone offset indication.
- For all dates and times that do not contain a time zone offset (or that contain the "Z" suffix), they will be assumed to be expressed in UTC.
- If a time zone offset is provided, it must consist of a "+" or "-" sign, followed by hours and minutes using the time separator between them.
- Time zone offsets are not compatible with epoch format. Epoch format must always be reported in UTC.
Below are some examples.
| Example | UTC value used | Comments |
|---|---|---|
| 2020-02-21 03:37:14 | 2020-02-21 03:37:14 (same) | No time indication, so UTC is assumed. Corresponds to 03:37:14 on February 21, 2020, UTC time. |
| 2020-02-21 03:37:14Z | 2020-02-21 03:37:14 (same) | The Z suffix indicates the time is expressed in UTC, so this example is equivalent to the previous one. |
| 2020-02-21 20:30:25 -05:00 | 2020/02/22 01:30:25 | Indicates a 5-hour offset to the west. Note that in UTC time, the date advances 5 hours and moves to the next day. |
| 2020-02-21 20:30:25 +05:00 | 2020-02-21 15:30:25 | Indicates a 5-hour offset to the east. |