Filters

Besides Search, this is the main functionality of ECDAPI. It returns metadata of the documents matching the filter criteria. The candidate documents are those in the given store or in all active stores of the given store type / hierarchy level.
Please note that for performance reasons there is a hard-coded internal limit of 10000 results (including pagination). Huge result sets shall be retrieved by splitting them into subsets via filtering (e.g. by source or by time).

CONSTRUCTING A FILTER

A filter is constructed as follows: 
{
    "term": string,
    "operator": enum,
    "value": string
}
  • term defines the document attribute in dot notation
  • operator is one of “equals”, “notEquals”, “atMost”, “atLeast”, “smaller”, “larger”, “exists” or “notExists”, the default value is “equals”
  • value the value of the document attribute
Example: Get all events of a series by ID 
GET http://<api-url>/stores-active/contentInstance/event/filter?filter={"term":"internalIds.seriesId","value":"105739158"}
There is a special case for the operator “in” where the filter expects a list of “values”:[string] that the attribute specified by term has to match. Example: Get events on channels ITV2 and ITV3 
GET http://<api-url>/stores-active/contentInstance/event/filter?filter={"term":"source","operator":"in","values":["ITV2","ITV3"]}
You can combine filters using operator “and”, “or” or “nestedAnd”: 
{
    "operator": enum ,
    "criteria": [@genericFilter]
}
Example: Get events that have keyword of value talkshow 
GET http://<api-url>/stores-active/contentInstance/event/filter?filter={"operator":"nestedAnd","criteria":[{"term":"tags.category.categoryId","value":"Keyword"},{"term":"tags.value.valueId","value":"talkshow"}]}

WINDOW OF AVAILABILTY FILTERING

A special type of often used filtering is by scheduledStart- and End- DateTime Absolute windows can be defined by providing timestamps for the start and end of the window:
"windowOfAvailabilityStart": timestamp
"windowOfAvailabilityEnd": timestamp Example: Get events broadcast between 5AM UTC on June 21st and 5AM on June 22nd on channels ITV 2 and ITV3 
GET http://<api-url>/stores-active/contentInstance/event/filter?filter={"term":"source","operator":"in", "values":["ITV2","ITV3"]}&windowOfAvailabilityStart=2016-06-21T05:00:00Z&windowOfAvailabilityEnd=2016-06-22T05:00:00Z
Relative windows can be defined by providing a relative time and an offset for the start and the end of the window where origin is either “currentTime” or “startOfDay” and “offset” a duration in XSD duration format. A “timeZone”: timezone, can optionally be provided to interpret relative window of availability origins. Example: Search for “unscrupulous” on events scheduled for the next 24 hours 
GET http://<api-url>/stores-active/contentInstance/event/search?query=unscrupulous&relativeWindowOfAvailabilityStart={"origin":"currentTime","offset":"PT0H"}&relativeWindowOfAvailabilityEnd={"origin":"currentTime","offset":"PT0H"}
Windows can have different types defining the interpretation of the windows of availability windowOfAvailabilityType: enum: overlap: any overlap between the asset’s availability and the specified window of availability will be allowed
strictStart: the start of the asset has to lie within the specified window of availability
strictEnd: the end of the asset has to lie within the specified window of availability
strict: both the start and end of the asset have to lie within the specified window The default value is “overlap”.

NOW AND NEXT INFORMATION

Another special case of filtering is the “now and next” type request. A special keyword beforeAfter allows to return a number of documents available around the origin time.
  • origin may be an absolute timestamp or “currentTime”.
  • offset points to the first document to be returned,
  • limit defines the number of documents returned per source (typically per TV channel)
Example: The following request retrieves now (origin:currentTime, offset:0) & next (limit:2) information for all available channels: 
GET http://<api-url>/stores-active/contentInstance/event/filter?beforeAfter={"origin":"currentTime","offset":0,"limit":2}

Advanced Details

Context merging rules
If a contextId is provided together with an ad-hoc context, the two are merged according to the following rules:

  • the two contexts are merged at top level attribute level
  • if the ad-hoc and the pre-defined contexts both contain the same top-level attribute, the one in the ad-hoc context is kept
  • no merging at lower levels of the context object, in particular no merging of list attributes