Introduction

The Channel v4 APIs allows clients to get information about TV channels that are available in the service. The API reports metadata about the channels as well as configuration details. The API is public requiring no authentication. If configured, the API supports multi-tenancy through Operator Channels.

Entities

Entity	Purpose
Channel	This is a representation of a Channel. It contains metadata information such as name and logo, information about enabled services for the channel and configuration options.

Endpoints overview

Endpoint	HTTP method	Purpose
/api/metadata/v1/channels	GET	Get a paginated list of all available channels.
/api/metadata/v1/channels/{channel_id}	GET	Get information of a specific channel by channel ID

Services

The Channel entity contains a list of enabled services. The entries in that list defines what services are available for the given channel, as well as service-specific attributes specifying how the service can be used.

Available Services for channels

Live

This service enables a user to watch the channel as a live stream.

Service attribute	Type	Description
startover	boolean	The channel live stream can be watched starting from the scheduled start time of the currently airing program.
pause	boolean	The channel live stream can be paused and resumed later where it left off.
trickplay	boolean	The channel live stream can be skipped back and forth within the boundaries of the currently available live stream buffer.

nPVR

This service enables a user to create recordings of programs aired on the channel, allowing them to be streamed on-demand after the program has aired.

Service attribute	Type	Description
watch_ongoing	boolean	Recordings from this channel can be watched while the program is still being aired.
trickplay	boolean	Streams of recordings from this channel can be skipped back and forth.

Catchup

This service enables the user to watch programs that have aired on the channel on-demand for a limited time after they have aired, without having created a recording for the channel.

Service attribute	Type	Description
trickplay	boolean	Streams of catchup items from this channel can be skipped back and forth.

Use cases

Get list of visible channels

Client can make a call to GetIndexChannels to list all visible channels and their necessary information. The response will look like this

GetIndexChannels

{
  "data": [
    {
      "id": "42",
      "type": "Channel",
      "attributes": {
        "name": "Yle",
        "description": "Lozente",
        "images": [
          {
            "image_type": "Thumbnail",
            "alternate_access_description": "Bruce Willis shooting a big gun at some bad guys, pew pew pew",
            "width_pixels": 320,
            "height_pixels": 200,
            "iso_639-2_lang": "fin",
            "url": "https://www.demo.com/assets/img/thumbnails/movies/diehard.png"
          }
        ],
        "channel_number": {
          "default": 1
        },
        "media_type": "video|audio",
        "enabled_services": [
          {
            "type": "Live",
            "startover": false,
            "pause": false,
            "trickplay": false
          },
          {
            "type": "nPVR",
            "watch_ongoing": true,
            "trickplay": true
          },
          {
            "type": "CatchUp",
            "trickplay": false
          }
        ],
        "channel_domains": [
          "foo",
          "bar"
        ],
        "dvb_info": [
          {
            "type": "C|T|T2",
            "onid": 123,
            "tsid": 123,
            "sid": 4324,
            "quality": "SD|HD|UHD"
          }
        ],
        "metadata_provider_information": [
          {
            "provider": "ERICSSON",
            "external_id": "724693092"
          }
        ]
      },
      "relationships": {
        "stream": {
          "data": {
            "id": "24",
            "type": "LiveStream"
          }
        }
      }
    }
  ]
}

The request accepts parameter language to describe channel name and description by the corresponding language. The other param is page[number] so client can get list of channels by page.

The list of channels are paginated and it is configured

Get list of channels including hidden channels

Client can make a call to GetIndexChannels to list all channels and their necessary information. The hidden channel are responded if client requests with parameter "show_hidden=true" . If the param is not requested or "show_hidden=false", the endpoint returns all visible channels.

Get information of channel by id

Client can make a call to GetChannelById to get a specific channel's information. The information of hidden channel is also returned if client knows the channel id. The response looks like this:

GetChannelById

{
  "data": {
    "id": "42",
    "type": "Channel",
    "attributes": {
      "name": "Yle",
      "description": "Lozente",
      "images": [
        {
          "image_type": "Thumbnail",
          "alternate_access_description": "Bruce Willis shooting a big gun at some bad guys, pew pew pew",
          "width_pixels": 320,
          "height_pixels": 200,
          "iso_639-2_lang": "fin",
          "url": "https://www.demo.com/assets/img/thumbnails/movies/diehard.png"
        }
      ],
      "channel_number": {
        "default": 1
      },
      "media_type": "video|audio",
      "enabled_services": [
        {
          "type": "Live",
          "startover": false,
          "pause": false,
          "trickplay": false
        },
        {
          "type": "nPVR",
          "watch_ongoing": true,
          "trickplay": true
        },
        {
          "type": "CatchUp",
          "trickplay": false
        }
      ],
      "channel_domains": [
        "foo",
        "bar"
      ],
      "dvb_info": [
        {
          "type": "C|T|T2",
          "onid": 123,
          "tsid": 123,
          "sid": 4324,
          "quality": "SD|HD|UHD"
        }
      ],
      "metadata_provider_information": [
        {
          "provider": "ERICSSON",
          "external_id": "724693092"
        }
      ]
    },
    "relationships": {
      "stream": {
        "data": {
          "id": "24",
          "type": "LiveStream"
        }
      }
    }
  }
}

The endpoint accepts parameter language to return channel name and description by language.

Migration guide

The legacy endpoint /api/user/<email>/channel is replaced by GetIndexChannels to list all channels

The legacy endpoint /api/user/<email>/channel/<channel_id> is replaced by GetChannelById to list the specific channel.

Postman collection

Table of Contents

Child Pages

Channel v4 client APIs