browse

Table of Contents


 

Schedule EPG API V3 Overview

The schedule EPG API endpoint provides both schedule and program metadata in the same location. Schedule EPG supports both XML and JSON outputs. 

  • OAuth Authentication:
    • To access the Schedule API, Partners must first authenticate into Wurl’s OAuth API to receive an access token which expires in 1 hour
  • Output Formats:
    • Schedule EPG data can be formatted as .XML or .JSON. The EPG delivers standard metadata depending on the formatting option chosen, listed in detail below on this page .
  • Time Zone Offsets:
    • Schedule EPG is provided in 0 UTC time zone and cannot be offset. If a Channel partner prefers their stream to be delivered in a different time zone from 0 UTC, the Streamer must offset the Schedule EPG’s time zone.
  • Daily Update Time:
    • Schedule EPG is updated once daily at 00:00 UTC. 
  • Days of Data:
    • The Schedule API endpoint provides 7 days of data forward from tomorrow by default. The API can also be queried by day, and by number of days up to 14 days.
  • Backup Metadata: 
    • For certain program fields such as program thumbnails, the EPG sends backup metadata derived from the channel if a Content Company doesn’t provide metadata at the program level.

API OAuth Authentication

Each Wurl partner who ingests Schedule EPG is provided with a unique EPG App UID & Secret at the time of integration. These credentials are used to request the authentication tokens required to access individual channel schedule APIs.

Authentication Instructions

1. Using your EPG App's unique UID & Secret, request a token from the Wurl OAuth API

Request a token from the Wurl authentication provider: https://auth.wurl.com/oauth2/token

Your EPG APP UID and Secret should be added to the request Headers, as follows:

Curl 'https://auth.wurl.com/oauth2/token' \
-X POST \
-H "Authorization: Basic $(echo -n '<uid>:<secret>' | base64)" \
--data-urlencode 'grant_type=client_credentials'

The OAuth API will return a Bearer Token that expires in 3600s (1 Hour). The response is formatted as follows:

{"access_token":<token>,"expires_in":3600,"token_type":"Bearer"}

 

2. Pass the token in the header of your request to the Schedule API

Pass this OAuth token in the header of your request to access the Schedule EPG API data for all channels. The same token may be used to access all channel-specific Schedule APIs that are requested before the token expires (1 hour).

Curl 'https://platform.wurl.com/api/channels/<wurl_channel_slug>/schedule?format=<json or tivo>' \
-
H "Authorization: Bearer <TOKEN>" \ 
-H "Content-Type: application/json" \
-H "Accept: application/json"

A properly formatted request will return the channel's Schedule EPG data in the format requested.

 

API Query Parameters

API endpoint will provide the following parameters to allow support for format and dates. Below are the methods to which a Streamer can query the API:

Base URL 

https://platform.wurl.com/api/channels/<wurl_channel_slug>/schedule?format=<format>&date=<YYYY-MM-DD>&num_days=<#>
  • wurl_channel_slug (required)
    • Required - Unique identifier for the channel, provided by Wurl.
  • format (required)
    • Required - Defines the EPG output format. Options are json (json) or tivo (xml)
  • date (optional)
    • Can be added to grab data for a specific date. The input format is  <YYYY-MM-DD>.
    • If not included, the API will provide tomorrow + 7 days of EPG data.
  • num_days (optional) 
    • Sets the numbers of days of schedule data to be returned by the API, from 1 to 14.
    • When combined with the date parameter, the API will return data for that date + the specified num_days.

 

Schedule XML Metadata Fields

Field

Description

Example

ProgramType

Program Type as defined by the Content Company:

Series, Movie, OTO

OTO

ProgramTitle

Series Title. If no Series title has been added by the content company, the SeriesEpisodeTitle is sent in this value.

Nasa 50th Anniversary

SeriesId

Wurl Episode ID

11246766

SeriesEpisodeNumber

Episode Number, for Series or OTO ProgramTypes only

2

SeriesEpisodeTitle

Episode or Movie title, depending on ProgramType 

Ask Nasa 2

SeriesSeasonNumber

Season Number, For Series or OTO Program Types

3

Runtime

Length of Program in minutes

30

OriginalAirDate

The original TV air date of the program

2021-04-30T14:58:15Z

YearOfRelease

Year of the original TV air date of the program

2021

PgmRating Type

Episode or Channel Rating Type

US TV or MPAA

PgmRating

Episode or Channel Rating value

TV-PG

PgmDescription

Episode Description

Descriptionum Lorem ipsum dolor sit amet.

Image FileLocation

Image URL. If not set at the program level, the Channel thumbnail will be sent.

https://dki01q1l7yn3y7539/Ask-Nasa-2-default_v5.jpeg

Image Type

Image type: Default (Key) or non-default (Supporting). If not set at the program level, the Channel thumbnail will be sent.

Program: Key

Image AssetID

Image ID. If not set at the program level, the Channel thumbnail will be sent.

168172284

Image Title

Image title input in the Scheduler. If not set at the program level, the Channel thumbnail will be sent.

default

Image FileName

Image filename. If not set at the program level, the Channel thumbnail will be sent.

Ask-Nasa-2-default_v5.jpeg

Image FileFormat

Image file format. If not set at the program level, the Channel thumbnail will be sent.

JPEG

Schedule CalendarDT

Schedule Datetime

2021-01-11T00:00:00.000Z

Schedule StartTime

Start time of the Schedule program instance, in UTC

18:00

Schedule Duration

Duration of the Scheduled program instance, in minutes

30

 

Schedule JSON Metadata Fields

Field

Description

Example

id

Unique ID for Wurl Episode

4cc90c26-a6a-11b-5f4-7ef631ed79a

airDate

Schedule Date in UTC

2021-07-24

originalAirDate

The original TV air date of the program

2021-04-30

description

Program Description

Descriptionum Lorem ipsum dolor sit amet.

duration

Duration of the Scheduled program, in minutes

30

episodeNumber

Episode Number, if available.

2

image name

Image title input in the Scheduler. If not set at the program level, the Channel thumbnail will be sent.

default

image width

Image pixel width

1920

image height

Image pixel height

1080

image uri

Image URL. If not set at the program level, the Channel thumbnail will be sent.

https://dki01q1l7yn3y7539/Ask-Nasa-2-default_v5.jpeg

externalIds

Program external IDs, such as TMS ID

as_1671

position

Position of this program in the day's schedule

3

seasonNumber

Season Number, if available.

2

showId

Wurl Series ID

666127

showTitle

Series Title, if available.

Nasa 50th Anniversary

title

Episode Title

Ask Nasa

timeSlot

Start time of the Schedule program instance, in UTC

12:00 AM

timeZone

Schedule Timezone, Schedule EPG is always sent in UTC time.

UTC

 

 

Previous
Next

Was this article helpful?

0 out of 0 found this helpful