Feed API
--------
Introduction
============
[sec:introduction]
This document describes the technical possibilities available to the
TicketSwitch affiliate or partner wanting to go one step beyond the
basic the Link Generator. It is split into two sections:
[sec:nonTechnical] gives a non-technical overview of the possibilities
offered by TicketSwitch event feeds; [sec:technical] is intended as
complete technical documentation of the feeds.
This document does *not* cover the more advanced option that is
'complete integration' offered by the ``xml_core``, since it requires
significant technical expertise and development time not available to
many affiliates. Documentation covering the ``xml_core`` is available on
request.
[sec:nonTechnical]
Why use TicketSwitch event feeds?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The Link Generator offers a simple way for affiliates to generate a few
links to single events, individual performances or search results. It is
suitable for use to maintain static pages by hand, which contain links
to the buy-process provided by TicketSwitch. This has many benefits,
including simplicity and transparency; but it is a manual process. As
such, it is not suitable for managing sites with large libraries of
links, for dynamic sites driven by existing content management systems,
or sites wishing to automatically link to events as soon as they come on
sale.
The step beyond manual use of the Link Generator is to use one of the
three flavours of event feed provided by TicketSwitch. This allows
affiliate sites to include automatically generated content and links
from TicketSwitch, cutting down on manual maintenance, and keeping the
site more up-to-date. Even for affiliates who don't use them to automate
their own site, the event feeds can be used as a user friendly means to
be notified when a new event goes on sale.
Who should read this document?
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[sec:whoread]
The following groups of people may benefit from reading this document:
- existing TicketSwitch affiliates who are interested in reducing the
manual maintenance of their site
- existing TicketSwitch affiliates who are interested in being notified
when new events become available for sale
- potential new TicketSwitch affiliates who are interested in the
technical possibilities of integration offered by TicketSwitch
This document assumes some familiarity with the relationship between
TicketSwitch and our affiliates, and the usual way in which affiliate
sites link to the customized buy-process provided. The first part
([sec:nonTechnical]) of this document does not assume any technical
knowledge.
The second section is of interest to those affiliates wishing to use an
event feed to drive a part of their own web site, or as part of a full
``xml_core`` integration project. Since it includes full technical
details, it is not of interest to the general reader. See
[sec:technical].
What is 'syndication'?
^^^^^^^^^^^^^^^^^^^^^^
[sec:syndication]
In the context of the web, the word 'syndication' describes how web
publishers (usually news organisations or blog authors) make their
content available for display on external web sites.
In this case, TicketSwitch takes the part of the news organisation,
allowing the affiliate site to display the syndicated content. The
'syndicated content' takes the form of events and event information.
This document usually avoids using the word 'syndication'.
Three flavours of event feed
============================
[sec:feedFlavours]
As standard, TicketSwitch makes three different formats of event feed
available to its affiliates. All three feeds are formatted as XML which
is a near-universal method of expressing information in a
machine-readable form. Many free and commercial programs are available
to interpret the contents of the XML, or to display it in a
user-friendly way either on an affiliate site, or directly to the end
customer.
The three flavours are RSS, Atom and a proprietary ``xml_feed``.
The RSS and Atom feeds
^^^^^^^^^^^^^^^^^^^^^^
[sec:rssFeedIntro]
Both 'RSS 2.0' and the newer 'Atom' format are standards [1]_ for
distributing feeds over the Internet. There are many widely used
programs for interpreting RSS and Atom, including NetNewsWire (for Mac
OS X) and SomePCRssReader for Windows. Programs that interpret RSS or
Atom feeds and display them to the end user are sometimes called
'Desktop Aggregators',
There are also many web sites such as
`reader.google.com `__ which provide the same
service as a desktop aggregator. TicketSwitch includes links in the
buy-process to various online aggregators that allow customers to
subscribe to ``rss_feed``\ s directly.
The web browsers Safari and Firefox both support RSS, while Microsoft is
planning to add support in Internet Explorer 7. Even web browsers that
do not understand the feed format as such, usually display feeds
reasonably well by applying the included style-sheet to the raw XML.
Finally, there are many free and commercial programs for automatically
creating a web site from an RSS or Atom feed. One well known example is
`www.rss2html.com `__.
The wide support for RSS and Atom makes these feed formats suitable for
use by affiliates (and even by customers) as a very convenient way of
checking for new events as they go on sale, or for reading about
existing events.
The original '``xml_feed``'
^^^^^^^^^^^^^^^^^^^^^^^^^^^
[sec:xmlFeedIntro]
The original '``xml_feed``' is a proprietary XML format designed
specifically by TicketSwitch for use by affiliates requiring an event
feed. It is not limited by compatibility with an existing feed format,
so it is able to provide event information in the most natural and
useful form. Note, however, that most of the additional information is
also available in the RSS and Atom feed via a proprietary
extension [2]_.
Since the ``xml_feed``\ 's XML format is specific to TicketSwitch, there
are no third party programs available to interpret or display it. Unlike
the RSS or Atom feeds, this makes the ``xml_feed`` unsuitable for use by
the end customer. However, standard XML-processing tools such as
``xsltproc`` are compatible with the ``xml_feed`` as well as the RSS and
Atom feeds.
Which feed flavour should I use?
================================
[sec:whichFeed]
Since the three feed flavours are extremely similar, this is a difficult
question to answer! The decision is largely a matter of personal
preference, but there are some general rules.
For use in desktop and web aggregator programs:
- The ``xml_feed`` is a proprietary format so it cannot be used with
free or commercial aggregator programs.
- as RFC4287, Atom is an IETF 'Proposed Standard', and is technically
superior to RSS, so Atom should be chosen over RSS where possible.
- Atom is relatively new, so it may not be supported by a particular
aggregator. If your aggregator does not support Atom 1.0, use RSS
instead, (after complaining to its maintainer).
For use with off-the-shelf tools for generating feed-driven web sites
(such as `www.rss2html.com `__):
- The ``xml_feed`` is a proprietary format so it cannot be used with
standard feed processors.
- The choice between Atom and RSS comes down to the technical
superiority of Atom vs. the wider support for RSS.
For use with in-house tools (e.g. using ``xsltproc``) for generating
feed-driven web sites:
- The greater familiarity of RSS and Atom may make them more attractive
for in-house development. Most TicketSwitch-specific data are
available via proprietary RSS and Atom extensions.
- The ``xml_feed`` is able to encapsulate all the data naturally
associated with each event since it's not limited by compatibility
with an existing standard.
Uses of event feeds
^^^^^^^^^^^^^^^^^^^
[sec:feedUses]
This section gives a brief outline of the possible applications of
TicketSwitch event feeds to the affiliate and their customers.
Feeds as a sales channel
^^^^^^^^^^^^^^^^^^^^^^^^
[sec:customerUse]
This section describes how TicketSwitch's standard RSS and Atom feeds
may be used directly by the end customer. TicketSwitch currently
includes links to the ``rss_feed`` on many pages of its affiliate buy
process. We also use 'feed auto-discovery links' in the HTML ``
``
section of all appropriate pages. These links serve three purposes:
- Regular customers may use these links to subscribe to the feeds using
their own desktop or web-based aggregator, or within their existing
web browser.
- Search engines that understand RSS (including MSN search and Yahoo!)
are able to index content served through RSS links, and add weight to
links to the event information pages.
- Major web-based RSS aggregators (such as
`www.PubSub.com `__) are able to index
TicketSwitch's RSS feeds, and pass them on as part of a new feed,
based on their user's search criteria.
When working as an additional sales channel, the RSS feeds are used
directly by the end customer without requiring any action on the part of
the affiliate.
The effectiveness of RSS and Atom feeds as a direct sales channel is
likely to be limited to those customers who are existing users of feed
technology (for instance those who read a blog via RSS). Take-up may
grow as software vendors integrate support for feeds into their
products, but in any case it is cost-free from the affiliate's
perspective.
Feeds as notification of new events
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[sec:operationalUse]
RSS or Atom feeds are arguably the most convenient way for affiliates to
keep up-to-date on the latest events available to purchase through
TicketSwitch. Rather than regularly checking the TicketSwitch web site
for updates it is much simpler to use a desktop aggregator (or 'RSS news
reader') to subscribe to the RSS feeds.
Events appear in desktop aggregator soon after they become available for
sale to the affiliate. Although it is possible to use the event link
from the RSS feed directly in the affiliate site by copying it from the
aggregator, it is much better to use the dedicated Link Generator, which
provides much greater control and may produce shorter links (all other
things being equal, search engines 'prefer' shorter links).
Feeds as an automated source of site content
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[sec:siteUse]
With a little work and technical knowledge, it is possible to use any of
the three flavours of TicketSwitch event feed to provide content for all
or part of an affiliate site. There are three main benefits of this:
- The level of manual maintenance can be reduced.
- The affiliate site can automatically be kept up-to-date when
TicketSwitch events come on and off sale.
- It may be easier to produce a 'search engine friendly' affiliate site
using content from TicketSwitch event feeds.
Feed-generated sites and search engines.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[sec:feedSeo]
There is a great deal of conflicting information available about so
called Search Engine Optimisation ('SEO'). Today, many search engines
employ an 'Over Optimisation Penalty' and other techniques in order to
prevent sites from using huge link farms, doorway pages or other
artificial means to improve their search engine rankings.
It would be possible for an affiliate to use TicketSwitch event feeds to
produce such doorway pages. TicketSwitch may withdraw access to event
feeds if an affiliate is found to be abusing them. *TicketSwitch does
not condone link spamming or other unethical SEO practices.* Any
automated site-generation process involving TicketSwitch event feeds
must product pages that are intended to be customer friendly, rather
than a tool for unethical SEO.
Another point to note is that search engines often penalise sites that
share a large proportion of content with another site. The event
information available through the feeds is available to all TicketSwitch
affiliates and to other sites. Affiliates who can source their own
original event content may have more success with their search engine
placement.
Linking to feeds
================
[sec:feedLinks]
The Link Generator can be used to obtain links to customer-facing
``rss_feed``\ s, which may be put on an affiliate's site, but it is
usually possible to generate links by hand instead. Feed URLs take the
following form:
-
-
-
The must be replaced with your ``user_id`` assigned to you by
TicketSwitch. If this is not done, any links returned by the feed will
not be associated with you: the page will not carry your branding, the
sales will not be credited to you and you will not earn any commission.
Please note that an unrestricted ``xml_feed`` will return a large amount
of data.
Additional parameters may be added to these feed links to filter the
returned events, or to request different data returned. These parameters
are described in Section [sec:feedParams].
[sec:technical]
Feeds - Technical Overview
==========================
Introduction
^^^^^^^^^^^^
The rest of this document provides a technical description of
TicketSwitch event feeds. This will be useful to a developer wishing to
integrate TicketSwitch feeds into their own site or system. This section
provides a general overview of the structure of TicketSwitch event
feeds.
Section [sec:feedParams] describes all the CGI input parameters that are
understood by the feeds. Generally, the same inputs apply to all three,
but there are a few differences, which are described in the document.
Any inputs that are specific to ``xml_feed`` are described in
[sec:xmlFeedParams].
Part [sec:feedFormat] gives a detailed description of the XML returned
by each of the feeds. ``rss_feed`` and ``atom_feed`` are described in
[sec:atomFormat] and [sec:rssFormat] respectively. The feed extensions
that are implemented are described in [sec:extensions], while the
``xml_feed`` is described in [sec:xmlFormat].
Finally, [sec:feedExamples] gives examples of actual XML as returned.
Support for event feeds
^^^^^^^^^^^^^^^^^^^^^^^
If you have any questions regarding the XML feed or any related subjects
then feel free to contact TicketSwitch. We are happy to provide
technical assistance to people wanting to use the feeds (subject to
availability of manpower).
General questions about the TicketSwitch affiliate program, or
individual affiliate accounts should be directed to
```<``\ affiliates@ticketswitch.com\ ``>`` `__.
Technical queries, bug reports and requests for technical help using the
event feeds should go to
```<``\ feeds@ticketswitch.com\ ``>`` `__.
It is helpful if you quote your TicketSwitch ``user_id`` in all
correspondence.
General feed structure
^^^^^^^^^^^^^^^^^^^^^^
Although the XML they produce is different in each case, all three
flavours of TicketSwitch event feed are structurally very similar. Each
feed reads its CGI inputs, performs an event search in the database and
returns a list of those events expressed as XML.
The events returned may be restricted by arbitrary search criteria in
the CGI inputs and by any additional restrictions applied to the
TicketSwitch user. There are additional inputs affecting the order of
the results in the XML. All these CGI inputs are processed in the same
way by the feed scripts as they are by the ``search`` script in the
standard customer-facing buy process on the web.
In addition to the inputs describing search criteria, there are other
optional CGI inputs that may be used to change the data that is returned
in the XML results, or to change the way it is formatted. As far as
possible, all CGI inputs area available to all three feed scripts, and
work in the same way in every case. All available CGI input parameters
are described in the following section.
The preferred language of the human-readable content may be specified by
the appropriate HTTP header as well as via an explicit CGI input
variable. See [sec:lowLevelParams] and [sec:lang] for more details.
Linking to feeds
^^^^^^^^^^^^^^^^
This section describes how you should make links to TicketSwitch event
feeds. Generally speaking, technical users of event feeds are expected
to be able to generate their own links according to the instructions in
this section and the rest of this document. There is no tool for
generating feed links analogous to the Link Generator for searches and
events.
The basic feed link is You *must* replace '``tswlink``' with your
``user_id`` as specified by TicketSwitch. If you do not do this, any
links returned by the feed will not carry your ``user_id``. That means
they will not carry your branding, sales will not be credited to you,
and the feed will not reflect the event selection visible to you.
You may replace ``rss_feed`` with ``atom_feed`` or ``xml_feed``
depending on which feed flavour you are trying to fetch. Some users
(business-to-business users in particular) must also give a password via
``user_passwd`` before the feeds will work. This restriction is to avoid
the possibility of an attacker using the feeds to circumvent the usual
business-to-business login process.
If you have been told to use a special 'channel', you must specify that
channel after the ``user_id``. For example a hypothetical
business-to-business feed link giving a password of '``examplepw``' and
coming in on a channel called '``b2b``' might use the link .
Any additional parameters must be specified as a standard CGI query
string following a question mark. This document describes the inputs
that are available and how to use them. The values must be url-encoded
as appropriate.
Feed input parameters
^^^^^^^^^^^^^^^^^^^^^
[sec:feedParams]
Standard search criteria parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[sec:criteriaParams]
The following section lists all the inputs that represent search
criteria used to restrict the search results. All search criteria must
be satisfied simultaneously for an event to be returned. In other words,
the search criteria are combined with a logical AND. No other Boolean
operations (e.g. OR or NOT) are supported.
Please note that like all TicketSwitch CGI inputs, these variables must
be specified at most once in a single request. An error will occur if
any variable is given more than once. Other than that, the caller may
use any of these variables freely.
``s_keys``
This variable will be interpreted as a space-separated [3]_ list of
keywords. The results are restricted to those events which have all
of the given keywords somewhere in their event, venue or area title.
The keywords are matched case-\ *in*\ sensitively and word
boundaries in the titles are not significant.
For example, to restrict the results to those events with 'Eminem'
in one of their titles, set ``s_keys=eminem``.
This is a simple variable to use, but there are often better ways to
achieve the intended effect: event titles are maintained by
TicketSwitch, and may change from time to time, possibly causing
unexpected changes in existing feed results. To restrict the results
to product at a given venue you should use ``s_ven``, ``s_area`` and
``s_src`` instead. To restrict to a single country you should use
``s_coco`` instead. To restrict to a single city you should use
``s_geo`` instead.
``s_coco``
This variable must contain an ISO3166 two letter country code. The
results will be restricted to product in the given country. For
example, to restrict the results to product in France, set
``s_coco=fr``.
``s_geo``
This variable describes a circle on the Earth's surface in order to
restrict the results to product within that circle. The centre of
the circle is specified in terms of WSG84 coordinates, with the
radius in km.
When present, ``s_geo`` must contain exactly three floating point
numbers separated by two single colons (':'). The first pair of
components are the WSG84 latitude and longitude of the centre of the
circle, in that order. The last component is the radius in km.
For example, to restrict the results to product in London (UK) only,
set ``s_geo=51.5:-0.1667:25``.
Note that products that are not related to a specific geographical
location (or that simply have no associated geographical
information) will never be returned by a search restricted by
``s_geo``.
``s_poly``
This input variable can be used to perform advanced geographical
restrictions in terms of arbitrary polygons on the Earth's surface.
The vertices are expressed in WSG84 latitude and longitude.
The actual value of ``s_poly`` must be one of a number of named
geographical polygons, set up in advance by TicketSwitch. The
creation of these geographical polygons is a time-consuming process.
At the time of writing, there are no such polygons set up. It is not
possible for an affiliate to create their own arbitrary geographical
polygons. This input is described for the sake of completeness.
``s_class``
This variable can be used to restrict the results using
TicketSwitch's event classification system. The value of ``s_class``
must be either the name of a main class (e.g. '``theatre``'), or a
slash-separated [4]_ class/subclass pair
(e.g. '``theatre/comedy``'). It is an error to use a value of this
variable that is not an existing class or class/subclass pair. The
current list of class/subclass pairs is available through the
``xml_feed``. See [sec:classList].
``s_src, s_are, s_ven, s_eve``
These four inputs can be used to restrict the results according to
TicketSwitch's natural hierarchy of backend systems, areas, venues
and events. See [sec:tswHier]. To specify a single event, all four
'model codes' must be given together, but it is possible to set
fewer than four. If ``s_eve`` is given on its own, the results may
include more than one event.
To restrict to all events at a particular venue, the caller should
specify the three codes ``s_src``, ``s_area`` and ``s_ven``, but
omit ``s_eve``. If any of the four inputs specifies a code that does
not exist, no results will be returned.
For example, to link to the Chicago at the Adelphi Theatre, London,
set ``s_src=kps_uk``, ``s_area=LDN``, ``s_ven=ADE/T`` and
``s_eve=44``. (This particular example may not continue to work in
the future.)
``s_dates``
This variable can be used to restrict the results to product that is
available at some point within a particular date range. The dates in
this variable must be in eight digit '``YYYYMMDD``' format,
separated by a colon ('``:``'). Either end of the date range may be
omitted, in which case the range is interpreted as unrestricted in
that direction. In any case, this variable must always contain
exactly one colon.
Note that any product returned is not guaranteed to be available
throughout the date range: the restriction is that any product known
to be unavailable over the entire range is not returned.
For example, to restrict the results to product that is available at
some point in 2006, set ``s_dates=20060101:20061231``. To restrict
to product available before the end of 2005, set
``s_dates=:20051231``. To restrict to product available after the
end of 2005, set ``s_dates=20051231:``.
``s_time``
This variable can be used to restrict the results to product with
performances at a given time of day (in the product's local time
zone). The parameter must be a four digit string in '``HHMM``'
format. Please note that use of this variable may exclude product
that is not performance based, (such as attraction tickets).
For example, to restrict the results to product with 19:30
performances only, set ``s_time=1930``.
``s_grp``
This variable can be used to restrict to events marked visible to
certain TicketSwitch 'user groups'. Event groups are intended
primarily for internal use, and it is not normally possible for
affiliates to derive useful results from using this variable.
All standard search criteria supported can be expressed using the
variables above. However, there are alternate input forms for dates and
geographical restrictions that may be more convenient to use. The caller
should not use both forms in a single request, but in case of conflict,
the standard forms (above) always override the alternate forms described
below.
``s_start_year, s_start_month, s_start_day, s_end_year, s_end_month, s_end_day``
These six variables are alternative forms of ``s_dates``. In each
case, the parameter value must be an integer in the appropriate
range. (The year must be expressed as four digits.)
It is an error to specify one of the ``s_start_year``,
``s_start_month`` and ``s_start_day`` without specifying all three.
A similar restriction applies to ``s_end_year``, ``s_end_month`` and
``s_end_day``.
``s_geo_lat, s_geo_long, s_geo_rad_km``
These three variables are alternate forms for ``s_geo``. In each
case, the parameter value must be a floating point number in the
appropriate range. It is an error to specify one of the
``s_geo_lat`` and ``s_geo_long`` without specifying all three.
``s_airport``
This variable is an alternate form to ``s_geo``. The three letter
IATA airport code is converted into WSG84 latitude and longitude
coordinates, and the results are restricted to a circle centred at
that point.
The radius of the circle must be specified in km, either as part of
the ``s_airport`` parameter value (with a colon separating the
radius from the airport code) or via the ``s_geo_rad_km`` parameter
described above. If a radius is not given, the ``s_airport``
parameter may be ignored.
For example, to return events within 50km of London Heathrow
Airport, set ``s_airport=LHR:50`` or set ``s_airport=LHR`` and
``s_geo_rad_km=50``.
``s_city``
This variable is another alternative to ``s_geo``. The proprietary
code is translated into WSG84 latitude and longitude coordinates and
a radius, and the feed are restricted to a circle of the given
radius centred at that point.
Valid values for this input may be obtained either from
```` (or ````) elements attached to events
returned by the feed, or by explicitly requesting a city list from
the ``xml_feed``.
Parameters for maintaining a local database
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[sec:dbUpdateParams]
Some affiliates may with to use the TicketSwitch event feeds to maintain
a local database of events. This database should be refreshed
periodically by re-fetching the complete list, but there are two
optional parameters that can be used to reduce the amount of processing
and data transfer required to maintain it while doing 'smaller' updates
more frequently.
For instance, an affiliate might fetch the complete product list once a
week, and apply twice daily updates.
This section describes the two CGI input parameters that are used for
this purpose. These variables are like the search criteria parameters
described in [sec:criteriaParams] in that they affect the list of
products returned; but they differ in that they are understood by
TicketSwitch event feeds only, and not by ``search`` or ``xml_core``.
``mod_since_hours``
This variable can be used to restrict the results to only those
products that have been changed recently in TicketSwitch's content
management system. The value of ``mod_since_hours`` must be an
integer, which is interpreted as a number of hours in the past.
For example, to restrict the feed to return only events which have
been modified within the last week, set ``mod_since_hours=168``. In
typical usage, the caller would request a much shorter time period.
Please note that there are circumstances where a product may be
changed without its 'modification timestamp' being updated. For that
reason, affiliates using ``mod_since_hours`` should also fetch the
complete list from time to time. Note also that changes to
associated event media files are not currently reflected in an
event's modification timestamp. Therefore ``mod_since_hours`` will
usually 'miss' changes to event media.
``dead_only``
Setting this parameter to '``yes``' causes the feed to return only
those events marked as 'dead' in TicketSwitch's database. All such
events should be removed from the affiliate's local database since
they will not be available for sale. Any links or 'buy-buttons'
associated with dead events will either cause an error, or return no
search results.
Note that 'dead' events are never usually deleted from
TicketSwitch's database, so that use of ``dead_only`` may cause a
very large volume of data to be returned. To reduce the burden at
both ends, ``dead_only`` should always be combined with
``mod_since_hours`` or some other appropriate restriction.
Feed paging parameters
^^^^^^^^^^^^^^^^^^^^^^
[sec:pageParams]
It would be antisocial (as well as expensive in terms of TicketSwitch's
bandwidth and processing costs) for the high volume, customer-facing
feeds (i.e. ``atom_feed`` and ``rss_feed``) to return the complete list
of events. Therefore, those scripts use paging to reduce the number of
events returned. Currently, the default page length for those scripts is
10 events. The actual default page length may change without warning.
The ``xml_feed`` does not use paging by default, but it can do so given
the appropriate input as described below.
There are three variables that are used to control paging:
``full``
This variable controls whether a feed returns to full list of
results, or uses paging to restrict the results to pages of a fixed
length. The value of ``full`` should be either '``yes``' or
'``no``'. Any other value is interpreted as '``yes``'.
Paging is enabled by default for RSS and Atom feeds (equivalent to
setting ``full=no``).
To generate a complete list of results in an RSS or Atom feed,
rather than the first page only, set ``full=yes``.
``page_len``
When present, this must be a positive integer representing the
maximum number of items to return in a single feed. If set to 0 it
is equivalent to setting ``full`` to '``yes``'.
The only way to enable paging functionality in the ``xml_feed``
(where it is disabled by default) is to use this input.
``item_limit``
This is a synonym for ``page_len``.
``page_no``
This variable allows access to the second or subsequent pages of
feed results. Its value should be a (1-based) integer indicating the
requested page number. If ``page_no`` requests a page beyond the
last page of results, it is ignored (so the first page is returned).
Note that the Atom format has built-in support for feed paging via
standard ```` elements, so that compliant feed readers can
automatically page through the complete logical feed if appropriate. The
``rss_feed`` uses these Atom elements as an extension.
See [sec:atomExtDefn] for a description of the ```` elements
returned enabling paging. The feeds also support OpenSearch, clients of
which usually have built-in support for feed paging. See
[sec:openSearchDefn] for more information about OpenSearch.
Feed sorting parameters
^^^^^^^^^^^^^^^^^^^^^^^
[sec:sortParams] All three feed scripts allow the results to be sorted
in one of three ways. By default, ``atom_feed`` and ``rss_feed`` returns
events ordered by date, reflecting expected behaviour of other RSS and
Atom type feeds, while ``xml_feed`` returns its results in alphabetical
order.
The following three input parameters may be used to override these
defaults:
``s_recent``
The presence of this input causes the feed results to be sorted by
the date when they were put on sale through TicketSwitch, with the
most recent products first.
This is the natural order for the RSS and Atom feeds, so it is the
default for those scripts.
To sort by date, set ``s_recent=yes``.
``s_alpha``
The presence of this input causes the feed results to be sorted in
alphabetical order, by event title then venue name.
This is the default order for the ``xml_feed``.
To sort in alphabetical order, set ``s_alpha=yes``.
``s_top``
The presence of this input causes the feed results to be sorted by
popularity, with the most popular products first. Popularity is
measured across all TicketSwitch users (including all affiliates).
To sort by popularity, set ``s_top=yes``.
Feed rendering parameters
^^^^^^^^^^^^^^^^^^^^^^^^^
[sec:renderingParams]
This section describes four optional CGI parameters that can be used to
disable the inclusion of XML style-sheets and to defeat certain
browsers' automatic feed detection algorithms. This can be useful for
debugging.
It is possible to associate a style-sheet with an XML document by
including a Processing Indication (a 'PI') at the top of the document.
By default, the output of ``rss_feed`` includes a PI for an XSL
style-sheet. In the future, TicketSwitch may add additional PIs to the
output of other feeds, and may use other style-sheet formats, such as
CSS.
Under some circumstances, the presence of a PI can interfere with XML
processing programs, such as ``xsltproc``. It can also be useful to use
a browser (such as Firefox) to display the raw XML source of a feed, for
instance during development and testing. For these reasons, all
TicketSwitch event feeds accept the following CGI inputs used to disable
the PIs.
``no_style``
This parameter can be used to prevent the feed from generating any
style-sheet PIs at all.
To do so, set ``no_style=yes``.
``no_xslt``
This parameter can be used to prevent the inclusion of an XSL PI.
PIs for style-sheets in other formats are not affected.
To disable any XSL PIs, set ``no_xslt=yes``.
``no_css``
This parameter can be used to prevent the inclusion of a CSS PI. PIs
for style-sheets in other formats are not affected.
To disable any CSS PIs, set ``no_css=yes``.
Note that even in the presence of a style-sheet PI, the program
processing the XML may choose to ignore the PI, may substitute its own
style-sheet, or may not support it in the first place. Browsers that
respect XSL PIs include Firefox before version 2, Safari 1 and Internet
Explorer 6.
SafariRSS, Internet Explorer 7, Firefox 2 and most desktop feed readers
substitute their own style-sheets, ignoring any feed PIs. In some
browsers, ``hide_from_browser`` can be used to try to get around this
behaviour where it is inconvenient, by fooling the browser into not
realising that the document is a feed. The following technique works
with Firefox 2 and reportedly with Internet Explorer 7:
``hide_from_browser``
This parameter can be used to attempt to defeat feed autodetection
in some browsers, which try to rendering feed in their own way. This
is done by adding whitespace padding at the start of the feed.
If the browser does not interpret the file as a feed, it will
usually render any PI that may be present, or display a useful XML
source view. To add the padding, set ``hide_from_browser=yes``.
Specifying either ``no_style=yes`` or both ``no_css=yes`` and
``no_xslt=yes`` automatically enables ``hide_from_browser``.
Extra information parameters
============================
[sec:extraInfoParams]
TicketSwitch typically stores short paragraphs of information about each
event and each venue. The extra event and venue information is usually
stored as plain text, but it may sometimes have variants in other
formats. The most common example is the use of simple HTML markup in
event information.
In addition to this textual data, TicketSwitch also stores event media
files, such as thumbnail images, with each event. This is described in
the following section, [sec:eventMediaParams].
Both the textual data and the event media files are available through
TicketSwitch event feeds. All information is available through the
``xml_feed``. All information except the venue information is available
through ``rss_feed`` and ``atom_feed``.
``full_info``
This variable can be used to control whether a feed includes any
paragraphs of 'extra information' that are available for each
product. This option is disabled by default in the ``xml_feed``, but
enabled by default for ``rss_feed`` and ``atom_feed``.
For example, to cause the ``xml_feed`` to include full event and
venue information, set ``full_info=yes``. To prevent the
``rss_feed`` from including any full event information, set
``full_info=no``.
The inclusion of full information has a significant impact on the
size of a feed file (and the resources required to generate it).
Affiliates are encourages to set ``full_info=no`` in cases where
this information is not required.
``mime_text_type``
The full event (and venue) information discussed above may be stored
in a variety of formats appropriate for different sales channels. It
is possible to request that an event feed return the information in
any of these formats. If necessary, the feed will convert the
information into the requested format. Any markup will be escaped as
appropriate for inclusion in an XML document.
There are exactly four permitted values for this variable:
'``plain``', '``html``', '``xml``' and '``vnd.wap.wml``'. By
default, the ``xml_feed`` returns event and venue information in
'``plain``' text format, while the RSS and Atom feeds use
'``html``'. Note that the use of '``xml``' and '``vnd.wap.wml``' in
``atom_feed`` may produce output that is not a valid Atom 1.0
document.
``full_info_images``
It is often beneficial to embed thumbnail images representing a
product within that product's event information. It is possible for
the event feed scripts to do this automatically for the case when
the event information would be returned as HTML. This is not
possible for other ``mime_text_type``\ s.
The use of ``full_info_images`` is enabled by default for the RSS
and Atom feeds, but is not currently supported in the ``xml_feed``.
To prevent the ``rss_feed`` from embedding event images in the full
event information, set ``full_info_images=no``. It is not possible
for the caller to have fine control over how the images are
embedded, or which images are chosen. Currently, the following html
is typical:
::