Solutions

How do you set the date range in a report we pull down through the Webapi?

Solutions ID:    KB4262
Version:    2.0
Status:    Published
Published date:    01/24/2011
Updated:    01/24/2011
 

Problem Description

How do I use the function  "dateRelativeUnit" in conjunction with the fuction  "dateStart"  and "dateEnd" ?

What is the differenece between "dateEnd" and "endDate"?

Does using "dateEnd", and "endDate" manifest in the same programmatic end result?  How do I use both?

Why does using these functions in a argument, "dateRelativeUnit=week&dateStart=2&endDate=0"  seem to work, but  using date&dateStart in place of week&dateStart doesn't seem to work?

Resolution

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 .
  • Previous.
  • 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.

Examples
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. :

  1. 0 = 2009-01-01 12:00:00 PM GMT
  2. 1 = 2008-01-01 12:00:00 PM GMT
  3. 2 = 2007-01-01 12:00:00 PM GMT

These functions below result in the above absolute values.

  1. Current Year: (2009-01-01 - today) "dateRelativeUnit=year&dateStart=0"
  2. Previous Year (2008-01-01 to 2009-01-01) "dateRelativeUnit=year&dateStart=1&dateEnd=0"
  3. Previous Two Years (2007-01-01 to 2009-01-01) "dateRelativeUnit=year&dateStart=2&dateEnd=0"

Definitions:

1: Parameter: dateEnd
Description: Configures an ending date filter.  

Example

  1. dateEnd=2007-12-31T13:00:00-00:00
  2. dateEnd=1254299093
  3. dateEnd=5

2: Parameter: dateStart
Description: Configures a beginning date filter. There are three different syntaxes for the
date:

  • 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

Example

  • dateStart=2007-12-31T13:00:00-00:00
  • dateStart=1254299093
  • dateStart=5

3: dateRelativeUnit
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).

Example

  • 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


Rate this Page

Please take a moment to complete this form to help us better serve you.

Did this document help answer your question?
 
 
If you are finished providing feedback, please click the RATE CONTENT button. Otherwise, please add more detail in the following text box and then click RATE CONTENT.
 
 

Your response will be used to improve our document content.

Ask a Question