Dates at Carriots

This section talks about how Carriots manage dates in the platform.

Dates in the REST API


Status or Data streams will have a date validation for the field "at" to keep streams management safe. "at" field must be a Unix timestamp (UTC) but reserved word "now" can be used instead. If "now" is used Carriot s will fill the "at" value with reception date and time timestamp (UTC).

The "date" Unix/Linux shell command with "+%s" parameter will get the actual timestamp. In there is also a timestamp converter. And Carriots provide its own date service

Date shell command execution example:

Other entities and responses:

Carriots API REST Dates will be represented by strings with ISO 8601:2004 standard.

ISO 8601 standard "Data elements and interchange formats – Information interchange – Representation of dates and times" specifies date and times representation providing unambiguous notation and facilitates data migration between different systems.

Format Description
Year YYYY (eg 2012)
Year and month: YYYY-MM (eg 2012-10)
Complete date: YYYY-MM-DD (eg 2012-10-06)
Complete date plus hours and minutes: YYYY-MM-DDThh:mmTZD (eg 2012-10-06T17:35+01:00)
Complete date plus hours, minutes,
seconds and a decimal fraction of a second
YYYY-MM-DDThh:mm:ss.sTZD (eg 2012-10-06T17:35:21.45+01:00)
Code Description
YYYY four-digit year
MM two-digit month (01=January, etc.)
DD two-digit day of month (01 through 31)
hh two digits of hour (00 through 23) (am/pm NOT allowed)
mm two digits of minute (00 through 59)
ss two digits of second (00 through 59)
s one or more digits representing a decimal fraction of a second
TZD time zone designator (Z or +hh:mm or -hh:mm)

More details at

Dates in the Control Panel

Carriots store all system relevant dates in UTC timestamps format. System relevant dates are those updated by the system and the streams "at" field used in filtering and ordering functionalities. Those dates are:

  • Entities "Created at" field
  • Entities "Updated at" field
  • Streams "at" field

When Carriots shows those dates in the control panel, user's timezone is used to represent them in the local time defined by the user.

Date service

Carriots provide a date service which returns the actual date or timestamp to valid queries. Valid queries require "carriots.apikey" header to be specified.

URL: type --&format=-- format --&time_zone=-- time_zone --
HTTP method: GET


Parameter Description
type (optional) Text. One of "date" or "timestamp". Default value is "date" (if nothing specified).
"date" returns an ISO 8601 date
"timestamp" always returns an UTC timestamp and ignores "format" and "time_zone" parameters.
format (optional) Text. Default value is "ISO8601".
Can be a string with a constant as specified in PHP manual (link): ATOM, COOKIE, ISO8601, RFC822, RFC850...
Can also be a free format string as specified in PHP manual (link)
Example: /now/?format=Y-m-d%20H:i:s query will return something like {"date":"2013-04-19 07:52:11"} Note that spaces and oher URL non-friendly characters must encoded (space = %20)
time_zone (optional) Text. Default value is "UTC".
Must be one of the strings listed in the PHP Manual (link)
Example: /now/?time_zone=Pacific/Auckland query will return something like {"date":"2013-04-19T19:57:07+1200"}

Response codes

Code Description
200 Operation successfull
Possible values:{"date":-- the date --}
400 Request not valid. Only one error will be reported.
Possible values:
- code: empty message: Bad parameter format details: empty
- code: empty message: Bad parameter timezone details: empty
- code: empty message: Bad request details:
404 Resource not found
503 Service unavailable.
- code: 5031 message: BD error details:
- code: 5032 message: exception details: {message: }