ZAP2XML : Convert zap2it TV listings to XMLTV or XTVD .xml

zap2xml is a small and fast command line script that connects to a Zap2it or TVGuide account, downloads the tv listings data, and converts it to XMLTV or XTVD formatted .xml

* You are welcome to try an alternative tv listings utility: mc2xml

zap2xml setup:

  1. Register your free TV Listings account (input zip/postal code and select lineup)
  2. Click Set Preferences:

    Manage Favorite Channels
    1. Select your favorite channels from the "Available Channels" and put them in the "My Favorite Channels" list
    Additional Settings
    1. Checkmark [✔] "Show six hour grid"
    2. Checkmark [✔] "Show only my favorite channels in the grid"
    3. Click "Save"

  3. You may need to install the required supporting perl libraries (not needed with the Par-Packed Windows file)
  4. Run zap2xml with the userEmail and password parameters of your account
    • Example: zap2xml -u zap2xmluser@email.xx -p password
  5. Optionally set up a cron job/task scheduler task to run it every day

zap2xml setup:

  1. Register your free account
  2. Click Change to select your provider (input zip code or pick a country and select lineup)
  3. Optionally select your favorite channels (click the channel hearts or click "Favorites" link) to limit channel output
  4. You may need to install the required supporting perl libraries (not needed with the Par-Packed Windows file)
  5. Run zap2xml with "-z" parameter, along with the userEmail and password parameters of your account
    • Example: zap2xml -z -u tvguideuser@email.xx -p password
  6. Optionally set up a cron job/task scheduler task to run it every day

zap2xml options (case sensitive):

  • -u <username>
  • -p <password>
  • -d <# of days> (default = 7)
  • -n <# of no-cache days> (from end) (default = 0)
  • -N <# of no-cache days> (from start) (default = 0)
  • -s <start day offset> (default = 0)
  • -o <output xml filename> (default = "xmltv.xml")
  • -c <cacheDirectory> (default = "cache")
  • -l <lang> (default = "en")
  • -i <iconDirectory> (default = don't download channel icons)
  • -m <#> = offset program times by # minutes (better to use TZ env var)
  • -b = retain website channel order
  • -x = output XTVD xml file format (default = XMLTV)
  • -w = wait on exit (require keypress before exiting)
  • -q = quiet (no status output)
  • -r <# of connection retries before failure> (default = 3, max 20)
  • -R <# of sequential skips of missing detail IDs before failure> (default = 50)
  • -e = encode entities (html special characters like accents)
  • -E "amp apos quot lt gt" = selectively encode standard XML entities
  • -F = output channel names first (rather than "number name")
  • -O = use old tv_grab_na style channel ids (
  • -A "new live" = append " *" to program titles that are "new" and/or "live"
  • -M = copy movie_year to empty movie sub-title tags
  • -U = UTF-8 encoding (default = "ISO-8859-1")
  • -L = output "<live />" tag (not part of xmltv.dtd)
  • -T = don't cache files containing programs with "TBA|To Be Announced"
  • -P <http://proxyhost:port> = to use an http proxy
  • -C <configuration file> (default = "~/.zap2xmlrc")
  • -S <#seconds> = sleep between requests to prevent flooding of server
  • -D = include extra program details = 1 extra http request per program!
  • -W = include extra program details (only for movies) = 1 extra http request per movie!
  • -I = include program icons (image URLs) - 1 extra http request per program!
  • -J <xmltv> = include xmltv file in output
  • -Y <lineupId> (if not using username/password)
  • -Z <zipcode> (if not using username/password)
  • -z = use instead of
  • -a = output all channels (not just favorites) from
  • -j = add "series" category to all non-movie programs

Example 1: zap2xml -u zap2xmluser@email.xx -p password -A "new" -i icons

Example 2: zap2xml -z -u tvguideuser@email.xx -p password -o myfile.xml

To minimize web traffic zap2xml keeps all downloaded files in a cache subdirectory. It deletes old files in this directory based on last access time. (if last access > days + 2)

zap2xml uses your system's time and timezone so make sure your system clock is correct. Set your TZ environment variable before running zap2xml if you want to change the timezone of scheduled programs (ie: export TZ=GMT).

zap2xml is written in perl. Perl is also packaged for windows and needs the TimeDate package to be installed from the Perl Package Manager (ppm install TimeDate))

zap2xml relies on some standard perl libraries. If you run the script and a Perl error message states that it is missing a library you can use "perl -MCPAN -e shell" from your shell to install these dependencies (example: "install IO::HTML") or they may be available through apt-get depending on your distribution.
Example for OSMC: "sudo apt-get install libcompress-raw-zlib-perl libhtml-parser-perl libhttp-cookies-perl liblwpx-paranoidagent-perl libconfig-json-perl libjson-xs-perl"

please verify downloaded filesize to make sure your download is complete!
downloads are for personal use only, not for redistribution, integration or other use

 Perl Downloads 
size: 50190 bytes

 Windows Downloads 
file: zap2xml-install.exe
size: 3527586 bytes
* A self extracting PAR packed Windows binary
(if you don't want to install perl on windows)

Windows Note: "Can't locate" error usually means something
(virus scanner?) deleted that standard perl file when it was extracted to your
C:\Users\Name\AppData\Local\Temp\par-### folder
Delete that temp cache dir and retry (ensure isn't deleted again)

If your virus scanner returns a false positive result on the windows install.exe
you can install Perl and run the text file perl (.pl) script


  • 2007
    • Initial Release
    • Added -l and -e options
    • Added Compress::Zlib requirement (without Zlib you get 0 byte cache files)
    • GZip cached files to save hd space
    • Added -i <dir> option to download channel icons to a directory (they are copied to ###.gif as well)
    • Added -? usage instructions, updated dd_prog_id to (10.4) format from (8.4)
    • Removed brackets around movie_year, encode by default the 5 XML standard entities
    • Added -E option (-E "" disables encoding of the standard 5, -E "apos quot" only does those 2, etc)
    • Added decoding for utf8 characters, changed order of date field (passes dtd validation)
    • Added -U option
    • Check for program descriptions in p tags as well as span tags
    • Fix check for HD icon, set binmode when outputting UTF-8 file
    • Add -q and -s options, and output status messages to STDERR so "-o - > xmltv.xml" can work
    • Support an optional key=value text config file (~/.zap2xmlrc or specify via -C option)
    • Added -L option
    • Check for available "HD" and "High Definition" tags (video-hd, video-ahd)
    • Remove expired programs (old/already run programs with no time data from zap2it)
    • Added -A option to append an asterisk to new and/or live program names (-A "new" or -A "live" or -A "new live")
    • Use "USERPROFILE" as default home directory if "HOME" is not set (Windows)
    • Added -r option (retries= in config file) to specify # of zap2it connection retries before failure
    • Added -n option (ncdays= in config file) to specify # of days to ignore the cache. Example: If you use -d 5 to download 5 days of data with -n 2, it will not use the cache for the last 2 days. (-d 7 -n 7 will not use the cache at all [but will put more of a burden on the zap2it website]).
    • Added -P option (proxy= in config file) to specify an optional http proxy
    • Added -T option
    • Added -O option, changed default channel IDs to match xmltv's (station # rather than channel #, probably should have always been this way)
    • Added -N option (ncsdays= in config file) (same as -n, but count days from start rather than end)
    • Added -F option, strip trailing whitespace from options in config file (for Windows)
    • Added -t option (trailer= in config file) - Trailers are big. Only set this option if you really want them.
    • Strip "sponsored" from genre
    • Added -g option, added originalAirDate to <date> field for programs that are marked Live or New
    • Added -x option (outformat=xtvd in config file) - This outputs an XTVD formatted .xml file instead of XMLTV. (lineuptype/lineupname/lineuplocation are parsed from the source .html, or you can specify these in the config file)
    • Added previously-shown tag, update video tag to match XMLTV
    • Copy channel icons to "# NAME.gif" (as well as "#.gif")
    • Handle rare time when channel # is missing on zap2it web page
    • Channel links no longer contain postalcode/lineupIds, added those options to the user definable config file (xtvd output format)
  • 2008
    • 02-15 Updated parser for zap2it's new "new/live/hd" tags
    • 03-11 Updated program description cookie to match zap2it's new one
    • 05-25 Updated to handle zap2it's latest website changes
    • 05-29 Handle channel numbers with "." in them
    • 06-26 Updated to handle zap2it's latest website changes
    • 08-02 Updated to handle zap2it's latest website changes
    • 08-31 Updated to handle zap2it's latest website changes
    • 09-10 Updated to encode utf8 for certain perl Zlib versions that don't like "wide characters"
    • 12-09 Updated to handle zap2it's latest website changes
    • 01-10 Fix icon download
    • 04-08 Updated to handle zap2it's latest website changes

    • Moved website

  • 2014-04-08
    • Updated to handle zap2it's latest website changes (completely new site)
      • Data sent in 3 hour/45 channel json chunks
      • Be sure to log in to zap2it's new site to set your postal/zip code, lineup, and select favorite channels
      • Channel Id's might have changed in your xmltv output. There are short and long channel IDs and to prevent duplicates the long ones are used. If you have duplicate channel#'s it may require changing the ID format to "I<chan#>.<chanid>.labs..."
      • Added episode-num "common" tag (S00E00). Don't know what else to call it or where to put it that fits the xmltv spec.
  • 2014-04-17
    • zap2xml: Added json parameter "tz" hopefully fixing some download problems around midnight
    • zap2xml: Added -w option for windows users who want to press a key before exit (if the window closes too quickly and you want to see what went wrong if having problems)
    • zap2xml: handle spaces in zipcode
    • If you do have problems the first thing to try is to delete your cache folder and retry
    • If no channels are output in your xmltv.xml file, login to the zap2it site and check that favorites have been set. The zap2it website has problems storing favorites at the moment (it worked a few days ago). You may have to use -B to get all channels until they fix it.
    • Added zap2xml2 download option: (the old zap2xml)
      • continues to host the old style grid listings with 14 days of data
      • zap2xml2 is the old zap2xml script but has been modified to run on the tvschedule url
      • login with your old account, and be sure to set preferences to "show six hour grid", "show only favorites" and select your favorite channels
      • Example: "zap2xml2 -u username -p password" (I have only tried it once and it seems to work)
  • 2014-04-19
    • zap2xml: utf8 fix
  • 2014-05-05
    • zap2xml: fix handling of sponsored channels
    • zap2xml: extend tz param to get a few more hours of data (zap2it limits 7 day data range based on GMT/tz, ideally script shouldn't run at hour changes in case of client/server clock differences ie: run at least 5 minutes after hour if you want to maximize data range)
  • 2014-05-14
    • zap2xml: fix icon handling
  • 2014-05-25
    • zap2xml: zap2it url change: tvlistings -> www
  • 2014-10-01
    • zap2xml: add facebook and google login options (oauth) (zap2it still doesn't offer new accounts)
      • Must manually login via facebook or google (through zap2it site) to explicitly allow zap2it app account access (to email address and birthday), and then select zap2it lineup and favorite channels
      • 2-factor authentication not supported
      • Use command line option "-1" for facebook or "-2" for google, along with -u and -p
      • Example: ./zap2xml -2 -u -p mygooglepass
      • If you store your password in a clear text batch file, consider creating a throw-away account
    • zap2xml: add xmltv_ns episode tags
  • 2015-03-28
    • zap2xml: separate stdout (information) from stderr (errors)
  • 2015-07-09
    • zapit removed their newer listings(?), zap2xml2 still works
  • 2015-07-22
    • zap2xml2 renamed back to zap2xml (the newer json zap2it listings don't seem to be returning)
    • added -D option: this gets program detail for each program (season/episode info, movie cast, star rating, genres) but requires 1 http request per program! Use with care!
    • added -I option: this gets the program image url for each program but requires 1 http request per program! (not useful unless your PVR software makes use of xmltv program icons)
    • both options cache just like the main grid, but these options can initially result in a lot of http requests if you have a big grid with a lot of programs; perhaps consider using with at least "-S 1" (1 second delay between requests) to be less of a server burden (might also need an increase in -r retries if you get repeated "internal server errors")
  • 2015-07-26
    • detect when not using a 6 hour grid and adjust to the 3 hour grid, and handle any mismatches in the cache (selecting "six hour grid" in your zap2it preferences reduces the # of http requests, but some miss this setup step)
  • 2015-07-30
    • detect when zap2it isn't sending a grid (ie: when a lineup is not valid and requires manually selecting a new lineup)
    • channel numbers were sometimes not being added
  • 2015-08-02
    • add: -i <iconDirectory> option if you want to download the small channel icons, and include their urls in your xmltv.xml file (2 extra http requests per channel icon)
    • add: -m # option (if you want to offset the program times by a certain number of minutes, + or -). Ideally your system should already handle program times correctly if you have the proper timezone set
    • fix position of subtitles tag
  • 2015-09-06
    • raise error if decoding content fails (missing IO::HTML)
  • 2015-09-19
    • add -M option: copy movie year to empty movie sub-title tags
    • add delays on errors or exiting on Windows (console window closes quickly)
  • 2015-10-18
    • -T option update: search for "TBA" in addition to "To Be Announced" in title or sub-title (ie: sporting events when teams are TBA)
    • start time based on current time (rather than start of current day), unless using -s
  • 2015-10-21
    • add -b option: retain website channel order
  • 2015-10-23
    • fix gridhour calculation on daylight savings time change
  • 2015-12-04
    • add "series" category to programs with "EP" ids or seriesIds in their details (-j will add "series" category to "SH" type programs as well)
    • add -Y and -Z to specify lineupId and zipcode without needing to log in (gets all channels, can't select favorites)
    • add -J to include an existing xmltv file in output, example:
      • zap2xml -Y "PC:10001" -Z 10001 -c ota -o ota.xml
      • zap2xml -Y "DISH501:-" -Z 10001 -c dish -J ota.xml -o dish-and-ota.xml
  • 2015-12-13
    • add -z option to use instead of
      • Sign up and use your account to select a lineup and channel favorites
      • has season/episode numbers in the grid data without needing to download each program's detailed data, it also supports other countries but has less lineup selection in some locations
      • all channels in a lineup are downloaded, but only favorites are output in the xmltv file (unless you don't have any favorites selected on the tvguide website, or if you specify -a)
      • -I will get program images (1 http request per program)
      • -D will get program details (1 http request per program) - only useful for getting "movie_year" if you want that, so it currently only gets details for movie type programs
      • if you don't want an account, get the lineupId and specify it using -Y (no favorites can be set), examples:
        • zap2xml -z -u me@email.xx -p password
        • zap2xml -z -Y "80004"
  • 2015-12-14
    • -z utf8 fix
  • 2016-01-08
    • fix: don't overwrite -D retrieved long descriptions with the shorter grid ones
  • 2016-03-18
    • support grabbing channel logos from tvguide (-i <iconDir>) - extracting logos from sprite requires perl GD module
  • 2016-05-21
    • zap2it: support premiere, finale (last-chance) and rating tags
  • 2017-01-01
    • zap2it: add -W option to only get extra details for movies (-D gets details for all programs)
    • zap2it: when using -D (or -W), skip episode ids that are missing ("500 internal server errors")

Config file options (~/.zap2xmlrc):

  • start=0
  • days=7
  • ncdays=0
  • ncsdays=0
  • retries=3
  • user=user
  • pass=password
  • cache=cache
  • icon=icons
  • trailer=trailers
  • lang=en
  • proxy=http://localhost:8080
  • outfile=xmltv.xml
  • outformat=xmltv (or 'xtvd')
  • lineuptype=type (xtvd only - Cable/CableDigital/Satellite/LocalBroadcast)
  • lineupname=name (xtvd only)
  • lineuplocation=location (xtvd only)
  • lineupid=X:80000
  • postalcode=01010


  • If you have improvements please email them to: zap2xml (at)