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.<\/p>\n
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.<\/p>\n
North America:<\/strong> http:\/\/fyi.uat.ecdapi.net<\/p>\n
Europe:<\/strong> http:\/\/rbmdemo.ecdapi.net<\/p><\/blockquote>\n
API DATA<\/h3>\n
\n
- Rich program metadata for linear and non-linear video content as well as person \/ actor information, ratings, awards\u2026<\/li>\n
- Links to images, video on demand (VoD) \/ catch-up TV catalogues, Movie Trailers, 3rd party sites.<\/li>\n<\/ul>\n
API FUNCTIONS<\/h3>\n
\n
- Comprehensive EPG tool set allowing complex filtering, sorting and grouping by any attribute(s) [Pagination].<\/li>\n
- Configurable weighted Search and search phrase completion [Faceted search].<\/li>\n
- Personalized functions for managing user data such as favorite channels, reminders, playlists and more.<\/li>\n
- Optional: Push notifications to mobile devices.<\/li>\n
- Optional: Advanced recommendation (similarity, preference, collaborative, statistical, social and editorial engines).<\/li>\n<\/ul>\n
GETTING STARTED<\/h3>\n
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.).<\/p>\n
The API is document based and currently supports the following document types:<\/p>\n
\n
source:<\/code><\/strong> information about channels and or VoD \/ catch-up sources.<\/li>\ncontentInstance:<\/code><\/strong> hierarchical information about the program data:\n\n
series:<\/code> information about series (grouping seasons and programs).<\/li>\nseason:<\/code> information about seasons (grouping programs).<\/li>\nprogram:<\/code> information about programs independent of airing.<\/li>\nevent:<\/code> information about one airing of a programme (or one availability period for non-linear content).<\/li>\n<\/ul>\n<\/li>\ncontributor:<\/code><\/strong> information about people, for instance actors, presenters or directors.<\/li>\nannotations:<\/code><\/strong> templates for which document attributes filter and search requests shall return to a client.<\/li>\nentitlements:<\/code><\/strong> templates with additional filtering criteria defining which content can be retrieved.<\/li>\n<\/ul>\nMAKING YOUR FIRST REQUEST<\/h3>\n
Most requests to the API are built up as follows:<\/p>\n
http(s):\/\/<api-url>\/<store>\/<document-type>\/<function>?<parameter(s)>\n<\/code><\/pre>\nExample: search for \u201chouse\u201d in all event documents on the API sandbox instance ( here being ** “sandbox.ecdapi.net”**):<\/p>\n
GET http:\/\/sandbox.ecdapi.net\/stores-active\/contentInstance\/event\/search?query=house\n<\/code><\/pre>\nYou should also attach a Content-Type header and any authentication required by the instance you are working with.<\/p>\n
Content-Type: application\/json\n<\/code><\/pre>\nAPI keys should be attached either as request parameters in the URL:\u00a0
?api_key={xxyyzz}<\/code><\/p>\nUseful headers that you may want to attach are:<\/p>\n
\n
Accept-encoding: gzip:<\/code> API to return a compressed HTTP response<\/li>\ncontent-encoding:gzip<\/code> API will use this to compress the media-type.<\/li>\nAccess-Control-Allow-Origin:<\/code> for dealing with cross site scripting issues.<\/li>\n<\/ul>\nThe API will also return useful caching headers:
Expires: Tue, 08 Feb 2019 09:44:05 GMT<\/code><\/p>\nA selection of requests to support common use cases can be found\u00a0here<\/a>.<\/p>\n
THE API FUNCTIONS<\/h3>\n
\n
filter:<\/code> strict filters for selecting a subsection of the documents, for instance \u201call events for channel X of genre Y\u201d.<\/li>\nsearch:<\/code> documents are scored based on how well they match the search criteria, for instance search for (part of) a title.<\/li>\nsearch_phrase:<\/code> search for terms completing the query and return in which fields they were found, for instance suggest completions for \u201cfish\u201d.<\/li>\nattribute:<\/code> faceted search, for instance count the number of countries in the document set.<\/li>\n<\/ul>\nCONSTRUCTING A FILTER<\/h3>\n
A filter is constructed as follows:<\/p>\n
{\n \"term\": string,\n \"operator\": enum,\n \"value\": string\n}\n<\/code><\/pre>\n\n
term<\/code> defines the document attribute in dot notation<\/li>\noperator<\/code> is one of \u201cequals<\/code>\u201d, \u201cnotEquals<\/code>\u201d, \u201catMost<\/code>\u201d, \u201catLeast<\/code>\u201d, \u201csmaller<\/code>\u201d, \u201clarger<\/code>\u201d, \u201cexists<\/code>\u201d or \u201cnotExists<\/code>\u201d, the default value is \u201cequals<\/code>\u201d<\/li>\nvalue<\/code> the value of the document attribute<\/li>\n<\/ul>\nExample: Get all events of a series by ID<\/p>\n
GET http:\/\/<api-url>\/stores-active\/contentInstance\/event\/filter?filter={\"term\":\"internalIds.seriesId\",\"value\":\"105739158\"}\n<\/code><\/pre>\nThere is a special case for the operator \u201c
in<\/code>\u201d where the filter expects a list of\u201cvalues\u201d:[string]<\/code> that the attribute specified by term has to match.<\/p>\nExample: Get events on channels ITV2 and ITV3<\/p>\n
GET http:\/\/<api-url>\/stores-active\/contentInstance\/event\/filter?filter={\"term\":\"source\",\"operator\":\"in\",\"values\":[\"ITV2\",\"ITV3\"]}\n<\/code><\/pre>\nYou can combine filters using operator \u201c
and<\/code>\u201d, \u201cor<\/code>\u201d or \u201cnestedAnd<\/code>\u201d:<\/p>\n{\n \"operator\": enum ,\n \"criteria\": [@genericFilter]\n}\n<\/code><\/pre>\nExample: Get events that have keyword of value talkshow<\/p>\n
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\"}]}\n<\/code><\/pre>\n
For more information, visit our Filters<\/a> page<\/code><\/h3>\nSEARCH<\/h3>\n
ECDAPI\u2019s 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.<\/p>\n
Simple Search for a keyword<\/h4>\n
Example: Search all searchable text fields for \u201cdevon\u201d in all event documents<\/p>\n
GET http:\/\/<api-url>\/stores-active\/contentInstance\/event\/search?query=devon\n<\/code><\/pre>\nLimiting search to certain fields<\/h3>\n
Example: Search for \u201cterminator\u201d in searchableTitles in all event documents<\/p>\n
GET http:\/\/<api-url>\/stores-active\/contentInstance\/event\/search?query=terminator&attributes=[\"searchableTitles.*\"]\n<\/code><\/pre>\nSearch for contributors<\/h4>\n
Example: search for “spacey” in the contributor documents<\/p>\n
GET http:\/\/<api-url>\/stores-active\/contributor\/search?query=spacey\n<\/code><\/pre>\nCOMBINING SEARCH AND FILTERING<\/h3>\n
Search and filtering can be combined in order to limit the scope of the search to a subset of the available program data:<\/p>\n
Example: search for \u201cgirls\u201d in VoD events only<\/p>\n
GET http:\/\/<api-url>\/stores-active\/contentInstance\/event\/search?query=girls&filter={\"term\":\"eventType\",\"value\":\"vod\"}\n<\/code><\/pre>\nSEARCH PHRASE COMPLETION<\/h3>\n
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.<\/p>\n
Example: get search phrase suggestions for all supported fields for \u201cgir\u201d<\/p>\n
GET http:\/\/<api-url>\/stores-active\/contentInstance\/event\/search-phrase\/gir\n<\/code><\/pre>\nLimiting search phrase completion to certain fields<\/h4>\n
Example: Search for \u201cgir\u201d in searchableTitles and searchableTextItems in all event documents<\/p>\n
GET http:\/\/<api-url>\/stores-active\/contentInstance\/event\/search-phrase\/gir?attributes=[\"searchableTitles.*\",\"searchableTextItems.*\"]\n<\/code><\/pre>\n","protected":false},"excerpt":{"rendered":"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 […]<\/p>\n","protected":false},"author":1,"featured_media":0,"parent":279,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"footnotes":""},"class_list":["post-28","page","type-page","status-publish","hentry"],"_links":{"self":[{"href":"https:\/\/apihelp.ecd-demo.com\/index.php\/wp-json\/wp\/v2\/pages\/28","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/apihelp.ecd-demo.com\/index.php\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/apihelp.ecd-demo.com\/index.php\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/apihelp.ecd-demo.com\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/apihelp.ecd-demo.com\/index.php\/wp-json\/wp\/v2\/comments?post=28"}],"version-history":[{"count":2,"href":"https:\/\/apihelp.ecd-demo.com\/index.php\/wp-json\/wp\/v2\/pages\/28\/revisions"}],"predecessor-version":[{"id":1484,"href":"https:\/\/apihelp.ecd-demo.com\/index.php\/wp-json\/wp\/v2\/pages\/28\/revisions\/1484"}],"up":[{"embeddable":true,"href":"https:\/\/apihelp.ecd-demo.com\/index.php\/wp-json\/wp\/v2\/pages\/279"}],"wp:attachment":[{"href":"https:\/\/apihelp.ecd-demo.com\/index.php\/wp-json\/wp\/v2\/media?parent=28"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}