Retrieve content information
VOD content information is retrieved by using the MDS Editorials API. This API provides a specialised structure for client devices that differs from the source structure. As suggested by the API name, the top-level objects are the editorial content objects (as described above). These then 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.
Since the 20.37 (2020 Q3) release, the default for the isVisible and isValid flags is true. (Previously, the default was false.)
If you need to get information about invalid and/or not visible content, set the flag(s) to false in your request.
Starting with version 20.51, there is an alternative data model that makes associating products with content easier. MDS added a new API for retrieving content information for deployments that use the newer, editorial-based model:
- If you are still using the technical-based model, you must use the original API – see Retrieving content information – technical model.
- If you use the editorial-based model, you must use the newer API – see Retrieving content information – editorial model.
Retrieving content information – technical model
E-T-P-V data model
Although the ETPV objects are in a nested structure, each item can be referenced directly without specifying the whole structure before it. So to get the editorial title, it is just editorial.Title; for the technical media, it is just technical.media and so on. ETPV objects have special boolean values that indicate whether or not 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 Best practices for more details.
Retrieving the content of a catalogue node for browsing
In this example, the content details for contents within a particular node are retrieved. Since the objective is to build a paged list, only the minimum details are required to render it.
http://server:port/metadata/delivery/[provider]/vod/editorials?filter={"voditem.nodeRefs":"8d2ea53e-b05d-44db-bfb0-624c71415fdb", "locale":"en_gb", "isPurchasable":true, "voditems.deviceType":"STB", "editorial.region":"Wales"}&sort=[["voditem.DisplayPriority",1]]&fields=["editorial.Title", "editorial.Rating", "editorial.Description", "product.price"]&offset=0&limit=10Retrieving the details of a specific asset
Once the user selects an asset to show further information on, the same API is called again using a different filter and fields. This time, since the specific content is known, its ID is passed in.
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=10Retrieving the content of a product
A product may contain multiple assets. In the previous example, the user could be presented with the different purchasing options; they may want to know what other content is included in the product if not immediately apparent. Some of the product content may not be immediately accessible so that validity filters may be applied.
http://server:port/metadata/delivery/[provider]/vod/editorials?filter={"product.id":"745aebf7-eb70-4e82-9a38-2798c841ecbb", "locale":"en_gb", "isPurchasable":true, "voditems.deviceType":"STB", "editorial.region":"Wales"}&sort=[["voditem.DisplayPriority",1]]&fields=["editorial.Title", "editorial.Rating", "editorial.Description"]&offset=0&limit=10Retrieving the members of a series
A user interested in a series may want to look up all members of that series that are available to be watched. This content can be retrieved using the seriesRef.
http://server:port/metadata/delivery/[provider]/vod/editorials?filter={"editorial.seriesRef": "Series_2753", "locale":"en_gb", "isPurchasable":true, "voditems.deviceType":"STB", "editorial.region":"Wales"}&fields=["editorial.Title", "editorial.Rating", "editorial.Description"]&offset=0&limit=10Filtering content by age rating
All content should be assigned a given rating, denoting its suitability for certain groups (for example, the UK's age rating of U, PG, 12, 12A, 15, 18). In MDS, each rating is given a precedence value, allowing them to be sorted numerically. This allows only content suitable for a particular age group or younger to be displayed, for example:
http://server:port/metadata/delivery/[provider]/vod/editorials?filter={"editorial.Rating.precedence": {"$lte": 15 }}, "locale":"en_gb", "isPurchasable":true, "voditems.deviceType":"STB", "editorial.region":"Wales"}&fields=["editorial.Title", "editorial.Rating", "editorial.Description"]&offset=0&limit=10Retrieving content information – editorial model
E-T-P data model
The E-T-P model is similar to the E-P-T-V mode, except that it does not include the vodItem.
Although the ETP objects are in a nested structure, each item can be referenced directly without specifying the whole structure before it. So to get the editorial title, it is just 'editorial.Title'; for the technical media, it is just 'technical.media' and so on. ETPV objects have special boolean values that indicate whether or not 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 ETP objects returned can be very large, as each editorial can have any number of technicals and products. You MUST ensure that you are filtering appropriately and only request the fields you need. See Best practices for more details.
Retrieving the content of a catalogue node for browsing
In this example, the content details for contents within a particular node are retrieved. Since the objective is to build a paged list, only the minimum details are required to render it.
http://server:port/metadata/delivery/v2/[provider]/vod/editorials?filter={"voditem.nodeRefs":"8d2ea53e-b05d-44db-bfb0-624c71415fdb", "locale":"en_gb", "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 details of a specific asset
Once the user selects an asset to show further information on, the same API is called again using a different filter and fields. This time, since the specific content is known, its ID is passed in.
http://server:port/metadata/delivery/v2/[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 productA product may contain multiple assets. In the previous example, the user could be presented with the different purchasing options; they may want to know what other content is included in the product if not immediately apparent. Some of the product content may not be immediately accessible, so validity filters may be applied.
http://server:port/metadata/delivery/v2/[provider]/vod/editorials?filter={"product.id":"745aebf7-eb70-4e82-9a38-2798c841ecbb", "locale":"en_gb", "isPurchasable":true, "voditems.deviceType":"STB", "editorial.region":"Wales"}&sort=[["voditem.DisplayPriority",1]]&fields=["editorial.Title", "editorial.Rating", "editorial.Description"]&offset=0&limit=10Retrieving the members of a series
A user interested in a series may want to look up all members of that series that are available to be watched. This content can be retrieved using the seriesRef.
http://server:port/metadata/delivery/v2/[provider]/vod/editorials?filter={"editorial.seriesRef": "Series_2753", "locale":"en_gb", "isPurchasable":true, "voditems.deviceType":"STB", "editorial.region":"Wales"}&fields=["editorial.Title", "editorial.Rating", "editorial.Description"]&offset=0&limit=10
Filtering content by age ratingAll content should be assigned a given rating, denoting its suitability for certain groups (for example, the UK's age rating of U, PG, 12, 12A, 15, 18). In MDS, each rating is given a precedence value, allowing them to be sorted numerically. This allows only content suitable for a particular age group or younger to be displayed, for example:
http://server:port/metadata/delivery/v2/[provider]/vod/editorials?filter={"editorial.Rating.precedence": {"$lte": 15 }}, "locale":"en_gb", "isPurchasable":true, "voditems.deviceType":"STB", "editorial.region":"Wales"}&fields=["editorial.Title", "editorial.Rating", "editorial.Description"]&offset=0&limit=10Retrieving a list of subscribed products
The list of subscribed product ids is retrieved from the SDP or 3rd party portal holding the subscription information and then passed into the MDS Products API using an $in operator.
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=100