Public API (deprecated) - Date Resolution

Date Resolution

The dateRange object holds parameter values that are used to define a specific date range when requesting data. The dateRange is resolved to a specific first and last date based on these parameters.

Example: https://services.foresee.com/services/calendar/lookup?criteria={“dateRange”:{“f”:”2016-07-01″,”l”:”2016-07-02″}}

There are three modes of date resolution:

  • Custom – The first and last dates are set explicitly by the caller, as in the previous example.
  • Absolute – The desired date periods are indicated by one of the absolute date range types.
  • Relative – The date range is defined by one of the absolute range types, relative to a reference or ‘as of’ date.

The following table contains general date parameters, values, and examples for the dateRange object.

Parameter Variables Description
a: “as of” Date Format: YYYY-MM-DD Defaults to today unless explicitly set.
k: Customer Key Required for calls involving custom calendars.
c: Calendar Type
  • GREGORIAN, G
  • FISCAL, F
  • Gregorian – All starting points (Year, Month, Week) are according to the Gregorian calendar.
  • Fiscal – Customer specifies all starting points.
r: Range
  • DAY, DY
  • WEEK, WK
  • MONTH, MO
  • QUARTER, QR
  • YEAR, YR
  • DAYS, D
  • WEEKS, W
  • MONTHS, M
  • QUARTERS, Q
  • YEARS, Y
  • CUSTOM, C
In association with a non-zero Number Value, indicates a specific numbered period:
  • Day – The numbered day of the year, generally between 1 and 365 (or the maximum number of days in the relevant year according to the Calendar Type).
  • Week – The numbered week of the year, generally between 1 and 52 (or the maximum number of weeks in the relevant year according to the Calendar Type).
  • Month – The numbered month of the year, generally between 1 and 12.
  • Quarter – The numbered three-month period of the year, generally between 1 and 4.
  • Year – The specific four-character year.
In association with Number Value, indicates a sequence of periods relative to the “as of” Date:
  • Days – The number of days prior. Example: "r":"D", "n":"2" returns yesterday and the day before.
  • Weeks – The number of full weeks (according to the Calendar Type) prior to the current. A zero value returns the week-to-date ending one day prior to the “as of” Date. A negative number returns seven day periods ending with the “as of” Date. Example: "r":"W", "n":"-3" returns 21 days ending with the “as of” Date.
  • Months – The number of full months (according to the Calendar Type) prior to the current. A zero value returns the month-to-date ending one day prior to the “as of” Date. A negative number returns month periods based on the day-of-the-month of the “as of” Date. Example: "r":"M", "n":"-2" with an “as of” Date of March 8 returns January 9 through March 8.
  • Quarters – The number of full three-calendar-month periods (according to the Calendar Type) prior to the current. A zero value returns the quarter-to-date ending one day prior to the “as of” Date. A negative number returns three month periods based on the day-of-the-month of the “as of” Date. Example: "r":"Q", "n":"-3" with an “as of” Date of December 18 returns March 19 through December 18.
  • Years – The number of full years (according to the Calendar Type) prior to the current. A zero value returns the year-to-date ending one day prior to the “as of” Date. A negative number returns years based on the day-of-the-month of the “as of” Date (ignoring the start and end dates of the calendar type).
In association with First and Last dates of range, indicates a specific period with corresponding period-to-date:
  • Custom – Specify the First and Last dates of range for the period. Example: "r":"C", "f":"2014-07-09", "l":"2014-07-29" returns the 21 days of the range.
p: Period
  • DEFINED, D
  • PRIOR, P
  • CURRENT, C
  • NEXT, N
  • PRIOR_YEAR, Y
  • Defined – Indicates the First and Last dates of range are defined. Example: "r":"YR", "n":"2013" is Defined as the calendar year of 2013.
  • Prior – Moves the First and Last dates of range according to the Range Type and Number Value to an earlier range. Example: "r":"MO", "p":"P", "n":"3" returns the third month Prior to the last full month (according to the Calendar Type).
  • Current – Sets the Last date of range to the end of the present Range Type, which is generally a future date. Example: "r":"MO", "p":"C" sets "l" to the last day of the current month.
  • Next – Moves the First and Last dates of range according to the Range Type and Number Value to the following range. Example: "r":"MO", "p":"N", "n":"3" returns the fourth month.
  • Prior Year – Moves the First and Last dates of range to the year before the Number Value. Example: "r":"YR", "n":"2011", "p":"Y" returns the year 2010.
n: Number Value
f: First date of range Format: YYYY-MM-DD
l: Last date of range Format: YYYY-MM-DD

Other articles in this section:

  1. OAuth Protocol
  2. Date Resolution (current article)
  3. Endpoints
  4. Glossary of Terms