Skip to content
Dag Wieers edited this page Feb 3, 2021 · 19 revisions

The JSON-EPG format is an alternative format for the XMLTV format (as used by Kodi's PVR IPTV Simple add-on) to list TV and Radio channel EPG data with all required metadata.

JSON-EPG format

This is a draft for version 1 of the standard.

The key used in the epg dictionary should be the same as the id of the channel in the JSON-STREAMS format. This will be used to link the data to the right channel.

Attributes

Attribute Required Description
start Yes The start time of the program in ISO-8601 datetime format.
stop Yes The end time of the program in ISO-8601 datetime format.
title Yes The title of the program.
description No The description of the program.
subtitle No The subtitle of the program. This can be the Episode name.
episode No The episode number in case of a show in the S01E01 format.
genre No The genre of this program.
image No A URL to an image for this program.
date No The original air date for this program.
credits No A list of credits for this program.
stream No An direct plugin://-url to play this program.

More information

  • start and stop
    The start and end times for a program is in the ISO-8601 format (YYYY-MM-DDTHH:MM:SSor YYYY-MM-DDTTHH:MM:SS+HH:MM). If timezone information is missing, than UTC (Z) is implied.

  • credits
    An optional list of credits can be supplied for this program. A credit is an object with the property type that can be actor, director, writer, adapter, producer, composer, editor, presenter, commentator or guest, and a property name that contains the name of the person. For the type actor, an optional property role can be added to give the name of the character that is played.

    Examples:

    • {"type": "director", "name": "David Benioff"}
    • {"type": "writer", "name": "George R.R. Martin"}
    • {"type": "actor", "name": "Kit Harington", "role": "John Snow"}
  • stream
    This is the endpoint that will be called when this program should play. It will be used to directly play a program from the EPG.

    Example: plugin://plugin.video.example/play/catalog/f71549ba-f985-41c3-916a-6cc3b3305b83

Example

{
  "version": 1,
  "epg": {
    "een.be": [
      {
        "start": "2020-04-01T12:45:00",
        "stop": "2020-04-01T12:50:00",
        "title": "My Show",
        "genre": "Quiz",
        "description": "Description of My Show",
        "subtitle": "Episode name for My Show",
        "episode": "S01E05",
        "image": "https://www.example.com/shows/my-show/s01e05.png",
        "date": "2018-04-01",
        "stream": "plugin://plugin.video.example/play/catalog/3F2504E0-4F89-11D3-9A0C-0305E82C3301",
        "credits": [
          {
            "type": "director",
            "name": "David Benioff"
          },
          {
            "type": "director",
            "name": "D.B. Weiss"
          },
          {
            "type": "writer",
            "name": "George R.R. Martin"
          },
          {
            "type": "actor",
            "name": "Kit Harington",
            "role": "Jon Snow"
          },
          {
            "type": "actor",
            "name": "Emilia Clarke",
            "role": "Daenerys Targaryen"
          }
        ]
      }
    ],
    "radio1.be": [
      {
        "start": "2020-04-01T12:45:00",
        "stop": "2020-04-01T12:50:00",
        "title": "My Show",
        "description": "Description of My Show",
        "subtitle": "Episode name for My Show",
        "episode": "S01E05",
        "image": "https://www.example.com/shows/my-show/s01e05.png",
        "date": "2018-04-01"
      }
    ]
  }
}

Useful references

The following links may help you understand the original XMLTV format: