Time format overview

The short version

All dates will be represented using the following ISO8601-compliant format:

yyyy-MM-dd'T'hh:mm:ss'Z'

Here are some examples illustrating this format:

  • 8:07:00 P.M. UTC on January 18, 2009: 2009-01-18T20:07:00Z
  • 9:02:43 A.M. Eastern Daylight Time on August 31, 2012: 2012-08-31T13:02:43Z (note the adjustment to express the time in UTC)

Details

The accepted date-time format for this API is the Complete date plus hours, minutes and seconds form of the W3C Date-time format. All dates present in server responses will be expressed using the W3C DTF format and use the UTC timezone and a Z timezone indicator. Since the W3CDTF is a subset of the ISO8601 standard, any date parsing library which understands ISO8601 date-times will understand this format. Also, since date strings emitted by the API are highly uniform, parsing them manually should be straightforward.

When sending a date string to the server in an API request, any date string which conforms to any of the W3C DTF patterns and includes at least year, month, day-of-month, hour, and minute components is considered a valid date. All other date components are optional. If no timezone is specified, it will be interpreted as UTC. Any unspecified component will be assumed to have a value of 0.

Filtering By Date

When filtering on a date-type field, there are several ways to specify your parameter:

  • Precise Date, e.g. 2007-03-14T06:22:10+04:00

    By specifying your date down to the second, any items with a precisely matching date will be returned.

  • Imprecise Date, e.g. 2007-03

    You may choose to specify only a partial date, and any items whose dates match the date components you specify will be returned. For instance, if your filter parameter value is 2007-03-15T07, all items with a date of July 15, 2007, within the one hour-range from 7AM UTC (inclusive) to 8AM UTC (exclusive) will be returned. For the level of precision you choose, all less-precise components must be provided. Timezone indicators are allowed.

  • Date Range, e.g. [2010,2012-06-15]

    You may specify a specific range of dates by using an expression starting with an open bracket, followed by a date string with any level of precision you choose, a comma, a second date string, and closing bracket.

References

W3C Note specifying W3C DTF profile of ISO 8601 Date time format