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://bernhard.co/richard",
    "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
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://krajcik.net/jack",
    "type": "image/png",
    "width": 600,
    "height": 900,
    "ratio": "2_3"
  },
  {
    "url": "http://blick.name/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
season	Season	Required
release_date	Date	Optional. format 'YYYY-MM-DD'
studio	optional	Optional. Max 255
thumbnails	Thumbnail array	Optional

"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://hirthe.net/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

Wurl Programming API: Restreaming EPG Endpoint Specification

browse