TV Guide - KPN


Enrich your platform with TV program and channel data

Complete information on TV content

  • Media

API Button


This API provides you different TV related data services. Currently there are 3 main calls with some of them have 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 information on TV programming and channel.

Conceptual model

General Picture

API workflow

Sequence diagram


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

LIVECHANNELS: Livechannels describe all livechannels available on the platform. Every channel object contains the available details like Name, Description, Type, …, …

SEARCH: By using search certain content items can be requested. By defining filters as parameters and a search query

PROGRAM: Live TV items part of the linear broadcast are defined as PROGRAM

VOD: Movies part of the Video on Demand Catalogue are defined as VOD

EPG: EPG contains the TV Guide data with all the programs occurring in a window of 7 days in the past till 7 days in the future


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

PROGRAM: Details of a Live TV items part of the linear broadcast

VOD: Details of Movies part of the Video on Demand Catalogue


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 \
 '' \
 -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 "" -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",
    "": "",
    "token_type": "BearerToken",
    "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"


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/

You can try the application from different tools/platforms.

Get information related with live channels

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

Get information about VOD

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

Get information about EPG

Gets the information available about the programs in a widnow fo 7 days ahead and 7 days behind. This resource allows set search criterias in order to reach the desired output

Get detailed information about certain content

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

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