EPG Feed Guide

This page explains how to fetch our electronic programme guide (EPG) and how to read the data. The feed is available as XMLTV, JSON and iCalendar and always contains the latest approved schedule.

01Overview

• Read-only: the feed cannot change anything.
• Always current: every request is built live from the approved schedule. Changes still awaiting internal approval are never published.
• Local time: all times are local channel time (Europe/Zurich) with the UTC offset included, so summer and winter time are handled correctly.
• UTF-8: all text is UTF-8, without HTML tags or invisible control characters.

02Your feed link

You will normally receive a personal link containing an access token. The token identifies you; please keep it confidential. If it is ever compromised, we can revoke it and send you a new one.

Both forms return exactly the same data. Use whichever form you were given.

03Choosing the time range

Without parameters you receive the default range set by the channel (for example yesterday plus the next 7 days). Add a query string to request a specific period:

Dates are always written YYYY-MM-DD. Parameters can be added to both link forms:

<token>.xml?date=2026-10-20
?t=<token>&f=json&from=2026-10-20&to=2026-10-26

04XMLTV

One <channel> followed by the programmes in chronological order. Standard XMLTV according to the official xmltv.dtd, in DTD element order. Elements without a value are omitted (no empty tags), so receivers such as TVHeadend, Jellyfin, Plex or Enigma2 read the feed without workarounds. Only <title> and the ciegolink ID are always present.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tv SYSTEM "xmltv.dtd">
<tv generator-info-name="CiegoLink EPG Planer" generator-info-url="https://ciegolink.com" source-info-name="Example TV" source-info-url="https://example.tv">
  <channel id="example.tv">
    <display-name lang="de">Example TV</display-name>
    <icon src="https://…/uploads/logo-1a2b3c4d.png"/>
    <url>https://example.tv</url>
  </channel>
  <programme start="20261020201500 +0200" stop="20261020214500 +0200" channel="example.tv">
    <title lang="de">Tatort</title>
    <sub-title lang="de">Der Fall Müller</sub-title>
    <desc lang="de">Kommissarin Weber ermittelt …</desc>
    <category lang="en">Movie / Drama</category>   <!-- 1st: DVB genre -->
    <category lang="de">Krimi</category> <!-- 2nd: channel category -->
    <length units="minutes">90</length>
    <icon src="https://…/uploads/20261018-154401-704fcde2.jpg"/>
    <episode-num system="xmltv_ns">11.4.</episode-num>
    <episode-num system="onscreen">S12E05</episode-num>
    <episode-num system="ciegolink">t044473196da4-202610202015</episode-num>
  </programme>
</tv>

• start / stop: YYYYMMDDhhmmss ±hhmm in local time with offset.
• Language: lang (two-letter code of the channel's main language, e.g. de) on <display-name>, <title>, <sub-title>, <desc> and the channel category. The DVB genre is always the official English term with lang="en". The full list of channel languages is in the JSON feed.
• <category>: first the DVB genre, then the channel's own category – each only if set.
• <episode-num>: xmltv_ns and onscreen only if season or episode is known; ciegolink (unique broadcast ID) is always present. Receivers ignore unknown systems.
• <rating system="explicit"><value>yes</value></rating> appears only for explicit content (adults only). XMLTV has no dedicated explicit flag; this is the usual way to carry it.

05JSON

The same data as XMLTV plus channel languages and contact details. Every field is always present: empty texts are "", missing numbers are null.

{
  "generator": "CiegoLink EPG Planer",
  "generated": "2026-10-18T18:40:00+02:00",
  "timezone": "Europe/Zurich",
  "from": "2026-10-20T00:00:00+02:00",
  "to": "2026-10-21T00:00:00+02:00",
  "channel": {
    "id": "example.tv",
    "name": "Example TV",
    "language": "de-CH",
    "languages": ["de-CH", "fr-CH"],
    "logo": "https://…/uploads/logo-1a2b3c4d.png",
    "url": "https://example.tv",
    "contact": { "phone": "+41 44 123 45 67", "email": "epg@example.tv" }
  },
  "programmes": [
    {
      "id": "t044473196da4-202610202015",
      "show_id": "s29aaffabc8b7",
      "start": "2026-10-20T20:15:00+02:00",
      "stop": "2026-10-20T21:45:00+02:00",
      "duration": 90,
      "title": "Tatort",
      "subtitle": "Der Fall Müller",
      "description": "Kommissarin Weber ermittelt …",
      "season": 12,
      "episode": 5,
      "episode_label": "S12E05",
      "genre": "film",
      "genre_name": "Movie / Drama",
      "dvb_content": "0x1",
      "category": "Krimi",
      "image": "https://…/uploads/20261018-154401-704fcde2.jpg",
      "explicit": false
    }
  ]
}

06iCalendar (ICS)

Paste the .ics link into your calendar app as a subscription (not an import), so it updates automatically.

• One event per broadcast. SUMMARY is the title.
• DESCRIPTION contains season/episode, subtitle and description.
• CATEGORIES contains the genre and category, IMAGE the programme image.
• UID is the programme ID (see Programme IDs), so calendar apps update events instead of duplicating them.

07Field reference

Genres (DVB)

The genre follows the content descriptor of ETSI EN 300 468 (content_nibble_level_1), so it can be mapped directly into DVB EIT.

Season & episode

xmltv_ns counts from zero and has the form season.episode.part; unknown parts stay empty.

Programme IDs

Each broadcast has an ID of the form <series-id>-<YYYYMMDDhhmm>. The time part is the broadcast's originally planned slot.

• The ID stays the same when a single broadcast is edited or moved.
• The ID changes when a whole recurring series is moved to a new time.

08HTTP, caching & errors

• Caching: responses may be cached for 60 seconds (Cache-Control: public, max-age=60).
• Polling: fetching every 15 to 60 minutes is plenty. Please do not poll more than once per minute.
• CORS: enabled (Access-Control-Allow-Origin: *), so the JSON feed can be loaded directly from a web page.
• Content types: application/xml, application/json and text/calendar, all UTF-8.

09Integration checklist

1. Store your link with the token securely, e.g. as a secret in your configuration rather than in public code.
2. Map our channel ID (<channel id="…">) to your channel. It only changes after prior notice.
3. Fetch the default range every 15–60 minutes, or request specific days with ?date= or ?from=…&to=….
4. Replace all programmes of the fetched range with the response.
5. Use the first <category>, or dvb_content in JSON, for genre mapping to DVB EIT.
6. Show sub-title and the onscreen episode number where your EPG has room for them.