Dates and Timezones

Date and Time Strings

For date values in the request body, you must use the ISO 8601 standard, this ensure consistency across different localization techniques and timezones.

A simple example would be: 2011-09-26T00:00:00+0000. For data parameters without a time code the short version of the ISO 8601 standard is used, for example 2011-09-26.

📘

Important Notice

If the short version of the ISO 8601 standard is used, e.g. for birth dates, the timezone is assumed UTC and not the requester's time zone.

Unix Timestamp

Some specific methods of the API, as the ones using the Request Signing, may require the Unix Time (aka. as POSIX Time or Epoch Time). This is used as such to ensure consistency with widely used practices in the market regarding cryptographic and signing algorithms.

The problem with Timezones

In the video below, Tom Scott from Computerphile explains the problems computer systems dealing with timezone manually, why it should be avoided and how to actually manage it in the real life. The lesson is quite simple: let the system deal with it.

As much as possible, try to use UTC date times during data transit and delegate to the OS (or browser for web apps) to distinguish and display the correct date (with the user timezone and preferred locale format) in the end-user device.