Ubuntu Manpage: tv_grab_uk_atlas - Grab TV and radio programme listings for UK from MetaBroadcast website

NAME

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

SYNOPSIS

       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

       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.

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

       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 the tv_grab_uk_atlas.map.channels.conf file in
       your $HOME/.xmltv/supplement/tv_grab_uk_atlas/ directory after you have run the grabber at
       least once.

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:
       <https://metabroadcast.com/blog/create-and-manage-your-atlas-api-key>

       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 your API key does not allow access to Press Association data (log-in to your account at
       http://atlas.metabroadcast.com/admin and "Request Access" to "PA" source data).  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.