Skip to main content
The XMLTV API serves EPG (Electronic Programme Guide) data that tuliprox has processed from your configured EPG sources. The output is a standards-compliant XMLTV XML document.

​
EPG endpoint

All three paths are equivalent:
MethodPath
GET/xmltv.php
GET/epg
GET/update/epg.php

​
Parameters

​
username
string
required
The username defined in api-proxy.yml.
​
password
string
required
The password for the user.
​
token
string
Token credential. Accepted in place of username + password.

​
Response

Returns a text/xml streaming response in XMLTV format. tuliprox applies the following transformations before serving:
  • Time-shifting: If the user has epg_timeshift configured, all programme start and stop times are shifted accordingly.
  • URL rewriting: If epg_timeshift is set or URL rewriting is enabled, icon/logo URLs in the EPG are rewritten to proxy through tuliprox.
If no EPG file has been built for the target yet, an empty but valid XMLTV document is returned: 
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE tv SYSTEM "xmltv.dtd">
<tv generator-info-name="Xtream Codes" generator-info-url=""></tv>

​
Error responses

ConditionResponse
Invalid credentialsHTTP 403 (or configured auth_error_status)
User permission deniedHTTP 403 Forbidden
No EPG configured for targetEmpty XMLTV document (HTTP 200)

​
Examples

curl "http://localhost:8901/xmltv.php?username=alice&password=s3cr3t"

​
XMLTV document structure

The response is a standard XMLTV document. Each channel with at least one programme entry is included. 
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE tv SYSTEM "xmltv.dtd">
<tv generator-info-name="X" generator-info-url="http://localhost:8901">

  <channel id="channel.id.here">
    <display-name>Channel Name</display-name>
    <icon src="http://localhost:8901/resource/epg/alice/s3cr3t/..."/>
  </channel>

  <programme start="20260317120000" stop="20260317130000" channel="channel.id.here">
    <title>Show Title</title>
    <desc>Show description text.</desc>
  </programme>

</tv>
The generator-info-url attribute in the <tv> element contains the server’s base URL, which is useful for debugging which tuliprox instance served the EPG.

​
EPG resource proxy

When URL rewriting is enabled, icon URLs in the EPG are rewritten to route through this endpoint, which obscures the original provider URL and proxies the image through tuliprox. 
GET /resource/epg/{username}/{password}/{resource}
​
username
string
required
The authenticated username.
​
password
string
required
The authenticated password.
​
resource
string
required
The obfuscated resource identifier (generated internally by tuliprox). Not intended to be constructed manually.

​
EPG time-shifting

Per-user EPG time-shifting lets you offset programme times. This is useful when a provider’s EPG times are in the wrong timezone for your users. Configure it in api-proxy.yml: 
credentials:
  - username: alice
    password: s3cr3t
    epg_timeshift: "+120"   # shift all times forward by 120 minutes
Accepted formats:
  • "+60" or "-60" — shift by ±N minutes
  • A timezone name such as "Europe/Berlin" — express times in the target timezone

Build docs developers (and LLMs) love

Get started for freeTalk to us