tv_grab_uk_atlas(1) 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.

SEE ALSO

LAST SEARCHED