Retrieve recordings for an account

Request

To retrieve recordings for an account, the operator should send a GET request to:

CODE

https://<host>:<port>/cdvr/v2/operator/recordings/accounts/{accountId}

Note that this is an operator API and should not be called by a client application.

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

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.

Note that rails can also be configured to display the user’s recordings – see Add content to a rail.

Headers

Content-Type: application/json
tenantId – the tenant ID
Authorisation

Mandatory arguments

accountId (in URL) – the ID of the account to retrieve recordings for

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
period.start – only include recordings from after the specified time (in Unix epoch seconds).
This is typically used together with period.end to specify a time window.
period.end – only include recordings from before the specified time (in Unix epoch seconds).
This is typically used together with period.start to specify a time window.

Examples

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

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.

If the specified account cannot be found, the request returns an HTTP 404 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,
      "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",
      "failureReason": "string"
    }
  ]
}

Request

Headers

Mandatory arguments

Optional arguments (in URL)

Examples

Get recordings for only one locale and device type

Get all scheduled recordings

Response

Example

See also