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.

Note: Schedule Ingestion Behavior

When a new schedule file is ingested, the system treats it as a full replacement of all future schedule data. At the time of ingestion, all existing schedule entries beyond the current day are cleared and replaced with the contents of the newly provided file.

As a result, any dates not included in the latest schedule delivery will be removed from the system, even if they were previously provided.

Requirement:
To ensure uninterrupted schedule continuity, each schedule delivery must include all dates that should remain available, including any overlap with previously published schedules.

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. 

Channel

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

"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.

"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’.

*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.

"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.

"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.

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

USA Ratings Scales Preferred by most US Streamers:

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.

"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. 

"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.