Getting Started

SCOPE

Simply.TV Content Discovery API (CDAPI) is designed in the REST (Representational State Transfer) architectural style, using HTTP as the underlying protocol. Metadata are presented in the form of JSON documents. Documents are organized into stores by Tenant, Store Type (e.g. content, contributors, sources), Hierarchy Level, and Store ID.

For the purpose of this website and the examples presented on this site, the ECDAPI instance we are working off of here will be those below, depending on the region. The instance (tenant) that you’ll be using in production environment will be different.

North America: http://fyi.uat.ecdapi.net

Europe: http://rbmdemo.ecdapi.net

API DATA

  • Rich program metadata for linear and non-linear video content as well as person / actor information, ratings, awards…
  • Links to images, video on demand (VoD) / catch-up TV catalogues, Movie Trailers, 3rd party sites.

API FUNCTIONS

  • Comprehensive EPG tool set allowing complex filtering, sorting and grouping by any attribute(s) [Pagination].
  • Configurable weighted Search and search phrase completion [Faceted search].
  • Personalized functions for managing user data such as favorite channels, reminders, playlists and more.
  • Optional: Push notifications to mobile devices.
  • Optional: Advanced recommendation (similarity, preference, collaborative, statistical, social and editorial engines).

GETTING STARTED

ECDAPI is restful and uses standard internet technologies such as HTTP(S), and JSON to allow access from web applications and/or from any internet-connected device (set-top boxes, smart TVs, tablets, smartphones, wearables etc.).

The API is document based and currently supports the following document types:

  • source: information about channels and or VoD / catch-up sources.
  • contentInstance: hierarchical information about the program data:
    • series: information about series (grouping seasons and programs).
    • season: information about seasons (grouping programs).
    • program: information about programs independent of airing.
    • event: information about one airing of a programme (or one availability period for non-linear content).
  • contributor: information about people, for instance actors, presenters or directors.
  • annotations: templates for which document attributes filter and search requests shall return to a client.
  • entitlements: templates with additional filtering criteria defining which content can be retrieved.

MAKING YOUR FIRST REQUEST

Most requests to the API are built up as follows:

http(s)://<api-url>/<store>/<document-type>/<function>?<parameter(s)>

Example: search for “house” in all event documents on the API sandbox instance ( here being ** “sandbox.ecdapi.net”**):

GET http://sandbox.ecdapi.net/stores-active/contentInstance/event/search?query=house

You should also attach a Content-Type header and any authentication required by the instance you are working with.

Content-Type: application/json

API keys should be attached either as request parameters in the URL: ?api_key={xxyyzz}

Useful headers that you may want to attach are:

  • Accept-encoding: gzip: API to return a compressed HTTP response
  • content-encoding:gzip API will use this to compress the media-type.
  • Access-Control-Allow-Origin: for dealing with cross site scripting issues.

The API will also return useful caching headers: Expires: Tue, 08 Feb 2019 09:44:05 GMT

A selection of requests to support common use cases can be found here.

THE API FUNCTIONS

  • filter: strict filters for selecting a subsection of the documents, for instance “all events for channel X of genre Y”.
  • search: documents are scored based on how well they match the search criteria, for instance search for (part of) a title.
  • search_phrase: search for terms completing the query and return in which fields they were found, for instance suggest completions for “fish”.
  • attribute: faceted search, for instance count the number of countries in the document set.

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"}]}

For more information, visit our Filters page

SEARCH

ECDAPI’s search feature offers intelligent free text search capabilities among the documents in the stores. Results are scored by relevance. In addition to simple search (single word or phrase used as query), structured search based on Lucene syntax is supported.

Simple Search for a keyword

Example: Search all searchable text fields for “devon” in all event documents

GET http://<api-url>/stores-active/contentInstance/event/search?query=devon

Limiting search to certain fields

Example: Search for “terminator” in searchableTitles in all event documents

GET http://<api-url>/stores-active/contentInstance/event/search?query=terminator&attributes=["searchableTitles.*"]

Search for contributors

Example: search for “spacey” in the contributor documents

GET http://<api-url>/stores-active/contributor/search?query=spacey

COMBINING SEARCH AND FILTERING

Search and filtering can be combined in order to limit the scope of the search to a subset of the available program data:

Example: search for “girls” in VoD events only

GET http://<api-url>/stores-active/contentInstance/event/search?query=girls&filter={"term":"eventType","value":"vod"}

SEARCH PHRASE COMPLETION

Retrieves search phrase options matching a partial query. Returns the complete string along with the name of the attribute where it was found. This is typically presented while the query is being typed providing an autocomplete feature.

Example: get search phrase suggestions for all supported fields for “gir”

GET http://<api-url>/stores-active/contentInstance/event/search-phrase/gir

Limiting search phrase completion to certain fields

Example: Search for “gir” in searchableTitles and searchableTextItems in all event documents

GET http://<api-url>/stores-active/contentInstance/event/search-phrase/gir?attributes=["searchableTitles.*","searchableTextItems.*"]