VOD content discovery

Summary

A typical client UI application will need to retrieve on-demand content metadata to display to the end-user. On-demand content usually includes movies and TV shows, but can also include music videos, karaoke videos, and so on.

Video on-demand is technically distinct from live broadcast by its delivery mechanism, therefore the content discovery APIs can be separated.

The requests required and how the data is used depend on the requirements of the deployment. Because on-demand metadata cannot be delivered on a broadcast stream in the same way that linear TV metadata can, the method to retrieve the metadata is the same for all devices - over HTTP.

Data models

The basic data models involved in these use cases are described below. All this data can be found in the Metadata Server (MDS). Product subscription data is found in the Service Delivery Platform (see Subscription data).

Nodes

Also known as a catalogue nodes, a node represents a collection of VOD items. A node can contain child nodes, VOD items, or both (though both is rare as it is confusing from a UI prespective). The whole collection of nodes is known as the 'catalogue', and is a tree structure of any depth. Nodes at the top of the tree are known as Root nodes, as they have no parent node. The root nodes should be the first nodes shown to the user when browsing.

Node data model

Name	Type	Description	Localised	Always available
`_id`	String	Internal identifier for the object.	No	Yes
`ancestors`	Array of strings	A list of the IDs of all the nodes above the current one, in order, starting from the highest-level one.	No	Yes
`BarkerChannelRef`	String	The URI of the barker channel promoting this node.	No	No
`children`	Array of strings	A list of IDs of the node's children.	No	Yes
`companyId`	String	The ID of the broadcaster company that is offering the catalogue node.	No	No
`descendants`	Array of strings	A list of IDs of all the nodes below the current one in the tree.	No	Yes
`id`	String	The CMS's identifier for the object.	No	Yes
`isRoot`	Boolean	True if the node is a top-level/root node.	No	Yes
`locale`	String	The locale used for the object's localisable fields.	No	Yes
`nls.Title`	String	Native language support for the title field to allow proper sorting on these fields, rather than utf-8 order.	No	No
`nodeOrder`	Integer	The index of the node, used for explicit ordering of nodes in a parent node or group. Since MDS 1.1STD4.	No	No
`parent`	String	The ID of the node's parent.	No	Yes
`PrivateMetadata`	String	Used to pass data directly from the operator to the end-user device without any CMS/SDP processing. One possible use is to pass a list of keyword/value pairs, separated by semi-colons.	No	No
`PromoImages`	String	A list of promo image URLs. The Metadata Server does not validate the format of this field’s value, and does not attempt to access the URLs to verify the existence of the image files.	No	No
`provider`	String	The identifier of the metadata provider, from the ID of the export's `CMSVodData` element.	No	Yes
`Rating.code`	String	Parental rating code (from the CMS).	No	Yes
`Rating.name`	String	Localized name for the rating, for example, `Adult` or `Adulto`.	Yes	Yes
`Rating.precedence`	Integer	Quantitative rating value.	No	Yes
`regions`	Array of strings	The region identifiers targeted by the catalogue node.	No	No
`title`	String	The name of the catalogue node. This field is not localized. Multi-language clients should use the `Title` field instead.	No	Yes
`Title`	String	The name of the catalogue node.	Yes	Yes
`xml`	String	The type of object. This is always `Node`.	No	Yes

11 reads

VOD item

A VOD item is a scheduled link between a Node and a Technical Content item. It contains information about when the Technical Content should appear in the Node, and its operator-defined display order within that Node. It is also linked to any number of products.

VOD item data model

Name	Type	Description	Localised	Always available
`_id`	String	Internal identifier for the object.	No	Yes
`contentRef`	String	The CMS ID of the technical content that has been scheduled.	No	Yes
`DisplayPriority`	JSON object (see below)	The priority index for this item, which determines its display order in each catalogue node in which it appears.	No	No
`DisplayPriority.<CMS‑id>`	Number	The priority index for this item, which determines its display order when it appears in the catalogue with ID <CMS‑id>.	No	No
`id`	String	The CMS's identifier for this `VodItem`.	No	Yes
`nodeRefs`	Array of strings	The IDs of the catalogues that this item belongs to.	No	No
`period`	JSON object (see below)	The time period this item will appear in the catalogue.	No	No
`period.duration`	Number	The length of time this item will appear in the catalogue, in seconds.	No	No
`period.end`	String: a date and time in ISO 8601 format	The date and time this item will stop appearing in the catalogue.	No	Yes
`period.start`	String: a date and time in ISO 8601 format	The date and time this item will start appearing in the catalogue.	No	Yes
`previewDate`	Date	The date from which this entity can be viewed as "test data". The preview period is between `previewDate` and `period.start` (when the item becomes available to the general public).	No	No
`PrivateMetadata`	String	Generic field used to pass directly data from the customer to the end-user device without any CMS/SDP processing. One possible use it to pass a list of keyword/value pairs, separated by semi-colons.	No	No
`providerId`	String	Unique metadata provider identifier.	No	Yes
`RecommendedVodItemIds`	Array of strings	A list of `VodItem` IDs recommended for this item (information taken from a recommendation engine or from the customer) with rank (a positive integer, where a higher number means a stronger recommendation) using the following pattern: `<ProgrammeId>/<Rank>`	No	No
`title`	String	Technical identification of the `VodItem`.	No	No
`type`	String	The type of this `VodItem`. One of: `catchup` `truevod` `pushvod` `pullvod`	No	No
`xml`	String	The type of the object. Always `VodItem`.	No	Yes

9 reads

Technical content

Technical content contains data about a single delivery mechanism for a Content item. For every delivery mechanism available, there will be a different technical content item. Each technical item contains the information required for the compatible device to be able to playback the content, for example an HLS playlist, RSTP URL, or other identifier. Each technical item contains a list of compatible device types (as defined by the operator) that the device can use to filter the technical content to those it can consume.

The technical content also repeats most of the editorial content metadata, but it could contain some alterations specific to the technical item. Every technical content item belongs to a parent Editorial Content.

Technical content

Name	Type	Description	Localised	Always available
`_id`	String	Internal identifier for the object.	No	Yes
`Actors`	Array of strings	A list of actors. For example: `"Tom Cruise", "Nicole Kidman"`	No	No
`Aspect`	String	The aspect ratio, for example, `16:9` or `Widescreen`.	No	No
`Audio`	Array of strings	A listof "locale-type" patterns representing the audio streams available for this series. locale: three-letter ISO language code type: `VisualImpaired` or `Standard` For example: `"Eng-Standard", "Eng-VisualImpaired", "Fra-Standard"`	No	No
`AudioMode`	String	The audio mode. For example, `Mono`, `SRS`, `THX`, `5.1`, `Nicam Stereo`, or `Dual Mono`.	No	No
`BestSalesIndex`	Integer	Sales index (position) for use in "Top" lists (for example, Top 10 Best Selling). These are positive numbers, starting at 1. If -1 or not present, this series is not in any "Top n" index.	No	No
`Categories`	String	A list of operator-defined category or genre names for this content.	No	No
`companyId`	String	Provider related identifier.	No	No
`ContentType`	String	Free text. Used for implementation-specific data.	No	No
`CopyProtections`	String	A list of usage rules for controlling certain hardware outputs to prevent unauthorised content copying. For example: `"CGMS-A", "HDCP"` If the value is 0 or not present, there is no restriction.	No	No
`Copyright`	String	A copyright message.	Yes	No
`Countries`	String	A string of two-letter ISO codes representing countries relevant to this content.	No	No
`Definition`	String	The video definition. One of `HD`, `SD`, or `3D`.	No	No
`Description`	String	The description of the content.	Yes	No
`Directors`	String	A list of directors.	No	No
`duration`	Number	The approximate duration of the item, in seconds.	No	Yes
`Episode`	String	Localised text representation of the index of the episode in the series. This field is used to display the episode number. For example: `Season 3, Episode 2`	Yes	No
`episodeNumber`	Integer	The index of the episode in the series. This field is used for sorting episodes.	No	No
`id`	String	The CMS's identifier for the object.	No	Yes
`IsRecordable`	Boolean	Whether the end user is allowed to record this series.	No	No
`Language`	String	The original language of the content (three-letter ISO language code).	No	No
`locale`	String	The locale used for the object's localisable fields.	No	Yes
`mainContentRef`	String	The CMS ID of the associated editorial content.	No	Yes
`media`	JSON object	Details of the media stream providing the asset.	No	Yes
`media.{format}.comment`	String	Operational comments of the media.	No	No
`media.{format}.drmId`	String	The content ID assigned by the DRM components. This ID is used to reference the content in the DRM system. This DRM ID is valid in the context of the DRM instance name.	No	No
`media.{format}.drmInstanceName`	String	Name of the DRM instance assigned to the content.	No	No
`media.{format}.fileName`	String	Name of the file on the video server.	No	Yes
`media.{format}.fileSize`	Integer	The file size in bytes.	No	No
`media.{format}.format`	String	The format of the media. Used to identify its type/format. The CMS supports these values: `AV_ClearTS` `AV_EncryptedTS` `AV_PlaylistName` `Data_PMT` `AV_HarmonicOSPlaylistName`	No	No
`media.{format}.frameDuration`	Integer	The duration of the media in frames.	No	No
`media.{format}.id`	String	The CMS's identifier for the media stream.	No	No
`PrivateMetadata`	String	Generic field used to pass directly data from the operator to the end-user device without any processing. One possible use it to pass a listof keyword/value pairs, separated by semi-colons.	No	No
`Producers`	String	A list of producers.	No	No
`profileRef`	String	The CMS ID of the encoding profile that applies to this asset.	No	No
`ProgramId`	String	The ID of the broadcast event that this item relates to.	No	No
`ProgrammeStartDate`	String: a date and time in ISO 8601 format	If the asset represents a catch-up item, the start date and time of the corresponding event.	No	No
`ProgrammeEndDate`	String: a date and time in ISO 8601 format	If the asset represents a catch-up item, the end date and time of the corresponding event.	No	No
`PromoImages`	String	A list of promo image URLs. This must include URL-safe characters only.	No	No
`promoRefs`	String	The CMS IDs of any assets that are trailers for this asset.	No	No
`providerId`	String	The identifier of the metadata provider, from the ID of the export's `CMSVodData` element.	No	Yes
`Rating.code`	String	Parental rating code (from CMS).	No	Yes
`Rating.precedence`	Integer	Quantitative rating value.	No	Yes
`Rating.name`	String	Localised name for the rating, for example, `Adult` or`Adulto`.		Yes
`Scoring`	Integer	Score of the asset.	No	No
`seriesRef`	String	The CMS ID of the series that this episode belongs to.	No	No
`ServiceLongName`	String	If the asset represents a catch-up item, the long name of the service (channel) the event was broadcast on.	No	No
`ShortTitle`	String	The short name of the content.	Yes	No
`Studio`	String	The content owner.	No	No
`Subtitles`	Array of strings	A listof “locale-type” patterns representing the subtitle streams available for this series. locale: 3-letters ISO language code type: `HearingImpaired` or `Standard` For example: `"Eng-Standard", "Eng-HearingImpaired", "Fra-Standard"`	No	No
`Synopsis`	String	A longer description of the asset.	Yes	No
`title`	String	The name of the asset. This field is not localised. Multi-language clients should use the `Title` field instead.	No	Yes
`Title`	String	The name of the asset. The CMS mandates that this field will be populated for at least one locale-form of the asset.	Yes	No
`TotalDownloads`	Integer	Total number of downloads of the content/episode.	No	No
`ViewingNumber`	Integer	How many times a user can watch the content once purchased. If 0 or not present, there is no limitation.	No	No
`xml`	String	The type of the object. Always `technical`.	No	Yes
`Year`	Integer	The year of production of the content.	No	No

21 reads

Editorial content

Editorial content contains editorial metadata about the content, such as title, description, actors, and so on. It also contains a link to a parent Series entity if applicable, and any associated Image metadata.

Editorial data model

This object represents an editorial asset, or "main content" in CMS terms.

Editorial assets contain the content item's editorial metadata. They do not include any information about encoding, stream location, format, or definition. Different encodings of the same editorial asset are represented as technical assets.

Editorial and technical assets have the same fields. The only differences are that editorial assets:

never have a mainContentRef.
never have a media field (sub-object).
have editorial in the xml field, not technical.
do not normally have values for certain technical fields, such as Definition, profileRef, and so on.
have the additional fields listed in the following table.

Name	Type	Description	Localised	Always available
Images	Array of VOD Image data model objects	List of images related to the editorial item Since MDS 1.1.	No	No

For the full list of fields, see the VOD Technical Data Model.

23 reads

Products

An on-demand product is the same as a live content product; it makes content available for a length of time for a specific price. The metadata includes details such as product availability, price, currency, and type. A product can be linked to any number of VOD Items. Likewise, a VOD Item could be linked to any number of products, though it is expected that each product has a different offering, for example, different product types or content.

There are two product types:

Subscription
Transaction

Products

Name	Type	Description	Localised	Always available
`_id`	String	Internal identifier for the object.	No	Yes
`businessProductType`	String	A numeric value provided by the CAS to classify the type of product.	No	No
`casId`	String	The identifier of this product within the CAS. This is the technical ID for all conditional-access-related operations. For the NAGRA CAS, this ID is a numeric value with up to 12 digits.	No	No
`casInstanceName`	String	The name that uniquely identifies the CAS server that manages access to this channel or event.	No	No
`casMopId`	String	The MOP ID assigned by the NAGRA CAS to this product, if applicable. The presence of this value depends upon the CAS features that have been activated for the customer project.	No	No
`endPurchase`	String: a date and time in ISO 8601 format	The end date and time of the period when the end user may purchase this product.	No	No
`endValidity`	String: a date and time in ISO 8601 format	The end date and time of the period when this product is valid. Access to the content/event sold by this product is not allowed after this time.	No	No
`id`	String	The CMS's identifier for the object.	No	Yes
`impulsive`	Boolean	Whether the product can be acquired by the end-user “impulsively”, that is, without requiring a right to be delivered explicitly from the head-end. CMS 4 always sets this field to `true`.	No	No
`isSOCU`	Boolean	Whether start-up and catch-up can be used with this content. For PPV and subscription products, the default is configured in the CMS. For other products, the default value is `false`.	No	No
`ordering`	Boolean	Whether the product can be acquired by the end-user in “ordering” mode, that is, via a right delivered from the head-end. CMS 4 always sets this field to `false`.	No	No
`payMode`	String	Indicates how the product can be paid for when acquired in "ordering" mode. Must be one of: `payableLocally`, `voucher`, or`other`. This field should not be present if `ordering` is `false`.	No	No
`payPerTime`	Boolean	Whether this a pay-per-time product.	No	No
`price`	Sub-object	The prices this product can be purchased for. (See following rows.) MDS only currently supports one price in one currency per product.	No	No
`price.currency`	String	The currency the price is in.	No	Yes
`price.endPurchase`	String: a date and time in ISO 8601 format	The end date and time of the period when the end user may purchase the product at this price.	No	No
`price.providerId`	String	The identifier of the metadata provider, from the `id` of the export's `CMSVodData` element.	No	Yes
`price.startPurchase`	String: a date and time in ISO 8601 format	The start date and time of the period when the end user may purchase the product at this price.	No	No
`price.value`	Number	The value of the price in the specified currency.	No	Yes
`PrivateMetadata`	String	Used to pass data directly from the customer to the end-user device without any processing. One possible use is to pass a list of keyword/value pairs, separated by semi-colons. No validation is done by the Metadata Server on the value of this field.	No	No
`ProfileName`	String	Allows a product to be associated to an externally-managed profile.	No	No
`promotions`	Array of strings	A list of IDs of promotions that apply to this product. Since MDS 1.2.	No	No
`provider`	String	The identifier of the metadata provider, from the `id` of the export's `CMSVodData` element.	No	Yes
`rentalDuration`	Integer	Number of seconds from the first viewing during which a VOD asset can still be watched (for example, `86400`).	No	No
`startPurchase`	String: a date and time in ISO 8601 format	The start date and time of the period when the end user may purchase this product.	No	No
`startValidity`	String: a date and time in ISO 8601 format	The start date and time of the period when this product is valid. Access to the content/event sold by this product is not allowed before this time.	No	No
`title`	String	The name of the product. This field is not localised. Multi-language clients should use the `TitleForProduct` field instead	No	Yes
`TitleForProduct`	String	The name of the product.	Yes	No
`type`	String	The type of product. Must be one of: `subscription`, `single`, `multiple`, or `bundle`. `single` products reference only one content item. `multiple` products reference an immutable selection of content items, payable in a single transaction. `subscription` products reference a mutable selection of content items, payable as a recurring subscription.	No	Yes
`xml`	String	The type of object. Always `Product`.	No	Yes

18 reads

Subscription product

A subscription product is a product that typically has no predefined end date, and incurs a recurring charge on an account for continued access. Access to content contained within only stops if subscription to the product is cancelled or the content stops becoming available within the product.

The typical use case for subscription products in the context of on-demand content is to give long term access to collection of on-demand items.

Transaction product

A transaction product is a product that gives access to content for a limited length of time for a single charge. It can include any number of VOD items.

Series

The Series represents a collection of Content items that belong together, either representing a Season or the whole Series (but currently not both). The Series contains metadata such as a description and promotional image information. It also acts as a link for all related content. Not all content items have a series, and some deployments do not provide this information at all.

Series data model

Name	Type	Description	Localised	Always available
`_id`	String	Internal identifier for the object.	No	Yes
`Actors`	Array of strings	A list of actors. For example: `"Tom Cruise", "Nicole Kidman"`	No	No
`Aspect`	String	The aspect ratio, for example, `16:9` or `Widescreen`.	No	No
`Audio`	Array of strings	A list of "locale-type" patterns representing the audio streams available for this series. locale: three-letter ISO language code type: `VisualImpaired` or `Standard` For example: `"Eng-Standard", "Eng-VisualImpaired", "Fra-Standard"`	No	No
`AudioMode`	String	The audio mode. For example, `Mono`, `SRS`, `THX`, `5.1`, `Nicam Stereo`, or `Dual Mono`.	No	No
`BestSalesIndex`	Integer	Sales index (position) for use in "Top" lists (for example, Top 10 Best Selling). These are positive numbers, starting at 1. If -1 or not present, this series is not in any "Top n" index.	No	No
`Categories`	String	A list of operator-defined category or genre names for this series.	No	No
`ContentType`	String	Free text. Used for implementation-specific data.	No	No
`CopyProtections`	Array of strings	A list of usage rules for controlling certain hardware outputs to prevent unauthorised content copying. For example: `"CGMS-A", "HDCP"` If the value is 0 or not present, there is no restriction.	No	No
`Copyright`	String	A copyright message.	Yes	No
`Countries`	Array of strings	A string of two-letter ISO codes representing countries relevant to this series.	No	No
`Definition`	String	The video definition. One of `HD`, `SD`, or `3D`.	No	No
`Description`	String	The description of the series.	Yes	No
`Directors`	Array of strings	A list of directors.	No	No
`id`	String	The CMS identifier for the object.	No	Yes
`IsRecordable`	Boolean	Whether the end user is allowed to record this series.	No	No
`Language`	String	The original language of the series (three-letter ISO language code).	No	No
`nls.Title`	String	Native language support for the title field, which allows it to be sorted correctly in the local languare rather than using UTF-8 ordering.	No	No
`PrivateMetadata`	String	Generic field used to pass data directly from the operator to the end-user device without any processing. One possible use is to pass a list of keyword/value pairs.	No	No
`Producers`	Array of strings	A list of producers.	No	No
`PromoImages`	Array of strings	A list of promo image URLs. Must contain only URL-safe characters.	No	No
`provider`	String	The identifier of the metadata provider, from the `id` of the export's `CMSVodData` element.	No	Yes
`Rating.code`	String	Parental rating code (from CMS).	No	Yes
`Rating.name`	String	Localised name for the rating, for example, `Adult` or`Adulto`.	Yes	Yes
`Rating.precedence`	Integer	Quantitative rating value.	No	Yes
`Scoring`	Integer	Score of the series.	No	No
`ShortTitle`	String	The short name of the series.	Yes	No
`Studio`	String	The content owner.	No	No
`Subtitles`	Array of strings	A list of “locale-type” patterns representing the subtitle streams available for this series. locale: 3-letters ISO language code type: `HearingImpaired` or `Standard` For example: `"Eng-Standard", "Eng-HearingImpaired", "Fra-Standard"`	No	No
`Synopsis`	String	A longer description of the series.	Yes	No
`title`	String	The name of the series. This field is not localised. Multi-language clients should use the `Title` field instead.	No	Yes
`Title`	String	The name of the series. The CMS mandates that this field will be populated for at least one locale-form of the asset.	Yes	No
`TotalDownloads`	Integer	Total number of downloads of the series (or of episodes within the series, according to the operator's preference).	No	No
`ViewingNumber`	Integer	How many times a user can watch the series (or episodes within it) once purchased. If 0 or not present, there is no limitation.	No	No
`xml`	String	The type of the object. Always `series`.	No	Yes
`Year`	Integer	The year of production of the content.	No	No

7 reads

Content promotions

Also known as "trailers", promotions in this context are content items that promote other content items. They are typically played when looking at an item's media card to give a taste of the full content and motivate the user to play or purchase the content.

Content promotion data model

This object represents a trailer or "promotion" in CMS terms. The objects are organised in a two-level hierarchy. The second level, or promotion "version" holds the details of the playable media file and its metadata. The top-level, or "main" promotion is a container to group together the different media of the same trailer.

Name	Type	Description	Localised	Always available
`_id`	String	Internal identifier for the object.	No	Yes
`Definition`	String	The video definition. One of `HD`, `SD`, or `3D`.	No	No
`duration`	Number	The approximate duration of the trailer, in seconds.	No	Yes
`id`	String	The CMS identifier for the object.	No	Yes
`media`	Sub-object	The media details of the promo. Will only be present in promotion versions.	No	Yes
`media.{format}`	Sub-object	The format of the media object.	No	No
`media.{format}.fileName`	String	The endpoint filename.	No	No
`media.{format}.` `frameDuration`	Number	The duration of the trailer in frames.	No	No
`media.{format}.format`	String	The format of the media promotion.	No	No
`media.{format}.id`	String	The ID of the media promotion.	No	No
`PrivateMetadata`	String	Generic field used to pass directly data from the customer to the end-user device without any CMS/SDP processing. One possible use is to pass a list of keyword/value pairs, separated by semi-colons.	No	No
`profileRef`	String	The CMS ID of the associated encoding profile. Will only be present in promotion versions.	No	No
`provider`	String	The identifier of the metadata provider, from the ID of the export's `CMSVodData` element.	No	Yes
`technicals`	Sub-object	The parent main promotion's child technicals. (There can be one or more.) A list of "VOD Promotion" objects, that is, as defined in this page. Will not be present in promotion versions. Since MDS 1.1.	No	No
`title`	String	The title of the trailer.	No	Yes
`voditem`	Sub-object	A VOD item containing scheduling information about the promotion. Will only be present in promotion versions. For further details, see VodItem Data Model. Since MDS 1.1.	No	No

7 reads

Offer promotions

Promotions in this context are product or offer promotions. They are defined by the operator to incentivise product purchases. The metadata contains details such as promotion description, discount type (percentage or value), discount value, and availability.

Offer promotion data model

In the MDS API, open the NAGRA Media Metadata Server: Delivery API Reference and go to the Promotion JSON object section.

6 reads

Images

Images are used in a number of contexts, including:

Artwork for content, such as "DVD covers" or promotional artwork.
Backgrounds and wallpaper for various views within the client app.

Image data model

In the MDS API, open the NAGRA Media Metadata Server: Delivery API Reference and go to the /metadata/delivery/<provider>/vod/images section.

6 reads

Model graph

The following diagram shows the links between the various models within MDS.

Each model is grouped within the API by which it can be accessed.

Use cases

Subscription information: Use cases regarding retrieval of subscription information is covered on the Subscription data page.

Retrieving catalogue node information

The catalogue node information can be retrieved by using the MDS nodes API. Refer to the MDS API reference, open the document corresponding to the Metadata delivery API and go to the '/metadata/delivery/vod/nodes' section.

Retrieving the root nodes

Root nodes are nodes that are (somewhat confusingly) considered to be at the top of the catalogue tree (but the tree is upside down). These nodes have no parent nodes, and are typically the first nodes the user sees when using a video-on-demand UI. Each node has an isRoot boolean flag, and on root nodes this value is true. Therefore, to retrieve the root nodes, use a query such as:

CODE

http://server:port/metadata/delivery/[provider]/vod/nodes?filter={"isRoot":true, "locale":"en_gb"}&sort=[["nodeOrder",1]]&fields=["id", "Title", "Rating", "Children"]&offset=0&limit=10

The nodeOrder gives the operator/content provider specified nodeOrder, so in the above example you ask for the nodes in that order, instead of ordering it in the UI.

The Children field gives a list of child node identifiers. Typically, most deployments do not mix nodes and content on the same level, so the existence of child nodes can usually be used to determine if the node has child nodes or content. Be aware that if a node has a large amount of child nodes, evaluating the response will comparatively take much longer. This might be more efficient, however, than doing two calls, one to find any nodes, and one to find any assets.

Retrieving the child nodes of a node

Once a user has selected a root node or other node to navigate into, the child nodes of that node should be retrieved to continue navigation. The child nodes of a parent node can be retrieved by specifying the parent node id as a filter. For example, given a parent node with id, "8d2ea53e-b05d-44db-bfb0-624c71415fdb":

CODE

http://server:port/metadata/delivery/[provider]/vod/nodes?filter={"parent":"8d2ea53e-b05d-44db-bfb0-624c71415fdb", "locale":"en_gb"}&sort=[["nodeOrder",1]]&fields=["id", "Title", "Rating", "Children"]&offset=0&limit=10

Retrieving content information

VOD content information is retrieved by using the MDS Editorials API. Refer to the MDS API reference, open the document corresponding to the Metadata delivery API and go to the '/metadata/delivery/vod/editorials' section.

This API provides a specialised structure for client devices that differs from the original source structure. The top level objects, as suggested by the API name, are the editorial content objects (as described above). These contain their related technical content within their structure. Each technical object contains all related products, and finally each product contains all related VodItems. This complete structure is known as an E-T-P-V.

Although the ETPV objects are in a nested structure, each item can be referenced directly without having to specify the whole structure before it. So to get the editorial title use "editorial.Title". For the technical media, use "technical.media", and so on.

ETPV objects have special boolean values that indicate whether the combination is valid (watchable), visible (should be shown in the catalogue), and purchasable based on the current time and their respective schedules. These should be used to ensure that only applicable data is returned to the UI application.

Optimisation: The ETPV objects returned can be very large, as each editorial can have any number of technicals, products and vodItems. You must ensure that you are filtering appropriately, and only request the fields you need. See Optimisation for more details.

E-T-P-V data model

Name	Type	Description	Localised	Always available
`_id`	String	Internal identifier for the object.	No	Yes
`e`	String	Internal identifier for the associated editorial content.	No	Yes
`editorial`	VOD Editorial data model	The associated editorial content.	No	Yes
`isPreviewScreening`	Boolean	Whether this object is part of a test trail (and therefore should be be available to be seen by the general public). Note that this is not related to trailers or promotions, but simply test data.	No	Yes
`isPurchasable`	Boolean	Whether this object can be bought. That is, whether the current date is between the produc's start and end purchase dates.	No	Yes
`isValid`	Boolean	Whether this object is still valid and can therefore be used. That is, whether the current date is between the product's start and end validity dates.	No	Yes
`isVisible`	Boolean	Whether this object is visible in the catalogue. That is, whether the current date is between the `VodItem` period's start and end dates.	No	Yes
`p`	String	Internal identifier for the associated `Product`.	No	Yes
`product`	VOD Product data model	The associated product.	No	Yes
`provider`	String	Identifier for the service provider.	No	Yes
`t`	String	Internal identifier for the associated technical content.	No	Yes
`technical`	VOD Technical data model	The associated technical content.	No	Yes
`v`	String	Internal identifier for the associated `VodItem`.	No	Yes
`voditem`	VOD VodItem data model	The associated `VodItem`.	No	Yes

11 reads

Retrieving the content of a catalogue node for browsing

In this example, you retrieve the content details for contents within a particular node. Because the objective is to build a paged list, you only need the minimum details to render it.

CODE

http://server:port/metadata/delivery/[provider]/vod/editorials?filter={"voditem.nodeRefs":"8d2ea53e-b05d-44db-bfb0-624c71415fdb", "locale":"en_gb", "isVisible":true, "isValid":true, "isPurchasable":true, "voditems.deviceType":"STB", "editorial.region":"Wales"}&sort=[["voditem.DisplayPriority",1]]&fields=["editorial.Title", "editorial.Rating", "editorial.Description", "product.price"]&offset=0&limit=10

Retrieving the detail of a specific asset

Once the user selects an asset to show further information on, the same API is called, but a different filter and fields are used. This time, because you know the specific content, you pass in its id.

CODE

http://server:port/metadata/delivery/[provider]/vod/editorials?filter={"editorial.id":"PBLA3000000773419349_PY", "locale":"en_gb", "voditems.deviceType":"STB"}&sort=[["voditem.DisplayPriority",1]]&fields=["technical.Title", "technical.Rating", "technical.Synopsis", "technical.Actors", "technical.Studio", "technical.Audio", technical.Year","product.price", "product.type", "product.rentalDuration"]&offset=0&limit=10

Retrieving the content of a product

A product can contain multiple assets. In the previous example, the user could be presented with the different purchasing options. They might want to know what other content is also included in the product, if not immediately obvious.

Some of the product's content might not be immediately accessible, so you might want to apply the validity filters. For example:

CODE

http://server:port/metadata/delivery/[provider]/vod/editorials?filter={"product.id":"745aebf7-eb70-4e82-9a38-2798c841ecbb", "locale":"en_gb", "isVisible":true, "isValid":true, "isPurchasable":true, "voditems.deviceType":"STB", "editorial.region":"Wales"}&sort=[["voditem.DisplayPriority",1]]&fields=["editorial.Title", "editorial.Rating", "editorial.Description"]&offset=0&limit=10

Retrieving the members of a series

Given that a user is interested in a series, they might want to look up all members of that series that are available to be watched. You can retrieve this content by using the seriesRef:

CODE

http://server:port/metadata/delivery/[provider]/vod/editorials?filter={"editorial.seriesRef": "Series_2753", "locale":"en_gb", "isVisible":true, "isValid":true, "isPurchasable":true, "voditems.deviceType":"STB", "editorial.region":"Wales"}&fields=["editorial.Title", "editorial.Rating", "editorial.Description"]&offset=0&limit=10

Retrieving the content belonging to an offer promotion

For any offer (for example, 25% discount) you can find all content to which the offer applies by use of the product.promotions field.

For example, say you have a promotion id "25off", you can find all related content using the following query:

CODE

http://server:port/metadata/delivery/[provider]/vod/editorials?filter={"product.promotions": "25off", "locale":"en_gb", "isVisible":true, "isValid":true, "isPurchasable":true, "voditems.deviceType":"STB", "editorial.region":"Wales"}&fields=["editorial.Title", "editorial.Rating", "editorial.Description"]&offset=0&limit=10

Filtering content by age rating

All content should be assigned a given rating, denoting its suitability for certain groups (for example, the UK's age ratings of U, PG, 12, 12A, 15, 18).

In MDS each rating is given a precedence value, allowing them to be sorted numerically. This allows us to display only content suitable for a certain age group or younger, for example:

CODE

http://server:port/metadata/delivery/[provider]/vod/editorials?filter={"editorial.Rating.precedence": {"$lte": 15 }}, "locale":"en_gb", "isVisible":true, "isValid":true, "isPurchasable":true, "voditems.deviceType":"STB", "editorial.region":"Wales"}&fields=["editorial.Title", "editorial.Rating", "editorial.Description"]&offset=0&limit=10

Retrieving VOD product information

The ETPV entities provided by the editorials API contains the product information required when browsing content. It might be necessary, however, to only retrieve a list of products without their associated content, for example, to display a list of currently subscribed products.

Retrieving a list of subscribed products

First retrieve the list of subscribed product ids from the SDP or 3rd party portal that holds the subscription information. See Subscription data.

Then pass this list into the MDS Products API (see link below), using an $in operator.

CODE

http://server:port/metadata/delivery/[provider]/vod/products?filter={"product.id": {"$in": ["d9a775d4-ff5c-4c6e-8a1c-0fa4b47897ee", "3cf22d3e-42ea-4676-8930-29de3e264552", "bc4e2254-f9e0-497b-89ae-19118ed590bc"]}, "locale":"en_gb"}&fields=["title", "price", "rentalDuration", "type"]&offset=0&limit=10

Refer to the MDS API reference, open the document corresponding to the Metadata delivery API and go to the 'metadata/delivery/vod/products' section.

Retrieving VOD series information

VOD series information is available through the MDS Series API. Refer to the MDS API reference page, open the document corresponding to the Metadata delivery API and go to the '/metadata/delivery/vod/series' section.

Retrieving a series by ID

Series elements are linked to editorial content through the seriesRef field. A series can be looked up by id as follows:

CODE

http://server:port/metadata/delivery/[provider]/vod/series?filter={"id": "Series_2753", "locale":"en_gb"}&offset=0&limit=10

Retrieving VOD offer promotions information

VOD offer promotions (such as 25% off) are available for access through the MDS Offers Promotions API. Refer to the MDS API reference, open the document corresponding to the Metadata delivery API and go to the 'Promotion JSON' object section.

Retrieving an offer promotion by id

A product is associated with a promotion through its "promotions" field, which lists the IDs of the related promotions.

To look up a related promotion use the ID reference:

CODE

http://server:port/metadata/delivery/[provider]/offers/promotions?filter={"id": "25off"}&offset=0&limit=10

Retrieving VOD content promotions information

VOD content promotions (trailers) are available for access through the MDS Content Promotions API. Refer to the MDS API reference, open the document corresponding to the Metadata delivery API and go to the /metadata/delivery/vod/promotions section.

Retrieving a content promotion by id

An editorial content is associated with a promotion through its promoRefs field, which lists the IDs of the related promotions.

To look up a related promotion use the ID reference:

CODE

http://server:port/metadata/delivery/[provider]/offers/promotions?filter={"id": "25off"}&offset=0&limit=10

Retrieving VOD image information

VOD images are available in two places.

Retrieving an image from content

Firstly, if associated with some content, they can appear within the MDS Editorials API for convenience. To access these images, add the field "editorials.Images" to your field list.

CODE

http://server:port/metadata/delivery/[provider]/vod/editorials?filter={"voditem.nodeRefs":"8d2ea53e-b05d-44db-bfb0-624c71415fdb"}&fields=["editorial.Images"]&offset=0&limit=10

Retrieving an image by id

If more specific querying of Images is required, or the images are not tied to content, you can use the MDS Images API, as follows:

CODE

http://server:port/metadata/delivery/[provider]/vod/images?filter={"id": "img1"}&offset=0&limit=0

An image references the content to which it is associated through the "illustratedRef" field, and can be either a piece of content or a content promotion.

Refer to the MDS API reference, open the document corresponding to the Metadata delivery API and go to the '/metadata/delivery/vod/images' section.

Retrieving VOD product IDs

Retrieving the products that contain a series

To retrieve the product(s) that contain a specified series, use the functionality provided by the Cloud Application Framework (CAF).

This functionality must be explicitly enabled, as explained in the VoD Series-Product Aggregation section of the CAF User Guide.

To retrieve a list of products, specify the series ID in the filter part of the request:

CODE

http://server:port/caf/vod/series?filter={"<key>":"<value>"}

For example, to perform a search for a series with an ID of 269417:

CODE

http://server:port/caf/vod/series?filter={"id":"269417"}

The response may include zero, one, or multiple products that include the series.

You can also:

Search by other fields.
Add parameters to the request to sort the results, specify which fields to return, limit the number of search results, and so on.

For full details, see the CAF User Guide.

Summary

Data models

Nodes

VOD item

Technical content

Editorial content

Products

Subscription product

Transaction product

Series

Content promotions

Offer promotions

Images

Model graph

Use cases

Retrieving catalogue node information

Retrieving the root nodes

Retrieving the child nodes of a node

Retrieving content information

Retrieving the content of a catalogue node for browsing

Retrieving the detail of a specific asset

Retrieving the content of a product

Retrieving the members of a series

Retrieving the content belonging to an offer promotion

Filtering content by age rating

Retrieving VOD product information

Retrieving a list of subscribed products

Retrieving VOD series information

Retrieving a series by ID

Retrieving VOD offer promotions information

Retrieving an offer promotion by id

Retrieving VOD content promotions information

Retrieving a content promotion by id

Retrieving VOD image information

Retrieving an image from content

Retrieving an image by id

Retrieving VOD product IDs

Retrieving the products that contain a series

See also