KPN TV Guide API

  • beta

API reference on SwaggerHub

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

To authenticate you'll need to request an access token. Use your API Store app's credentials (Consumer Key and Consumer Secret) to make an authentication request. The authorization service returns a JSON message that contains the access_token field.

Use one of the following 3 options:

cURL

Execute below cURL command to receive an access token. Replace APP_CONSUMER_KEY and APP_CONSUMER_SECRET with your app's credentials.

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'

If you are using cURL for Windows, please use the command below instead.

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 authentication 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": "6e38edxxxxxxxxxxxxxxxx4065d79c",
    "scope": "",
    "expires_in": "3599",
    "refresh_count": "0",
    "status": "approved"
}

SwaggerHub

  1. Click on the Authorize button on the top right.
  2. In the form, fill in client_id and client_secret, using your app's credentials.
  3. Click Authorize.

Postman

When using Postman, you will have to import the Swagger file into a Postman collection as follows:

  1. Open the API reference on SwaggerHub.
  2. On the top right, click Export, click Download API and click 'YAML Unresolved'.
  3. In Postman from the menu click File and click Import... Choose the YAML file you downloaded in the previous step. A new collection will be added.
  4. Select Get Access Token from the collection.
  5. Make sure the right environment is selected, corresponding to the API.
  6. Edit the environment variables client_id and client_secret, using your app's credentials.
  7. Check the response code and message.
  8. Press the Send button to get an access token.

Note: Request variables are no longer linked to an environment, but to the collection.

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