openapi: 3.0.3 info: title: Metadata version: "3.11" description: | ## An Introduction to the Metadata Model To watch live TV, or on-demand video, you must first be able to find some content to view. The metadata APIs described below allow you to browse for content, and to access the content via a number of different routes, such as catalogue browsing, through a series / season or by direct search. It also gives you all the information you need to determine whether you're allowed to watch content, and how to play it when you are. --- ## Where to Start There are three main paths you are likely to take when exploring content, and each has a key route through. Let's discuss each case: ### Video On Demand The entrypoint for VoD is usually via the catalogue tree (**Node**). A catalogue is an organised tree of nodes, where each node has some broad theme. Think of a folder / sub-folder structure. An example catalogue tree is shown below: + *Root* + *New Releases* + *Popular* + *Action* + *Horror* + *Drama* + *Kids* + *Preschool* + *Superheroes* + *Young Adult* To read the catalogue structure please see ```/vod/nodes```. Once you have identified the catalogue node(s) that you would like to read, you can see the content of that node through the ```/vod/editorals``` API. Each **Editorial** returned contains an aggregate view of watchable content, describing it at a broad level, a list of all products required to purchase it and all the technical information required to watch it once bought. Each **Editorial** may have references to further enrich the content when required. You can access this additional information through further API calls: * **Series**/**Season** - see ```/vod/series``` * **Promotions** - see ```/vod/promotions``` * **Products** - see ```/vod/products``` ### Broadcast Television BTV begins with **Services** (or **Channels**). First lookup the channels that are available for you to watch using the ```/btv/services``` call. Once you have established the services that you are able to watch, go on to query ```/btv/programmes``` to see what is available to watch on one or more channels. By limiting your query to a slice of time, you will be able to construct an EPG view of the data. There may be further information referenced by the **Programme** or **Service** that is available through subsequent API calls: * **Series**/**Season** - see ```/btv/series``` * **Products** - see ```/btv/products``` ### Search Search allows you to find content in any of the previously discussed areas, through a free-text search. To make search requests please see the ```/search``` API. The response to the search API is minimal. It is intended to give you enough information to display to the user but you are expected to make subsequent API calls to the core APIs to fully expand on any interesting results. --- ## Philosophy The metadata API is highly consumer driven. A lot of control is given to clients, and although certain limitations are put in place to guide developers down the correct path it is expected that client developers act responsibly. ### Control The API allows you to filter, project and sort on any field in the object model (with few limitations). * **filter**(s) are written using a mongo-like syntax - see [query](https://docs.mongodb.com/manual/reference/operator/query/). Usually this means simply providing a query-object that gives a prototype to match against, although more comprehensive range and logical operations are also possible. Particularly impactful or risky operations ($where, $regex) are banned. * **sort** can be performed against any field. * **fields** can select any field for a limited response, although certain fields will always be returned (ids for example). ### Responsibilities Please contact your service team about the following: * **whitelisting** - in a production environment, your queries will be whitelisted to prevent damaging executions. * **indexes** - in a production environment, indexes must be configured to back your queries. --- ## Key Concepts There are many different concepts mentioned within the API. The core aspects of the model are listed in the table below, and should act as a reference | **Term** | **Description** | | -------------------------------- | -------------------------------- | | **BTV** | **B**roadcast **T**ele**V**ision. This is traditional live TV. See ```/btv/*```. | | **Channel** | See **Service**. | | **Deep Link** | A **Deep Link** is a reference from some content to the same content in an external, third-party, system. For example the same movie present in Netflix, Disney+ or Apple TV. | | **Device Type** | The type of device on which content may be played (e.g. IOS, Android). Generally exists on **Technical Content** or **Technical Service** | | **DVB** | An identifier for Digital Video Broadcast (cable) TV | | **EPG** | Electronic Programme Guide. The big grid on your TV when you are channel hopping. | | **Editorial Content** | The non-technical part of the content (Title, Actors, Directors, etc). The part a end-user will likely care most about. | | **Editorial Service** | The non-technical part of the service (Channel Name, Channel Number, etc). The part a end-user will likely care most about. | | **Event** | See **Programme**. | | **LTCU** | Long Term CatchUp. Handled as a special type of VoD, this is content that was previously on TV but is now able to be watched on-demand. See ```/vod/editorials```. | | **Node** | A catalog node, for example 'New Releases' or 'Family Favourites'. Holds related content, or other nodes, for structured browsing. See ```/vod/nodes``` | | **PPV** | Pay-Per-View. Access to watch a live event on a one-off occasion (e.g. Boxing Match or the Superbowl) | | **Product** | The item an end-user purchases to gain access to content or a service. There are multiple types of product, such as **Transactional** (one-off purchase), **Subscription** a recurring purchase, **PPV** access to a channel for a specific **Programm**. See ```/btv/products``` and ```/vod/products``` | | **Programme** | A live TV programme. It is shown on a specific **Service** at a certain time. See ```/btv/programmes```. | | **Promotion** | Or trailer. A short video advertising the content. | | | **REPG** | Reverse EPG. The ability to go back in time and watch content that was on an hour ago. Related to **Start Over** | | **Root Node** | A catalog node that has no parent. Generally a client will start here and dig down. | | **STCU** | Short Term CatchUp. This is a property of a technical associated with a programme. The technical will have information on whether the programme is able to be played as STCU and how to achieve that. | | **Season** | A sub-division of a series - e.g. Game of Thrones Season 2. A series will have many seasons. | | **Series** | A collection of content - e.g. Game of Thrones. A series can have many seasons. | | **Service** | A TV channel. See ```/btv/services```. | | **Start Over** | Some TV channels will allow you to restart a programme that has already begun. | | **Subscription** | A product, that costs an amount on a recurring basis (e.g. monthly) and provides access to TV channels, VoD or both. | | **SVoD (Subscription VoD)** | A sub-category of subscription product. A product, that costs an amount on a recurring basis (e.g. monthly) and provides access to many VoD assets. | | **TVoD (Transactional Product)** | A one off purchase of VoD content. Could be a time-limited rental, or a purchase | | **Technical Content** | The technical part of the content (Playback URI, Device Type, etc). Usually hidden from the end-user, describes to the device if it is allowed to play content and where to get it. | | **Technical Service** | The technical part of the service (Playback URI, Device Type, etc). Usually hidden from the end-user, describes to the device if it is allowed to play the service and where to stream it. | | **Trailer** | See **Promotion**. | | **VoD** | **V**ideo **O**n **D**emand. This is video that can be played at the user's request. See ```/vod/*```. | servers: - url: /metadata security: - bearerAuth: [] tags: - name: BTV - name: Core - name: Internal - name: VoD paths: /btv/blackout_programmes: get: summary: Get banned programmes description: | Returns a list of programmes a client is restricted from viewing based on configured rules. The rules apply to the client with the following criteria: 1. Event must be marked with the property "serverGlobalBlackoutControl": "1". 2. Rule must match the customer type (ftth, ott) found in the JWT token, as part of the filteringInformation.filter-string section. 3. Rule must match the device type in the JWT token, represented by the deviceProfileId property. 4. Rule must match the network type (e.g. 3G, 4G, WiFi). This is passed in as a query parameter. ## Examples: ### Find blacked out programmes for the next 24 hours ```/btv/blackout_programmes?connection_type=4G``` ### Find blacked out programmes for the specified time period ```/btv/blackout_programmes?connection_type=4G&start=1722423600&end=1722510000``` It's worth noting that the query, for a time period ```t1 -> t2```, takes the form ```end >= t1 && start <= t2```. This is to avoid discounting programmes that have started, but not yet finished, at either end of the time period. ### Page through blacked out programmes ```/btv/blackout_programmes?connection_type=4G&limit=100&page=3``` ### Find blackout rules for specific programme Rather than requesting a time period, you can request blackout rules for a specific programme. If no blackout rules are found for this event, the response will be empty. ```/btv/blackout_programmes?connection_type=4G&id=GLOBAL_14771_20210509103000``` tags: - BTV parameters: - in: query name: connection_type schema: type: string example: 4G required: true description: The type of network connection the client is using. - in: query name: start schema: type: integer format: int64 required: false description: The start time of the query period, in epoch time. If not provided, the current time is used. - in: query name: end schema: type: integer format: int64 required: false - in: query name: id schema: type: string required: false description: The id of the programme to check for blackouts. - in: query name: page schema: type: integer format: int32 required: false description: The page of results to retrieve. - in: query name: limit schema: type: integer format: int32 required: false description: The page size. - in: query name: cache schema: type: boolean required: false description: True to allow caching on CDN, false to prevent CDN caching. This just sets or unsets the relevant response headers. - in: query name: locale schema: type: string example: en_US description: The locale to use for the response. This is used to determine the language of the response. responses: 200: description: Successful response content: application/json: schema: oneOf: - $ref: '#/components/schemas/BlackoutProgrammesResponse' - $ref: '#/components/schemas/Error' headers: Cache-Control: schema: type: string description: Cache control header 400: description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' /btv/products: get: summary: Get Btv Products description: | Products are usually accessed through the `/btv/services` API. However, if you require direct access to a product, without all the content related to it, this API can provide that information. ## Examples: ### Find product by id A simple lookup by id: ``` /btv/products?filter={ "id": "GLOBAL_gold_product" } ``` tags: - BTV parameters: - in: query name: filter schema: type: string example: '{ "id": "GLOBAL_gold_product" }' required: false description: A key/value pairing list. Where key is a field name, and value is the value the field should be. - in: query name: sort schema: type: string example: '[["Title", 1]]' required: false description: A list of tuples of field name and sort order. A sort order of 1 is ascending, and a sort order of -1 is descending. - in: query name: fields schema: type: string example: '["id", "Title"]' required: false description: A list of fields names to return in the response. - in: query name: page schema: type: integer format: int32 required: false description: The page of results to retrieve. - in: query name: limit schema: type: integer format: int32 required: false description: The page size. - in: query name: cache schema: type: boolean required: false description: True to allow caching on CDN, false to prevent CDN caching. This just sets or unsets the relevant response headers. - in: query name: pretty schema: type: boolean required: false description: True to return human readable formatted JSON. False to return compact and efficient JSON. - in: query name: distinct schema: type: string required: false description: If provided, returns a distinct list of values for the given field. responses: 200: description: Successful response content: application/json: schema: oneOf: - $ref: '#/components/schemas/ProductsResponse' - $ref: '#/components/schemas/DistinctResponse' /btv/programmes: get: summary: Get btv programmes description: | Once you have identified the **Services** that are able to be watched, you can use the ```/btv/programmes``` API to build an EPG view. It is best to query the API in terms of time slices, e.g. all programmes on channels 1-10 between 8am and 10am. If possible, make your time slices coarse grained rather than very fine grained, for example query [08:00.00, 09:00.00] rather than [08:31:45, 09:31:45] as this allows for better caching on all middleware layers, and will improve the performance of your application. All times are in UNIX epoch time. The model is an aggregate of **Programme**, **Editorial Content**, **Technical Contents**, although only the former is mandatory. Editorial content can augment the programme with additional editorial information. Technical content allows support of **STCU** and **Start Over**. ## Examples: ### Find EPG slice of programmes for channels 1-3 Takes a time slice of the EPG across a number of channels. It's worth noting that the query, for a time period ```t1->t2```, takes the form ```end > t1 && start < t2```. This is to avoid discounting programmes that have started, but not yet finished, at either end of the time period. ```/btv/programmes?filter={"serviceRef": {"$in": ["chan1", "chan2", "chan3"], "period.end": { "$gte": 1634198400 }, "period.start": {"$lte": 1634202000} }&sort=[["period.start", 1]]``` ### Find programme by id ```/btv/programmes?filter={"id": "programme1"}``` ### Find programmes belonging to a series The seriesRef lives on the editorial. ```/btv/programmes?filter={"editorial.seriesRef": "series1"}``` ### Find STCU programmes Find programmes flagged as supporting short-term catchup ```/btv/programmes?filter={"isSTCU": true}``` tags: - BTV parameters: - in: query name: filter schema: type: string example: { "editorial.id": "GLOBAL_bbc_one" } required: false description: A key/value pairing list. Where key is a field name, and value is the value the field should be. - in: query name: sort schema: type: string example: [ [ "editorial.tvChannel", 1 ] ] required: false description: A list of tuples of field name and sort order. A sort order of 1 is ascending, and a sort order of -1 is descending. - in: query name: fields schema: type: string items: type: string example: ["editorial.id", "editorial.Title"] required: false description: A list of fields names to return in the response. - in: query name: page schema: type: integer format: int32 required: false description: The page of results to retrieve. - in: query name: limit schema: type: integer format: int32 required: false description: The page size. - in: query name: cache schema: type: boolean required: false description: True to allow caching on CDN, false to prevent CDN caching. This just sets or unsets the relevant response headers. - in: query name: pretty schema: type: boolean required: false description: True to return human readable formatted JSON. False to return compact and efficient JSON. - in: query name: distinct schema: type: string required: false description: If provided, returns a distinct list of values for the given field. - in: query name: group schema: type: string enum: - content required: false description: If provided, groups the vod response by contentLinkId - in: query name: groupLimit schema: type: integer format: int32 required: false description: Restricts the number of programmes returned per group when using the group parameter. - in: query name: restrict_by_age schema: type: boolean default: false required: false description: True to filter request by max-age - in: query name: previewable schema: type: integer format: int32 required: false description: >- Number of promotions (trailers) to include per programme item. Absent or 0 = do not attach promotions. Greater than 0 = attach up to N promotions per programme entry. responses: 200: description: Successful response content: application/json: schema: oneOf: - $ref: '#/components/schemas/ProgrammesResponse' - $ref: '#/components/schemas/DistinctResponse' /v2/vod/editorials: get: summary: Get vod editorials description: | This is the main way to get access to the content available for you to watch on-demand. It presents an aggregate view of watchable content, the list of all products required to purchase it and all the technical information required to watch it once bought. The aggregate object is made up of an **EditorialContent**, multiple **TechnicalContents**, any **Products** selling the content and **DeepLinks** that can reference the content on other media providers. ## Notes on the query model This API has a key difference between the request and response models. The request model should be treated in the singular - so **editorial**, **technical**, **product** or **link**. The response model presents an aggregate view, and so you'll see **technicals**, **products** and **links** included in the response, but rolled up. ## Notes on validity By default, any content or product that has expired will be automatically hidden. If you need to see expired content or products you can do so by use of the following flags: | **Flag** | **Description** | | ---- | ----------- | | **isVisible** | Content is able to be sold and viewed in the catalogue tree. By default true. | | **isValid** | Product is able to be used. By default true. | | **isPurchasable** | Product is able to be bought. No default (both true and false are returned) | | **isEditorialValid** | Editorial content is available to be watched. By default true. Editorials with availability windows are also independently filtered — at least one window must be currently active regardless of this flag. | | **isTechnicalValid** | Technical content specific to a device is available to be watched. By default true. | ## Examples: ### Find content by id Lookup a specific editorial content by its id. ``` /vod/editorials?filter={"editorial.id": "GLOBAL_die_hard"} ``` ### Find content belonging to a specific series / season Lookup a range of content by their series reference. ``` /vod/editorials?filter={"editorial.seriesRef": "GLOBAL_game_of_thrones"} ``` Or by their season reference. ``` /vod/editorials?filter={"editorial.seasonRef": "GLOBAL_game_of_thrones_season_1"} ``` ### Find content within a node Find content that appears within a specific node - for example, all content found in the "New Releases" catalogue. ``` /vod/editorials?filter={"editorial.nodeRefs": "GLOBAL_new_releases"} ``` ### Filter by specific device types Often you'll only want content playable on a specific device, by specifying the deviceType you can filter out any content that you cannot play. ``` /vod/editorials?filter={"deviceType": "Android"} ``` ### Find long term catchup Long term catchup represents BTV content that has been captured and is now available as VoD - think BBC iPlayer. Long term catchup assets will have certain flags that appear within the technical content. ``` /vod/editorials?filter={"technical.isLTCU": true} ``` parameters: - in: query name: filter schema: type: string example: { "editorial.id": "GLOBAL_die_hard" } required: false description: A key/value pairing list. Where key is a field name, and value is the value the field should be. - in: query name: sort schema: type: string example: [ [ "editorial.Title", 1 ] ] required: false description: A list of tuples of field name and sort order. A sort order of 1 is ascending, and a sort order of -1 is descending. - in: query name: fields schema: type: string example: [ "editorial.id", "editorial.Title" ] required: false description: A list of fields names to return in the response. - in: query name: page schema: type: integer format: int32 required: false description: The page of results to retrieve. - in: query name: limit schema: type: integer format: int32 required: false description: The page size. - in: query name: cache schema: type: boolean required: false description: True to allow caching on CDN, false to prevent CDN caching. This just sets or unsets the relevant response headers. - in: query name: distinct schema: type: string required: false description: If provided, returns a distinct list of values for the given field. - in: query name: group schema: type: string enum: - content required: false description: If provided, groups the vod response by contentLinkId - in: query name: groupLimit schema: type: integer format: int32 required: false description: Restricts the number of vod returned per group when using the group parameter. - in: query name: all_ages schema: type: boolean required: false description: True to ignore maxAgeRating, returning content for all ages. - in: query name: show_dcg schema: type: boolean required: false description: True to show plain dynamic content groups (DCG) in the response, false to hide them. - in: query name: previewable schema: type: integer format: int32 required: false description: >- Number of promotions (trailers) to include per series item. Absent or 0 = do not attach promotions. Greater than 0 = attach up to N promotions per series entry. tags: - VoD responses: 200: description: Successful response content: application/json: schema: oneOf: - $ref: '#/components/schemas/VoDEditorialV2Response' - $ref: '#/components/schemas/DistinctResponse' /vod/nodes: get: summary: Get vod catalogue nodes description: | A catalog node, for example 'New Releases' or 'Family Favourites'. Holds related content, or other nodes, for structured browsing. Nodes are hierarchical, similar to a folder structure. Nodes can contain other nodes and/or watchable content. Child nodes are found through this API. For content belonging to a node please see ```/vod/editorials```. ## Examples: ### Find root nodes for the en_GB locale Those nodes found at the top of the hierarchy with no parent. ``` /vod/nodes?filter={"isRoot":true, "locale":"en_GB"} ``` ### Find a specific node by id. ``` /vod/nodes?filter={"id":"GLOBAL_action", "locale":"en_GB"} ``` ### Find child nodes belonging to a specific parent. ``` /vod/nodes?filter={"parent":"GLOBAL_action", "locale":"en_GB"} ``` parameters: - in: query name: filter schema: type: string example: {"parent":"GLOBAL_action", "locale":"en_GB"} required: false description: A key/value pairing list. Where key is a field name, and value is the value the field should be. - in: query name: sort schema: type: string example: [["Title", 1]] required: false description: A list of tuples of field name and sort order. A sort order of 1 is ascending, and a sort order of -1 is descending. - in: query name: fields schema: type: string example: [ "id", "Title" ] required: false description: A list of fields names to return in the response. - in: query name: page schema: type: integer format: int32 required: false description: The page of results to retrieve. - in: query name: limit schema: type: integer format: int32 required: false description: The page size. - in: query name: cache schema: type: boolean required: false description: True to allow caching on CDN, false to prevent CDN caching. This just sets or unsets the relevant response headers. - in: query name: pretty schema: type: boolean required: false description: True to return human readable formatted JSON. False to return compact and efficient JSON. - in: query name: distinct schema: type: string required: false description: If provided, returns a distinct list of values for the given field. tags: - VoD responses: 200: description: Successful response content: application/json: schema: oneOf: - $ref: '#/components/schemas/NodesResponse' - $ref: '#/components/schemas/DistinctResponse' /vod/products: get: summary: Get vod products description: | Products are usually accessed through the ```/vod/editorials``` API. However, if you require direct access to a product, without all the content related to it, this API can provide that information. ## Examples: ### Find product by id A simple lookup by id: ``` /vod/products?filter={ "id": "GLOBAL_gold_product" } ``` tags: - VoD parameters: - in: query name: filter schema: type: string example: { "id": "GLOBAL_gold_product" } required: false description: A key/value pairing list. Where key is a field name, and value is the value the field should be. - in: query name: sort schema: type: string example: [ [ "Title", 1 ] ] required: false description: A list of tuples of field name and sort order. A sort order of 1 is ascending, and a sort order of -1 is descending. - in: query name: fields schema: type: string example: [ "id", "Title" ] required: false description: A list of fields names to return in the response. - in: query name: page schema: type: integer format: int32 required: false description: The page of results to retrieve. - in: query name: limit schema: type: integer format: int32 required: false description: The page size. - in: query name: cache schema: type: boolean required: false description: True to allow caching on CDN, false to prevent CDN caching. This just sets or unsets the relevant response headers. - in: query name: distinct schema: type: string required: false description: If provided, returns a distinct list of values for the given field. responses: 200: description: Successful response content: application/json: schema: oneOf: - $ref: '#/components/schemas/ProductsResponse' - $ref: '#/components/schemas/DistinctResponse' /btv/series: get: summary: Get btv series description: | **Series** and **Seasons** are groups of organized content. This API concerns just the series/season entities, and not the content within them. To find out how to query for content within a series/season, please see ```/btv/editorials```. ## Examples: ### Find series / season by id A simple lookup by id: ``` /btv/series?filter={ "id": "GLOBAL_game_of_thrones" } ``` ### Find seasons belonging to a series ``` /btv/series?filter={ "seriesRef": "GLOBAL_game_of_thrones" } ``` tags: - BTV parameters: - in: query name: filter schema: type: string example: { "id": "GLOBAL_game_of_thrones" } required: false description: A key/value pairing list. Where key is a field name, and value is the value the field should be. - in: query name: sort schema: type: string example: [ [ "Title", 1 ] ] required: false description: A list of tuples of field name and sort order. A sort order of 1 is ascending, and a sort order of -1 is descending. - in: query name: fields schema: type: string example: [ "id", "Title" ] required: false description: A list of fields names to return in the response. - in: query name: page schema: type: integer format: int32 required: false description: The page of results to retrieve. - in: query name: limit schema: type: integer format: int32 required: false description: The page size. - in: query name: cache schema: type: boolean required: false description: True to allow caching on CDN, false to prevent CDN caching. This just sets or unsets the relevant response headers. - in: query name: distinct schema: type: string required: false description: If provided, returns a distinct list of values for the given field. - in: query name: group schema: type: string enum: - content required: false description: If provided, groups the series response by contentLinkId - in: query name: groupLimit schema: type: integer format: int32 required: false description: Restricts the number of series returned per group when using the group parameter. - in: query name: all_ages schema: type: boolean required: false description: True to ignore maxAgeRating, returning content for all ages. - in: query name: previewable schema: type: integer format: int32 required: false description: >- Number of promotions (trailers) to include per series item. Absent or 0 = do not attach promotions. Greater than 0 = attach up to N promotions per series entry. responses: 200: description: Successful response content: application/json: schema: oneOf: - $ref: '#/components/schemas/SeriesResponse' - $ref: '#/components/schemas/DistinctResponse' /btv/services: get: summary: Get btv services description: | Services (or channels) are the entrypoint to the BTV metadata. Here we get a lineup of those channels that we're able to watch. The API is an aggregate view over three types of entities: **Editorial Services**, **Technical Services** and **Products**. The root of the aggregate is the **Technical Service**, and due to this you may see repeat **Editorial Services** in the result - this is by design. ## Examples: ### List services ordered by channel number ascending ``` /btv/services?sort=[["editorial.tvChannel", 1]] ``` ### List services for a specific device ``` /btv/services?filter={"technical.deviceType": "Android"}&sort=[["editorial.tvChannel", 1]] ``` ### Lookup a specific service ``` /btv/services?filter={"editorial.id": "GLOBAL_bbc_one"} ``` ### Look for services sold by a specific product ``` /btv/services?filter={"product.id": "GLOBAL_sports_pack"} ``` parameters: - in: query name: filter schema: type: string example: { "editorial.id": "GLOBAL_bbc_one" } required: false description: A key/value pairing list. Where key is a field name, and value is the value the field should be. - in: query name: sort schema: type: string example: [ [ "editorial.tvChannel", 1 ] ] required: false description: A list of tuples of field name and sort order. A sort order of 1 is ascending, and a sort order of -1 is descending. - in: query name: fields schema: type: string example: [ "editorial.id", "editorial.Title" ] required: false description: A list of fields names to return in the response. - in: query name: page schema: type: integer format: int32 required: false description: The page of results to retrieve. - in: query name: limit schema: type: integer format: int32 required: false description: The page size. - in: query name: cache schema: type: boolean required: false description: True to allow caching on CDN, false to prevent CDN caching. This just sets or unsets the relevant response headers. - in: query name: distinct schema: type: string required: false description: If provided, returns a distinct list of values for the given field. - in: query name: all_ages schema: type: boolean required: false description: True to ignore maxAgeRating, returning content for all ages. - in: query name: previewable schema: type: integer format: int32 required: false description: >- Number of promotions (trailers) to include per service item. Absent or 0 = do not attach promotions. Greater than 0 = attach up to N promotions per service entry. tags: - BTV responses: 200: description: Successful response content: application/json: schema: oneOf: - $ref: '#/components/schemas/ServicesResponse' - $ref: '#/components/schemas/DistinctResponse' /delivery/changes: get: summary: Get changes from journal description: | Returns changes to programmes, vod or channels, since a certain time. Changes are returned in chronological order, and will available for pagination. ## Examples: ## Get all recorded changes for available records ``` /metadata/delivery/changes?locale=en_GB ``` A basic response would looking something like the following, where "change" is a copy of the record that has been updated. ``` { "changes": [{ "id": "GLOBAL_p1", "action": "reschedule", "type": "programme", "change": { "id": "GLOBAL_p1", "serviceRef": "GLOBAL_sky_one", "period": { "start": 1454284800.0, "end": 2147483707.0, "duration": 693198907 }, "Title": "Game of Thrones" } }], "total_records": 1 } ``` ## Get all recorded changes since a certain time ``` /metadata/delivery/changes?locale=en_GB&since=1643912152 ``` ## Get changes for just programmes ``` /metadata/delivery/changes?locale=en_GB&since=1643912152&type=programme ``` ## Get page 3 of changes size 100 (201-300) ``` /metadata/delivery/changes?locale=en_GB&since=1643912152&page=3&limit=100 ``` ## Get EPG changes by channel. Groups programme changes into a single channel change, and provides the time period for the EPG that changed. ``` /metadata/delivery/changes?locale=en_GB&since=1643912152&type=channel ``` In the case of channel updates, the body does not contain the programme information, but instead the channel reference and a start/end time period. You can use this information to retrieve an EPG update using the ```/epg``` or ```/btv/programmes`` APIs. For example: ``` { "changes": [{ "id": "Sky One", "action": "reschedule", "type": "channel", "start": 1675209600, "end": 1675216800 }, { "id": "Sky Two", "action": "reschedule", "type": "channel", "start": 1675213200, "end": 1675216800 }], "total_records": 2 } ``` tags: - Core parameters: - in: query name: since schema: type: integer format: int64 required: true description: The timestamp to get changes since. - in: query name: type schema: type: string enum: - programme - vod - channel required: false description: Available values - programme, vod, channel. - in: query name: fields schema: type: string example: [ "id", "Title" ] required: false description: A list of fields names to return in the response. - in: query name: page schema: type: integer format: int32 required: false description: The page of results to retrieve. - in: query name: limit schema: type: integer format: int32 required: false description: The page size. - in: query name: locale schema: type: string required: false description: The locale in which to retrieve the metadata responses: 200: description: Successful response content: application/json: schema: $ref: '#/components/schemas/ChangesResponse' /v1/products: get: summary: Get Products description: | Products are usually accessed through the `/btv/services` API. However, if you require direct access to a product, without all the content related to it, this API can provide that information. ## Examples: ### Find product by id A simple lookup by id: ``` /metadata/v1/products?id=GLOBAL_gold_product ``` ### Find product by type A simple lookup by type: ``` /metadata/v1/products?type=pack ``` ### Find products that are part of a certain product group ``` /metadata/v1/products?pack_collection=GLOBAL_sports_pack ``` tags: - Core parameters: - in: query name: id schema: type: array items: type: string required: false description: If provided, returns the product with the matching id. example: GLOBAL_gold_product - in: query name: type schema: type: string required: false description: If provided, returns products with the matching type. example: subscription - in: query name: pack_collection schema: type: string required: false description: If provided, returns products that are part of a pack collection example: GLOBAL_sports_pack - in: query name: member_of_pack schema: type: string required: false description: If provided, returns products that are a member of the given pack product example: GLOBAL_pack1 - in: query name: sort schema: type: string example: '[["Title", 1]]' required: false description: A list of tuples of field name and sort order. A sort order of 1 is ascending, and a sort order of -1 is descending. - in: query name: fields schema: type: string example: '["id", "Title"]' required: false description: A list of fields names to return in the response. - in: query name: page schema: type: integer format: int32 required: false description: The page of results to retrieve. - in: query name: limit schema: type: integer format: int32 required: false description: The page size. - in: query name: cache schema: type: boolean required: false description: True to allow caching on CDN, false to prevent CDN caching. This just sets or unsets the relevant response headers. - in: query name: distinct schema: type: string required: false description: If provided, returns a distinct list of values for the given field. responses: 200: description: Successful response content: application/json: schema: oneOf: - $ref: '#/components/schemas/ProductsResponse' - $ref: '#/components/schemas/DistinctResponse' /v1/pack_collections: get: summary: Get Pack Collections description: | ## Examples: ### Find pack collection by id A simple lookup by id: ``` /metadata/v1/pack_collections?id=GLOBAL_collection1 ``` tags: - Core parameters: - in: query name: id schema: type: array items: type: string required: false description: If provided, returns the product with the matching id. example: GLOBAL_gold_product - in: query name: sort schema: type: string example: '[["Title", 1]]' required: false description: A list of tuples of field name and sort order. A sort order of 1 is ascending, and a sort order of -1 is descending. - in: query name: fields schema: type: string example: '["id", "Title"]' required: false description: A list of fields names to return in the response. - in: query name: page schema: type: integer format: int32 required: false description: The page of results to retrieve. - in: query name: limit schema: type: integer format: int32 required: false description: The page size. - in: query name: cache schema: type: boolean required: false description: True to allow caching on CDN, false to prevent CDN caching. This just sets or unsets the relevant response headers. - in: query name: distinct schema: type: string required: false description: If provided, returns a distinct list of values for the given field. responses: 200: description: Successful response content: application/json: schema: oneOf: - $ref: '#/components/schemas/PackCollectionsResponse' - $ref: '#/components/schemas/DistinctResponse' /internal/commercial/v1/contentAuthorizations: get: summary: content authorization tags: - Internal description: | This API is a port of one that exists on CPM, to attempt to detach CPM from live traffic. See [here](https://atlassian.hq.k.grp/confluence/pages/viewpage.action?pageId=148327221) for the original API definition. ## Examples: ### Get content authorization for VoD with security id nkintdrm183557 ``` /metadata/internal/commercial/v1/contentAuthorizations?content.securityId=nkintdrm183557&content.startAvailabilityOffset=-P15D&content.endAvailabilityOffset=P15D ``` ```json { "content": { "id": "GLOBAL_CT0000258837_VERSION_DASH", "name": "CT0000258837_Fifi And The Flowertots S2 Ep.87 [G] [DreamWorks Jan 22]_VERSION_DASH", "rights": { "storageAllowed": "true" } }, "editorial": { "id": "GLOBAL_CT0000258837", "name": "CT0000258837_Fifi And The Flowertots S2 Ep.87 [G] [DreamWorks Jan 22]" }, "geoValidation": { "geoFilteringBillAddrCountryList": "IN;US", "geoFilteringBillAddrCountryWhiteList": true, "countryCodeWhiteList": "IN;US", "blockVPN": false, "validateByOnNet": true }, "products": { "productSet": [{ "id": "GLOBAL_S222009013", "name": "Go Max - iOS IAP", "start": "2020-01-01T00:00:00Z", "end": "2050-12-31T15:59:00Z", "type": "subscription", "rights": { "impulsive":"false", "storageAllowed":"true" } }, { "id": "GLOBAL_S111009510", "name": "Entertainment+", "start": "2020-01-01T00:00:00Z", "end": "2050-12-31T15:59:00Z" "type": "transactional", "rights": { "impulsive":"true", "rentalDuration":"P4DT12H30M5S", "consumptionWindow":"P2DT12H30M5S", "storageAllowed":"true" } }], "totalRecords": 2 } } ``` parameters: - in: query required: true name: content.securityId schema: type: string description: The digital rights management identifier (drmID) example: NIKHD_DASH - in: query required: false name: content.startAvailabilityOffset schema: type: string description: The start availability offset in ISO 8601 format example: -P15D - in: query required: false name: content.endAvailabilityOffset schema: type: string description: The end availability offset in ISO 8601 format example: P15D responses: 200: description: Successful response content: application/json: schema: $ref: '#/components/schemas/ContentAuthorizationsResponse' /internal/commercial/v1/products: get: summary: commercial Products description: | This api provides an aggregation of direct information about products. ## Examples: ### Find product by id A simple lookup by id: ``` /internal/commercial/v1/products?filter={ "id": "GLOBAL_gold_product" } ``` tags: - Internal parameters: - in: query name: filter schema: type: string example: { "id": "GLOBAL_gold_product" } required: false description: A key/value pairing list. Where key is a field name, and value is the value the field should be. - in: query name: sort schema: type: string example: [ [ "Title", 1 ] ] required: false description: A list of tuples of field name and sort order. A sort order of 1 is ascending, and a sort order of -1 is descending. - in: query name: fields schema: type: string example: [ "id", "Title" ] required: false description: A list of fields names to return in the response. - in: query name: page schema: type: integer format: int32 required: false description: The page of results to retrieve. - in: query name: limit schema: type: integer format: int32 required: false description: The page size. - in: query name: cache schema: type: boolean required: false description: True to allow caching on CDN, false to prevent CDN caching. This just sets or unsets the relevant response headers. - in: query name: distinct schema: type: string required: false description: If provided, returns a distinct list of values for the given field. responses: 200: description: Successful response content: application/json: schema: oneOf: - $ref: '#/components/schemas/ProductsResponse' - $ref: '#/components/schemas/DistinctResponse' /internal/commercial/v1/products/{productId}: get: summary: commercial Products By Id description: | This api provides an aggregation of direct information about products. ## Examples: ### Find product by id A simple lookup by id: ``` /internal/commercial/v1/products?filter={ "id": "GLOBAL_gold_product" } ``` tags: - Internal parameters: - in: path name: productId required: true description: The id of the product to retrieve schema: type: string example: GLOBAL_gold_product responses: 200: description: Successful response content: application/json: schema: oneOf: - $ref: '#/components/schemas/ProductsResponse' - $ref: '#/components/schemas/DistinctResponse' /internal/commercial/v2/contentAuthorizations/event/{eventId}: get: summary: ppv content authorization tags: - Internal description: | This API is a port of one that exists on CPM, to attempt to detach CPM from live traffic. ## Examples: ### Get content authorization for PPV with eventId 123456 ``` /metadata/internal/commercial/v2/contentAuthorizations/event/123456 ``` ```json { "resource": { "id": "GLOBAL_CT0000258837_VERSION_DASH", "name": "CT0000258837_Fifi And The Flowertots S2 Ep.87 [G] [DreamWorks Jan 22]_VERSION_DASH", "rights": { "impulsive":"true", "rentalDuration":"P4DT12H30M5S", "storageAllowed":"true", "additionalProperties": {} }, "viewStart": "2020-01-01T00:00:00Z", "viewEnd": "2020-01-01T01:00:00Z", "drmId": "12345", "sessionGroupId": "12345", "usageRule": "", "qmWaterMark": true }, "editorial": { "id": "GLOBAL_CT0000258837", "name": "CT0000258837_Fifi And The Flowertots S2 Ep.87 [G] [DreamWorks Jan 22]" }, "geoValidation": { "geoFilteringBillAddrCountryList": "IN;US", "geoFilteringBillAddrCountryWhiteList": true, "countryCodeWhiteList": "IN;US", "blockVPN": false, "validateByOnNet": true }, "products": { "productSet": [{ "id": "GLOBAL_S222009013", "name": "Go Max - iOS IAP", "start": "2020-01-01T00:00:00Z", "end": "2050-12-31T15:59:00Z", "type": "subscription", "isFreemium": true, "isShared": true, "freemium": { "start": "2020-01-01T00:00:00Z", "end": "2050-12-31T15:59:00Z", "validityPeriod": "P15D" }, "rights": { "impulsive":"false", "storageAllowed":"true" }, "capabilityProductInfo": { "type": "unknown" } }], "totalRecords": 1 } } ``` parameters: - in: path required: true name: eventId schema: type: string description: The eventId of the PPV event example: 123456 - in: query name: preferredChannelId schema: type: string example: 4G required: false description: The preferred technical channel ID for the client. responses: 200: description: Successful response content: application/json: schema: $ref: '#/components/schemas/ContentAuthorizationsPpvResponse' /internal/dynamicgroups: get: summary: Get dynamic content groups description: | Dynamic groups enable you to create groups based on search criteria rather than individual items directly. Items meeting the search criteria are returned to the client at runtime, and the items returned can change over time. ## Examples: ### Find dynamic content groups by id A simple lookup by id: ``` /internal/dynamicgroups?filter={ "id": "GLOBAL_game_of_thrones" } ``` tags: - Internal parameters: - in: query name: filter schema: type: string example: { "id": "GLOBAL_game_of_thrones" } required: false description: A key/value pairing list. Where key is a field name, and value is the value the field should be. - in: query name: sort schema: type: string example: [ [ "Title", 1 ] ] required: false description: A list of tuples of field name and sort order. A sort order of 1 is ascending, and a sort order of -1 is descending. - in: query name: fields schema: type: string example: [ "id", "Title" ] required: false description: A list of fields names to return in the response. - in: query name: page schema: type: integer format: int32 required: false description: The page of results to retrieve. - in: query name: limit schema: type: integer format: int32 required: false description: The page size. - in: query name: cache schema: type: boolean required: false description: True to allow caching on CDN, false to prevent CDN caching. This just sets or unsets the relevant response headers. - in: query name: distinct schema: type: string required: false description: If provided, returns a distinct list of values for the given field. responses: 200: description: Successful response content: application/json: schema: oneOf: - $ref: '#/components/schemas/DynamicGroupsResponse' - $ref: '#/components/schemas/DistinctResponse' /internal/securityinfo/{drmId}: get: summary: Get security info by DRM id description: | Returns security information for the provided drmId. The response will return security information for a channel or VoD. If the drmId matches both a channel and VoD, then the channel will be returned as a preference. ## Examples: ### Get security information for a channel ```/metadata/internal/securityinfo/NIKHD_DASH``` ``` { "type": "channel", "drmId": "NIKHD_DASH", "drmInstanceName": "DASH", "cdnId": "CDN_id_1", "cdnType": "Broadpeak" } ``` tags: - Internal parameters: - in: path name: drmId required: true description: The digital rights management identifier (drmID)) schema: type: string example: DRM12345 responses: 200: description: Successful response content: application/json: schema: oneOf: - $ref: '#/components/schemas/SecurityInfoResponse' - $ref: '#/components/schemas/Error' 404: description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' /vod/promotions: get: summary: Get vod promotions description: | The purpose of this API is to deliver promotion/trailer metadata to clients. Promotions are short videos advertising the content. They are often used to entice users to watch a particular piece of content. Promotions with availability windows are automatically filtered — at least one window must be currently active for the promotion to appear in results. ## Examples: ### Find trailers for a specific content Lookup trailers for a content by id ``` /vod/promotions?filter={"id": "GLOBAL_die_hard_trailer"} parameters: - in: query name: filter schema: type: string example: { "id": "GLOBAL_die_hard_trailer" } required: false description: A key/value pairing list. Where key is a field name, and value is the value the field should be. - in: query name: sort schema: type: string example: [ [ "Title", 1 ] ] required: false description: A list of tuples of field name and sort order. A sort order of 1 is ascending, and a sort order of -1 is descending. - in: query name: fields schema: type: string example: [ "id", "Title" ] required: false description: A list of fields names to return in the response. - in: query name: page schema: type: integer format: int32 required: false description: The page of results to retrieve. - in: query name: limit schema: type: integer format: int32 required: false description: The page size. - in: query name: cache schema: type: boolean required: false description: True to allow caching on CDN, false to prevent CDN caching. This just sets or unsets the relevant response headers. - in: query name: distinct schema: type: string required: false description: If provided, returns a distinct list of values for the given field. tags: - VoD responses: 200: description: Successful response content: application/json: schema: oneOf: - $ref: '#/components/schemas/DistinctResponse' - $ref: '#/components/schemas/VoDPromotionResponse' /vod/series: get: summary: Get vod series description: | **Series** and **Seasons** are groups of organized content. This API concerns just the series/season entities, and not the content within them. To find out how to query for content within a series/season, please see ```/vod/editorials```. ## Examples: ### Find series / season by id A simple lookup by id: ``` /vod/series?filter={ "id": "GLOBAL_game_of_thrones" } ``` ### Find seasons belonging to a series ``` /vod/series?filter={ "seriesRef": "GLOBAL_game_of_thrones" } ``` tags: - VoD parameters: - in: query name: filter schema: type: string example: { "id": "GLOBAL_game_of_thrones" } required: false description: A key/value pairing list. Where key is a field name, and value is the value the field should be. - in: query name: sort schema: type: string example: [ [ "Title", 1 ] ] required: false description: A list of tuples of field name and sort order. A sort order of 1 is ascending, and a sort order of -1 is descending. - in: query name: fields schema: type: string example: [ "id", "Title" ] required: false description: A list of fields names to return in the response. - in: query name: page schema: type: integer format: int32 required: false description: The page of results to retrieve. - in: query name: limit schema: type: integer format: int32 required: false description: The page size. - in: query name: cache schema: type: boolean required: false description: True to allow caching on CDN, false to prevent CDN caching. This just sets or unsets the relevant response headers. - in: query name: distinct schema: type: string required: false description: If provided, returns a distinct list of values for the given field. - in: query name: group schema: type: string enum: - content required: false description: If provided, groups the series response by contentLinkId - in: query name: groupLimit schema: type: integer format: int32 required: false description: Restricts the number of series returned per group when using the group parameter. - in: query name: all_ages schema: type: boolean required: false description: True to ignore maxAgeRating, returning content for all ages. - in: query name: previewable schema: type: integer format: int32 required: false description: >- Number of promotions (trailers) to include per series item. Absent or 0 = do not attach promotions. Greater than 0 = attach up to N promotions per series entry. responses: 200: description: Successful response content: application/json: schema: oneOf: - $ref: '#/components/schemas/SeriesResponse' - $ref: '#/components/schemas/DistinctResponse' /internal/recording/programmes: get: summary: Get programmes for recording description: | This API returns programme metadata for a given programme id. It is designed to be used when scheduling recordings, to ensure the correct programme is recorded. ## Examples: ### Get programme details for recording with programmeId: SKY_p200000 ``` /recording/programmes?programmeId=SKY_p200000 ``` ### Get programmes associated with contentRef: SKY_CONTENT_200000, broadcasted on channel: GLOBAL_sky_one, sorted by start period ascending ``` /recording/programmes?contentRef=SKY_CONTENT_200000&serviceRef=GLOBAL_sky_one&sort=[["period.start",1]] ``` ### Get all programmes(episodes) for seriesId=SKY_SERIES_10000 broadcasted on channel: GLOBAL_sky_one ``` /recording/programmes?seriesId=SKY_SERIES_10000&serviceRef=GLOBAL_sky_one ``` ### Get all programmes(episodes) for seriesId=SKY_SERIES_10000, seasonId=SKY_SEASON_1 broadcasted on channel: GLOBAL_sky_one ``` /recording/programmes?seriesId=SKY_SEASON_1&seasonId=SKY_SEASON_1&serviceRef=GLOBAL_sky_one ``` ### Get page 1, limit 10 programmes(episodes) for seriesId=SKY_SERIES_10000 broadcasted on channel: GLOBAL_sky_one ``` /recording/programmes?seriesId=SKY_SERIES_10000&serviceRef=GLOBAL_sky_one&page=1&limit=10 ``` ### Get programmes associated with editorial's contentLinkId: SKY_CONTENT_200000, broadcasted on channel: GLOBAL_sky_one, sorted by start period ascending ``` /recording/programmes?contentLinkId=SKY_CONTENT_200000&serviceRef=GLOBAL_sky_one&sort=[["period.start",1]] ``` tags: - Recordings parameters: - in: query name: programmeId schema: type: string description: The identifier of the programme to retrieve example: SKY_200000 - in: query name: serviceRef schema: type: string required: false description: The service reference of the channel the programme is on example: GLOBAL_sky_one - in: query name: contentRef schema: type: string description: The content reference of the programme - in: query name: contentLinkId schema: type: string description: The content link identifier of the programme's editorial example: SKY_CONTENT_200000 - in: query name: seriesId schema: type: string required: false description: The series identifier of the programme example: SKY_SERIES_10000 - in: query name: seasonId schema: type: string required: false description: The season identifier of the programme example: SKY_SERIES_10000 - in: query name: page schema: type: integer format: int32 required: false description: The page of results to retrieve. - in: query name: limit schema: type: integer format: int32 required: false description: The page size. - in: query name: sort schema: type: string example: [ [ "period.start", 1 ] ] required: false description: A list of tuples of field name and sort order. A sort order of 1 is ascending, and a sort order of -1 is descending. - in: query name: fields schema: type: string items: type: string example: [ "serviceRef", "period" ] required: false description: A list of fields names to return in the response. responses: 200: description: Successful response content: application/json: schema: $ref: '#/components/schemas/ProgrammesForRecordingResponse' 404: description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT schemas: CsCues: type: object description: Client-side cue data for features such as credit skipping and recap skipping properties: csCuesEnabled: type: boolean description: Whether client-side cues should be processed during playback example: true cueProfileId: type: string description: ID of a cue point profile to use for resolving cue points example: "GLOBAL_profile123" csCueList: type: array description: The list of cue point definitions for the content items: $ref: '#/components/schemas/CsCue' example: csCuesEnabled: true cueProfileId: "GLOBAL_profile123" csCueList: - name: "intro-skip" type: "recap" description: "Skip the recap" duration: 30000 timeOffset: 0 - name: "credits-skip" type: "credits" description: "Skip the end credits" timeFromEnd: 120000 CsCue: type: object description: A single cue point definition properties: name: type: string description: Unique identifier or label for the cue example: "intro-skip" type: type: string description: Category of cue, e.g., 'credits', 'recap', 'ad', 'chapter' example: "credits" description: type: string description: Human-readable description of the cue duration: type: integer format: int64 description: Duration of the cue in milliseconds example: 30000 metadata: type: object additionalProperties: true description: Custom key/value pairs for this cue timeOffset: type: integer format: int64 description: Time offset from the start of the content in milliseconds example: 0 timePercentage: type: number format: double description: Percentage from the start of the content (0-100) example: 95.5 timeFromEnd: type: integer format: int64 description: Time offset from the end of the content in milliseconds example: 120000 ContentAuthorizationsResponse: description: The response to a content authorizations request additionalProperties: true properties: content: $ref: '#/components/schemas/ContentAuthorizationsContent' editorial: $ref: '#/components/schemas/ContentAuthorizationsEditorial' geoValidation: $ref: '#/components/schemas/ContentAuthorizationsGeoValidation' products: $ref: '#/components/schemas/CAProducts' ContentAuthorizationsPpvResponse: additionalProperties: true description: The response to a content authorizations ppv request properties: resource: $ref: '#/components/schemas/ContentAuthorizationsResource' products: $ref: '#/components/schemas/CAProducts' CAProducts: description: The products available for the content in a ppv request properties: productSet: type: array items: $ref: '#/components/schemas/CAProduct' totalRecords: type: integer example: 1 description: The total number of products available for the content CAProduct: description: A product formatted in the legacy CPM style. This is used for PPV content authorization. additionalProperties: true properties: id: type: string description: The product identifier example: GLOBAL_S111009510 name: type: string description: The non-localized name of the product example: "Entertainment+" self: type: string description: The URL to the product example: "http://host/rest/api/commercial/v1/products/GLOBAL_S111009510" start: type: string format: date-time description: The start date of the product in ISO 8601 format (UTC) example: "2019-01-01T00:00:00Z" end: type: string format: date-time description: The end date of the product in ISO 8601 format (UTC) example: "2019-12-31T23:59:59Z" type: type: string description: The type of product example: "subscription" isFreemium: type: string nullable: true description: True if the product is a freemium product example: "false" published: type: string nullable: true description: True if the product is published example: "true" isShared: type: string nullable: true description: True if the product is a shared product example: "false" freemium: $ref: '#/components/schemas/CAPFreemium' storageAllowed: type: string nullable: true description: True if the product may be stored for offline viewing example: "true" rights: $ref: '#/components/schemas/ProductRights' externalAuthoriserId: type: string description: Identifier for an external authoriser system used for purchasing or validating the product CAPFreemium: type: object nullable: true description: Freemium details if the product is freemium properties: start: type: string description: The start date of the freemium period in ISO 8601 format (UTC) example: "2019-01-01T00:00:00Z" end: type: string description: The end date of the freemium period in ISO 8601 format (UTC) example: "2019-12-31T23:59:59Z" validityPeriod: type: string description: The duration of the freemium period in ISO 8601 duration format example: "P4DT12H30M5S" ContentAuthorizationsContent: description: The technical content corresponding to the security id used to retrieve the auth response additionalProperties: true properties: id: type: string description: The content identifier example: GLOBAL_CT0000258837_VERSION_DASH name: type: string description: The non-localized name of the content example: "CT0000258837_Fifi And The Flowertots S2 Ep.87 [G] [DreamWorks Jan 22]_VERSION_DASH" self: type: string description: The URL to the content example: "http://host/rest/api/content/v1/technicalContents/GLOBAL_CT0000258837_VERSION_DASH" sessionGroupId: type: string description: The session group identifier for the content example: 123 usageRule: type: string description: Rules concerning the usage of the content example: DVR qmWatermark: type: boolean description: Flag signalling that during license requests the requested content should have Quickmark watermarking enforced cdnTokenDetails: type: object description: Details about the CDN token used to access the content properties: cdnType: type: string description: The type of CDN token example: "Cloudflare" cdnId: type: string description: The identifier of the CDN token example: "foobar1234" dynamicRange: type: "array" items: type: "string" ratings: type: array items: $ref: '#/components/schemas/Rating' description: Parental ratings, for various ratings bodies example: [ { "ratingBody": "BBFC", "code": "PG", "precedence": 1 } ] rights: $ref: '#/components/schemas/ContentRights' ContentRights: description: Rights describing how the content may be used properties: storageAllowed: type: boolean description: True if the content may be stored for offline viewing ContentAuthorizationsResource: description: The resource corresponding to the security id used to retrieve the auth response additionalProperties: true properties: id: type: string description: The content identifier example: GLOBAL_CT0000258837_VERSION_DASH name: type: string description: The non-localized name of the content example: "CT0000258837_Fifi And The Flowertots S2 Ep.87 [G] [DreamWorks Jan 22]_VERSION_DASH" type: type: string description: The type of the res3ource, e.g. "series", "season" example: "promotion" viewStart: type: string description: The start time of the ppv event in ISO 8601 format example: 2019-01-22T00:00:00Z viewEnd: type: string description: The end time of the ppv event in ISO 8601 format example: 2019-01-22T23:59:59Z rights: $ref: '#/components/schemas/ContentRights' geoValidations: $ref: '#/components/schemas/ContentAuthorizationsGeoValidation' self: type: string description: The URL to the content example: "http://host/rest/api/content/v1/technicalContents/GLOBAL_CT0000258837_VERSION_DASH" qmWatermark: type: boolean description: Flag signalling that during license requests the requested content should have Quickmark watermarking enforced cdnTokenDetails: type: object description: Details about the CDN token used to access the content properties: cdnType: type: string description: The type of CDN token example: "Cloudflare" cdnId: type: string description: The identifier of the CDN token example: "foobar1234" drmId: type: string description: The DRM identifier for the content example: 123 sessionGroupId: type: string description: The session group identifier for the content example: 123 usageRule: type: string description: Rules concerning the usage of the content example: DVR ratings: type: array items: $ref: '#/components/schemas/Rating' description: Parental ratings, for various ratings bodies example: [ { "ratingBody": "BBFC", "code": "PG", "precedence": 1 } ] required: - geoValidations ProductRights: description: Rights describing how the content may be used properties: impulsive: type: boolean description: True if the content is available for impulsive purchase example: true rentalDuration: type: string description: The duration of the rental in ISO 8601 format example: P4DT12H30M5S consumptionWindow: type: string description: The duration for which the content may be used, in ISO 8601 format example: P2DT12H30M5S storageAllowed: type: boolean description: True if the content may be stored for offline viewing example: true storageStartPeriod: type: string description: The period after which storage starts, in ISO 8601 format example: P1D storageDuration: type: string description: The duration for which the content may be used, in ISO 8601 format example: P2DT12H30M5S ContentAuthorizationsEditorial: description: The editorial content the content authorizations for which the request was made properties: id: type: string description: The editorial content identifier example: GLOBAL_CT0000258837 name: type: string description: The non-localized name of the editorial content example: "CT0000258837_Fifi And The Flowertots S2 Ep.87 [G] [DreamWorks Jan 22]" self: type: string description: The URL to the content example: "http://host/rest/api/content/v1/technicalContents/GLOBAL_CT0000258837_VERSION_DASH" ContentAuthorizationsGeoValidation: description: Information about where the content may be watched (geographically) additionalProperties: true properties: geoFilteringBillAddrCountryList: type: array items: type: string description: The list of countries where the content may be watched example: "GB" geoFilteringBillAddrCountryWhiteList: type: boolean description: True if the list of countries is a whitelist, false if it is a blacklist example: true countryCodeWhiteList: type: string description: The country code whitelist for the content example: "GB" blockVPN: type: boolean description: True if VPNs are blocked for the content example: true validateByOnNet: type: boolean description: True if the content is validated by the network to which it is connected example: true filteringList: type: string description: A list of regions to allow or deny, split by semi colons example: "IN;US" filteringListIsAllowList: type: boolean description: whether the filtering list should be used as a filtering list or a blocking list blockingList: type: string description: A list of regions to block, split by semi colons example: "IN;US" blockingListIsAllowList: type: boolean description: whether the blocking list should be used as a blocking list or a whitelist blockIfOffNet: type: boolean description: True if the content should be blocked if the user is not on network example: true DeepLink: additionalProperties: true properties: id: type: string example: "NFX_123" description: The identifier of the deep link name: type: string example: Cowspiracy description: The non-localized name of the deep link contentRef: type: string example: "GLOBAL_123" description: A reference to the parent content in the core platform period: allOf: - $ref: '#/components/schemas/Period' description: The time period for which the deep link is valid provider: type: string example: Netflix description: The provider of the referenced content deviceType: type: array description: The devices able to use this deep link items: type: string example: [ "Android" ] resolution: type: array description: The resolution of the content on the third party items: type: string example: [ "HD", "4K" ] original: type: boolean description: True if the linked source is the original source example: false action: description: The action to take on use of the link, e.g. open media card, or directly follow link type: string example: direct url: type: string example: "https://netflix.com/abc/xyz" description: The actual URI to follow playbackOptions: type: array description: Playback information about the third party platform items: type: object properties: price: type: number format: double example: 5.99 description: Cost to watch at third party provider (e.g. their subscription price) definition: type: string description: The definition of the content at third party provider example: HD currency: type: string description: The currency to purchase from the third party provider example: GBP license: type: string description: The license from the third party provider contentType: type: string example: "LIVE" description: The type of content being linked, e.g. "LIVE", "VOD", "CATCHUP" schedule: allOf: - $ref: '#/components/schemas/Schedule' description: Schedule information for the content availability DistinctResponse: properties: values: description: A list of distinct values for the field type: array items: type: string DvbInfo: additionalProperties: true type: object description: | A DVB Triplet consists of a number of identifiers that, when used together, provide a means to uniquely identify a DVB service. properties: nid: type: integer description: Network Id triplet: type: object properties: onid: type: integer description: Original Network Id tsid: type: integer description: Transport Stream Id sid: type: integer description: Service Id uid: type: string description: Concatenation of onid.sid.uid example: { "nid": 1234, "triplet": { "onid": 156, "tsid": 8100, "sid": 257, "uid": "156.8100.257" } } DynamicGroups: properties: id: type: string example: GLOBAL_ND0000001997_Group description: Id of the dynamic content group title: type: string example: "Boxing" description: Title of the dynamic content group enabled: type: boolean description: A flag to signal whether the dynamic content group is enabled sources: type: array items: type: string example: ["GLOBAL_1234567890", "GLOBAL_ABC1234570"] query: type: object properties: language: type: string example: "lucene" description: Search language of the dynamic content group body: type: string example: "actor: \"Sylvester Stallone\" AND (metadata.none.CUST_PROV: \"TIME\" OR \"DISNEY\")" description: The query string of the dynamic content group sort: type: string example: "A-Z" description: Sort order of the dynamic content group pageSize: type: integer description: The number of records, per page, to return query example: 5 limit: type: integer description: The number of records, in total, to return from query example: 10 DynamicGroupsResponse: properties: total_records: type: integer description: The number of records, in total, that satisfy your query example: 1 groups: type: array items: $ref: '#/components/schemas/DynamicGroups' EditorialService: additionalProperties: true properties: id: type: string example: GLOBAL_140 description: The id of the editorial service matched period: allOf: - $ref: '#/components/schemas/Period' description: The time period for which the service is valid companyId: type: string example: GLOBAL description: The provider of the channel longName: type: string example: Asianet description: The full name of the TV channel tvChannel: type: integer example: 139 description: The channel number guardTimeStart: type: number format: float example: 600.0 description: For recordings, the grace time, before a programme begins, that a recording will start to be taken guardTimeEnd: type: number format: float example: 600.0 description: For recordings, the grace time, after a programme ends before the recording is completed catchUpSupport: type: boolean example: false description: A flag to signal whether the channel has any catch up support startOverSupport: type: boolean example: false description: A flag to signal whether the channel supports starting over a currently running programme from the beginning ppvEnabled: type: boolean example: false description: A flag to signal whether the channel supports pay-per-view events networkPvrSupport: type: boolean example: false description: A flag to signal whether the channel supports network recordings longTermCatchUpSupport: type: boolean example: false description: A flag to signal whether the channel supports long-term (aka VoD) catch-up csaiEnabled: type: boolean example: false description: A flag to signal whether the channel supports CSAI (Client-Side Ad Insertion) active: type: boolean example: true description: Whether the channel is active contentGroups: type: array items: type: string description: A list of channel groups to which the channel belongs example: [ "sports_channels" ] productRefs: type: array items: type: string description: A list of products that sell the channel example: [ "gold_pack" ] Categories: type: array items: type: string description: A list of categories of the channel, e.g. News, Sport example: [ "News", "Sport" ] Rating: allOf: - $ref: '#/components/schemas/Rating' description: A parental rating for the channel, e.g. "M (Mature)" - generally prefer Ratings Ratings: type: array items: $ref: '#/components/schemas/Rating' description: A parental rating for the channel, by rating body e.g. "M (Mature)" Description: type: string description: A brief description of the channel example: Sports news and highlights clientControls: additionalProperties: true type: object description: | Client controls are used to denote features of the service or content that can be supported on the client. For example, NPVR (network recordings), NETFLIX or FFWD (fast-forward) example: { 'FFWD': false, 'SO': false, 'HD': true, 'UHD': true, 'NETFLIX': true, 'AMAZON': true, 'PVR': true, 'TVOD': true, 'NPVR': false } dvbinfo: type: array items: $ref: '#/components/schemas/DvbInfo' sourcePreference: type: string description: The preferential source (e.g. OTT/DVB) from which the TV channel should be streamed storageAllowed: type: boolean description: Whether the item can be stored locally regional: type: array items: $ref: '#/components/schemas/Regional' Regional: additionalProperties: true description: Specific properties for a region. Used to override the default properties of a service. properties: location: type: string description: Location on which to apply this regional information locationType: type: string description: The type of location, e.g. city channelName: type: string description: Regionalized channel name channelNumber: type: integer description: Regionalized channel number sourcePreference: type: string description: Regionalized source preference dvbinfo: type: array items: $ref: '#/components/schemas/DvbInfo' Node: additionalProperties: true description: A catalog node, for example 'New Releases' or 'Family Favourites'. Holds related content, or other nodes, for structured browsing. properties: id: type: string description: The node identifier example: "GLOBAL_ND0000003102" period: allOf: - $ref: '#/components/schemas/Period' description: The time period for which the node is valid parent: type: string description: A reference to the parent of the node example: "GLOBAL_LY0000121042" isRoot: type: boolean description: True if a root node (top of the node tree) example: false children: type: array items: type: string description: Direct children of the node example: [ "GLOBAL_ND0000003209", "GLOBAL_ND0000003195", "GLOBAL_ND0000003191" ] ancestors: type: array items: type: string description: Parent, grandparent, etc of the node example: [ "GLOBAL_LYS0000138", "GLOBAL_LYS0000139", "GLOBAL_LY0000121042" ] descendants: type: array items: type: string description: All children, grandchildren, etc of the node example: [ "GLOBAL_ND0000003209", "GLOBAL_ND0000003195", "GLOBAL_ND0000003191", "GLOBAL_ND0000003194", "GLOBAL_ND0000003807", "GLOBAL_ND0000003199", "GLOBAL_ND0000003197" ] Description: type: string description: A brief description of the content held within the node example: Brand new movies on demand Title: type: string description: The localized title of the node example: Movies On Demand CUST_PublishStartTime: type: number description: The date at which the node is published example: "2023-01-01T00:00:00Z" Regions: type: array items: type: string description: The regions in which the node is available orderingFields: type: array items: type: string description: The fields by which the node can be ordered, e.g. "Title", "StartDate" example: [ "Title", "StartDate" ] NodesResponse: properties: total_records: type: integer description: The number of records, in total, that satisfy your query example: 1 nodes: type: array items: $ref: '#/components/schemas/Node' Period: additionalProperties: true properties: start: type: number format: float example: 1620556200.0 description: Start time (UNIX epoch seconds) end: type: number format: float example: 1620558000.0 description: End time (UNIX epoch seconds) duration: type: integer format: int64 example: 1800 description: Duration in seconds Product: additionalProperties: true properties: id: type: string example: GLOBAL_S222009007 description: The id of the product startPurchase: type: number format: float example: 1577836800.0 description: The date from when purchase will be possible (in UNIX epoch time) endPurchase: type: number format: float example: 2556115140.0 description: The date at which the ability to purchase will cease (in UNIX epoch time) price: type: object description: The cost of the product additionalProperties: true properties: startPurchase: type: number format: float example: 1577836800.0 description: The date from when purchase will be possible (in UNIX epoch time) endPurchase: type: number format: float example: 2556115140.0 description: The date at which the ability to purchase will cease (in UNIX epoch time) currency: type: string example: SGD description: The currency in which the transaction must be made value: type: number example: 1.99 format: float description: The cost of the product deviceType: type: array description: The types of devices that can use this product (derived from profiles) items: type: string example: [ IOS ] billingModel: type: object additionalProperties: true description: The rental duration of the product once purchased properties: period: type: integer format: int32 example: 86400 startValidity: type: number format: float example: 1577836800.0 description: The date at which the product becomes valid to use (in UNIX epoch time) endValidity: type: number format: float example: 2556115140.0 description: The date at which the ability to use the product will cease (in UNIX epoch time) type: type: string example: "subscription" nullable: true description: The product type, e.g. subscription, transactional, ppv packSaleOnly: type: boolean description: Indicates whether the product can only be sold as part of a pack or bundle. isPartOfPack: type: boolean description: Indicates whether the product is part of a pack or bundle. This property is used to determine if the product is grouped with other items as part of a package offering. isFreemium: type: boolean example: false description: Whether a product is freemium (free to begin with, and then a cost to continue) freemium: $ref: '#/components/schemas/Freemium' technicalTypes: type: array items: type: string description: The technical specifics to which the product applies - corresponds to Definition on a technical content. If a product has technical types, it is only applicable to the types of content that match. example: [ "SD", "HD", "DASH", "HLS" ] Title: type: string example: "Go Select - RCC" Description: type: string example: "Go Select - RCC" LicenseDuration: type: string example: "P100Y0M0DT0H0M0S" description: The duration for which you're allowed to use the product. consumptionWindow: type: number format: float example: 86400.0 description: The window in which you're allowed to consume the content once begun. rentalDuration: type: number format: float example: 604800.0 description: The duration of the full rental. storageAllowed: type: boolean description: Whether the item can be stored locally isPreviewEnabled: type: boolean description: Whether the product is previewEnabled previewConfiguration: type: object description: If the product is previewEnabled, following preview configurations apply properties: previewCycle: type: string description: Enumeration of preview cycle, allowed values are daily, monthly. example: daily maxPreviewDuration: type: integer description: Maximum preview duration in minutes per day/month. example: 10 maxSessions: type: integer example: 3 description: Maximum parallel sessions per user. memberOfPacks: type: array items: type: string description: References to pack IDs to which this product belongs. nullable: true clientPurchasable: type: boolean description: | Indicates where a Product, Pack type or otherwise, can be sold direct to a Client. If false then Product cannot be purchased directly by Client. Where unset, true behaviour is assumed for backwards compatibility. sortOrder: type: integer deprecated: true description: The sort order of the product, used to determine the order in which products are displayed example: 1 productTags: type: array items: type: string description: Tag to identify the product variants externalAuthoriserId: type: string description: Identifier for an external authoriser system used for purchasing or validating the product Freemium: type: object description: Freemium details if the product is freemium properties: start: type: number format: float example: 1577836800.0 description: The date from when the freemium period will start (in UNIX epoch time) end: type: number format: float example: 2556115140.0 description: The date at which the freemium period will end (in UNIX epoch time) validityPeriod: type: number example: 300 description: The duration of the freemium period in ISO 8601 duration format PackProduct: type: object description: | Represents a bundled product or pack of products which contains references to other products and specifies whether it belongs to another pack. Extends the Product class, inheriting common product attributes. allOf: - $ref: '#/components/schemas/Product' - type: object properties: packMembers: type: array items: type: string description: References to product IDs that are part of this pack nullable: true type: type: string enum: [ "pack" ] description: The type of the product, always returns "pack" readOnly: true ProductsResponse: properties: total_records: type: integer description: The number of records, in total, that satisfy your query example: 1 products: type: array items: oneOf: - $ref: '#/components/schemas/Product' - $ref: '#/components/schemas/PackProduct' PackCollectionsResponse: properties: total_records: type: integer description: The number of records, in total, that satisfy your query example: 1 collections: type: array items: $ref: '#/components/schemas/PackCollection' PackCollection: additionalProperties: true properties: id: type: string example: GLOBAL_collection1 description: Id of the pack collection Title: type: string example: "Pack Collection One" description: The localized title of the pack collection Rating: additionalProperties: true properties: ratingBody: type: string example: BBFC description: The body that issued the rating, ex. BBFC, MPAA code: type: string example: 0 description: Rating code, e.g. M (for mature) precedence: type: integer example: 0 description: Relative precedence (e.g. U would be 0, PG 1 and PG-13 3) Schedule: description: Schedule information for content availability additionalProperties: true properties: start: type: integer format: int64 description: The scheduled start time in epoch seconds example: 1727827200 end: type: integer format: int64 description: The scheduled end time in epoch seconds example: 1735689599 Series: additionalProperties: true properties: id: type: string example: GLOBAL_ND0000001997_Series description: Id of the series type: type: string example: series description: Whether the series is a series or season contentLinkId: type: string description: A common content link that ties multiple contents together allowing them to be grouped. example: cid_12345 period: allOf: - $ref: '#/components/schemas/Period' description: The time period for which the series is valid grouped: description: List of other series records, when grouping by content type: array items: $ref: '#/components/schemas/Series' Rating: allOf: - $ref: '#/components/schemas/Rating' description: The parental rating of the series - generally deprecated by Ratings Ratings: type: array items: $ref: '#/components/schemas/Rating' description: Parental ratings, for various ratings bodies Title: type: string example: "Dead Time Stories S2" description: The localized title of the series Description: type: string example: "Dead Time Stories S2" description: The localized description of the series links: type: array items: $ref: '#/components/schemas/DeepLink' example: [ { "id": "NFX_123", "name": "Dead Time Stories S2", "contentRef": "GLOBAL_123", "provider": "Netflix", "period": { "start": 1620556200, "end": 1620558000, "duration": 1800 }, "deviceType": [ "Android" ], "resolution": [ "HD", "4K" ], "original": false, "type": "string", "action": "string", "url": "https://netflix.com/abc/xyz", "playbackOptions": [ { "price": 5.99, "definition": "HD", "currency": "GBP", "license": "string" } ] } ] extras: type: array nullable: true description: >- Optional list of promotions (trailers) attached to the series when requested by the caller (e.g. via the `previewable` query parameter). Absent or empty by default. items: $ref: '#/components/schemas/VodPromotionPreview' VodPromotionPreview: type: object description: >- Trimmed promotion object embedded inside /vod/series when `previewable` is requested. This shape is optimized for client preview display. additionalProperties: false properties: id: type: string description: The id of the promotion example: GLOBAL_EP013898090011 type: type: string description: The type of the promotion (e.g. trailer) example: trailer Title: type: string description: The title of the promotion example: Behind the scenes Description: type: string description: The description of the promotion example: An all-access look behind the scenes of this latest Marvel Cinematic Universe creation Ratings: type: array description: Ratings for the promotion (derived from technical/media metadata) items: $ref: '#/components/schemas/Rating' technicals: type: array description: Technical metadata for the promotion id: type: string description: The id of the technical content example: GLOBAL_EP013898090011 deviceType: type: array description: The types of devices that can play this content (derived from profiles) items: type: string example: [ IOS ] media: description: Media details for the promotion preview allOf: - $ref: '#/components/schemas/Media' Duration: type: integer format: int32 description: Duration in seconds example: 5580 DisplayPriority: type: integer format: int32 description: Display priority ordering example: 1 cueProfileId: type: string description: Reference to a cue point profile that provides shared cue points for content within this series example: "GLOBAL_binge_profile_001" SeriesResponse: properties: total_records: type: integer description: The number of records, in total, that satisfy your query example: 1 series: type: array items: $ref: '#/components/schemas/Series' ProgrammesResponse: properties: total_records: type: integer description: The number of records, in total, that satisfy your query example: 1 programmes: type: array items: $ref: '#/components/schemas/Programme' ServiceAggregate: additionalProperties: true properties: locale: type: string example: en_GB description: The language in which the metadata is presented editorial: $ref: '#/components/schemas/EditorialService' technical: $ref: '#/components/schemas/TechnicalService' deviceType: type: array description: The types of devices that can play this channel (derived from profiles) items: type: string example: [ "IOS", "Android" ] promotions: type: array nullable: true description: >- Optional list of promotions (trailers) attached to the service when requested by the caller (e.g. via the `previewable` query parameter). Absent or empty by default. items: $ref: '#/components/schemas/VodPromotionPreview' ServicesResponse: properties: total_records: type: integer description: The number of records, in total, that satisfy your query example: 1 services: type: array items: $ref: '#/components/schemas/ServiceAggregate' TechnicalService: additionalProperties: true properties: id: type: string example: GLOBAL_140_D description: The id of the technical service matched period: allOf: - $ref: '#/components/schemas/Period' description: The time period for which the service is valid mainChannelId: type: string example: GLOBAL_140 description: A reference to the editorial companyId: type: string example: GLOBAL description: The provider of the channel drmId: type: string example: Asianet_DASH description: A key required for digital rights management when requesting entitlements to play out the channel drmInstanceName: type: string example: security_device description: The security device managing the entitlements catchUpSupport: type: boolean example: false description: A flag to signal whether the channel has any catch up support startOverSupport: type: boolean example: false description: A flag to signal whether the channel supports starting over a currently running programme from the beginning ppvEnabled: type: boolean example: false description: A flag to signal whether the channel supports pay-per-view events networkPvrSupport: type: boolean example: false description: A flag to signal whether the channel supports network recordings longTermCatchUpSupport: type: boolean example: false description: A flag to signal whether the channel supports long-term (aka VoD) catch-up active: type: boolean example: true description: Whether the channel is active StartOverLocation: type: string example: https://example.com/startover description: The URI to playout the current programme from the start NetworkLocation: type: string example: https://example.com/channel description: The URI to playout the channel live productRefs: type: array items: type: string description: A list of products that sell the channel example: [ "gold_pack" ] deviceType: type: array description: The types of devices that can play this channel (derived from profiles) items: type: string example: [ IOS ] Categories: type: array items: type: string description: The categories to which the channel belongs. Category is more general than genre. example: [ "News", "Sport" ] PromoImages: type: array items: type: string description: A list of promotional images, e.g. channel logo - generally use of the image service is preferred. example: [ "https://example.com/Linear_channels2/139_1920x1080_HTV.png" ] Description: type: string description: A brief description of the channel example: Sports news and highlights products: type: array description: A list of products related to this channel. You should be entitled to at least one product to play out the content. items: $ref: '#/components/schemas/Product' qmWatermark: type: boolean description: Flag signalling that during license requests the requested channel should have Quickmark watermarking enforced usageRule: type: string example: UHD storageAllowed: type: boolean description: Whether the item can be stored locally generateLocation: type: boolean description: Flag signalling that the location should be generated by an additional backend request cdn: type: object properties: type: type: string example: "akamai" description: The type of CDN e.g. Broadpeak id: type: string example: "BP12345" description: The id of the CDN e.g. BP12345 Programme: additionalProperties: true properties: id: type: string example: GLOBAL_14771_20210509103000 description: The identifier of the programme locale: type: string example: en_US description: The language in which the metadata is presented created: type: number format: float example: 1620556200.0 description: The date at which the programme was created (in UNIX epoch time) contentLinkId: type: string description: A common content link that ties multiple contents together allowing them to be grouped. example: cid_12345 grouped: description: List of other programme records, when grouping by content type: array items: $ref: '#/components/schemas/Programme' eventId: type: string example: GLOBAL_14771_20210509103000 broadcastEventId: type: string example: GLOBAL_14771_20210509103000 description: Identifier linking this programme to a broadcast event serviceRef: type: string example: GLOBAL_14771 contentRef: type: string example: GLOBAL_14771_20210509103000 airingTimeStart: type: number format: float example: 1620556200.0 description: Start time (UNIX epoch seconds) airingTimeEnd: type: number format: float example: 1620558000.0 description: End time (UNIX epoch seconds) period: allOf: - $ref: '#/components/schemas/Period' description: The broadcast time of the programme isCatchUp: type: boolean example: true description: True if programme supports any catch up isStartOver: type: boolean example: true description: True if programme supports start over isSTCU: type: boolean example: true description: True if programme supports short term catch up isLTCU: type: boolean example: false description: True if programme supports long term catch up isPPV: type: boolean example: false description: True if programme supports pay-per-view isnPvr: type: boolean description: True if programme supports nPVR seasonRef: type: string description: Reference to season seriesRef: type: string description: Reference to series contentGroups: type: array items: type: string example: [ ] description: Content groups to which the programme belongs productRefs: type: array items: type: string example: [ ] description: Products to which the programme belongs isFreemium: type: boolean example: false description: True if programme supports freemium Year: type: integer description: Year in which the content was produced Rating: allOf: - $ref: '#/components/schemas/Rating' description: The parental rating of the content - generally deprecated by Ratings Ratings: type: array items: $ref: '#/components/schemas/Rating' description: Parental ratings, for various ratings bodies Categories: type: array items: type: string description: The categories to which the content belongs. Category is more general than genre. example: [ "Drama", "Series" ] Audio: type: array description: List of available audio tracks for the content items: type: string example: [ "Korean-Standard" ] PromoImages: type: array items: type: string description: A list of promotional images - generally use of the image service is preferred. example: [ "https://example.com/poster/18Again.jpg" ] Actors: type: array description: A list of the performing actors. items: type: string example: [ "Kim Ha Neul", "Yoon Sang Hyun" ] Directors: type: array description: A list of the directors of the content. items: type: string example: [ ] Producers: type: array description: A list of the producers of the content. items: type: string example: [ ] Writers: type: array description: A list of the writers of the content. items: type: string example: [ ] Subtitles: type: array description: Subtitles available for the programme items: type: string example: [ "Eng-Standard" ] Definition: type: string example: SD description: Definition of the broadcast, e.g. HD, 4K Description: type: string example: Learn about the wonderful world of numismatics with your host Mike Mezack! description: Description of the content Title: type: string example: Coin Collecting with Mike Mezack description: Localized title of the content Synopsis: type: string example: Learn about the wonderful world of numismatics with your host Mike Mezack and get the opportunity to build your own collection with some of the best deals around! description: Synopsis of the content BlackoutControlRulesetId: type: string example: "67f2ef8a-b032-485d-9b37-a28fb1a6339d" default: default editorial: $ref: '#/components/schemas/ProgrammeEditorial' links: type: array items: $ref: '#/components/schemas/DeepLink' example: [ { "id": "NFX_123", "name": "Coin Collecting with Mike Mezack", "contentRef": "GLOBAL_123", "provider": "Netflix", "period": { "start": 1620556200, "end": 1620558000, "duration": 1800 }, "deviceType": [ "Android" ], "resolution": [ "HD", "4K" ], "original": false, "type": "string", "action": "string", "url": "https://netflix.com/abc/xyz", "playbackOptions": [ { "price": 5.99, "definition": "HD", "currency": "GBP", "license": "string" } ] } ] storageAllowed: type: boolean description: Whether the item can be stored locally _mod: type: string enum: - add - reschedule - update description: Describes the type of change that has occurred to the programme. extras: type: array nullable: true description: >- Optional list of promotions (trailers) attached to the programme when requested by the caller (e.g. via the `previewable` query parameter). Absent or empty by default. items: $ref: '#/components/schemas/VodPromotionPreview' ProgrammeEditorial: additionalProperties: true properties: id: type: string example: GLOBAL_14771_20210509103000 description: The id of the programme contentLinkId: type: string description: A common content link that ties multiple contents together allowing them to be grouped. example: cid_12345 created: type: number example: 1620036031 description: When the content was ingested into the platform contentType: type: string example: movie description: The type of the content - e.g. movie, tvshow period: allOf: - $ref: '#/components/schemas/Period' description: The validity time of the content companyId: type: string example: GLOBAL description: The source provider of the programme Year: type: integer example: 1984 description: The year of production of the content Rating: allOf: - $ref: '#/components/schemas/Rating' description: The parental rating of the content - generally deprecated by Ratings Ratings: type: array items: $ref: '#/components/schemas/Rating' description: Parental ratings, for various ratings bodies csaiEnabled: type: boolean example: false description: A flag to signal whether the content supports CSAI (Client-Side Ad Insertion) csaiAdCueTimes: type: array example: [ { "timeOffset": 0, "adDuration": 5 }, { "timeOffset": 10, "adDuration": 5 } ] description: A list of ad cue times for CSAI (Client-Side Ad Insertion) items: type: object properties: timeOffset: type: integer description: The time offset from the start of the content (in seconds) adDuration: type: integer description: The duration of the ad (in seconds) example: { "timeOffset": 0, "adDuration": 5 } Categories: type: array items: type: string description: The categories to which the content belongs. Category is more general than genre. example: [ "Drama", "Series" ] Audio: type: array description: List of available audio tracks for the content items: type: string example: [ "Korean-Standard" ] PromoImages: type: array items: type: string description: A list of promotional images - generally use of the image service is preferred. example: [ "https://example.com/poster/18Again.jpg" ] Actors: type: array description: A list of the performing actors. items: type: string example: [ "Kim Ha Neul", "Yoon Sang Hyun" ] Directors: type: array description: A list of the directors of the content. items: type: string example: [ ] Producers: type: array description: A list of the producers of the content. items: type: string example: [ ] Writers: type: array description: A list of the writers of the content. items: type: string example: [ ] Subtitles: type: array description: List of subtitle languages available for the content items: type: string example: [ ] Definition: type: string example: SD Description: type: string description: The description of the content example: Learn about the wonderful world of numismatics with your host Mike Mezack! Title: type: string description: The title of the content example: Coin Collecting with Mike Mezack Synopsis: type: string description: A more detailed description of the content. example: Learn about the wonderful world of numismatics with your host Mike Mezack and get the opportunity to build your own collection with some of the best deals around! technicals: type: array items: $ref: '#/components/schemas/ProgrammeTechnical' ProgrammeTechnical: additionalProperties: true properties: id: type: string description: The id of the technical content example: GLOBAL_CT0000092941_VERSION_HLS created: type: integer format: int32 description: When the content was ingested into the platform example: 1602708384.0 mainContentRef: type: string description: Reference to the editorial content to which this belongs example: GLOBAL_CT0000092941 period: allOf: - $ref: '#/components/schemas/Period' description: The time period for which the technical asset is valid isLTCU: type: boolean description: Whether the content is long-term catch-up. When true you should see additional properties on the technical related to the original broadcast. example: false isSTCU: type: boolean description: Whether the content is short-term catch-up. example: false deviceType: type: array description: The types of devices that can play this content (derived from profiles) items: type: string example: [ IOS ] ProgramId: type: string description: When LTCU, shows the original broadcast programme id example: GLOBAL_74885_20211012090000 ProgrammeStartDate: type: string description: When LTCU, shows the original start date of the broadcast programme in ISO8601 format. example: 2021-10-12T09:00:00Z ProgrammeEndDate: type: string description: When LTCU, shows the original end date of the broadcast programme in ISO8601 format. example: 2021-10-12T09:25:00Z ServiceId: type: string description: When LTCU, shows the service on which the original programme was broadcast. example: GLOBAL_74885 ServiceLongName: type: string description: When LTCU, shows the service name on which the original programme was broadcast. example: Sky One generateLocation: type: boolean description: Flag signalling that the location should be generated by an additional backend request cdn: type: object properties: type: type: string example: "akamai" description: The type of CDN e.g. Broadpeak id: type: string example: "BP12345" description: The id of the CDN e.g. BP12345 VoDEditorialV2Response: properties: total_records: type: integer description: The number of records, in total, that satisfy your query example: 1 editorials: type: array items: $ref: '#/components/schemas/VodEditorial' VodEditorial: additionalProperties: true properties: id: type: string example: GLOBAL_CT0000092941 description: The id of the content created: type: integer format: int32 example: 1602708239.0 description: When the content was ingested into the platform contentGroups: type: array description: A list of references to groups to which the content belongs. items: type: string example: [ ] nodeRefs: type: array description: A list of references to the nodes to which the content belongs. items: type: string example: [ "GLOBAL_ND0000003243" ] contentLinkId: type: string description: A common content link that ties multiple contents together allowing them to be grouped. example: cid_12345 csaiEnabled: type: boolean example: false description: A flag to signal whether the content supports CSAI (Client-Side Ad Insertion) csaiAdCueTimes: type: array example: [ { "timeOffset": 0, "adDuration": 5 }, { "timeOffset": 10, "adDuration": 5 } ] description: A list of ad cue times for CSAI (Client-Side Ad Insertion) items: type: object properties: timeOffset: type: integer description: The time offset from the start of the content (in seconds) adDuration: type: integer description: The duration of the ad (in seconds) example: { "timeOffset": 0, "adDuration": 5 } csCuesEnabled: type: boolean description: Whether client-side cues should be processed during playback example: true cueProfileId: type: string description: ID of a cue point profile to use for resolving cue points example: "GLOBAL_profile123" csCueList: type: array description: The list of cue point definitions for the content items: $ref: '#/components/schemas/CsCue' contentType: description: The type of the content, e.g. tvshow, movie type: string example: tvshow period: allOf: - $ref: '#/components/schemas/Period' description: The time period for which the content is valid availabilityWindows: type: array description: > Time windows during which the editorial content is available. When present, at least one window must be currently active (start <= now <= end) for the editorial to appear in results. When empty or absent, the editorial falls back to period-based validity via isEditorialValid. items: $ref: '#/components/schemas/Period' example: - start: 1735689600.0 end: 1767225599.0 - start: 1798761600.0 end: 1830297599.0 seriesRef: type: string description: A reference to the series to which the content belongs example: GLOBAL_ND0000003243_Series seasonRef: type: string description: A reference to the season to which the content belongs example: GLOBAL_ND0000003243_Season_1 companyId: type: string description: The source of the content, e.g. Disney, Netflix example: GLOBAL episodeNumber: type: integer format: int32 example: 1 description: The number of the episode if in a series/season duration: type: integer format: int32 description: The length of the content example: 4089 Categories: type: array items: type: string description: The categories to which the content belongs. Category is more general than genre. example: [ "Drama", "Series" ] Genre: type: array items: type: string description: The genre to which the content belongs. Genre is more specific than category. example: [ "Romance" ] PromoImages: type: array items: type: string description: A list of promotional images - generally use of the image service is preferred. example: [ "https://example.com/poster/18Again.jpg" ] Actors: type: array description: A list of the performing actors. items: type: string example: [ "Kim Ha Neul", "Yoon Sang Hyun" ] Directors: type: array description: A list of the directors of the content. items: type: string example: [ ] Producers: type: array description: A list of the producers of the content. items: type: string example: [ ] Writers: type: array description: A list of the writers of the content. items: type: string example: [ ] Rating: allOf: - $ref: '#/components/schemas/Rating' description: The parental rating of the content - generally deprecated by Ratings Ratings: type: array items: $ref: '#/components/schemas/Rating' description: Parental ratings, for various ratings bodies Subtitles: type: array description: List of subtitle languages available for the content items: type: string example: [ ] Audio: type: array description: List of available audio tracks for the content items: type: string example: [ "Korean-Standard" ] AudioMode: type: string description: The audio quality of the content example: "Nicam Stereo" Title: type: string description: The title of the content example: "18 Again" ServiceId: type: string description: If a LTCU or STCU is the id of the channel on which the original programme was broadcast. example: "GLOBAL_12345" Description: description: The description of the content type: string example: "Dae Young (Yoon Sang Hyun) used to be a basketball genius, yet he decided to settle down young. After 20 years, while he’s having trouble with his career and relationship with his wife Da Jung (Kim Ha Neul), he suddenly regains his 18-year-old looks…" technicals: type: array description: List of technical (playable) media for this content items: $ref: '#/components/schemas/VodTechnical' storageAllowed: type: boolean description: Whether the item can be stored locally grouped: description: List of other VoD records, when grouping by content type: array items: $ref: '#/components/schemas/VodEditorial' links: description: List of references to external platforms (e.g. Netflix, Amazon Prime, etc) type: array items: $ref: '#/components/schemas/DeepLink' example: [ { "id": "NFX_123", "name": "18 Again", "contentRef": "GLOBAL_123", "provider": "Netflix", "period": { "start": 1620556200, "end": 1620558000, "duration": 1800 }, "deviceType": [ "IOS" ], "resolution": [ "HD", "4K" ], "original": false, "type": "string", "action": "string", "url": "https://netflix.com/abc/xyz", "playbackOptions": [ { "price": 5.99, "definition": "HD", "currency": "GBP", "license": "string" } ] } ] extras: type: array nullable: true description: >- Optional list of promotions (trailers) attached to the series when requested by the caller (e.g. via the `previewable` query parameter). Absent or empty by default. items: $ref: '#/components/schemas/VodPromotionPreview' VodTechnical: additionalProperties: true properties: id: type: string description: The id of the technical content example: GLOBAL_CT0000092941_VERSION_HLS created: type: integer format: int32 description: When the content was ingested into the platform example: 1602708384.0 mainContentRef: type: string description: Reference to the editorial content to which this belongs example: GLOBAL_CT0000092941 period: allOf: - $ref: '#/components/schemas/Period' description: The time period for which the technical asset is valid isLTCU: type: boolean description: Whether the content is long-term catch-up. When true you should see additional properties on the technical related to the original broadcast. example: false media: allOf: - $ref: '#/components/schemas/Media' description: Details for the playable media deviceType: type: array description: The types of devices that can play this content (derived from profiles) items: type: string example: [ IOS ] products: type: array description: A list of products related to this content. You should be entitled to at least one product to play out the content. items: $ref: '#/components/schemas/Product' ProgramId: type: string description: When LTCU, shows the original broadcast programme id example: GLOBAL_74885_20211012090000 ProgrammeStartDate: type: string description: When LTCU, shows the original start date of the broadcast programme in ISO8601 format. example: 2021-10-12T09:00:00Z ProgrammeEndDate: type: string description: When LTCU, shows the original end date of the broadcast programme in ISO8601 format. example: 2021-10-12T09:25:00Z ServiceId: type: string description: When LTCU, shows the service on which the original programme was broadcast. example: GLOBAL_74885 ServiceLongName: type: string description: When LTCU, shows the service name on which the original programme was broadcast. example: Sky One qmWatermark: type: boolean description: Flag signalling that during license requests the requested content should have Quickmark watermarking enforced storageAllowed: type: boolean description: Whether the item can be stored locally usageRule: type: string description: Rules concerning the usage of the content example: DVR cdn: type: object properties: type: type: string example: "akamai" description: The type of CDN e.g. Broadpeak id: type: string example: "BP12345" description: The id of the CDN e.g. BP12345 Media: additionalProperties: true properties: AV_PlaylistName: properties: fileName: type: string example: https://example.com/Content/DASH_NG/CatchUp/channel(name=9e3a31fa-13ef-15fa-a824-9e7762d2ae05) description: Playout filename uri: type: string example: https://example.com/Content/DASH_NG/CatchUp/channel(name=9e3a31fa-13ef-15fa-a824-9e7762d2ae05) description: Playout uri format: type: string description: Format of the media file drmId: type: string description: Id used to gain entitlement to the media example: xyz drmInstanceName: type: string example: security_device description: Security device providing authentication BlackoutProgrammesResponse: properties: total_records: type: integer description: The number of records, in total, that satisfy your query example: 1 programmes: type: array items: $ref: '#/components/schemas/BlackoutProgramme' BlackoutProgramme: properties: id: type: string example: GLOBAL_14771_20210509103000 description: The identifier of the programme serviceRef: type: string example: GLOBAL_14771 description: The id of the channel on which the programme is broadcast contentRef: type: string example: GLOBAL_14771_20210509103000 description: The identifier of the editorialContent period: allOf: - $ref: '#/components/schemas/Period' description: The broadcast time of the programme blackoutRulesetId: type: string description: The set of rules used against this programme (as configured by BlackoutControlRulesetId) example: Sports blackout: type: object properties: live: type: boolean default: false description: true if live broadcast is banned for the client so: type: boolean default: false description: true if start over is banned for the client cu: type: boolean default: false description: true if any catch up is banned for the client Error: properties: error: type: object properties: code: type: string description: The error code example: "400-000" message: type: string description: A description of the error that occurred example: "Invalid request, connection_type is a required parameter" SecurityInfoResponse: required: - type - drmId - drmInstanceName properties: type: type: string description: The type of content returned example: vod enum: - vod - channel drmId: type: string description: Id used to gain entitlement to the media example: NIKHD_DASH drmInstanceName: type: string example: DASH description: Security device providing authentication cdnId: type: string example: CDN_id_1 description: The identifier of the content w.r.t the CDN on which it is hosted cdnType: type: string example: Broadpeak description: The CDN itself ChangesResponse: properties: total_records: type: integer description: The number of records, in total, that satisfy your query example: 1 changes: type: array items: $ref: '#/components/schemas/Change' Change: properties: id: type: string description: The identifier of the programme or vod example: GLOBAL_14771_20210509103000 action: type: string enum: - add - delete - update - reschedule description: The change being made example: update timestamp: type: integer description: Timestamp of change example: 1643912152 type: type: string enum: - vod - programme - channel start: type: integer description: If a change represents a larger time slice, the start point example: 1643912152 end: type: integer description: If a change represents a larger time slice, the end point example: 1652962122 change: oneOf: - $ref: '#/components/schemas/VodEditorial' - $ref: '#/components/schemas/Programme' VoDPromotionResponse: properties: total_records: type: integer description: The number of records, in total, that satisfy your query example: 1 promotions: type: array items: $ref: '#/components/schemas/VodPromotion' VodPromotion: additionalProperties: true properties: id: type: string example: GLOBAL_CT0000092941 description: The id of the promotion created: type: integer format: int32 example: 1602708239.0 description: When the content was ingested into the platform contentType: description: The type of the content, e.g. tvshow, movie type: string example: tvshow contentRef: description: A reference to the content to which the promotion belongs type: string priority: type: integer description: The priority order of the promotion, in numeric order duration: type: integer format: int32 description: The length of the promotion period: allOf: - $ref: '#/components/schemas/Period' description: The time period for which the content is valid availabilityWindows: type: array description: > Time windows during which the promotion is available. When present, at least one window must be currently active (start <= now <= end) for the promotion to appear in results. When empty or absent, no availability window filtering is applied. items: $ref: '#/components/schemas/Period' example: - start: 1735689600.0 end: 1767225599.0 - start: 1798761600.0 end: 1830297599.0 Ratings: type: array items: $ref: '#/components/schemas/Rating' companyId: type: string description: The source of the content, e.g. Disney, Netflix example: GLOBAL Title: type: string description: The title of the content example: "18 Again" Description: description: The description of the content type: string example: "Dae Young (Yoon Sang Hyun) used to be a basketball genius, yet he decided to settle down young. After 20 years, while he’s having trouble with his career and relationship with his wife Da Jung (Kim Ha Neul), he suddenly regains his 18-year-old looks…" technicals: type: array description: List of technical (playable) media for this content items: $ref: '#/components/schemas/VodPromotionTechnical' VodPromotionTechnical: additionalProperties: true properties: id: type: string description: The id of the technical content example: GLOBAL_CT0000092941_VERSION_HLS created: type: integer format: int32 description: When the content was ingested into the platform example: 1602708384.0 mainContentRef: type: string description: Reference to the editorial content to which this belongs example: GLOBAL_CT0000092941 period: allOf: - $ref: '#/components/schemas/Period' description: The time period for which the technical asset is valid media: allOf: - $ref: '#/components/schemas/Media' description: Details for the playable media deviceType: type: array description: The types of devices that can play this content (derived from profiles) items: type: string example: [ IOS ] ProgrammesForRecordingResponse: properties: total_records: type: integer description: The number of records, in total, that satisfy your query example: 1 programmes: type: array items: $ref: '#/components/schemas/ProgrammeForRecording' ProgrammeForRecording: type: object required: - id - providerId - serviceRef - period - isnPvr properties: id: type: string example: '123' contentRef: type: string example: '456' providerId: type: string description: The unique identifier of the provider of the service, e.g. "sky" example: "GLOBAL" serviceRef: type: string example: '789' contentLinkId: type: string example: '001' period: $ref: '#/components/schemas/Period' airingStartTime: type: integer example: 1000 airingEndTime: type: integer example: 1500 ratings: type: array items: $ref: '#/components/schemas/Rating' title: type: string description: 'Programme Title' storageAllowed: type: boolean example: true isnPvr: type: boolean example: true isLTCU: type: boolean example: false isSTCU: type: boolean example: true metadata: $ref: '#/components/schemas/Metadata' example: { "none": {} } editorial: $ref: '#/components/schemas/EditorialContent' EditorialContent: type: object required: - id - contentType properties: id: type: string example: '456' seriesRef: type: string example: 1 seasonRef: type: string example: 1 episodeNumber: type: integer example: 1 seasonNumber: type: integer example: 1 duration: type: integer example: 900 contentLinkId: type: string example: '001' contentType: type: string example: 'movie' csaiEnabled: type: boolean example: false description: A flag to signal whether the content supports CSAI (Client-Side Ad Insertion) csaiAdCueTimes: type: array example: [ { "timeOffset": 0, "adDuration": 5 }, { "timeOffset": 10, "adDuration": 5 } ] description: A list of ad cue times for CSAI (Client-Side Ad Insertion) items: type: object properties: timeOffset: type: integer description: The time offset from the start of the content (in seconds) adDuration: type: integer description: The duration of the ad (in seconds) example: { "timeOffset": 0, "adDuration": 5 } metadata: $ref: '#/components/schemas/Metadata' example: { "en_US": { "Title": "Saving Private Ryan", "Synopsis": "Following the Normandy Landings, a group of U.S. soldiers go behind enemy lines to retrieve a paratrooper whose brothers have been killed in action.", "Description": "Following the Normandy Landings, a group of U.S. soldiers go behind enemy lines to retrieve a paratrooper whose brothers have been killed in action.", "Language": "English", "Subtitles": "en", "Audio": "English" }, "none": { "Actors": ["Tom Hanks", "Matt Damon"], "Writers": ["Robert Rodat"], "Producers": ["Steven Spielberg"], "Directors": ["Steven Spielberg"], "Categories": ["Drama", "Comedy"], "Genre": ["Action", "Adventure"], "SubGenre": ["Thriller", "Mystery"], "Countries": "GB", "SeasonNumber": 1, "Aspect": "3:4", "AudioMode": "Dolby Atmos", "Color": "BW", "Definition": "4K" } } ratings: type: array items: $ref: '#/components/schemas/Rating' technicals: type: array items: $ref: '#/components/schemas/TechnicalContent' TechnicalContent: type: object properties: id: type: string description: The unique identifier of the technical channel deviceType: type: array description: List of device types that can play the VoD items: type: string isLTCU: type: boolean description: Whether the VoD is long term catch-up isSTCU: type: boolean description: Whether the VoD is short term catch-up serviceId: type: string description: The id of the service example: "GLOBAL_12345" programmeStartDate: type: integer description: The epoch start date of the programme example: 100 programmeEndDate: type: integer description: The iso8601 end date of the programme example: "2023-10-01T11:00:00Z" media: $ref: '#/components/schemas/Media' period: $ref: '#/components/schemas/Period' metadata: $ref: '#/components/schemas/Metadata' Metadata: type: object description: A block of metadata properties. This is a generic object keyed on locale, with each locale (or none) containing a map of arbitrary key-value properties. example: { "none": { "Color": "BW", "Definition": "4K", "Aspect": "16:9", "CUStartDate": 1000, "CUEndDate": 1500 } } additionalProperties: $ref: '#/components/schemas/MetadataLocaleBlock' MetadataLocaleBlock: type: object additionalProperties: type: - object - array - string - number - boolean