The Features resources allow clients to retrieve curated selections of TV assets. A Feature collection has two top-level concepts; a feature type and a date range.

The following instructions will help you retrieve a feature of interest.

Firstly, you must select your feature type from the Feature Type Collection endpoint.

{
  "hasNext":false,
  "total":2,
  "item":[
    {
      "id":"bd1d606a-a4ce-56ac-b820-1ca79b394dab",
      "name":"Highlight",
      "namespace":"highlight"
    },
    {
      "id":"545702db-6d63-5811-86d3-78b062824ca4",
      "name":"Monthly",
      "namespace":"monthly"
    }
  ]
}

From this response you must select the feature type you wish to retrieve, the table below explains the values you need.

Property	Example(s)	Description
namespace	highlight monthly	The namespace of the feature type, this is used within the feature endpoint.

Once you have select a feature type namespace you must pass this to the Feature endpoint along with a date or range you are interested in.

🚧
Date Parameter Behaviour
There are two ways to filter the feature collections using dates:

Pass in a single date param
If you specify a single date within the date parameter the result set will only contain one feature item, this is useful for when you are only interested in the feature item for the current time frame.

Pass in a start and end date combination.
The default behaviour is to pass the current date as the start of the range and the end as five months from now.

{
  "hasNext":false,
  "total":1,
  "item":[
    {
      "id":"668d8a9c-0b63-5f9f-8fbe-26d656b01c75",
      "start":"2018-02-01T00:00:00.000Z",
      "end":"2018-02-28T23:59:59.999Z",
      "type":"monthly",
      "selection":[
        {
          "available":"2018-02-01T13:55:00.000Z",
          "attribute":[
            "now-tv"
          ],
          "summary":{
            "long":"A behind-the-scenes look at the latest trip into JK Rowling's wizarding world, including interviews with stars Eddie Redmayne and Colin Farrell",
            "short":"A behind-the-scenes look at the latest trip into JK Rowling's wizarding world"
          },
          "channel":{
            "title":"Sky Cinema Premiere",
            "id":"3a84612c-318d-56a1-8a39-bcff1bd6c2e8"
          },
          "asset":{
            "id":"25460a3b-06c6-5b47-8fd8-de6faf26ecb8",
            "type":"one-off",
            "title":"Fantastic Beasts and Where to Find Them: Special",
            "certification":{

            },
            "meta":{

            },
            "category":[
              {
                "code":"arts-culture",
                "name":"Arts/Culture (without music)"
              },
              {
                "code":"arts-culture:film-cinema",
                "name":"Film/Cinema",
                "dvb":"7600"
              }
            ],
            "attribute":[

            ],
            "summary":{
              "medium":"A behind-the-scenes look at the latest trip into JK Rowling's wizarding world, including interviews with stars Eddie Redmayne and Colin Farrell",
              "short":"A behind-the-scenes look at the latest trip into JK Rowling's wizarding world"
            },
            "related":[

            ],
            "link":[

            ],
            "subject":[
              {
                "code":"programme:patv:2524488",
                "profile":"asset"
              }
            ]
          }
        }
      ]
    }
  ]
}

The table below outlines the structure of a feature and where to get the items that have been selected.

Property	Example(s)	Description
start	2018-02-01T00:00:00.000Z	The start date of the selection
end	2018-02-28T23:59:59.999Z	The end date of the selection
type	monthly	The feature type namespace
selection.available	2018-02-01T13:55:00.000Z	The date the asset is available for viewing
selection.attribute	Data Dictionary Values	Attribute attached to the feature, currently we link on-demand platforms as attributes.
selection.summary	short long	The editorial around the featured asset.
selection.channel	Sky Cinema Premiere	The channel of the selected asset.
selection.asset		The selected asset.

🚧
v1 to v2
See our Migration section for further information on the changes made to this resource between API v1 and v2