Last modified on August 24, 2023 at 6:51 pm
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