Retrieve recordings for a specific series

Request

To retrieve recordings and recording requests for a specific series, send a GET request to:

https://<host>:<port>/cdvr/v2/recordings/series/{seriesId}

This API supports:

• Filtering by status. This means that you can get a list of all recordings, or a list of all scheduled requests (that have not yet been recorded), and so on.

• Filtering by recording type (individual or series).

• Filtering by recording IDs. This allows you to supply a list of recording IDs and get the details for just these recordings.

• Filtering by locale.

• Filtering by device type.

• Filtering by time window.

• Limit on the number of records returned and specify paging.

• Sorting results chronologically by broadcast date or by expiration date (ascending or descending in both cases).

• Sorting results by the length of the duration of the recording (ascending or descending in both cases).

• Sorting results on programme name in alphabetical order / reverse alphabetical order.

• Optionally limiting the results to those specifically requested 

Headers

• Content-Type: application/json

• Authorisation

Mandatory arguments

• seriesId – the ID of the series for which to retrieve recordings

Other arguments (in URL)

• limit – the limit – the number of records to return

• page – the page number to return (cannot be used without limit)
  For example:

  • ?limit=10 returns the first 10 recordings.

  • ?limit=10&page=2 returns the second 10 recordings.

• sort – the sort order of the returned recordings. It can be one of:

  • CHRONOLOGICAL_ASC

  • CHRONOLOGICAL_DESC

  • EXPIRATION_ASC

  • EXPIRATION_DESC

  • DURATION_ASC

  • DURATION_DESC

  • METADATA_ASC

  • METADATA_DESC

• sortField – the metadata field used for sorting if METADATA_ASC or METADATA_DESC is specified in sort. It can be one of:

  • TITLE

  • SYNOPSIS

  • DESCRIPTION

  • SEASON_NUMBER

  • EPISODE_NUMBER

  • EPISODE

  • DEFINITION

  • YEAR

• sortLocale – the locale to be used for sorting. Only required if METADATA_ASC or METADATA_DESC is specified in sort.

• genericSort – generic sort that allows you to sort the results by one or more fields. If you specify multiple fields, the results will be sorted by the first specified field, then the second, and so on.
  You must append :1 or :-1 to specify whether the sort is ascending (1) or descending (1-).
  For example, to sort by title, then series number, then episode number, add this to the query:

  &genericSort={
       "programmeMetaData.title":1,
       "programmeMetaData.editorial.seriesRef":1,
       "programmeMetaData.editorial.episodeNumber":1
  }
  

• statuses – filters based on recording status. Available values are:

  • SCHEDULED

  • RECORDING

  • RECORDED

  • FAILED

  • NEW

  To specify multiple values (e.g., if you want to get both scheduled and recorded requests), use the statuses parameter as many times as required.
  For example:

  ?statuses=SCHEDULED&statuses=RECORDED

• filter – a generic filter that allows you to filter the results based on the value of any field

• fields – the fields to include in the response

• locale – the locale to filter by. If not specified, the default locale will be used. If neither the specified nor the default locale is available, all locales will be returned. Note that the 'none' metadata locale is common in all instances.

• deviceType – the device type to filter by

Response

A successful request returns an HTTP 200 status.

A bad request returns an HTTP 400 status.

An unauthorised request returns an HTTP 401 status.

Example

A successful request returns a payload that looks like this:

[
  {
    "totalRecords": 1,
    "recordingSet": [
      {
        "id": "7c589755-dbdf-434f-a6a8-666fdac06d28",
        "eventId": "eastenders_10297",
        "start": "2018-10-19T01:00:00.000Z",
        "end": "2018-10-19T01:30:00.000Z",
        "captureStart": "2018-10-19T01:00:00.000Z",
        "captureEnd": "2018-10-19T01:30:00.000Z",
        "status": "RECORDED",
        "channelId": "bbc1",
        "duration": 1800,
        "seriesRecordingId": "Friends",
        "captureDuration": 1800,
        "csaiEnabled": true,
        "csaiAdCueTimes": [
          {
            "timeOffset": 0,
            "adDuration": 0
          }
        ],
        "availability": {
          "start": "2018-10-19T01:01:01.001Z",
          "end": "2999-10-19T01:01:01.001Z"
        },
        "contentId": "eastenders_10297c",
        "contentType": "movie",
        "seriesId": "Friends",
        "seasonId": "Friends Season 1",
        "isReschedule": true,
        "isProtected": true,
        "productRefs": [
          "productRefOne"
        ],
        "Categories": [
          "News",
          "Sports"
        ],
        "tvChannel": "Channel Number : 500 ",
        "ratingPrecedence": {
          "predecessor": "12",
          "successor": "15"
        },
        "playback": {
          "iPad": {
            "drmId": "d1",
            "uri": "/xyz/a.ts"
          },
          "Android": {
            "drmId": "d2",
            "uri": "/xyz/b.ts"
          }
        },
        "images": {
          "additionalProp1": "string",
          "additionalProp2": "string",
          "additionalProp3": "string"
        },
        "tmsId": "EP021174500086",
        "InHomeBlockingRequired": false,
        "guardTime": {
          "startSecs": 0,
          "endSecs": 0,
          "source": "CONFIG"
        },
        "isPartiallyRecorded": false,
        "metadata": {
          "en_GB": {
            "title": "Die Hard",
            "description": "John McLane blah blah blah",
            "synopsis": "John McLane blah blah blah"
          }
        },
        "creationDate": "2018-10-19T01:00:00.000Z",
        "modifiedDate": "2018-10-19T01:00:00.000Z",
        "isjitp": true,
        "sourceId": "SOURCE1",
        "networkLocation": "string",
        "recordId": "string",
        "failureReason": "string"
      }
    ]
  }
]

See also

For full details of this API, see NPVR User Recordings API documentation v2.