beta
KPN

TV Guide - KPN

KPN

Enrich your platform with TV program and channel data

Complete information on TV content

  • Media

API reference on SwaggerHub API reference on Postman

Introduction

The TV Guide API provides you different TV related content services. Currently there are 3 main API calls and some successive calls. The data provided consists of JSON formatted text mainly related to TV content metadata. This data can be used to enrich all sort of platforms with actual TV data.

Conceptual model

Conceptual model

Definitions

Detail

Per content item more metadata can be requested using the content detail call.

EPG

EPG contains the TV Guide data with all the programs occurring 7 days in the past till 7 days in the future.

Livechannels

Livechannels describe all live channels available on the platform. Every channel object contains the available details like name, description, type, etc.

Program

Gives details of Live TV items part of the linear broadcast.

Search

Certain content items can be requested by setting a search query and paramaters for filtering.

Tray

A Tray is a JSON formatted output which consists of Arrays, Booleans, Integers, Strings and Objects defining the layout of the requested metadata.

VOD

VOD gives details of movies that are part of the Video on Demand Catalogue.

API workflow

API workflow

Getting started

The API is divided into 2 groups of resources:

  • Catalog: Groups resources to retrieve information from the catalog of contents.

  • Item: Groups resources to retrieve detailed information related to specific content from specific types.

Authentication

Oauth 2.0

For accessing and/or manipulating the resources, the client application (your application) needs to be granted permission to do so. The OAuth 2.0 standard defines a protocol that allows such third-party authorization through the use of access tokens. Access tokens are central in the protocol: those tokens, in the form of strings, are delivered by an authorization server (our authentication server) and they enable the client application to securely access protected data on behalf of the resource owner (the end-user).

We use Client Credentials Grant which means the application makes the request to the authentication service by sending authorization credentials and the service responds with an access token among other useful information

Get Access Token

Copy your app's credentials and replace APP_CONSUMER_KEY and APP_CONSUMER_SECRET with the copied values, then execute below curl command to receive access token.

curl -X POST \
 'https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials' \
 -H 'content-type: application/x-www-form-urlencoded' \
 -d 'client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET'

Note: If you are using curl for Windows then please use below command.

curl -X POST "https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials" -H "content-type: application/x-www-form-urlencoded" -d "client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET"

The authorization service returns a JSON message that contains the access token field.

{
    "refresh_token_expires_in": "0",
    "api_product_list": "[xxxxxxx]",
    "api_product_list_json": [
        " xxxxxxx"
    ],
    "organization_name": "kpn",
    "developer_email": "demo123@kpn.com",
    "token_type": "Bearer",
    "issued_at": "1521039195424",
    "client_id": "APP_CONSUMER_KEY",
    "access_token": "haf2SDl07E9N7RluNQ4kJ1TkGgso",
    "application_name": "6e38ed2d-48b1-4362-97d6-04254065d79c",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

How to...

Get information related with live channels

Gets the information available from channels and allows filtering to customize results.

Filter name   Description
from   Starting value of pagination
to   Ending value of pagination
maxResults  Max number of items to be retrieved
query   Free text search applied to channel name
filter_isAdult   Return the channels with the isAdult flag set or unset
filter_channelIds   Return the programs belonging to the specified channel id list
filter_chanellType  Return the channels of the given channel group (standard or extended)
filter_types  Return the channels of the given type (LIVE, PPVVAR, MUSIC, BARKER)
orderBy   Specify the channels sorting (orderId, name)
sortOrder   Specify the sorting order (asc, desc)


Get information about VOD

Gets the information available for Video On Demand, allows you to set the search criteria.

Filter name   Description
from   Starting value of pagination
to   Ending value of pagination
maxResults  Max number of items to be retrieved
query   Free text search applied to channel name
filter_contentType   Return the contents with the specified content type (VOD, BUNDLE, GROUP_OF_BUNDLES)
filter_contentSubtype   Return the contents with the specified contentsubtype
filter_contentTypeExtended   Return the contents with the specified filter_contentTypeExtended. (VOD, TVOY)
filter_parentId   Returns the contents belonging to the specified parent contentId. The parentId can be a Season ID or a Series ID
filter_title   Return the contents with the specified title. The title is a string that fully or partially matches with the searched contents
filter_year   Return the contents with the specified publishing year. The year is an integer in the format YYYY
filter_categoryId   Return the contents with a specific category identifier. The categoryId is an integer value
filter_genres   Return all the programs of the given genres if the filter_genreOperator is "or" or "not specified"
filter_genresOperator   To be used in combination with filter_genres. Defines the operator to be used in the query for filter_genre (and, or)
filter_seriesIds   Return all the episodes of the specified list of seriesIds. Note that this seriesId is not related to the parentId and it's not referred to any contentId
filter_season   Return all the episodes of the given season
filter_quality   Return the contents tagged with at least one of the input quality
filter_fuzzy   Adds AUTO fuzziness on the query string when activated (True, False)
orderBy   Specify the channels sorting (orderId, name)
sortOrder   Specify the sorting order (asc, desc)
outputFormat   Specify the format of the output to be returned (STANDARD, EXTENDED)


Get information about EPG

Gets the information available about the programs for 7 days ago and 7 days in the future. This resource allows to set search criteria in order to reach the desired output.

Filter name   Description
filter_startTime   An unix timestamp expressed in milliseconds
filter_endTime   An unix timestamp expressed in milliseconds
filter_day   Useful when you want all programs of a given day. It can be used for both past / future days. This filter calculates on its own the Summer/Winter time offsets. Using the filter_startTime and filter_endTime those offsets have to be calculates from the client application. Note: Mandatory if filter_startTimeand filter_endTime not set.
filter_channelIds   Return the programs belonging to the specified channel id list
outputFormat   Specify the format of the output to be returned (STANDARD, EXTENDED)


Get detailed information about certain content

Gets detailed information about different content identified by their ID and type.

The content type is called contentType and its values can be PROGRAM or VOD. The content identifier is a string that identifies the content and is called contentId.

Return codes

Code   Meaning
200   Success
201   Created
202   Accepted
400   Bad request
401   Unauthorized
404   Not Found
405   Method not Allowed
412   Precondition failed
429   Too many requests
500   Internal server error
502   Bad gateway
503   Service unavailable

Changelog

Version   Description
1.0   Initial version