Hey, how can we help?

browse

Overview

Wurl Programming API provides a solution to deliver Electronic Programing Guide (EPG) information to Wurl for a restreaming channel. The content metadata will be used and repackaged in the proper format to populate the EPG on a Streamer. This guide provides a specification and guidelines for how to integrate with the Wurl Programming API - Restreaming EPG endpoint.


Description

  1. Send schedule to the API via POST request in JSON format. The API only supports HTTPS protocol.
  2. The API supports pushing up to 8 days of schedule at a time.
  3. All schedules, except the current day, will be cleared each time a new lineup is pushed through API. It’s recommended to send the next 7 days’ lineups every time.
  4. Changes to current day lineups are not supported.
  5. Upon a successful push, API should return a success message. If there are one or more invalid fields, API will return an error message.
  6. Duration for each lineup event must be between 3:00 minutes and 6:00 hours.
  7. Wurl requires posting the schedule at least 2 days before the airing date. Streamers have various caches periods, so this ensures your schedule will be delivered accurately on time.
  8. Every partner will be provided with a unique API token by Wurl.
  9. If new data is pushed for a day’s lineup, the new data will overwrite the old data.
  10. If there is a gap or an overlap in a day’s lineup, that day will go into the backup schedule.
  11. If there is no EPG or lineup information pushed for a lineup day, that day will go into the backup schedule.

Request Name

Will be provided during your integration

Request Method 

POST

Protocol

HTTPS Only

Function

Deliver Electronic Programming Guide (EPG) data for restreaming.

 

JSON Structure

The section will describe the list of fields supported by the API. We’ll note the data type, field formatting and required fields in this section. Complete JSON Schema file and JSON example found here: JSON Schema, JSON Example

 

Root Node

Required. 

Field

Data Type

Remarks

channel

Channel

Required. Root node

 

Channel

Required. This section is where the channel to deliver the EPG/lineup is specified. 

Field

Data Type

Remarks

wurl_channel_slug

string

Required. Max 255

title

string

Required. Max 255

broadcast_url

string

Required. Valid URL

language

string

Required. ISO 639-1

programs

Program

Required.

events

Event

Required.

genres

Genre

Optional

 

"type": "object",
"properties": {
"channel": {
"type": "object",
"oneOf": [
{
"properties": {
"wurl_channel_slug": { "$ref": "#/definitions/string_255_not_null" },
"title": { "$ref": "#/definitions/string_255_not_null" },
"broadcast_url": { "$ref": "#/definitions/url" },
"language": { "$ref": "#/definitions/language" },
"genres": {"type": "array", "items": [ { "$ref": "#/definitions/genre"} ] },
"events": {"type": "array", "items": [ {"$ref": "#/definitions/event"} ] },
"programs": {"type": "array", "items": [ {"$ref": "#/definitions/program"} ] }
},
"required": ["wurl_channel_slug", "title", "broadcast_url", "language", "programs", "events"]
},
}
]
}
"required": ["channel"]
}
{
"channel": {
"wurl_channel_slug": "your-channel-slug",
"title": "Kutch, Kuhlman and Swift",
"broadcast_url": "http://broadcast_url_here",
"language": "de",
"genres": [
{
"source": "FOX",
"key": "25H6V",
"name": "Biography/Autobiography"
},
{
"source": "ROKU",
"key": "3HC9T",
"name": "Speech"
}
],

 

Program 

Required. This section is where metadata for each program is delivered. When using ‘programs’ the events should have a program_key attribute referencing a unique key for the program. A ‘key’ for an episode must match the ‘program_key’ under the ‘Event’ section for the API to successfully identify the episodes and match the metadata.

Field

Data Type

Remarks

key

string

Required. Max 255. Referenced by events program_key. Must be unique

title

string

Required. Max 255

external_id

string

Optional. Max 255

content_type

string

Required. [episode, movie, shortFormVideo, tvSpecial]

series

Series

Required. if content_type is 'episode'

short_description

string

Optional. Max 255

description

string

Optional

iab_categories

string array

Optional

release_date

Date

Optional, format 'YYYY-MM-DD'

thumbnails

Thumbnail array

Optional. Min 1280x720

genres

Genre array

Optional

ratings

Rating array

Optional

credits

Credit array

Optional

 

"program": {
"type": "object",
"properties": {
"key": { "$ref": "#/definitions/string_255_not_null" },
"title": { "$ref": "#/definitions/string_255_not_null" },
"short_description": { "$ref": "#/definitions/string_255" },
"description": {"type": "string"},
"content_type": {
"type": "string",
"enum": ["episode", "movie", "shortFormVideo", "tvSpecial"]
},
"iab_categories": {
"type": "array",
"items": [ { "$ref": "#/definitions/string_255" } ]
},
"release_date": { "$ref": "#/definitions/release_date" },
"thumbnails": {
"type": "array",
"items": [ { "$ref": "#/definitions/thumbnail" } ]
},
"genres": {
"type": "array",
"items": [ { "$ref": "#/definitions/genre" } ]
},
"ratings": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"source": {"type": "string"},
"rating": {"type": "string"}
},
"required": ["source", "rating"]
}
]
},
"credits": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"name": {"type": "string"},
"role": {
"type": "string",
"enum": ["actor", "director", "producer", "writer", "author"]
},
"description": { "type": "string" }
},
"required": ["name", "role"]
}
]
},
"series": {
"type": "object",
"properties": {
"title": { "$ref": "#/definitions/string_255_not_null" },
"release_date": { "$ref": "#/definitions/release_date" },
"description": {"type": "string"},
"studio": { "$ref": "#/definitions/string_255" },
"thumbnails": {
"type": "array",
"items": [
{ "$ref": "#/definitions/thumbnail" }
]
},
"season": {
"type": "object",
"properties": {
"title": { "$ref": "#/definitions/string_255" },
"number": {"type": "integer"},
"episode_number": {"type": "integer"},
"release_date": { "$ref": "#/definitions/release_date" }
},
"required": ["number", "episode_number"]
}
},
"required": ["description", "thumbnails", "season"]
}
},
"required": ["key", "title", "content_type", "thumbnails"]
},

Event 

Required. The events section is used to deliver schedule data. This data will build the lineup using the time slots field. The schedule event will be mapped to the corresponding program metadata using the ‘program_key’.

Field

Data Type

Remarks

program_key

string

Required. max 255 and should match a Program key

time_slot*

DateTime

Required. ISO 8601

duration

integer

Required. duration in seconds.

*time_slot ISO 8601 format example: “2020-12-11T13:42:42Z"

"event": {
"type": "object",
"oneOf": [
{
"properties": {
"program_key": { "$ref": "#/definitions/string_255_not_null" },
"time_slot": {"type": "string", "format": "date-time"},
"duration": { "$ref": "#/definitions/duration" }
},
"required": ["program_key", "time_slot", "duration"]

Thumbnail 

Optional: Providing thumbnails are strongly recommended for providing a rich experience for your viewers. This section defines specifications to provide thumbnails. It’s to be used with the Program section of the API. Please check your Streamer’s requirements within the Wurl Support portal. If your service requires thumbnails, then this section is required.

Field

Data Type

Remarks

url

string

Required. Valid URL

width

integer

Required

height

integer

Required

type

string

Optional. Represents mime type like image/png

ratio

string

Optional. Example 16:9, 4:3, etc

 

"thumbnails": [
{
"url": "http://thumbnail_url_here",
"type": "image/png",
"width": 600,
"height": 900,
"ratio": "2_3"
},
{
"url": "http://thumbnail_url_here/lucien",
"type": "image/png",
"width": 600,
"height": 900,
"ratio": "2_3"
}
],

 

Genre

Optional: This section defines specifications to provide genres. It’s to be used with the Program section of the API. Please check your Streamer’s requirements within the Wurl Support portal. If your service requires the genres, then this section is required.

Field

Data Type

Remarks

source

string

Required. Max 255

key

string

Required. Max 255

name

string

Optional. Max 255

 

"genres": [
{
"source": "Nielsen",
"key": "T1I91",
"name": "Western drama"
},
{
"source": "ROKU",
"key": "LDYQL",
"name": "Drama"
},
{
"source": "IAB",
"key": "G431W",
"name": "Entertainment"
}

 

Rating

Optional: This section defines specifications to provide ratings. It’s to be used with the Program section of the API. Please check your Streamer’s requirements within the Wurl Support portal. If your service requires the ratings, then this section is required.

Field

Data Type

Remarks

source

string

Required. Max 255

rating

string

Required. Max 255

 

"ratings": [
{
"source": "TVPG",
"rating": "TV-G"
},
{
"source": "MPAA",
"rating": "G"
}
],

USA Ratings Scales Preferred by most US Streamers:

Rating Source Preferred Values
TVPG
  • TV-G, or TVG

  • TV-Y, or TVY

  • TV-Y7, or TVY7

  • TV-14, or TV14

  • TV-PG, or TVPG

  • TV-MA, or TVMA

MPAA
  • G

  • PG

  • PG-13, or PG13

  • R

  • NC-17

 

 

Credit

Optional.This section defines specifications to provide credit. It’s to be used with the Program section of the API. Please check your Streamer’s requirements within the Wurl Support portal. If your service requires the credit, then this section is required.

Field

Data Type

Remarks

name

string

Required. Max 255

role

string

Required. [actor, director, producer, writer, author]

description

string

Optional

 

"credits": [
{
"name": "Ludo Bagman",
"role": "actor",
"description": "Always pass on what you have learned."
},
{
"name": "Astoria Greengrass",
"role": "writer",
"description": "All my possessions for a moment of time."
},
{
"name": "Graham Montague",
"role": "actor",
"description": "Contact the tower"
},
{
"name": "Neville Longbottom",
"role": "producer",
"description": "All my possessions for a moment of time."
},
{
"name": "Frank Bryce",
"role": "writer",
"description": "All my possessions for a moment of time."
}
]
},

 

Series

Required if ‘content_type’ is 'episode'. To be used with the Program section of API in order to define series metadata. 

Field

Data Type

Remarks

title

string

Required. Max 255

description

string

Required. Max 200

season

Season

Required

release_date

Date

Optional. format 'YYYY-MM-DD'

studio

optional

Optional. Max 255

thumbnails

Thumbnail array

Optional. Min 1280x720

 

"series": {
"title": "Buffy",
"description": "I can kill a couple of geeks all by myself. But, hey, if you'd like to watch... I mean, that's what you Watchers are good at, right? Watching?",
"release_date": "1971-03-18",
"studio": "Cruickshank LLC",
"thumbnails": [
{
"url": "http://thumbnail_url_here/diego",
"type": "image/png",
"width": 600,
"height": 900,
"ratio": "2_3"
}
],
"season": {
"title": "Season 2",
"number": 2,
"episode_number": 3,
"release_date": "1971-03-18"
}
}
},

 

Season 

Required if ‘content_type’ is 'episode'. To be used with the Program section of API in order to define season metadata. 

Field

Data Type

Remarks

number

integer

Required

episode_number

string

Required

release_date

Date

Optional. format 'YYYY-MM-DD'

title

string

Optional. Max 255

 

 

 

 

 

 

 

Previous
Next

Was this article helpful?

41 out of 50 found this helpful