Retrieve event recordings and requests

Request

To retrieve recordings and/or requests for the user, send a GET request to:

CODE

https://<host>:<port>/cdvr/v2/recordings

This returns all the recordings/requests for the user, whether they are individual event recordings or ones that form part of a series recording request.

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

You are recommended to use locale and device type filtering – they can greatly reduce the size of the response. This can improve performance on low-end devices.

Headers

Content-Type: application/json
Authorisation

Mandatory arguments

None

Optional arguments (in URL)

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:
CODE
```
&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
distinct – return only the most recently recorded episode per series (only valid when type=SERIES).
type – the type of recordings to include in the response:
- INDIVIDUAL – individual programme recordings or episodes that are part of a series but that were recorded individually
- SERIES – recordings made as part of a series recording (that is, where all episodes of the series are to be recorded)

Examples

The results of these requests can be displayed together in a similar way to a rail.

Get only non-series recordings

To get only individual recordings, that is, recordings that are not part of a series recording (though they may be individual episodes of a series), send a GET request to:

CODE

https://<host>:<port>/cdvr/v2/recordings?type=INDIVIDUAL

This returns recordings ordered by age (newest first).

Get only series recordings

To get only series recordings, that is, recordings that were recorded as the result of a series recording request, send a GET request to:

CODE

https://<host>:<port>/cdvr/v2/recordings?type=SERIES

This returns recordings ordered by age (newest first).

Get the latest recorded episode of each series

To get the latest recorded episode of each series, send a GET request to:

CODE

https://<host>:<port>/cdvr/v2/recordings?type=SERIES&distinct=true

This returns only the latest recorded episode for each series, ordered by age (newest first).

The response includes the SeriesTitle in the metadata section of each recording, which you can use to easily label the recording with the title of the series.

Get recordings for only one locale and device type

To get only the recordings for the specified locale and device type (to minimise the size of the response and to remove the need to filter it on the client), send a GET request like this:

CODE

https://<host>:<port>/cdvr/v2/recordings?local=en_us&deviceType=android

Get all scheduled recordings

To get a list of all scheduled recordings, send a GET request to:

CODE

https://<host>:<port>/cdvr/v2/recordings?statuses=SCHEDULED

The results include both series and non-series recording requests. These are ordered by time till next recording (soonest first).

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:

JSON

{
  "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,
      "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",
      "failureReason": "string"
    }
  ]
}

Request

Headers

Mandatory arguments

Optional arguments (in URL)

Examples

Get only non-series recordings

Get only series recordings

Get the latest recorded episode of each series

Get recordings for only one locale and device type

Get all scheduled recordings

Response

Example

See also