All incoming date-times or time durations must be in ISO8601 format. For date-times, either the basic (for example, 20120922T170102.123Z) or extended version (for example, 2012-09-22T17:01:02.123Z) is acceptable and the milliseconds precision is optional. For durations, either the standard (for example, P3Y6M4DT12H30M5S) or alternate extended form (for example, P0003-06-04T12:30:05) is acceptable. Where either a date-time or duration can be provided, it is an error to provide both.
Refer to ISO_8601 for details.
Providing no time range information in a search time is valid (that is, no time limits are placed on the search results). If a range is provided, then the following combinations are acceptable:
- Start and end date-time.
- Start date-time only.
- End date-time only.
- Duration only.
If both a start and end time are provided, then the start date-time must not be later than the end date-time (they are allowed to be the same). Providing start and end date-times in the future is also acceptable, provided that the start date-time is not later than the end date-time. Different timezones may be provided for the start and end date-times: they are converted to UTC prior to comparison.
If a duration is provided then it must be a positive duration. This sets the end date-time to now, and the start date-time to the end date-time less the provided duration (a negative duration means that the start date-time is later than the end date-time which is not permitted).