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
- Send schedule to the API via POST request in JSON format. The API only supports HTTPS protocol.
- The API supports pushing up to 8 days of schedule at a time.
- 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.
- Changes to current day lineups are not supported.
- Upon a successful push, API should return a success message. If there are one or more invalid fields, API will return an error message.
- Duration for each lineup event must be between 3:00 minutes and 6:00 hours.
- 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.
- Every partner will be provided with a unique API token by Wurl.
- If new data is pushed for a day’s lineup, the new data will overwrite the old data.
- If there is a gap or an overlap in a day’s lineup, that day will go into the backup schedule.
- 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 |
|
MPAA |
|
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 |