Time Filter Resource

Time filters are used to include or exclude certain stream intervals. Time filters can be used to determine:

Time of use (TOU) which are common in the energy industry (i.e. Winter on Peak).
Spring, Summer, Winter, Fall average weekend afternoon temperatures.
If a certain door or window opened more than once on a certain weekday within a certain time range (stream with rollup_calendar and time_filter).
Sales total on weekends.
And many more use cases - too many to list here...

Time filters are applied to Stream Feeds as they are uploaded or derived prior to saving to the store so filtered feeds are immediately available as data arrives.

A filter is applied during each roll-up calculation. Intervals that are filtered out by the time_filter will be ignored during roll-up calculations. Even though filtered intervals are marked as Gaps (or null values) during a roll-up, they will not be included in roll-up Gap functions (i.e. they will not be included in the GAPCOUNT totals).

Marking filtered out intervals as Gaps has several advantages:

The time_filter only needs to be applied once which improves performance throughout GroveStreams.
GroveStreams supports data sparsity when it comes to storage. Most null values are not stored so you'll be charged less for storage.
It improves performance since most Gaps are not stored they do not need to be read from disk.
Gap values created by a time_filter are ignored by both the GroveStreams' rollup_calendar and derivation calculation engines.

A time_filter is defined by a collection of cycle_ranges and by a collection of smaller time spans within a day. First add cycle_ranges to include a collection of time spans. Then adjust the time of day (TOD) array to exclude intervals that occur within each day.

For an interval to be considered as 'included' it must be included in one or more cycle_ranges and be included in the TOD array. Time filter intervals can be larger than stream interval sizes. For example, you may create a time_filter with interval sizes of 60 minutes and apply that time_filter to a stream with 1 minute interval sizes.

The TOD array is ignored for streams that have a custom base cycle. For this case, a stream interval must fall within one or more time_filter cycle_range for it to be included.

A time_filter with no cycle_ranges implies all days are to be included prior to the TOD exlusion check.

A time zone id can be associated with a time_filter or the component's time zone will be used during filter calculations if timeZoneId is a blank string. The time zone is used to determine each cycle_range start and end datetimes and for day of week and time of day calculations.

Time zone ids.

GET time_filter

Returns a list of time_filter resources.	Resource Information
	Rate Limited?	Yes
	session, oauth and org tokens compatible?	Yes
	api_key token token compatible?	Yes

Resource URL

http://grovestreams.com/api/time_filter

Parameters

none

Example Requests

/time_filter

Response Body


					
{
   "message": "",
   "time_filter":
					[
     {
      
					"uid": "4ab5fb49-e287-4dec-9440-ba670e2df632",

					      "description": "Winter Weekend
					afternoons",
       "name": "Winter
					On Peak - Hourly"
     },

					    {
       "uid":
					"8219de19-b407-4425-bbfd-8b964355656a",

					      "description": "Winter Weekend
					afternoons",
       "name": "Winter
					Off Peak - Minute"
     }
   ],

					  "success": true
 }

GET time_filter/{time_filterUid}

Returns a time_filter with the specified uid.	Resource Information
	Rate Limited?	Yes
	session, oauth and org tokens compatible?	Yes
	api_key token compatible?	Yes

Resource URL

http://grovestreams.com/api/time_filter/{time_filterUid}

Parameters

none

Example Requests

/time_filter/9e1a980b-f994-4704-8f78-ccc1849cd3a3

Response Body


					
{
   "message": "",
   "time_filter":
					{
     "cycle_range": [

					      {

					        "uid":
					"9e1a980b-f994-4704-8f78-ccc1849cd3a3",

					        "startDate":
					"1999-12-01T00:00:00",

					        "name": "",

					        "endDate":
					"2000-04-01T00:00:00"
       }

					    ],
     "uid":
					"4ab5fb49-e287-4dec-9440-ba670e2df632",
    
					"description": "Winter Weekend afternoons",

					    "name": "Winter On Peak - Hourly",

					    "intervalSize": 3600,
    
					"timeOfDay": {
       "wednesday": [

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false

					      ],

					      "thursday": [

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false

					      ],

					      "monday": [

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false

					      ],

					      "sunday": [

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        true,

					        true,

					        true,

					        true,

					        true,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false

					      ],

					      "saturday": [

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        true,

					        true,

					        true,

					        true,

					        true,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false

					      ],

					      "friday": [

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false

					      ],

					      "tuesday": [

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false

					      ]
     },

					    "timeZoneId": ""
   },
  
					"success": true
 }

GET time_filter/new

Returns a default time_filter with a unique UID. Does not persist the new time_filter in the store. It's the callers responsibility to PUT the new time_filter and register it.	Resource Information
	Rate Limited?	Yes
	session, oauth and org tokens compatible?	Yes
	api_key token compatible	Yes

Resource URL

http://grovestreams.com/api/time_filter/new

Parameters

none

Example Requests

/time_filter/new

Response Body


					
{
   "message": "",
   "time_filter":
					{
     "cycle_range": [

					      
     ],

					    "uid": "005cda96-7cab-4683-8c67-b1556fdd5ae1",

					    "description": "",
    
					"name": "",
     "intervalSize": 3600,

					    "timeOfDay": {

					      "wednesday": [

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false

					      ],

					      "thursday": [

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false

					      ],

					      "monday": [

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false

					      ],

					      "sunday": [

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false

					      ],

					      "saturday": [

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false

					      ],

					      "friday": [

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false

					      ],

					      "tuesday": [

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false,

					        false

					      ]
     },

					    "timeZoneId": ""
   },
  
					"success": true
 }

PUT time_filter

Inserts a new time_filter. The uid of the time_filter can be blank. If it is blank a uid will be created on the server and the response body will contain the new uid.	Resource Information
	Rate Limited?	Yes
	session, oauth and org tokens compatible?	Yes
	api_key token compatible	Yes

Resource URL

http://grovestreams.com/api/time_filter

Parameters

parentFolderUid

optional

The UID of the tools content repository folder to place this new time_filter into. The new time_filter will be placed into the root folder if this parameter is missing.

Example Requests

/time_filter

Insert an time_filter that only includes intervals that occur on Saturdays (US Central time zone).
The blank timeOfDay indicates to apply TOD array to all days.
intervalSize is the size of each TOD array item in seconds. Although a TOD of one second items is allowed via the sdk it is highly discouraged
as it will impact performance.

Request Body


					{
   "time_filter": {
     "uid":
					"",
     "name": "Saturdays Only - Central
					Time Zone",
     "description": "Only include
					intervals that occur on Saturdays - Central time zone",

					    "cycle_range": [

					      
     ],

					    "intervalSize": 86400,
    
					"timeZoneId": "US/Central",
     "timeOfDay":
					{
       "sunday": [

					        false

					      ],

					      "monday": [

					        false

					      ],

					      "tuesday": [

					        false

					      ],

					      "wednesday": [

					        false

					      ],

					      "thursday": [

					        false

					      ],

					      "friday": [

					        false

					      ],

					      "saturday": [

					        true

					      ]
     }

					  }
 }

POST time_filter

Used to update an existing time_filter.	Resource Information
	Rate Limited?
	session, oauth and org tokens compatible?	Yes
	api_key token compatible	Yes

Resource URL

http://grovestreams.com/api/time_filter

Parameters

none

Example Requests

/time_filter

Request Body


					
{
   "time_filter": {
    
					"uid": "",
     "name": "Saturdays Only -
					Central Time Zone",
     "description": "Only
					include intervals that occur on Saturdays - Central time zone",

					    "cycle_range": [
     
					 
     ],
    
					"intervalSize": 86400,
     "timeZoneId":
					"US/Central",
     "timeOfDay": {

					      "sunday": [

					        false

					      ],

					      "monday": [

					        false

					      ],

					      "tuesday": [

					        false

					      ],

					      "wednesday": [

					        false

					      ],

					      "thursday": [

					        false

					      ],

					      "friday": [

					        false

					      ],

					      "saturday": [

					        true

					      ]
     }

					  }
 }

DELETE time_filter/{time_filterUid}

Deletes a time_filter. Any streams that are referencing this time_filter will no longer reference a time_filter.	Resource Information
	Rate Limited?	Yes
	session, oauth and org tokens compatible?	Yes
	api_key token compatible	Yes

Resource URL

http://grovestreams.com/api/time_filter/{time_filterUid}

Parameters

none

Example Requests

/time_filter/d251a8f2-f7b9-4df7-886d-b24c7f4929d4

Response Body


					
{
     "message" : "Deleted time_filter
					with uid 'd251a8f2-f7b9-4df7-886d-b24c7f4929d4'",

					    "success" : true
 }