When using the WebAPI to create a report (/api/create), you can specify a date filter using absolute units or relative units. Absolute dates can be specified in Unix time or as an ISO 8601 string. Relative dates are powerful, but are slightly more complex. Relative dates specify date filters in one of the following categories:
- Current .
- Current and Previous.
If the dateRelativeUnit parameter is set, the dateStart and dateEnd define the number of units into the past. The following are valid units: year, month, week, day, and hour. It is important to understand that dateStart and dateEnd always represent a point in time that is on a boundary of a whole unit (year, month, week). A value of zero for dateStart or dateEnd represents the nearest whole unit in the past. Therefore, if dateStart is set to zero and dateRelativeUnit is set to year, the dateStart represents January 1, of the current year. If dateStart is set to zero and dateRelativeUnit is set to week, the dateStart represents Sunday of the current week.
In the following examples, dateRelativeUnit=year. and today's date is 2009-10-01 (YYYY-MM-DD). Thus, values for dateStart or dateEnd have the following absolute values. :
- 0 = 2009-01-01 12:00:00 PM GMT
- 1 = 2008-01-01 12:00:00 PM GMT
- 2 = 2007-01-01 12:00:00 PM GMT
These functions below result in the above absolute values.
- Current Year: (2009-01-01 - today) "dateRelativeUnit=year&dateStart=0"
- Previous Year (2008-01-01 to 2009-01-01) "dateRelativeUnit=year&dateStart=1&dateEnd=0"
- Previous Two Years (2007-01-01 to 2009-01-01) "dateRelativeUnit=year&dateStart=2&dateEnd=0"
1: Parameter: dateEnd
Description: Configures an ending date filter.
2: Parameter: dateStart
Description: Configures a beginning date filter. There are three different syntaxes for the
- Unix Time (number of seconds since January 1, 1970 UTC)
- ISO 8601 formatted string (for example: 2007-12-31T13:00:00-00:00).
- If dateRelativeUnit is set, it is the number of those units relative to the
Description: Allows specifying a date filter using relative dates instead of an absolute start and end time. Valid values are hour, date, week, month, and year. If dateRelativeUnit is set, dateStart and dateEnd must be the number of relative
units (not Unix time or an ISO 8601 string).
- dateRelativeUnit=week&dateStart=0// Current week
- dateRelativeUnit=week&dateStart=5&endDate=0// Previous 5 weeks (does not include current week) TIP: The use of 'endDate' specifies a relative unit that begins with this week, but doesn't include this week.
- dateRelativeUnit=week& dateStart=5// Previous 5 weeks (includes current week)
NOTE1: For more information about UNIX time, or ISO 8601, see TIME.
NOTE2: For more information on how to use the WEBAPI, seeKB3899