EPG Source Management¶

EPG sources (Electronic Program Guide) provide program information for each channel: program names, start and end times, descriptions, genres, and age ratings.

What is an EPG Source¶

An EPG source in Catena is a link to an external XML file with TV program schedules. The system periodically downloads this file and synchronizes program data for display in client applications.

Key capabilities:

Automatic synchronization — regular download and update of program guide
Multiple source support — different EPG sources for different channel groups
Download monitoring — tracking status and results of EPG updates
Program viewing — retrieving schedules via API for integration

Typical workflow:

Create an EPG source with XML file URL specified
Configure automatic update period
Link channels to EPG source (in channel settings)
System automatically downloads and updates program guide
Subscribers see current program guide in applications

Main EPG Source Parameters¶

Technical Parameters¶

Source ID (EPG Source ID)

Automatically generated when creating a source
Format: base64-encoded Snowflake ID with +/= replaced by -_.
Example: aKl9SW3AAAE.
Used for programmatic access via API
Not editable after creation

Source Name (Name)

Unique technical name of the EPG source
Used for identification in the system and in channel settings
Examples: main-epg, sports-epg, xmltv-provider

Portal ID

Identifier of the portal the source belongs to
Automatically set upon creation

Download Parameters¶

Source URL (URL)

Full URL to XML file with program guide
Supported protocols: HTTP, HTTPS
Example: https://epg.example.com/epg.xml
Required field

Update Period (Period)

Interval in days for automatic EPG update
Example: 7 — update every 7 days
Minimum value: 1 day
If not specified, default value is used
The system automatically downloads EPG according to the specified period without manual intervention

Last Download Result¶

Download Information (Last Fetch Result)

The last_fetch_result field contains information about the last EPG update:

fetched_at — time of last download (ISO 8601)
job_id — download job identifier
status — download status:
success — successfully downloaded
error — download error
timeout — timeout exceeded
message — text message about result
channels — number of updated channels
foundPrograms — number of programs found in XML
importedPrograms — number of imported programs
deletedPrograms — number of deleted old programs
fetchDuration — XML download time in seconds
importDuration — data import time in seconds

Creating an EPG Source¶

Via Web Interface¶

Open the "EPG Sources" section in the Catena control panel
Click the "Create EPG Source" button
Fill in required fields:
Name — technical source name (e.g., main-epg)
URL — full URL to EPG XML file
Fill in optional fields:
Period — update period in days (e.g., 7)
Save the source
Start initial download via "Update Now" button

After creation, the source will receive a unique ID and will be available for linking to channels.

Via Management API¶

curl -X POST https://your-catena-domain.com/tv-management/api/v1/epg-sources \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "main-epg",
    "url": "https://epg.example.com/xmltv.xml",
    "period": 7
  }'

Response:

{
  "epgSourceId": "eKl9SW3AAAE.",
  "portalId": "pKl9SW3AAAE.",
  "name": "main-epg",
  "url": "https://epg.example.com/xmltv.xml",
  "period": 7,
  "last_fetch_result": null
}

Viewing EPG Source List¶

Via Web Interface¶

The "EPG Sources" section displays a table with all sources:

Name — source name (Name)
URL — XML file address
Period — update interval in days
Last Update — date and time of last download
Status — result of last download (success/error/timeout)
Programs — number of imported programs
Actions — update, edit, and delete buttons

Via Management API¶

Get list of all EPG sources:

curl -X GET https://your-catena-domain.com/tv-management/api/v1/epg-sources \
  -H "X-Auth-Token: your-api-key"

Response:

{
  "epgSources": [
    {
      "epgSourceId": "eKl9SW3AAAE.",
      "portalId": "pKl9SW3AAAE.",
      "name": "main-epg",
      "url": "https://epg.example.com/xmltv.xml",
      "period": 7,
      "last_fetch_result": {
        "epgSourceId": "eKl9SW3AAAE.",
        "fetched_at": "2024-10-16T10:30:00Z",
        "job_id": "job123",
        "status": "success",
        "message": "EPG source fetched successfully",
        "channels": 25,
        "foundPrograms": 5000,
        "importedPrograms": 4950,
        "deletedPrograms": 2100,
        "fetchDuration": 5,
        "importDuration": 12
      }
    }
  ]
}

Getting Source Information¶

Via Management API¶

curl -X GET https://your-catena-domain.com/tv-management/api/v1/epg-sources/eKl9SW3AAAE. \
  -H "X-Auth-Token: your-api-key"

Response: Similar to EPG source object from the list.

Editing an EPG Source¶

Via Web Interface¶

Open the EPG sources list
Find the needed source and click the "Edit" button
Change parameters:
Name — technical name
URL — XML file address
Period — update period
Save changes

Note: Changing URL or period does not trigger automatic update — use "Update Now" button for immediate download.

Via Management API¶

curl -X PUT https://your-catena-domain.com/tv-management/api/v1/epg-sources/eKl9SW3AAAE. \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "main-epg",
    "url": "https://epg.example.com/updated-xmltv.xml",
    "period": 3
  }'

Forced EPG Update¶

You can trigger an unscheduled EPG update at any time.

Via Web Interface¶

Open the EPG sources list
Find the needed source
Click the "Update Now" button
Wait for completion — process may take from several seconds to minutes

Via Management API¶

curl -X POST https://your-catena-domain.com/tv-management/api/v1/epg-sources/eKl9SW3AAAE./update \
  -H "X-Auth-Token: your-api-key"

Response:

{
  "jobId": "job456"
}

Important: Update is performed asynchronously. Use jobId to track progress or check the last_fetch_result field after some time.

Deleting an EPG Source¶

Via Web Interface¶

Open the EPG sources list
Find the source to delete
Click the "Delete" button
Confirm deletion

Warning: When deleting an EPG source:

All programs from this source will be deleted
Channels linked to this source will lose EPG connection
Subscribers will stop seeing program guide for these channels

Via Management API¶

curl -X DELETE https://your-catena-domain.com/tv-management/api/v1/epg-sources/eKl9SW3AAAE. \
  -H "X-Auth-Token: your-api-key"

Viewing Programs from EPG Source¶

You can get a list of programs for analysis or debugging.

Getting Programs via API¶

Get all programs from source:

curl -X GET https://your-catena-domain.com/tv-management/api/v1/epg-sources/eKl9SW3AAAE./programs \
  -H "X-Auth-Token: your-api-key"

Filter by date:

curl -X GET "https://your-catena-domain.com/tv-management/api/v1/epg-sources/eKl9SW3AAAE./programs?date=2024-10-16" \
  -H "X-Auth-Token: your-api-key"

Filter by channel:

curl -X GET "https://your-catena-domain.com/tv-management/api/v1/epg-sources/eKl9SW3AAAE./programs?epgChannelName=channel1" \
  -H "X-Auth-Token: your-api-key"

Combined filtering:

curl -X GET "https://your-catena-domain.com/tv-management/api/v1/epg-sources/eKl9SW3AAAE./programs?date=2024-10-16&epgChannelName=channel1" \
  -H "X-Auth-Token: your-api-key"

Response:

{
  "programs": [
    {
      "programId": "prKl9SW3AAAE.",
      "portalId": "pKl9SW3AAAE.",
      "epgSourceId": "eKl9SW3AAAE.",
      "epgChannelName": "channel1",
      "date": "2024-10-16",
      "start": "2024-10-16T12:00:00Z",
      "end": "2024-10-16T13:00:00Z",
      "title": "News",
      "language": "en",
      "description": "Main news of the day",
      "genre": "News",
      "rating": "0+"
    }
  ],
  "next": "cursor-for-next-page"
}

Pagination:

curl -X GET "https://your-catena-domain.com/tv-management/api/v1/epg-sources/eKl9SW3AAAE./programs?cursor=cursor-for-next-page" \
  -H "X-Auth-Token: your-api-key"

Viewing EPG Update History¶

Catena automatically saves the history of all EPG updates, allowing you to track download success, analyze issues, and monitor source performance.

Automatic EPG Updates¶

How automatic updates work:

The system automatically triggers EPG updates according to each source's period parameter
Updates are performed in the background without system downtime
Each update is recorded in history with complete result information
Upon successful update, new programs become immediately available to subscribers

Benefits of automatic updates:

No manual intervention required to keep EPG current
Program guide always stays up-to-date for subscribers
Ability to track all update attempts and identify issues

Viewing History via Web Interface¶

The EPG source page displays:

Recent update history — table with all download attempts
Date and time of each update
Status — success/error/timeout
Statistics — number of found, imported, and deleted programs
Duration — download and import time
Error messages (if any)

Getting History via API¶

Get history of all EPG updates:

curl -X GET https://your-catena-domain.com/tv-management/api/v1/epg-fetches \
  -H "X-Auth-Token: your-api-key"

Filter by specific source:

curl -X GET "https://your-catena-domain.com/tv-management/api/v1/epg-fetches?epgSourceId=eKl9SW3AAAE." \
  -H "X-Auth-Token: your-api-key"

Pagination:

curl -X GET "https://your-catena-domain.com/tv-management/api/v1/epg-fetches?cursor=cursor-for-next-page" \
  -H "X-Auth-Token: your-api-key"

Response:

{
  "epgFetches": [
    {
      "epgFetchId": "fKl9SW3AAAE.",
      "epgSourceId": "eKl9SW3AAAE.",
      "created_at": "2024-10-16T10:25:00Z",
      "fetched_at": "2024-10-16T10:30:00Z",
      "job_id": "job123",
      "status": "success",
      "message": "EPG source fetched successfully",
      "channels": 25,
      "foundPrograms": 5000,
      "importedPrograms": 4950,
      "deletedPrograms": 2100,
      "fetchDuration": 5,
      "importDuration": 12
    },
    {
      "epgFetchId": "fKl9SW3AAAA.",
      "epgSourceId": "eKl9SW3AAAE.",
      "created_at": "2024-10-09T10:25:00Z",
      "fetched_at": "2024-10-09T10:29:00Z",
      "job_id": "job122",
      "status": "success",
      "message": "EPG source fetched successfully",
      "channels": 25,
      "foundPrograms": 4800,
      "importedPrograms": 4750,
      "deletedPrograms": 1950,
      "fetchDuration": 4,
      "importDuration": 10
    }
  ],
  "next": "cursor-for-next-page"
}

Update History Fields¶

Main history record fields:

epgFetchId — unique identifier of update attempt
epgSourceId — EPG source identifier
created_at — time when update task was created (ISO 8601)
fetched_at — time when download actually completed (ISO 8601)
job_id — background job identifier
status — update status:
success — successfully downloaded and imported
error — an error occurred
timeout — timeout exceeded
message — text description of result
channels — number of updated channels
foundPrograms — total programs found in XML file
importedPrograms — programs successfully imported to database
deletedPrograms — outdated programs deleted
fetchDuration — XML file download time (seconds)
importDuration — data processing and import time (seconds)

Analyzing Update History¶

Using history for monitoring:

Tracking stability — verify that updates occur regularly
Identifying issues — find records with error or timeout status
Performance analysis — track download and import times
Data quality control — compare program counts between updates

Usage examples:

# Check recent updates with errors
curl -X GET "https://your-catena-domain.com/tv-management/api/v1/epg-fetches" \
  -H "X-Auth-Token: your-api-key" | jq '.epgFetches[] | select(.status != "success")'

# Get average import time for a source
curl -X GET "https://your-catena-domain.com/tv-management/api/v1/epg-fetches?epgSourceId=eKl9SW3AAAE." \
  -H "X-Auth-Token: your-api-key" | jq '[.epgFetches[].importDuration] | add / length'

Linking Channels to EPG Source¶

An EPG source by itself does not provide program guide to channels. You need to explicitly specify in each channel's settings:

EPG Source Name — name of EPG source
EPG Channel Name — channel name in XML EPG

For more details see Channel EPG Integration section.

Example channel configuration:

curl -X PUT https://your-catena-domain.com/tv-management/api/v1/channels/cKl9SW3AAAE. \
  -H "X-Auth-Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sport1",
    "title": "Sport HD",
    "epgSourceName": "main-epg",
    "epgChannelName": "sport-channel-1"
  }'

After this, the program guide from main-epg source for channel sport-channel-1 will be available for channel sport1.

EPG XML Format¶

XMLTV Structure¶

Catena supports the standard XMLTV format. Basic structure:

<?xml version="1.0" encoding="UTF-8"?>
<tv>
  <!-- Channel descriptions -->
  <channel id="channel1">
    <display-name>First Channel</display-name>
  </channel>

  <!-- Programs -->
  <programme start="20241016120000" stop="20241016130000" channel="channel1">
    <title lang="en">News</title>
    <desc lang="en">Main news of the day</desc>
    <category lang="en">News</category>
    <rating system="age">
      <value>0+</value>
    </rating>
  </programme>
</tv>

Supported Fields¶

Required program fields:

start — start time (format: YYYYMMDDHHmmss)
stop — end time
channel — channel identifier (used for matching)
title — program name

Optional fields:

desc — program description
category — genre (News, Sports, Movie, etc.)
rating — age rating (0+, 6+, 12+, 16+, 18+)
lang — program language

Typical Use Cases¶

Connecting Standard XMLTV Provider¶

Task: Connect EPG from third-party provider

Steps:

Get XMLTV URL from provider (e.g., https://provider.com/epg.xml)
Create EPG source in Catena with this URL
Set update period to 1 day
Start initial download
Check download result in last_fetch_result
Link channels to source, specifying correct epgChannelName
Verify program guide display in client applications

Using Multiple EPG Sources¶

Task: Different channel groups get EPG from different sources

Example:

epg-russia — Russian channels
epg-europe — European channels
epg-sports — sports channels from specialized provider

Advantages:

Independent update of different channel groups
Ability to use specialized providers for specific topics
Problem isolation — error in one source doesn't affect others

Monitoring EPG Updates¶

Task: Track EPG download success

Solution via API:

# Get update history for all sources
curl -X GET https://your-catena-domain.com/tv-management/api/v1/epg-fetches \
  -H "X-Auth-Token: your-api-key"

# Or get history for a specific source
curl -X GET "https://your-catena-domain.com/tv-management/api/v1/epg-fetches?epgSourceId=eKl9SW3AAAE." \
  -H "X-Auth-Token: your-api-key"

# Check status for each record
# If status != "success" — there's a problem
# If last update is old — EPG is outdated

Setting up alerts:

Create EPG update history check script
Run on schedule (e.g., every hour)
Send notifications on errors or missing updates
Use /epg-fetches endpoint to get complete history

Best Practices¶

Choosing EPG Provider¶

Selection criteria:

Data completeness — presence of descriptions, genres, ratings
Timeliness — how often EPG is updated
Coverage — support for your needed channels
Reliability — service uptime, response speed
Format — compliance with XMLTV standard
Cost — free vs paid sources

Configuring Update Period¶

Recommendations:

1 day — for sources with daily updates
7 days — for sources with program guide week ahead
Less than a day — not recommended, creates unnecessary load

Consider:

How often provider updates EPG
XML file size (large files — update less often)
Load on your server

Error Handling¶

Monitoring:

Regularly check last_fetch_result.status
Set up alerts when status = "error" or "timeout"
Track fetched_at — warn if EPG hasn't updated for >2 days

On errors:

Check URL availability (open in browser)
Check XML format — structure validity
Check file size — possibly too large
Check server network settings (firewall, proxy)

Performance Optimization¶

Recommendations:

Don't download EPG more often than necessary
Use CDN for EPG XML distribution if it's your file
Ensure XML file is compressed (gzip)
Split large EPG into multiple sources by topics

Troubleshooting¶

EPG Not Loading¶

Possible causes:

URL unavailable or returns error
XML file has incorrect format
Network issues on Catena server side
Timeout — file too large

Solution:

Check last_fetch_result.message for error details
Open URL in browser — verify availability
Validate XML through online validator
Check file size — try to reduce
Check Catena server logs

Programs Not Displayed in Application¶

Possible causes:

Channel not linked to EPG source
Incorrect epgChannelName in channel settings
EPG not updated or download had error
Programs in EPG are outdated (past dates)

Solution:

Check channel settings — epgSourceName and epgChannelName
Compare epgChannelName with channel identifier in XML
Check last_fetch_result — was download successful
Check program presence via API /epg-sources/{id}/programs
Ensure EPG has programs for current/future date

Incomplete Program Data¶

Cause: EPG XML doesn't contain all fields (descriptions, genres, ratings)

Solution:

Contact EPG provider to improve data
Use another provider with more complete data
Accept as is — basic information (name, time) will still be available

Timezone Mismatch¶

Problem: Program times display incorrectly

Solution:

Ensure EPG XML time is in UTC or with timezone specified
Check timezone settings on Catena server
Client applications should convert UTC to user's local time

Duplicate Programs¶

Cause: EPG updates but old programs not deleted

Solution:

This is normal behavior during updates
The deletedPrograms field in last_fetch_result shows how many deleted
If duplicates remain, may be issue with program identification in EPG XML

EPG Source Management¶

What is an EPG Source¶

Main EPG Source Parameters¶

Technical Parameters¶

Download Parameters¶

Last Download Result¶

Creating an EPG Source¶

Via Web Interface¶

Via Management API¶

Viewing EPG Source List¶

Via Web Interface¶

Via Management API¶

Getting Source Information¶

Via Management API¶

Editing an EPG Source¶

Via Web Interface¶

Via Management API¶

Forced EPG Update¶

Via Web Interface¶

Via Management API¶

Deleting an EPG Source¶

Via Web Interface¶

Via Management API¶

Viewing Programs from EPG Source¶

Getting Programs via API¶

Viewing EPG Update History¶

Automatic EPG Updates¶

Viewing History via Web Interface¶

Getting History via API¶

Update History Fields¶

Analyzing Update History¶

Linking Channels to EPG Source¶

EPG XML Format¶

XMLTV Structure¶

Supported Fields¶

Typical Use Cases¶

Connecting Standard XMLTV Provider¶

Using Multiple EPG Sources¶

Monitoring EPG Updates¶

Best Practices¶

Choosing EPG Provider¶

Configuring Update Period¶

Error Handling¶

Performance Optimization¶

Troubleshooting¶

EPG Not Loading¶

Programs Not Displayed in Application¶

Incomplete Program Data¶

Timezone Mismatch¶

Duplicate Programs¶

See Also¶