Timeframe

A timeframe is the period of time over which you want to run an analysis. Timeframes are used optionally in Metrics and are required in Series. Timeframes can only be applied to the keen.timestamp property (they won’t work with your own custom timestamp properties).

Timeframes can be specified in two different ways:

  • Relative Timeframes - a timeframe that is relative to now. Example: this week
  • Absolute Timeframes - a timeframe that is specified by two points in time. Example: April 1st, 2012 at 4:00pm until April 15th, 2012 at 4:00pm.

Note

Note: If you don’t include a timeframe, it defaults to all time.

Relative Timeframes

Note

All relative times are UTC by default. To make them local, check out timezones.

Relative timeframes can be lumped into two categories – “this” and “previous”. The chart below illustrates the difference between the two. Use “this” when you want to include events happening right up until now. Use “previous” when you only want to get results for complete chunks of time (e.g. the full hour, day, or week).

../../_images/timeframe-graphic-transitional.png

Notice that “this_2_days” will include all of the current day and all of the previous day. Whereas “previous_2_days” includes the previous two fully completed days and none of the current day.

To specify a relative timeframe, simply add the timeframe parameter to your query string and set it equal to the relative time of your choice.

You can add the parameter to any query string:

https://api.keen.io/3.0/projects/<project_id>/queries/count?api_key=<read_key>&event_collection=<event_collection>&timeframe=previous_7_days&timezone=-28800

Below are the supported relative timeframes:

  • this_minute - Creates a timeframe starting from the beginning of the current minute until now.
  • this_hour - Creates a timeframe starting from the beginning of the current hour until now.
  • today or this_day - Creates a timeframe starting from the beginning of the current day until now.
  • this_week - Creates a timeframe starting from the beginning of the current week until now.
  • this_month - Creates a timeframe starting from the beginning of the current month until now.
  • this_year - Creates a timeframe starting from the beginning of the current year until now.
  • this_n_minutes - All of the current minute and the previous completed n-1 minutes.
  • this_n_hours - All of the current hour and the previous completed n-1 hours.
  • this_n_days - All of the current day and the previous completed n-1 days.
  • this_n_weeks - All of the current week and the previous completed n-1 weeks.
  • this_n_months - All the current month and previous completed n-1 months.
  • this_n_years - All the current year and previous completed n-1 years.
  • previous_minute - convenience for “previous_1_minute”
  • previous_hour - convenience for “previous_1_hour”
  • yesterday or previous_day - convenience for “previous_1_day”
  • previous_week - convenience for “previous_1_week”
  • previous_month - convenience for “previous_1_months”
  • previous_year - convenience for “previous_1_years”
  • previous_n_minutes - Gives a start of n-minutes before the most recent complete minute and an end at the most recent complete minute. Example: If right now it is 7:15:30pm and I specify “previous_3_minutes”, the timeframe would stretch from 7:12pm until 7:15pm.
  • previous_n_hours - Gives a start of n-hours before the most recent complete hour and an end at the most recent complete hour. Example: If right now it is 7:15pm and I specify “previous_7_hours”, the timeframe would stretch from noon until 7:00pm.
  • previous_n_days - Gives a starting point of n-days before the most recent complete day and an end at the most recent complete day. Example: If right now is Friday at 9:00am and I specify a timeframe of “previous_3_days”, the timeframe would stretch from Tuesday morning at 12:00am until Thursday night at midnight.
  • previous_n_weeks - Gives a start of n-weeks before the most recent complete week and an end at the most recent complete week. Example: If right now is Monday and I specify a timeframe of “previous_2_weeks”, the timeframe would stretch from three Sunday mornings ago at 12:00am until the most recent Sunday at 12:00am. (yesterday morning)
  • previous_n_months - Gives a start of n-months before the most recent completed month and an end at the most recent completed month. Example: If right now is the 5th of the month and I specify a timeframe of “previous_2_months”, the timeframe would stretch from the start of two months ago until the end of last month.
  • previous_n_years - Gives a start of n-years before the most recent completed year and an end at the most recent completed year. Example: If right now is the June 5th and I specify a timeframe of “previous_2_years”, the timeframe would stretch from the start of two years ago until the end of last year.

Absolute Timeframes

Absolute timeframes are specified similar to Filters.

To specify an absolute timeframe, create a JSON object with “start” and “end” properties. Set those properties equal to the desired start and end times in string form using ISO-8601 Format.

Example:

{
    "start" : "2012-08-13T19:00Z",
    "end" : "2013-09-20T19:00Z"
}

Timeframes are either passed through a HTTP POST/PUT body, or through the query string of an HTTP GET. If you’re making a GET request and you want to specify an absolute timeframe, you’ll have to URL encode your JSON string using the proper method in your language of choice.

Note

To use an absolute timeframe through the workbench, simply put the JSON object referenced above in the timeframe section.

This is what the above example looks like URL encoded:

%7b%22start%22%3a%222012-08-13T19%3a00Z%22%2c%22end%22%3a%222013-09-20T19%3a00Z%22%7d

Finally, set the timeframe parameter in your query string equal to the URL encoded string.

Example:

https://api.keen.io/3.0/projects/<project_id>/queries/count?api_key=<read_key>&event_collection=<event_collection>&timeframe=%7b%22start%22%3a%222012-08-13T19%3a00Z%22%2c%22end%22%3a%222013-09-20T19%3a00Z%22%7d

Note

If you use an absolute timeframe, we use the timezone in the ISO-8601 strings to define the timezone instead of the timezone parameter.

So, what are you waiting for? It only takes a few minutes and a few lines of code to start collecting the events that really matter to you.

Sign Up Free