Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  TV_GRAB_UK_ATLAS (1)

.ds Aq ’


tv_grab_uk_atlas - Grab TV and radio programme listings for UK from MetaBroadcast website (Atlas database).



tv_grab_uk_atlas --help

tv_grab_uk_atlas --info

tv_grab_uk_atlas --version

tv_grab_uk_atlas --capabilities

tv_grab_uk_atlas --description

[--days N] [--offset N] [--dst]
                                         [--channel S]
                                         [--config-file FILE]
[--output FILE] [--quiet] [--debug]

--hours N [--offset N]
                                         [--channel S]
                                         [--config-file FILE]
[--output FILE] [--quiet] [--debug]

--date DATE [--dst]
                                         [--channel S]
                                         [--config-file FILE]
[--output FILE] [--quiet] [--debug]

tv_grab_uk_atlas --configure [--config-file FILE]

tv_grab_uk_atlas --configure-api [--stage NAME]
[--config-file FILE]
[--output FILE]

tv_grab_uk_atlas --list-channels [--config-file FILE]
[--output FILE] [--quiet] [--debug]

tv_grab_uk_atlas --list-lineups [--output FILE]
[--quiet] [--debug]

tv_grab_uk_atlas --get-lineup [--config-file FILE] [--output FILE]
[--quiet] [--debug]


Output TV listings in XMLTV format for many channels available in UK. The data come from <>

First you must run <B>tv_grab_uk_atlas --configureB> to choose which channels you want to receive.

Then running <B>tv_grab_uk_atlasB> with no arguments will get a listings in XML format for the channels you chose for available days including today.


<B>--configureB> Prompt for which channels to download and write the configuration file.

<B>--config-file FILEB> Set the name of the configuration file, the default is <B>~/.xmltv/tv_grab_uk_atlas.confB>. This is the file written by <B>--configureB> and read when grabbing.

<B>--output FILEB> When grabbing, write output to FILE rather than standard output.

<B>--hours NB> When grabbing, grab N hours of data.

<B>--days NB> When grabbing, grab N days rather than all available days.

<B>--offset NB> Start grabbing at today/now + N days. When <B>--hoursB> is used this is number of hours instead of days. N may be negative.

<B>--date NB> Grab just this date (instead of days/offset).

<B>--dstB> Some PVRs have trouble with BST times and lose an hour at the end of the day schedule. This adds an extra hour to the schedule fetched.

<B>--channel SB> Grab just this channel (ignore the channels in the config file). Can be specified either as Atlas channel id (e.g. cbbw) or mapped channel name (e.g.

<B>--quietB> Suppress the progress-bar normally shown on standard error.

<B>--debugB> Provide more information on progress to stderr to help in debugging.

<B>--list-channelsB> Write output giving <channel> elements for every channel available in the current configuration.

<B>--list-lineupsB> Write output giving list of available viewing regions.

<B>--get-lineupB> Write output giving <channel> elements for every channel available in the current lineup.

<B>--capabilitiesB> Show which capabilities the grabber supports. For more information, see <>

<B>--versionB> Show the version of the grabber.

<B>--helpB> Print a help message and exit.

<B>--infoB> Print a help page and exit.


1. First you must obtain an Atlas API key from MetaBroadcast. This is free (at the present time) for personal use and is necessary to allow you to access the full schedule published by the Press Association. Any commercial use of the data obtained from Atlas will require a paid-for license.

Instructions are available here: <>

You will need to enter your API key during the --configure stage.

Remember to request Press Association (PA) as the content provider on your Atlas API key.

2. Grabber configuration consists of the usual: <B>tv_grab_uk_atlas --configureB>

Atlas have regionalised data which means you can obtain listings specific to your TV region. When you run the --configure option you will be asked which viewing platform (e.g. Freeview; Sky HD) and region (e.g. London; South East) you wish to access. (You can select only 1 region!).

Then you select which channels you want to fetch.

3. The file has two purposes. Firstly you can map the channel ids used by Atlas into something more meaningful to your PVR. E.g.


will change cbdm to FILM4 in the output XML.

Note: the lines are of the form map=={channel id}=={my name}.

The second purpose is to likewise translate genre names. So if your PVR doesnt have a category for Science Fiction but uses Sci-fi" instead, then you can specify

      cat==Science Fiction==Sci-fi

and the output XML will have Sci-fi.

IMPORTANT: the downloaded contains example lines to illustrate the format - you should edit this file to suit your own purposes!


All the normal XMLTV capabilities are included but there is an additional parameter --hours. Atlas allows schedule data to be retrieved either by number-of-days or by number-of-hours.

Where possible you should use this hours facility to reduce unnecessary load on the Atlas server.

When --hours is specified the --offset is interpreted as hours.

For example:

   - to retrieve a schedule for the next 12 hours:

        tv_grab_uk_atlas --hours 12

   - to retrieve a schedule for the next 12 hours starting tomorrow:

        tv_grab_uk_atlas --hours 12 --offset 24

Alternatively you can use the familiar days format:

        tv_grab_uk_atlas --days 1

        tv_grab_uk_atlas --days 1 --offset 1

Negative numbers are allowed, so for example the following are valid:

        tv_grab_uk_atlas --offset -4 --hours 12

        tv_grab_uk_atlas --offset -1 --days 1

Note that Atlas only has data for a maximum 14 days ahead and it varies; some channels have less than this.

An additional parameter --date YYYYMMDD allows you to fetch the schedule just for this date. (This is obviously similar to --days 1 with an appropriate --offset but avoids you having to calculate the offset; this is easier for some automated fetchers.) E.g.

        tv_grab_uk_atlas --date 20130923

A new parameter --dst allows you to add an extra hour to the schedule fetched from Atlas. Some PVRs have trouble with BST times and lose an hour at the end of the day"s schedule. This parameter might help to alleviate that.

        tv_grab_uk_atlas --days 1 --dst

A new parameter --channel allows you to override the config file and retrieve data for a specific channel:

        tv_grab_uk_atlas --offset -4 --hours 12 --channel cbdm


If you wish to run the fetcher via a browser then you can install the supplied cgi script.

(Note you must obviously have a webserver installed or be using a web-host for this to work.)

Copy the file into the cgi-enabled directory on your web space. (Hint: This directory is often called cgi-bin.) Ensure the file has execute permission.

(Tech note: use a normal cgi handler to run this file; fastcgi may not work.)

Specify the parameters on the URI as follows:


Valid combinations are:
offset and hours
or offset and days - in which case the offset is days also (otherwise its hours)
or date" - fetch just this day


If the grabber fails to download data for some channel on a specific day, it will print an errormessage to STDERR and then continue with the other channels and days. The grabber will exit with a status code of 1 to indicate that the data is incomplete.


The environment variable HOME can be set to change where configuration files are stored. All configuration is stored in $HOME/.xmltv/. On Windows, it might be necessary to set HOME to a path without spaces in it.


For information on supported channels, see the file in your $HOME/.xmltv/supplement/tv_grab_uk_atlas/ directory after you have run the grabber at least once.


<B>tv_validate_grabberB> may report an error similar to:

      "Line 5 Invalid channel-id BBC 1"

This is a because insists the channel-id adheres to RFC2838 despite the xmltv.dtd only saying preferably not SHOULD. (Having channel ids of the form will be rejected by many PVRs since they require the data to match their own list.)

This error can be ignored.


1. What does Enter your Atlas API key mean?

You must obtain an API key free from Atlas MetaBroadcast before you can use this grabber. Instructions are available here: <>

2. Im getting the error Status: 400 Bad Request"

Typically this is because you havent entered your API key during the --configure stage. Or your API key does not allow access to Press Association data (log-in to your account at and Request Access to PA" source data). Or if you requested a particular channel with the --channel option but the channel cannot be found.


The MetaBroadcast free license for these data does not allow non-personal use.

Certainly any commercial use of listings data obtained by using this grabber will breach copyright law, but if you are just using the data for your own personal use then you are probably fine.

By using this grabber you aver you are using the listings data for your own personal use only and you absolve the author(s) from any liability under copyright law or otherwise.


Geoff Westcott. This documentation and parts of the code based on various other tv_grabbers from the XMLTV-project.


Copyright (c) 2013 Geoff Westcott.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License (version 2) as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.


Search for    or go to Top of page |  Section 1 |  Main Index

perl v5.20.3 TV_GRAB_UK_ATLAS (1) 2016-04-03

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.