TV_GRAB_UK_ATLAS(1) User Contributed Perl Documentation TV_GRAB_UK_ATLAS(1)NAMEtv_grab_uk_atlas - Grab TV and radio programme listings for UK from
MetaBroadcast website (Atlas database).
SYNOPSIStv_grab_uk_atlas--help
tv_grab_uk_atlas--info
tv_grab_uk_atlas--version
tv_grab_uk_atlas--capabilities
tv_grab_uk_atlas--description
tv_grab_uk_atlas
[--days N] [--offset N] [--dst]
[--channel S] [--config-file FILE]
[--output FILE] [--quiet] [--debug]
tv_grab_uk_atlas--hours N [--offset N] [--channel
S] [--config-file FILE]
[--output FILE] [--quiet] [--debug]
tv_grab_uk_atlas--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]
DESCRIPTION
Output TV listings in XMLTV format for many channels available in UK.
The data come from <http://atlas.metabroadcast.com>
First you must run tv_grab_uk_atlas--configure to choose which
channels you want to receive.
Then running tv_grab_uk_atlas with no arguments will get a listings in
XML format for the channels you chose for available days including
today.
OPTIONS--configure Prompt for which channels to download and write the
configuration file.
--config-file FILE Set the name of the configuration file, the default
is ~/.xmltv/tv_grab_uk_atlas.conf. This is the file written by
--configure and read when grabbing.
--output FILE When grabbing, write output to FILE rather than standard
output.
--hours N When grabbing, grab N hours of data.
--days N When grabbing, grab N days rather than all available days.
--offset N Start grabbing at today/now + N days. When --hours is used
this is number of hours instead of days. N may be negative.
--date N Grab just this date (instead of days/offset).
--dst 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.
--channel S 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. "south.bbc1.bbc.co.uk").
--quiet Suppress the progress-bar normally shown on standard error.
--debug Provide more information on progress to stderr to help in
debugging.
--list-channels Write output giving <channel> elements for every
channel available in the current configuration.
--list-lineups Write output giving list of available viewing regions.
--get-lineup Write output giving <channel> elements for every channel
available in the current lineup.
--capabilities Show which capabilities the grabber supports. For more
information, see <http://wiki.xmltv.org/index.php/XmltvCapabilities>
--version Show the version of the grabber.
--help Print a help message and exit.
--info Print a help page and exit.
INSTALLATION
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:
<http://metabroadcast.com/blog/create-and-manage-your-atlas-api-key>
You will need to enter your API key during the --configure stage.
2. Grabber configuration consists of the usual: tv_grab_uk_atlas--configure
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 tv_grab_uk_atlas.user.map.conf has two purposes. Firstly
you can map the channel ids used by Atlas into something more
meaningful to your PVR. E.g.
map==cbdm==FILM4
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 doesn"t 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 "tv_grab_uk_atlas.user.map.conf" contains
example lines to illustrate the format - you should edit this file to
suit your own purposes!
USAGE
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
BROWSER INTERFACE
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 getatlas.pl 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:
offset=xxxx
hours=xxxx
days=xxxx
date=YYYYMMDD
channel=xxxx
dst
e.g.
http://my.webspace.com/cgi-bin/getatlas.pl?hours=12
http://my.webspace.com/cgi-bin/getatlas.pl?hours=12&offset=6
http://my.webspace.com/cgi-bin/getatlas.pl?date=20130930
http://my.webspace.com/cgi-bin/getatlas.pl?days=1&dst
Valid combinations are:
"offset" and "hours"
or "offset" and "days" - in which case the offset is "days" also
(otherwise it"s "hours")
or "date" - fetch just this day
ERROR HANDLING
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.
ENVIRONMENT VARIABLES
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.
SUPPORTED CHANNELS
For information on supported channels, see
$HOME/.xmltv/supplement/tv_grab_uk_atlas/tv_grab_uk_atlas.map.channels.conf
XMLTV VALIDATION
tv_validate_grabber may report an error similar to:
"Line 5 Invalid channel-id BBC 1"
This is a because ValidateFile.pm insists the channel-id adheres to
RFC2838 despite the xmltv.dtd only saying "preferably" not "SHOULD".
(Having channel ids of the form "bbc1.bbc.co.uk" will be rejected by
many PVRs since they require the data to match their own list.)
This error can be ignored.
FAQs
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:
<http://metabroadcast.com/blog/getting-full-uk-listings-data-from-atlas-it-s-easy>
2. I"m getting the error "Status: 400 Bad Request"
Typically this is because you haven"t entered your API key during the
--configure stage. Or if you requested a particular channel with the
--channel option but the channel cannot be found.
DISCLAIMER
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.
AUTHOR
Geoff Westcott. This documentation and parts of the code based on
various other tv_grabbers from the XMLTV-project.
COPYRIGHT
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.
SEE ALSOxmltv(5).
perl v5.20.2 2015-09-15 TV_GRAB_UK_ATLAS(1)
