Feature

Details for feature resource

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.

PropertyExample(s)Description
namespacehighlight
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:

  1. 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.

  2. 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.

PropertyExample(s)Description
start2018-02-01T00:00:00.000ZThe start date of the selection
end2018-02-28T23:59:59.999ZThe end date of the selection
typemonthlyThe feature type namespace
selection.available2018-02-01T13:55:00.000ZThe date the asset is available for viewing
selection.attributeData Dictionary ValuesAttribute attached to the feature, currently we link on-demand platforms as attributes.
selection.summaryshort
long
The editorial around the featured asset.
selection.channelSky Cinema PremiereThe channel of the selected asset.
selection.assetThe selected asset.

🚧

v1 to v2

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