32. Feed API

32.1. 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]

32.1.1. 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.

32.1.2. 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].

32.1.3. 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’.

32.2. 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.

32.2.1. 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_feeds 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.

32.2.2. 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.

32.3. 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.

32.3.1. 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.

32.3.2. 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 <head> 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.

32.3.3. 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).

32.3.4. 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.

32.3.5. 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.

32.4. Linking to feeds

[sec:feedLinks]

The Link Generator can be used to obtain links to customer-facing rss_feeds, 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]

32.5. Feeds - Technical Overview

32.5.1. 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.

32.5.2. 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> <mailto:affiliates@ticketswitch.com>`__. Technical queries, bug reports and requests for technical help using the event feeds should go to `<feeds@ticketswitch.com> <mailto:feeds@ticketswitch.com>`__. It is helpful if you quote your TicketSwitch user_id in all correspondence.

32.5.3. 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.

32.5.4. 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.

32.5.5. Feed input parameters

[sec:feedParams]

32.5.6. 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-insensitively 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 <city_code> (or <tsw:city_code>) elements attached to events returned by the feed, or by explicitly requesting a city list from the xml_feed.

32.5.7. 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.

32.5.8. 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 <atom:link> 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 <atom:link> 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.

32.5.9. 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.

32.5.10. 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.

32.6. 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_types.

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:

<div style="min-height:80px">
  <div style="float:left; padding:0; margin:5px 5px 5px 0;">
    <img align="left" style="padding: 0px; margin: 0px;"
      height="75" width="75"
      src="http://www.ticketswitch.com/shared/event_media/
        kps_uk/LDN/FOM_T/5935/small.jpg">
  </div>
  The text of the event information.
</div>

32.6.1. Event media parameters

[sec:eventMediaParams]

In addition to embedding image links in HTML event information, the feeds can also return any event media files encapsulated directly in the XML output. This feature is available for rss_feed or atom_feed when the is enabled, and is always available to the xml_feed. For details of how the media data are encapsulated in the feed, see [sec:eventMediaFormat].

There is a short list of filenames, each of which may have a single event media file associated with each event. The list of file possible filenames is currently this: ‘small.jpg‘, ‘large.jpg‘, ‘large-190x100.jpg‘, ‘large-525x200.jpg‘, ‘supplier.jpg‘, ‘seating_plan.jpg‘, ‘banner.gif‘, ‘banner.jpg‘ and finally ‘video.flv‘. New filenames may be added to this list in the future.

Which media files to return is controlled using the following CGI input parameters. Note that event_media_pattern has been deprecated in favour of request_media.

request_media

This variable causes the feed to return event media data for any of the filenames requested. This input is interpreted as a comma-separated list of filenames. It cannot contain patterns or wildcards. The order of the names within the list is not significant.

For example, to request data from any of the event media files named ‘small.jpg‘, ‘large.jpg‘ and ‘supplier.jpg‘, the feed user would set request_media=small.jpg,large.jpg,supplier.jpg.

event_media_pattern

This variable causes the feed to return any media data associated with each event. The contents of event_media_pattern are treated as a pattern to be matched against the two filenames ‘small.jpg‘ and ‘large.jpg‘ only. Within a pattern, an asterisk (‘*’) is treated as a wildcard, matching any number of characters in the filename. Every other character in the pattern string matches itself only.

For example, setting event_media_pattern=* may return data from both ‘small.jpg‘ and ‘large.jpg‘. Setting event_media_pattern=small.jpg will return only media files named ‘small.jpg‘.

To request data from media files other than ‘small.jpg‘ and ‘large.jpg‘, use request_media.

TicketSwitch can make no guarantees about the file format or image dimensions of any data returned via this mechanism. The caller is encouraged to perform their own checks on the returned file type. In the case of images, the caller may need to crop, re-scale or even reject any images that are not of the required dimensions.

The thumbnail event images used in the standard web buy-process are ‘small.jpg‘ and are usually 75x75 pixel JPEGs. This cannot be guaranteed.

Note that the use of event_media_pattern or request_media may cause a dramatic increase in the volume of data returned by the feed. Therefore, the caller should use this feature only when necessary, and certainly no more frequently than once per day.

Feed users wishing to make use of ‘video.flv‘ should contact TicketSwitch directly before doing so. Due to the extremely large file sizes involved with video files, it may be better to find another way to distribute that file.

32.6.2. Pricing parameters

[sec:eventPricingParams]

Pricing information may be requested from any of the feeds by using the following input. There are currently no other feed inputs affecting how prices are returned.

use_prices

This variable can be used to cause the event feed to attempt to return approximate event price ranges.

Please note that even if this parameter is used, prices cannot be displayed in rss_feed or atom_feed unless the namespace is enabled (see below).

The elements used to return the pricing information are described in [sec:eventPricingFormat].

For details of how the pricing data are expressed in the feed output, see [sec:eventPricingFormat].

32.7. Miscellaneous other parameters

[sec:otherParams]

This section described any input variables the do not fit into any other section.

link_title

This parameter allows the caller to have some control over the title and description of feeds that support it (rss_feed and atom_feed). The xml_feed currently has no place for a feed-level title, so this input has no effect on xml_feed.

The contents of link_title are used as part of the feed-level <title> and <atom:title> elements respectively. Note that even when link_title is specified, the feed’s title currently still includes the user’s displayed name. The precise format of a feed’s title is not guaranteed, even when link_title is used.

This element is of little use for users using the feed to build a dynamic site, but it can be useful to create customer-facing links to the feeds. TicketSwitch uses this technique in the buy-process.

use_cities

This option is enabled by default in the rss_feed and atom_feed. This input is only needed by the xml_feed to return events’ city information, which is not provided by default in the interest of backwards compatibility. If set to ‘yes‘, this input causes the xml_feed to return the <city_code> and <city_desc> elements where possible for each event. Setting use_cities to ‘no‘ will cause any feed not to return those elements (or their equivalents in the extension).

32.8. Namespace extension parameters

[sec:xmlnsParams]

The RSS 2.0 and Atom 1.0 standards both are both freely extensible via external namespaces. TicketSwitch uses this facility in both atom_feed and rss_feed in order to include information that would not otherwise fit into those formats.

It is not necessary to use namespace-based extensions in xml_feed since that script uses its own proprietary XML elements.

32.8.1. Available feed extensions

[sec:availableXmlns]

The rss_feed and atom_feed scripts implement part or all of the following feed extensions. These are listed by ‘tag’ or namespace prefix, even though this is not semantically significant. What is significant is the URL linked with each tag via the xmlns=... attribute in the XML. Many of these extensions are existing ‘well-known’ extensions in general use by other feeds, but some are specific to TicketSwitch.

,

The ‘Dublin Core’ metadata set and ‘DC Terms’. See the specification at http://dublincore.org/, and [sec:dcDefn] for more information.

, , ,

These four similar extensions allow items within the feed (and the feed itself) to be tagged with geographical information as appropriate. Typically the WSG84 latitude and longitude are used. See [sec:geoDefn] where TicketSwitch’s implementation of these extensions is described.

This extension exposes the search functionality of feeds to external web sites or other systems that understand the OpenSearch standard, such as http://opensearch.a9.com/. This extension is used in conjunction with the script rss_open_search_desc. See [sec:openSearchDefn] for more information.

This extension adds several optional <atom:link> elements to the feed output, including those allowing a compliant feed reader to reconstruct the entire logical feed from a single page (typically the first).

In an atom_feed, this is not an extension at all, but rather a set of optional extra core elements. It cannot be disabled for atom_feed. See [sec:atomExtDefn] for more information.

This extension allows an aggregator to reconstruct the entire feed, even though it is broken into smaller pages. This is a relatively new extension, so it is not widely supported. See [sec:historyDefn] for more information.

The rss_feed and atom_feed scripts also implement a proprietary TicketSwitch extension:

This proprietary extension encapsulates product information that has no place in either the native feed formats, or in any well-known namespaced extension. This extension allows the atom_feed and rss_feed to include most of the information previously only available in the xml_feed. See [sec:tswExtDefn] for more information.

Several of the well-known namespaced extensions are enabled by default in the atom_feed and rss_feed. The proprietary extension is disabled by default because it increases the volume of data returned by a feed for no benefit in the common case. The extension is disabled by default since it is not widely understood by aggregators.

Each extension can be explicitly enabled or disabled using the following CGI input variables:

use_xmlns_dc, use_xmlns_dcterms, use_xmlns_geo, use_xmlns_geourl, use_xmlns_geotags, use_xmlns_icbm, use_xmlns_openSearch use_xmlns_atom_ext, use_xmlns_history, use_xmlns_tsw

When present, the value of any of these variables should be either ‘yes‘ or ‘no‘. This causes the specified namespace to be enabled or disabled. For example, to enable the extension, set use_xmlns_tsw=yes; to disable the namespace, set use_xmlns_history=no.

None of these inputs currently has any effect on xml_feed.

32.9. xml_feed-specific parameters

[sec:xmlFeedParams]

There are a small number of input parameters that are only interpreted by the xml_feed, and have no effect on the other feed scripts. This is usually to enable features in the xml_feed that are disabled by default for reasons of backwards compatibility.

Users of the atom_feed and rss_feed are expected to be more robust in the face of unexpected new elements than are users of the xml_feed because RSS2 and Atom have a well-defined extension mechanism and independent standards.

32.9.1. xml_feed backward compatibility

[sec:xmlFeedCompat]

Since the xml_feed is proprietary to TicketSwitch and there is no external specification, TicketSwitch is always very careful about ensuring that any changes maintain backwards-compatibility.

As a general rule, any new features that are introduced into the xml_feed require the user to pass additional inputs before they are activated. Elements that are present in the default output of the xml_feed will continue to be supported, and new elements will not be added unless the feed user passes an additional flag. Furthermore, once an input parameter is made available to the xml_feed it will continue to be supported with the same effect, or a compatible effect.

Although it is not possible to give a complete guarantee that this level of backwards compatibility will always be maintained, the current xml_feed remains compatible with the very first version despite two complete re-writes with many new features being added.

Implementations should be written defensively to insulate themselves from reasonable minor changes in the future. In particular, implementation should not make assumptions about the relative order of existing XML elements, and should continue to function if new elements are added. One design pattern that goes some way towards this goal is always to refer to XML elements by name.

32.9.2. Requesting pre-built urls

[sec:xmlFeedPreBuiltParams]

Traditionally, the only way for users of the xml_feed to construct valid URLs from feed data involved a relatively complex manipulation of several XML elements. Implementations were also required to implement URL-encoding.

This complexity is necessary for maximum flexibility, but there is now a simpler method for applications that simply need to link to events and/or event and venue info pages.

The following variables are used to enable the generation of these pre-built urls. When present, the value of these variables should be either ‘yes‘ or ‘no‘. If not given, the xml_feed behaves as if these variables were present with a value of ‘no‘.

use_buy_button_urls

If this variable is set to ‘yes‘ it causes the feed to return basic pre-built links, including event buy-buttons. Enabling this imposes very little extra burden on TicketSwitch’s web servers.

use_info_button_urls

If this variable is set to ‘yes‘ it causes the feed to return pre-built info-buttons This is more ‘expensive’ in terms of server load than you might think because the feed must check for the presence of extra venue and event info for each event before it constructs the link.

32.9.3. Requesting lists of internal codes

[sec:xmlFeedCodeLists] Some feed (and ‘search.buy‘) inputs hold proprietary codes that are not governed by any external standard and as with other inputs, passing unknown values may cause an error. The xml_feed (but neither rss_feed nor atom_feed) provides a way to access a list of these inputs. Requesting these features completely changes the output format of the xml_feed as described in [sec:classList] and [sec:cityList].

class_list

When this input is present and not set to ‘no‘, the xml_feed switches to producing output as described in [sec:classList]. This provides access to inputs suitable for s_class, and lists possible values of event classifications.

Not all possible classification may be returned: the feed first identifies all events that would have been matched by the feed if the s_class input had not been specified, and returns only those classifications associated with that list of events. This means old or deprecated classifications will no longer be returned.

city_list

This input can be used to request information about TicketSwitch’s proprietary city codes. These codes are used as inputs to s_city or returned by <city_code> elements. The format of a feed where city_list is specified is described in [sec:cityList].

The value city_list may be ‘all‘, ‘all_product‘ or ‘yes‘. For ‘all‘ an entry for every city is returned irrespective of whether it has any product, or if that product would have been visible to the feed. For ‘all_product‘ all city codes are returned that have live product even if that product would not have been returned by the feed. For ‘yes‘, the behaviour is similar to like class_list in that it only returns cities associates with product that would otherwise have been returned by the feed.

Note that for city_list or if class_list is set to ‘yes‘, then the list returned will be filtered according to any search criteria applied to the feed. For instance, if s_keys is set to ‘mamma mia‘ and class_list is given, only classifications attached to event matching a keyword search for ‘mamma mia‘ would be returned.

32.10. Low-level script inputs

[sec:lowLevelParams]

This section describes the low-level input variables that are part of the generic TicketSwitch script framework. They are fundamental to the correct operation of any TicketSwitch scripts, feeds included. They are described here for completeness rather than to encourage feed users to manipulate them directly.

user_id Every TicketSwitch script runs as a particular user, which is identified by its unique user_id. Each affiliate is given their own user_id, which must be specified to the feed. Non-affiliate users (such as business-to-business organisations) are also assigned a unique user_id to specify to the feed. If you do not specify your ``user_id``, any sales made through the feed will not be credited to the right account.

sub_id This input has two purposes. For business-to-business users it is a critical part of the user identification process, with a different sub_id being assigned to each agent within a business-to-business organisation. In the context of business-to-business, the sub_id is sometimes known as a ‘client ID’.

The second function applies to non-business-to-business users such as affiliates. For affiliates, the sub_id. field may take any (reasonable!) value, which can be used to track sales or even to run a secondary affiliate program. Any sub_id attached to a link is preserved throughout the entire buy-process, and is logged with any sales made.

user_passwd This input is only necessary to authenticate a business-to-business user to TicketSwitch. Affiliates need not give a user_passwd (or even a crypto_block) when calling a feed. A user’s password is the same one used by affiliates to log into their link generator.

chan TicketSwitch divides sales into several different sales channels. Most affiliates use the ‘web‘ channel, which is the default and need not be specified. The ``chan`` input should only be used under instructions from TicketSwitch.

new_lang When present, this input must contain a valid ISO639 language code (and optional variant). This input can be used to request content in the language given. This request will take precedence over any languages listed in Accept-Language:. See [sec:lang] for more details.

crypto_block This input is used to hold a compressed and encoded block of arbitrary CGI parameters it also serves as a weak form of authentication for scripts that require it. Except for business-to-business users, feed do not require a crypto_block, but all scripts accept one and will interpret any parameters stored inside.

It is an error to pass a variable to a script outside a crypto_block that is already set inside the crypto_block, just as it is an error to specify the same parameter twice without a crypto block.

32.11. Apache path-info

[sec:pathInfo]

This section describes how TicketSwitch uses Apache path-info as a shorthand for accepting the three fundamental script inputs, user_id, chan and new_lang described above. This section is provided for information only. It is safer for feed users to use named CGI inputs rather than path-info, except when using URLs or prefixes pre-built by a feed, or as instructed by TicketSwitch.

After the script name (e.g. ‘rss_feed.exe‘), the next three slash-separated path-info components are alternatives to user_id, chan and new_lang respectively. Each of these components is optional, and has a default value depending on the hostname. The default is used if the path-info component is not specified, or if it is set to ‘-‘.

For example, the following URLs are all equivalent because the default user_id on is ‘tswlink‘ and the default chan is ‘web‘

As an example with a user_id that is not the default, the following are equivalent:

32.12. Equivalent paths

[sec:equivalentPaths] On all TicketSwitch scripts, the script extension ‘.exe‘ is equivalent to ‘.buy‘; the directory ‘cgi-bin/‘ is equivalent to ‘tickets/‘. The feeds and TicketSwitch buy-process normally uses ‘tickets/‘ and ‘.buy‘ on links that do not require a crypto_block.

The following URLs are equivalent:

[sec:feedFormat]

At the most basic level, all feeds are well formed XML1.0 documents. The following three section describe the XML structure of the three flavours of feed.

In the case of rss_feed and atom_feed, the output is compatible with the relevant specifications (i.e. RSS 2.0 and Atom 1.0). Where an event feed implements a well known feed extension the results will always be compatible with all requirements of that extension’s specification. Note that with the exception of Atom 1.0, is quite common for such ‘standards’ to be imprecise and poorly documented.

The xml_feed script uses a proprietary format so there is no external standard for it to conform to.

All three feeds will return a different error response when a low level error prevents normal execution. In this rare case, their output will not be compatible with the relevant specifications, but it will still be well formed XML1.0. See [sec:errorFormat] for details.

32.12.1. The output of rss_feed

[sec:rssFormat]

The XML returned by rss_feed is structured according to the RSS 2.0 specification at http://blogs.law.harvard.edu/tech/rss. This section simply describes how that specification is applied by TicketSwitch. For information on the syntax of each element consult the specification itself.

32.13. Child elements of <channel>

[sec:rssMetadata]

The nineteen possible child elements of <channel> are used as follows:

<title>

This currently contains the string ‘Tickets from UserName‘, where UserName is the affiliate user’s ‘real name’. The precise format of <title> may change. Some control over the value of this element is available via the link_title input. See [sec:otherParams].

(The real name is usually displayed at the top left of that affiliate’s web-finder. It may be changed at the request of the affiliate.)

<link>

This element will contain a URL to the affiliate user’s web-finder.

<description>

This will contain the same text as in the <title> element, except in the case where the feed is limited to a single country or a single ticketing system. In that case, it will also contain the name of that country and/or system.

In the future this element may also describe other restrictions in the feed’s search criteria, such as the names of cities or classes that the feed is restricted to.

<language>

This element will contain the ISO639 language code identifying the human language of the majority of content in the feed. This value is determined in the same way as the value in the Content-Language: header. See [sec:lang].

<copyright>

This element will contain ‘Copyright © 2004-2008 TicketSwitch’, or a similar string.

<managingEditor>

This element contains an email address for editorial questions or comments relating to the feed content. This address is currently webmaster@ticketswitch.com.

<webMaster>

This element contains an email address for technical questions or comment relating to the feed itself. This address is currently given as feeds@ticketswitch.com.

<pubDate>

This contains the most recent date when one of the items in the feed that was put on sale. When the feed is empty, this item will be omitted.

<lastBuildDate>

Not used. TicketSwitch’s feeds are generated dynamically ‘on the fly’ father than being ‘built’ and served out as static files.

<category>

If the feed was limited to a particular event class or subclass via the s_class input, then this element will contain the value of that parameter. Otherwise this element will be omitted.

<generator>

This element will contain the following string (or similar) identifying the rss_feed and TicketSwitch as the process responsible for generating the feed: ‘TicketSwitch - Middleware - rss_feed.exe’.

<docs>

This element will contain the following URL which describes the RSS 2.0 format: ‘http://blogs.law.harvard.edu/tech/rss‘.

<cloud>

Not used.

<ttl>

Not used.

32.14. Child elements of <item>

[sec:rssData]

In addition to holding the nineteen possible meta-data elements discussed above, <channel> holds a series of zero or more <item> elements. Each <item> corresponds to a TicketSwitch product (or search result). In RSS 2.0, there are ten possible child elements of <item>. They are used by rss_feed as follows:

<title>

This element contains the title of the product. The precise format of this field is subject to change, but it will always contain the title of the event itself. Currently, <title> also contains the name of the venue and the city name (if appropriate).

<link>

This contains a URL to the event information page for the product (i.e. an info-button link). If there is no extra information to be displayed on such a page, then <link> will contain a buy-button link to the product instead.

<description>

This contains the product’s extra event information text if there is any. If there is no event information for this product (or if full_info=no is specified), then this element will be omitted.

RSS 2.0 allows <description> to contain inline HTML (correctly encoded for XML). By default, rss_feed makes use of this facility by converting the extra event information to HTML. The mime_text_type input parameter can be used to change this default.

Note that it is not possible in RSS 2.0 to indicate whether <description> contains encoded HTML, plain text, or some other format. This is a deficiency of the RSS 2.0 specification is known to cause interoperability problems. Atom 1.0 does not have this problem.

<author>

Not used.

<category>

There may be zero or more <category> elements present, according to the event classifications of the product. When present, the content of these elements will be of the form ‘class/subclass’, making them suitable to be passed to rss_feed (or another feed) in the s_class variable.

The optional domain="…" attribute is not used because TicketSwitch does not currently have a suitable URL describing the individual categories.

<comments>

Not used.

<enclosure>

Not used.

<guid>

This contains a permanent unique identifier, for the product. Note that a given product will always have the same <guid>, irrespective of the feed it appears in. This applies even to a product appearing in feeds belonging to different affiliates. This ensures that a customer who subscribes to multiple TicketSwitch feeds in a desktop or web-based aggregator is not presented with the same item multiple times.

The optional isPermaLink="…" attribute will always have the value ‘no‘, indicating that although the content of <guid> resembles a URL, it does not point to any resource, and should never be dereferenced. (The caller would receive a ‘404‘ page not found error if <guid> were dereferenced.)

<pubDate>

This element will contain the date when this product was put on sale through TicketSwitch. This date will not normally change for a given event even when its name or content is updated.

<source>

The content of this element is the title of the current RSS feed (i.e. the contents of the <channel>‘s <title> element).

The required url="…" attribute will contain a link to the current user’s unrestricted rss_feed. (I.e. a link to rss_feed without any search criteria applied.) This allows aggregators to discover the primary (unfiltered) feed from the contents of a filtered feed.

32.15. Extensions in rss_feed

[sec:rssExtensions]

As permitted by the RSS 2.0 specification, TicketSwitch’s RSS feeds optionally include additional XML elements in separate namespaces. These extensions are described in [sec:extensions].

32.16. RSS 2.0 standards compliance

Unlike Atom 1.0, the RSS 2.0 ‘standard’ is not very well specified. Despite this, the rss_feed is designed to be fully compatible with that standard such as it is. The exception to this is when mime_text_type is used, causing the contents of <description> to be other than escaped HTML. Implementations where this would be a problem should not use that input parameter!

With this single exception, any deviation from the standard is most likely to be a bug, and should be reported to TicketSwitch.

32.16.1. The output of atom_feed

[sec:atomFormat]

The XML returned by atom_feed is structured according to the Atom 1.0 specification at http://www.ietf.org/rfc/rfc4287. This section simply describes how that specification is applied by TicketSwitch. For information on the syntax of each element consult the specification itself.

The elements in this section are described with an ‘atom:‘ prefix for consistency with the Atom 1.0 specification itself. Despite this, the actual elements returned by atom_feed will have no namespace prefix.

32.17. Child elements of <atom:feed>

[sec:atomMetadata]

Like RSS, the Atom 1.0 specification allows for the inclusion of information relating to the feed itself. Such meta-data is expressed as child elements of the top-level <atom:feed> element. This section describes how those meta-data elements are used by TicketSwitch.

<atom:author>

This element provides a contact address for technical issues relating to the atom_feed itself. The two child XML elements (<atom:name> and <atom:email>) currently contain the following strings respectively: 'feeds@ticketswitch.com‘ and ‘TicketSwitch’.

<atom:category>

If the feed is restricted to a particular event category (either just a class or a class/subclass pair) then the restriction will be described by an <atom:category> element. Atom does not define a meaning for the content of this element, so it will always be empty.

When present, this element will have a term="…" attribute containing either a single class or a slash-separated class/subclass pair. The attribute’s value is suitable for passing in the s_class input variable.

The element will also have a label="…" attribute containing a human-readable name for this string. One advantage of the atom_feed over the rss_feed is that it allows for such classification labels.

<atom:contributor>

Not used.

<atom:generator>

This element is used to identify the system responsible for generating the atom_feed. It will contain the string ‘TicketSwitch - Middleware - atom_feed.exe’ or similar.

<atom:icon>

When present, this element will contain the url pointing to a TicketSwitch icon. The image is currently a 64x64 pixel square at this URL: http://www.ticketswitch.com/images/ticketswitch/logo64.gif

<atom:id>

This element is used to identify feeds generated by atom_feed separately from feeds from other publishers. The value of this <atom:id> will be unique to TicketSwitch, but shared across all atom_feed urls irrespective of the search criteria or affiliate.

<atom:link>

Most feeds will have four top-level <atom:link> element each containing a URL relevant to the feed. The meaning of each link may be deduced from the rel="…" and type="…" attributes. The individual <atom:link> elements are described below.

An <atom:link> element with the relation rel="self" and content type type="application/atom+xml" will have its url="…" attribute pointing to the atom_feed itself.

An <atom:link> element with the relation rel="related" and content type type="text/html" will have its url="…" attribute pointing to the user’s web-finder.

An <atom:link> element with the relation rel="alternate" and content type type="text/html" will have its url="…" attribute pointing to an html search results page using the same search criteria and ordering as the current feed.

An <atom:link> element with the relation rel="alternate" and content type type="application/rss+xml" will have its url="…" attribute pointing to the corresponding rss_feed (again using the same search criteria and ordering).

For feeds that are paged, there will be more <atom:link> elements with content type type="application/atom+xml". They use the relations rel="first", rel="prev", rel="self", rel="next" and rel="last" to provide links to different pages of the complete logical feed.

<atom:logo>

When present, this element will contain the url pointing to a TicketSwitch logo. The current value of the URL contained by this element is http://www.ticketswitch.com/images/ticketswitch/logo.gif.

<atom:rights>

This element contains the following string: ‘Copyright © 2004-2006 TicketSwitch’ (or similar).

<atom:subtitle>

If the feed is restricted to a particular country or backend system then this element will contain a human-readable string indicating that fact. Otherwise this element will be omitted.

<atom:title>

This currently contains the string ‘Tickets from UserName‘, where UserName is the affiliate user’s ‘real name’. The precise format of <atom:title> may change. Some control over the contents of this element is available via the link_title input. See [sec:otherParams].

(The real name is usually displayed at the top left of that affiliate’s web-finder. It may be changed at the request of the affiliate.)

<atom:updated>

This will contain the most recent time when any one of the products in the feed was updated. If there are no products in the feed, this element will contain an arbitrary date in the recent past. This behaviour is not ideal, but <atom:updated> is mandatory, and due to the dynamic way the feed is generated, it is not possible to calculate a more appropriate value.

32.18. Child elements of <atom:entry>

[sec:atomData]

In addition the the feed-level meta-data elements, the top-level <atom:feed> element contains a series of <atom:entry> elements. Each of those elements describes a single product (search result) available for sale. This section describes how those child elements of <atom:entry> are used by atom_feed.

<atom:author>

Not used.

<atom:category>

This element is structured in the same way as the corresponding element at the <atom:feed> level. For products that have several classifications, there will be multiple instances of this element in that <atom:entry>.

Unlike the <atom:category> element at the <atom:feed> level, these elements are not dependent on the search criteria used to access the feed.

<atom:content>

This element will contain the product’s extra event information. For events that do not have any extra information (or when full_info=yes is set) this element will be omitted.

By default, the content of this element will be HTML (encoded appropriately for inclusion in an XML element). In that case, the type="…" attribute will be set to type="html".

This default behaviour can be overridden by by using the mime_text_type CGI input parameter. When mime_text_type=plain, the content will be returned as plain text, and the type="…" attribute will be set as type="text".

Note that setting mime_text_type to ‘xml’ or ‘vnd.wap.wml’ will cause atom_feed to return a <atom:content> element that is in violation of the Atom 1.0 specification. Atom consumers for whom this will cause a problem should not use mime_text_type in that way!

<atom:contributor>

Not used.

<atom:id>

This contains a permanent unique identifier, for the product. Note a given product will always have the same <atom:id>, irrespective of the feed it appears in. This applies even to a product appearing in feeds belonging to different affiliates. This ensures that a customer who subscribes to multiple TicketSwitch feeds in a desktop or web-based aggregator is not presented with the same item multiple times.

<atom:link>

Most <atom:entry> elements will have exactly one <atom:link> child element. The element will have a relation of rel="related" and content type of type="text/html". Usually, the url="…" attribute will be an info-button pointing to the product’s extra information page. In the case where the event has no extra information, the URL will be a buy-button instead.

<atom:published>

This element holds the date on which the product was made available for sale through TicketSwitch. This date will not normally change when the event’s content is updated, unless the change is so fundamental as to make the event resemble an entirely new product.

<atom:rights>

Not used.

<atom:source>

Not used.

<atom:summary>

Not used.

<atom:title>

This element will contain a human-readable string identifying the product. Although the actual format may change from time to time, it will always contain the title of the event itself.

This element may also contain the name of the venue where the event is held, and/or the name of the city.

<atom:updated>

This element contains a date identifying the last time this product’s content was updated in our content management system. Note that there are some circumstances when a product’s content may be updated without being reflected in this element.

32.19. Extensions in atom_feed

[sec:atomExtensions]

As permitted by the Atom 1.0 specification, TicketSwitch’s Atom feeds optionally include additional XML elements in separate namespaces. These extensions are described in [sec:extensions].

32.20. RFC4287

The Atom 1.0 format is defined by RFC4287, which is an IETF Proposed Standard. With a single exception, the atom_feed is written to be completely compatible with the standard. Any deviation from this should be reported to TicketSwitch as a bug.

The atom_feed is fully compliant with the standard, which means it complies with all the ‘MUST‘ requirements from RFC4287. However, it may violate some of the ‘SHOULD‘ recommendations. This is primarily a function of the source data driving the feed, which may have no extra event information.

The single exception to this rule is when the mime_text_type input is used. This can cause <atom:content> to return data in formats other than plain text or escaped HTML. Implementations where this is a problem should not use mime_text_type!

32.20.1. Feed namespaced extensions

[sec:extensions]

Under the control of the ‘use_xmlns_‘ CGI input parameters (see [sec:xmlnsParams]), both the rss_feed and atom_feed may return elements in external namespaces. Both specifications allow for this kind of extension.

For documentation on the syntax and semantics of each extension’s element, you should refer to the official specification for each extension. This section simply describes how each extension is used in rss_feed and atom_feed.

Currently, the default for rss_feed and atom_feed is to enable all of the ‘well-known’ extension (i.e. all supported extensions except and ) excluding [5]. Since the extension elements are essentially the same across both scripts, they are described together [6]. The xml_feed has no need of external namespaces, so the ‘use_xmlns_‘ input variables have no effect on that script.

32.21. The Dublin Core extensions

[sec:dcDefn]

TicketSwitch event feeds implement elements from the two related extensions and . The possible feed meta-data elements are described below. In the case of rss_feed, these are child elements of <channel>. In the case of atom_feed, these are child elements of <atom:feed>.

<dc:title>

This element will contain the title of the feed. I.e. the contents of rss_feed‘s <title> or atom_feed‘s <atom:title>. As described in [sec:otherParams], some control is available via the link_title element.

<dc:creator>

In atom_feed, this element will contain the name of a contact for the feed. Normally, that is the string ‘TicketSwitch’. This element will be omitted in the rss_feed in favour of a native element.

<dc:subject>

This element is intended as a list of keywords relating to the feed. In is only used for feeds whose search criteria include a keywords search (in which case it contains a comma-separated list of keywords).

<dc:description>

This element contains a slightly more detailed version of the title of the feed. In contains the contents of rss_feed‘s <description> or atom_feed‘s <atom:subtitle>.

<dc:publisher>

In atom_feed, this element will contain the name of a contact for the feed. Normally, that is the string ‘TicketSwitch’. This element will be omitted in the rss_feed in favour of a native element.

<dc:contributor>

Not used.

<dc:date>

Not used.

<dc:type>

Not used.

<dc:format>

Not used.

<dc:identifier>

This element contains a string uniquely identifying the feeds generated by TicketSwitch as distinct from those from other publishers. The content of this element are analogous to the contents of <atom:id> in the case of the atom_feed. Note that like <atom:id>, this element cannot be used to distinguish between feeds with different search criteria.

<dc:source>

This element will contain a URL pointing to the source of the feed itself. In other words, this element will contain a link to either rss_feed or atom_feed.

<dc:language>

Not used. (Other than in English, TicketSwitch can never guarantee that the entirety of the feed contents are available in any particular language. We will return the translations that are available. See [sec:lang].)

<dc:relation>

Not used.

<dc:coverage>

Not used.

<dc:rights>

This will contain the same string as atom_feed‘s <atom:rights> element. This element will be omitted in the rss_feed, in favour of its native <copyright> element.

Element from the Dublin Core can also be used to provide extra meta-data relating to individual products in the feed. Neither rss_feed nor atom_feed currently makes use of this facility, since there is no case where there is extra data available that would add value to the feed.

In addition to the Dublin Core, there is an additional set of meta-data known as Dublin Core Terms (). The rss_feed uses exactly one element from that set (unless disabled by setting use_xmlns_dcterms=no. The atom_feed and xml_feed use none.

<dcterms:modified>

This element may be present as a child of rss_feed‘s <item> element only. It contains the date when the product’s content was last updated in our content management system. Note that there are times when an event may be changed, yet this not be reflected in this element.

This is not used by atom_feed since it has the same meaning as the native <atom:updated> element.

32.22. The geographical extensions

[sec:geoDefn]

The rss_feed and atom_feed both support four different feed extensions for associating geographical information with the feed and with individual items. Three (, and ) are enabled by default.

The reason to implement several extensions that hold the same information is to gain support in as many aggregators as possible. For instance, one aggregator might support while another might only support . The three well-known extensions use the following XML elements

<geo:lat>, <geourl:latitude>, <icbm:latitude>

These elements hold the WSG84 latitude of the product or feed. Feeds that are not restricted geographically will omit these elements at the feed level. Events for which TicketSwitch does not store geographical data will also omit these elements.

<geo:long>, <geourl:longitude>, <icbm:longitude>

These elements hold the WSG84 longitude of the product or feed. Feeds that are not restricted geographically will omit these elements at the feed level. Events for which TicketSwitch does not store geographical data will also omit these elements.

The remaining supported geographical extension () is disabled by default. This is because, strictly speaking, it is defined only for HTML <meta> elements (used in the header of web pages). This means there are unlikely to be aggregators that understand it. This is unfortunate since unlike the other geographical extensions, it has the ability can human-readable strings identifying the location, and also a country code. When this extension is explicitly enabled by setting use_xmlns_dcterms=yes, the following elements are produced:

<geotags:lat>, <geotags:long>

These elements use WSG84 co-ordinates as described above.

<geotags:placename>

This element contains a human-readable string holding the city and country names associated with the feed or product.

<geotags:region>

This element is used to hold the ISO3166 country code associates with the event or feed.

32.23. The extension

[sec:openSearchDefn]

Both rss_feed and atom_feed implement the OpenSearch 1.1d2 specification as defined by http://opensearch.a9.com/. This allows TicketSwitch event content to be included in (and searched by) OpenSearch aggregator sites such as http://opensearch.a9.com/. The forthcoming release of Internet Explorer 7 is expected to support OpenSearch.

32.23.1. The OpenSearch description document

There is a utility script, rss_open_search_desc, that generates an OpenSearch description document. It can be called the same way as rss_feed or atom_feed, simply replacing the script name with ‘rss_open_search_desc‘. Like the other feed scripts, it should be passed the appropriate user_id so that any links it produces go through to the correct user.

Despite the name, rss_open_search_desc document includes links referring to atom_feed, rss_feed and even the usual search script that returns HTML pages. The returned OpenSearch description document also contains a little metadata relating to the search.

Most CGI inputs that are accepted by rss_feed and atom_feed are also accepted by rss_open_search_desc, and are simply passed through to any ‘downstream’ URLs generated. This includes all search criteria inputs as described in [sec:criteriaParams].

32.23.2. The OpenSearch response

When enabled, as it is by default, this extension causes the following feed-level elements to be returned. This section is provided for information only: the official specification should always be considered the canonical definition of these elements.

<openSearch:total_results>

The total number of items that would be returned by the feed if paging was not in use.

<openSearch:start_index>

The 1-based index into the total results set identifying the first item in the feed. The indices of the other feed items can be calculated by counting upwards from the value of this element.

<openSearch:items_per_page>

The ‘page length’ of the feed (in terms of numbers of items). Note that it is quite possible for the physical feed document to return fewer than this number of results, and for the value of <openSearch:items_per_page> to be greater than that of the element <openSearch:total_results>. See [sec:pageParams] for more information about feed paging.

<openSearch:link>

This element contains a URL to the feed’s OpenSearch description document (the rss_open_search_desc script). This element is structured exactly as <atom:link> except that it is in the OpenSearch namespace.

<openSearch:Query>

This element describes search that the feed represents, including any keyword applied.

The extension does not generate any extra item-level elements.

32.24. The extension

[sec:atomExtDefn]

Although strictly speaking it is not an extension at all when present in an Atom document such as the output of atom_feed, but it is convenient to treat this group of elements as a feed extension. This allows it to be enabled and disabled as necessary. More importantly, it allows <atom:link> elements to be included in the output of rss_feed [7] to enable paging and feed history reconstruction.

32.24.1. Feed-level elements

This extension produces a series of feed-level <atom:link> elements. Each element uses a rel="…" value to describe the relation of the linked resource to the feed document. The type="…" attribute gives the MIME type of the linked resource so that the client can distinguish between links that return HTML pages and other feeds for example.

The following is a list of rel="…" relations that are defined by the core Atom 1.0 specification in RFC4287.

rel="alternate" type="application/rss+xml", rel="alternate" type="application/atom+xml"

This pair of <atom:link> elements point to alternative representations of the same search results page in RSS 2.0 and Atom 1.0 format respectively. The URLs give point to rss_feed and atom_feed.

rel="alternate" type="text/html"

This is an <atom:link> pointing to the search results page as used by customer at the start of the buy-process. The search criteria and options are as near as possible to those that were passed to the feed (within the limitations of search script).

rel="related" type="text/html"

This is an <atom:link> pointing to the home page of the user’s buy-process, or to the log in page in the case of a business-to-business user.

rel="self"

This <atom:link> gives the canonical URL for ‘this script’, be it rss_feed or atom_feed. The URL will include any search criteria parameters, but will not include any special paging parameters so that it always points to the first page in a multi-page feed.

The following <atom:link> elements are returned in addition to the core ones above. These are intended to allow desktop aggregators to reconstruct the entire logical feed from a single page, and to allow them to maintain a cached ‘feed history’ efficiently without either requesting the feed excessively often or risking missing some items.

The following items all give the MIME type of the current feed (i.e. either type="application/rss+xml" or type="application/rss+xml" for rss_feed or atom_feed respectively). These link relations are taken from the official IANA registry of link relations.

rel="current" type="application/rss+xml", rel="current" type="application/atom+xml"

These <atom:link> elements hold URLs pointing to start of a conventional (i.e. date-ordered) feed of events. They discard any paging and ordering parameters, but preserve any criteria inputs that may have been passed to the script.

These elements gives the feed URL that should normally be used as a subscription in a desktop feed reader. They choice between Atom and RSS is left to the client.

rel="first", rel="last", rel="previous", rel="next"

The only difference between these <atom:link> elements is the page number specified in each case.

From a feed page in the middle of a long logical (pages) feed, these point to the first, previous, next and last pages of the logical feed. Either or both of rel="previous" and rel="next" may be missing on the first or last page of a logical feed respectively.

Note that the element with rel="first" will always point to a feed with page_no=1 so it will not change with time even though the elements it contains will change as new events are added.

32.24.2. Item-level elements

This ‘extension’ generates exactly one item-level element. It is another example of an <atom:link> element with a rel="…" value from the IANA registry of link relations.

rel="payment"

This <atom:link> element holds a URL that is a buy-button for the event. Although payment is not accepted on the page referenced, that page is the first page in the buy-process, which justifies the use of rel="payment".

32.25. The extension

[sec:historyDefn]

As of the fifth draft of Mark Nottingham’s feed history extension, supporting this extension no longer makes any difference to the output of any TicketSwitch feed. Most elements defined by previous drafts are now implemented as Atom link relations returned by the extension.

The feed history draft defines a single element:

<history:complete>

The presence of this item would indicate that the feed was a ‘complete’. Even when not ordered chronologically, no TicketSwitch event feed is complete in the sense of the feed history draft because new events may be added at any time.

32.26. The extension

[sec:tswExtDefn]

In addition to the ‘well-known’ feed extensions, rss_feed and atom_feed support an additional extension that is used to encapsulate significant extra data that is naturally associates with TicketSwitch products (or feeds), but cannot otherwise be returned. This extension includes much of the information previously only available in the xml_feed itself.

Being a proprietary format, there is no external documentation available for this extension. This section should be taken as normative.

When this extension is enabled (by setting use_xmlns_tsw=yes in rss_feed or atom_feed), the following XML elements are added to the feed’s top level meta-data container. (I.e. <channel> in the case of rss_feed, and <atom:feed> in the case of atom_feed.) These elements re-use the names (or naming style) from the xml_feed or xml_core as far as possible.

32.26.1. extension feed-level elements

[sec:tswExtMetadata]

The following two feed-level elements are present in a feed where the TicketSwitch extension is enabled:

<tsw:user_id>

This element hold the short token used by TicketSwitch to identify the TicketSwitch user (e.g. affiliate) for the purposes of branding, event restrictions, and credit for sales. This field is provided primarily for information, but it may be useful in constructing links.

<tsw:user_real_name>

This element holds the ‘real name’ associated with the TicketSwitch user identified by <tsw:user_id>.

The following elements will be omitted for business-to-business users, because they would make no sense (or pose a risk) for business-to-business applications. They are present for non-business-to-business users including all affiliates.

<tsw:crypto_block>

This element holds an ‘empty’ crypto_block suitable for passing to another TicketSwitch script that requires it (such as search).

<tsw:search_url_prefix>

This element contains a prefix from a URL pointing to the search script. This prefix should be combined (perhaps in an HTML <form>) with a blank crypto_block (such as the contents of <tsw:crypto_block>) and, optionally, other search criteria.

Attempting to go to the page identified by this URL prefix without adding a ``crypto_block`` will result in an error.

<tsw:unrestricted_search_url>

This element contains a complete URL to the search results for this TicketSwitch user. The search is not restricted by any criteria that may have been passed to the feed, so it will list every event available for sale to this user (subject to paging).

<tsw:criteria_search_url>

This element contains a complete URL to the search results corresponding to this script. Any search criteria passed to the feed are included in this link.

<tsw:web_finder_url>

This element holds a complete URL pointing to this user’s web-finder. This is suitable for use on a web page as a ‘home’ button for the affiliate’s buy-process.

For business-to-business users only these additional two elements will be present instead of the above five:

<tsw:business_login_url>

This element holds a url pointing to the page business-to-business users may use to log in to the business-to-business buy-process.

<tsw:client_user_id>

This element holds a short string containing ‘client’ or ‘sub-user’. This can be used to identify individual business-to-business agents.

32.26.2. extension event-level elements

[sec:tswExtData]

The following elements are added to each feed item to return extra TicketSwitch-specific data with individual feed events. Many of these elements are identical to the corresponding elements returned by the xml_feed. See [sec:xmlFormat].

<tsw:event_token>

This provides a unique persistent identifier for the event, suitable for use as a primary key in an affiliate’s custom database of TicketSwitch events. For a given event, this identifiers will not change, and old <tsw:event_token>s will never be re-used.

<tsw:src_code>, <tsw:area_code>, <tsw:venue_code>, <tsw:event_code>

In combination, these four codes form an alternative primary key for the event. These inputs correspond to the four inputs s_src, s_src, s_src and s_src respectively. See [sec:tswHier].

<tsw:src_desc>, <tsw:area_desc>, <tsw:venue_desc>, <tsw:event_desc>

These elements contain human-readable titles corresponding to the four codes above. All except <tsw:area_desc> are suitable for display directly to the customer.

TicketSwitch areas correspond to loose groupings of events, usually geographical. They are often cities, but this is by no means reliable. If required, the name of the nearest city should be derived from the element <tsw:city_desc> instead.

<tsw:start_date>, <tsw:end_date>

If appropriate, these elements contain first and last available dates and times of the event. For performance-based events, these correspond to actual performance times. These elements may be omitted for items that are not date based, such as catalogues.

The format of these elements is ISO8601 making them easily machine readable, but not ideal for display to the customer.

<tsw:start_date_desc>, <tsw:start_time_desc>, <tsw:end_date_desc>, <tsw:end_time_desc>

These elements contain human-readable dates and times describing the dates in <tsw:start_date> and <tsw:start_date>. The format is currently as in ‘Tue, 20th June 2006’ and ‘7.30 PM’, but this may change without notice. Applications for which the precise date/time format is important should parse <tsw:start_date> and <tsw:start_date> before converting them appropriately. Again, for items such as catalogues that are not date-based these elements may be omitted.

<tsw:country_code>

This optional element contains the ISO3166 country code of the item (when the item is associated with a particular country). This will be omitted when the event is not associated with a particular country.

<tsw:country_desc>

When <tsw:country_code> is present, this element gives a human-readable name of the country. This element will be omitted when <tsw:country_code> is not present.

<tsw:city_code>

This element gives the internal TicketSwitch code representing the closest city to the event. Values returned here may be passed back to the feed through the s_city input to list all events at the given city. This element will be omitted by default in the xml_feed unless use_cities is set to ‘yes‘, or for the other feeds if use_cities input is explicitly set to ‘no‘.

<tsw:city_desc>

This element gives the name of the closest city. The city is derived automatically from any geographical latitude and longitude information stored with the event. As such, this element will be missing for events which do not have latitude or longitude information and for events where there is no nearby city in TicketSwitch’s database. This element will be omitted by default in the xml_feed unless use_cities is set to ‘yes‘, or for the other feeds if use_cities is explicitly set to ‘no‘.

For access to the underlying latitude and longitude data, clients should use an appropriate ‘well-known’ extension such as .

<tsw:postcode>

This element contains the event’s UK post code, US ZIP code or similar as appropriate. This data is often more naturally associated with a venue than an event, but in the general case it can vary at a single venue from one event to another.

This element may be omitted if the event has no postcode.

<tsw:event_seo_name>

This element contains a ‘sanitised’ version of the two elements <tsw:event_token> and <tsw:event_desc>, changed remove all but the most basic ASCII characters. The resulting string is unique for each event (because it includes the <tsw:event_token>) but suitable for use as part of a file name or within a url. The exact content of this element may change in the future without notice, but those two properties are guaranteed still to hold.

After sanitisation, this field will contain a mixture of lowercase ASCII letters, numbers and dashes. It will not contain any other punctuation, spaces, non-ASCII etc.

<tsw:event_image_url>

This element contains a ready made link to an appropriate event media file. Any one wishing to take advantage of this element must fetch the image file and store it in a local image file or database, and must not hot-link directly to our servers.

<tsw:event_buy_url>, <tsw:event_info_url>, <tsw:venue_info_url>

These three elements provide links to specific pages related to the event. Note that each feed format typically includes at least one ‘native’ link to the event, and many more are available via the extension.

The <tsw:event_buy_url> element is always present, and provides a buy-button taking the user straight into the buy-process for the event. The first page of the buy-process is typically a list of performances.

When present, <tsw:event_info_url> and <tsw:venue_info_url> give info-button links to pages of extra information related to the event or venue. Not all events have extra information of this kind, in which case either or both of these elements will be missing.

32.26.3. elements shared with xml_feed

When possible, the extension can be requested to return approximate price range information, and encapsulated event media data such as images thumb-nails. These elements are also returned as ‘native’ xml_feed elements. See [sec:eventPricingFormat] and [sec:eventMediaFormat] for information about how this data is returned in the extension.

32.26.4. extension example

[sec:tswExtExample]

32.26.5. The output of xml_feed

[sec:xmlFormat]

Unlike atom_feed and rss_feed, the xml produced by xml_feed is entirely proprietary to TicketSwitch. Therefore there is no external specification [8] and this documentation provides the specification.

The overall structure returned by the xml_feed is a single <event_list> element containing a small number of metadata elements, plus a zero of more <event> elements each describing an individual event. In common with the rss_feed and atom_feed, the XML returned is completely different if a low level error prevents normal execution. See [sec:errorFormat].

For total flexibility, the URL data returned by default by the xml_feed need further processing before they can be used to construct valid links. See [sec:feedXmlQueries] for details. Alternatively, it is possible to ask the xml_feed to return ‘pre-built links’ that are good enough for many common cases. See [sec:xmlFeedPreBuiltParams].

32.27. Child elements of <event_list>

[sec:xmlMetadata]

All xml_feed documents contain the following feed-level elements as children of <event_list>:

<return_link>

This element contains a URL prefix that must be combined with other URL components to form a URL the can be dereferenced without causing an error.

This link will produce an error if it is used on its own.

<bare_query>, <part_query_head>

These structured elements describe xml_feed XML queries that should be used in combination with <return_link> to produce a valid url. See [sec:feedXmlQueries].

The <bare_query> includes parameters to make a valid search link without including any search criteria that may have been passed to the feed. The <part_query_head> includes any search criteria passed to the feed. The latter is often combined with <part_query_body>from and <event> element.

If either of the use_buy_button_urls and use_info_button_urls inputs, the following two elements may also be returned. See [sec:xmlFeedPreBuiltParams] for more details of the meaning of those inputs.

<unbounded_search_url>

This element contains a complete URL to the search results for this TicketSwitch user. The search is not restricted by any criteria that may have been passed to the feed, so it will list every event available for sale to this user (subject to paging).

<web_finder_url>

This element holds a complete URL pointing to this user’s web-finder. This is suitable for use on a web page as a ‘home’ button for the affiliate’s buy-process.

32.28. Child elements of <event>

[sec:xmlData]

The list of events that comprises the feed is returned as a series of zero or more <event> child elements of <event_list>. Many of the child elements of <event> are identical to those from the extension (without the namespace tag).

<event_token>

This provides a unique persistent identifier for the event, suitable for use as a primary key in an affiliate’s custom database of TicketSwitch events. For a given event, this identifiers will not change, and old <event_token>s will never be re-used. Elsewhere, this field may be referred to as <event_id>.

<src_code>, <area_code>, <venue_code>, <event_code>

In combination, these four codes form an alternative primary key for the event. These inputs correspond to the four inputs s_src, s_src, s_src and s_src respectively. See [sec:tswHier].

<src_desc>, <area_desc>, <venue_desc>, <event_desc>

These elements contain human-readable titles corresponding to the four codes above. All except <area_desc> are suitable for display directly to the customer.

TicketSwitch areas correspond to loose groupings of events, usually geographical. They are often cities, but this is by no means reliable. If required, the name of the nearest city should be derived from the element <city_desc> instead.

The <src_desc> element is the supplier of the ticket, which should be displayed to the customer. Feed users should be aware that no tickets are supplies directly by TicketSwitch.

If the return of full event and venue information text has been enabled via the full_info variable, then there will be a <full_info> child element of <event>. It will contain the following child elements:

<full_info>

The following elements will always be present even if they are both blank (which is rare for most events).

<event_info>, <venue_info>

These elements will contain extended paragraphs of information as attached to the event or describing its venue. By default, a simple text representation of the data is returned (escaped for inclusion in an XML document). Note that line breaks are significant in a plain text context - they are often used to separate paragraphs or to set off headings from the surrounding text.

Alternative flavours of this data may be requested by using the mime_text_type input. For instance, if the requested format is to return HTML, the <event_info> and <venue_info> elements will contain HTML markup (again escaped for inclusion in an XML document).

Both full_info and mime_text_type are described in [sec:extraInfoParams].

<venue_addr>

This element will return a partial postal address for the venue. An address for display should normally be constructed by appending the venue name, followed by this field, followed by the postcode and country (where each of those fields is available). This element also respects the mime_text_type input as described above.

Note that venue addresses were included within the <venue_info> element in the past before this separate field was available. The migration of the data may not be complete.

Each event may be classified into zero or more event classes, which may be searched on or displayed to the customer. The classifications of each event are returned via the following child elements of <event>.

<event_class>

There will be zero of more <event_class> elements according to the classifications of the given event.

<main_class>

This is the internal code representing one main top-level classification of the event.

<sub_class>

Each <main_class> will have one or more <sub_class> elements representing sub classifications. Neither <main_class> nor <sub_class> may be suitable for display. Suitable displayed names are available in the standalone class list. See [sec:classList].

TicketSwitch’s event classification system is a two-level hierarchy set out by <main_class> and <sub_class>. These codes may be used to construct valid inputs to s_class. That input may either take a single value from <main_class>, or a slash-separated pair of values from <main_class> and <sub_class>. For example ‘s_class=theatre‘ or ‘s_class=theatre/musicals‘.

32.28.1. Pricing and event media in xml_feed

The xml_feed can return approximate price ranges and media data such as images associates with an event. The format of the output to do so is described separately in [sec:eventPricingFormat] and [sec:eventMediaFormat] respectively. Note that unlike rss_feed and atom_feed, the xml_feed does not use any namespace prefixes.

32.28.2. Link information

The most important elements returned are those enabling the caller to generate links to each event:

<part_query_body>

This element contains a string of extra CGI input parameters that can be combined with <part_query_head> and <return_link> to produce a url to the given event.

<full_query>

Alternatively, this xml_feed XML query can be combined directly with <return_link> to produce a url for this event. The combination of <part_query_head> and <part_query_body> is entirely equivalent to the use of <full_query> alone.

It may be inconvenient for implementations to handle the xml_feed XML query elements correctly. Instead, it is possible to use the following elements which contain pre-built URLs that need no further processing before they may be used. These elements are enabled via the use of use_buy_button_urls and use_info_button_urls. See [sec:extraInfoParams].

<buy_button_url>

This element contains a pre-built buy-button to the given event. It needs no further processing before it can be used.

<event_info_button_url>, <venue_info_button_url>

These two optional elements contain info-buttons pointing to pages of extra information about the event or venue. Not all feed items have such extra information, in which case these either or both of these elements will be omitted.

32.28.3. Date ranges

For items that are date based (most items), the following elements are also produced, describing the first and last available dates of the given event in various machine- and human- readable forms. Note that for items that are not date-based (such as catalogues) these elements may be omitted.

<start_date>, <end_date>, <start_date_desc>, <start_time_desc>, <end_date_desc>, <end_time_desc>

These elements give the first and last available dates for the feed item if appropriate. They are described in [sec:tswExtData].

In addition, these dates are given in different formats via the following elements. In every case, the dates and times being described are the same: merely the format is different.

<start_date_time_desc>, <end_date_time_desc>

These elements give human readable descriptions including both date and time of day. The exact format of this element is subject to change but an example is ‘Fri, 31st October 2008, 12.00 AM’.

<start_date_yyyymmdd>, <end_date_yyyymmdd>

These elements give machine readable forms of the dates in YYYYMMDD format: YYYY will be replaced by the 4-digit year, MM by the 2-digit 1-based month and DD by the 1-based day of the month. For example ‘20081031’.

<start_date_hhmm>, <start_date_hhmmss>, <end_date_hhmm>, <end_date_hhmmss>

These give machine readable forms of the times of day in HHMM[SS] format: HH will be replaced by the 2-digit hour, MM by the 2-digit minute, and SS by the 2-digit second.

<start_time_utc_seconds>, <end_time_utc_seconds>

These machine readable element give the number of seconds between the standard Unix reference date and the date/time being described. The reference date is midnight, 1st January 1970.

This format of dates is extremely useful for doing calculations and comparisons, but not suitable for display to end customers (or even programmers).

<start_time_utc_offset>, <end_time_utc_offset>

These elements describe the offset (due to time zone or daylight savings) of the time being described from UTC. This element should be used by implementations where knowledge of an event’s time-zone is important.

Note that many ticketing systems do not return precise time-zone information, in which case this value may be a best approximation.

32.28.4. Geographic Data

Where the information is available, there will be a <geographic_info> child element of <event> containing the event’s nominal coordinates as follows:

<geographic_info>

If present, this child element of <event> will contain:

<event_lattitude>

(sic)

<event_longitude>

These elements contain the WSG84 latitude and longitude coordinates respectively. Note the unusual spelling of the <event_lattitude> element, which will not be changed for reasons of backwards compatibility.

The following optional child elements of <event> may also be present, and are identical to the corresponding elements described in [sec:tswExtData]:

<country_code> <postcode> <city_code> <city_desc>

For backward compatibility, <city_code> and <city_desc> will be omitted unless the use_cities input is specified (see [sec:otherParams]). They may also be omitted in any case if the event has not been assigned to a city, perhaps because the event is very new, has no latitude/longitude data, or because there is no nearby city.

32.29. Generating URLs from xml_feed output

[sec:feedXmlQueries]

This section describes the system the xml_feed uses to encapsulate HTTP queries or urls in the XML returned. If the only possibility was to construct text-based links, then the complexity described here would not be necessary. The extra structure allows the link data to be used in other contexts such as HTML forms and POSTed HTTP requests.

Queries are encapsulated in the xml_feed in three parts

the ‘return link’

This is a simple string prefix that should form the first part of the url to be generated. When used in an HTTP POST request, this determines the host to which to connect, and the virtual path where the CGI script is located.

This component only holds low level data, typically just the name of the script to be run, and the affiliate user_id to use.

This component must always be combined with a ‘query head’ as described below. If used on its own, the ‘return link’ will usually return an error page.

the ‘query head’

This is potentially the most difficult part of a query for the feed consumer software to use. It encapsulates arbitrary CGI parameters in XML, with the child element names representing CGI parameter names, and child element string content representing the values to set.

The string content is not URL encoded, so if trying to form a URL for use with HTTP GET, the caller must URL encode the value first. [9]

Typically a ‘query head’ would just contain a single crypto_block parameter containing an opaque encoded string of data. However, all implementations must be prepared to receive multiple child elements in a query head and pass them all back to the script identified in the return link.

There must be exactly one ‘query head’ component used to produce any valid query-derived URL.

the ‘query body’

This optional component is a single field containing a query string of several CGI name/value pairs. The complete string is already URL-encoded so it needs no further processing before use in an HTTP GETtable URL.

Implementations wishing to use a query body in a POST request have two options: they can either extract the individual name/value pairs (undoing the URL-encoding) and POST them along with any other parameters, or they can use the entire string as the value of a sub_query CGI parameter. Note that in the latter case it will be necessary to re-URL-encode the string.

The sub_query input can also be used in other circumstances to pass multiple CGI variables in this way. It must only be used once in a single request. This technique is sometimes useful when constructing HTML forms involving radio buttons or drop-down menus.

All xml_feed results include a single <return_link> element at the feed level. This is the only instance of a ‘return link’ as described above. A typical example is:

<event_list>
  <return_link>
    http://www.ticketswitch.com/tickets/search.buy/tswlink
  </return_link>
  ...
<event_list>

There are at three places where ‘query heads’ occur: The <bare_query> and <part_query_head> are both examples at the feed level. The <full_query> child element of <event> is another example of a ‘query head’.

There is only once instance where a ‘query body’ element is used. That is the <part_query_body> child of the <event> element. This element is intended to be combined with the feed-level <part_query_head>.

This is an example of the query elements returned by the xml_feed:

<event_list>
  <return_link>
    http://www.ticketswitch.com/tickets/search.buy/tswlink
  </return_link>
  <bare_query>
    <crypto_block>
      c---URfoHrJ....JvdsDoYct0--Y
    </crypto_block>
  </bare_query>
  <part_query_head>
    <crypto_block>
      s---kg2mlmHHw...SN49WE4GY_-Y
    </crypto_block>
  </part_query_head>
  ...
  <event>
    <part_query_body>
      s_area=EW&s_eve=FAMILY&s_ven=FLINGOLA
    </part_query_body>
    <full_query>
      <crypto_block>
        U_--pCwgutVKGNULUw...KvluNxlDC6FpS8y1B7OiY
      </crypto_block>
    </full_query>
  </event>
  ...
<event_list>

If combined into a simple url, the <return_link>, <part_query_head> and <part_query_body> could be used as follows. Line breaks have been added for clarity.

http://www.ticketswitch.com/tickets/search.buy/tswlink
  ?crypto_block=s---kg2mlmHHw...SN49WE4GY_-Y
  &s_area=EW&s_eve=FAMILY&s_ven=FLINGOLA

Note that is it possible to ask the xml_feed to return pre-built which removes much of this complexity at the expense of some flexibility. See [sec:xmlFeedPreBuiltParams] for more information.

32.30. Obtaining a list of event classifications

[sec:classList]

The xml_feed has an alternative mode of execution where instead of returning a list of events, it returns a list of classifications. This allows the user to obtain a dynamic list of classes to use in searches via s_class.

32.30.1. Inputs for class_list mode

The following variable is used to switch the xml_feed to this mode of execution:

class_list

When present, this value of this input should be either ‘yes‘ or ‘no‘. If class_list is given with any value other than ‘no‘, the feed behaves as if ‘yes‘ was specified, activating class_list mode.

Internally, when in class_list mode, the xml_feed still accepts the usual criteria inputs as described in [sec:criteriaParams]. It performs a search for events as usual, and only returns a class if there is a matching events with that classification. The inputs controlling ordering have no effect in class_list mode, but the inputs controlling paging (page_len, page_no etc.) apply to numbers of classes returned (instead of events).

32.30.2. Elements returned in class_list mode

When class_list mode is activated in xml_feed via the class_list input parameter, the structure of the XML returned changed completely. Instead of <event_list>, the root element is <class_list>.

That element contains a series of zero or more <class> elements, each containing zero or more <subclass> child elements. See [sec:xmlClassListExample] for an example of the XML returned in class_list mode.

32.31. Obtaining a list of TicketSwitch cities

[sec:cityList]

The xml_feed has an alternative mode of execution where instead of returning a list of events, it returns a list of cities. This allows the user to obtain a dynamic list of codes to use in geographical searches via s_city. Note that it is also possible to do geographical searches via explicit latitude, longitude and radius values, and via IATA airport code. Internally, searches based on s_city are converted into latitude/longitude/radius searches.

32.31.1. Inputs for city_list mode

The following variable is used to switch the xml_feed to this mode of execution:

city_list

When present, this value of this input should be one of ‘yes‘, ‘no‘, ‘all‘ or ‘all_product‘. If class_list is given with any value other than ‘no‘, the feed activates class_list mode. In class_list mode, the value of the input determines the set of cities returned.

‘yes‘

The list of cities returned is limited to cities of those events that would have been returned by the feed if it was not in class_list mode, and if no paging was applied.

‘all_product‘

The list of cities is limited to those with live events, but not limited to events that would have been returned by the feed.

‘all‘

The complete list of currently valid cities is returned irrespective of whether they have (or ever had) any live product, and whether such product would have been returned by the user.

‘no‘

The class_list mode is not activated. There is no reason to set this input to ‘no‘ explicitly!

32.31.2. Elements returned in city_list mode

When city_list mode is activated in xml_feed via the city_list input parameter, the structure of the XML returned changed completely. Instead of <event_list>, the root element is <city_list>.

That element contains a series of zero or more <city> elements, each containing a series of child elements describing properties of the city. One each of the following child elements is returned for every <city> element.

<city_code>

This is the internal proprietary code used to identify the city. Values appearing in this element may be used as valid inputs to s_city.

Do not be tempted to rely on the internal structure of this element, which may change. The country associated with the event is available separately in <country_code>.

<country_code>

This is the ISO3166 of the country associated with the city. Use this element to determine the country of the city rather than relying on internal structure of the city code.

<city_desc>

This is the name of the city, suitable for display.

<latitude>, <longitude>

This pair of elements describe the WSG84 latitude and longitude of the notional centre of the city that will be used for geographical searches.

<radius_km>

This element represents the notional radius of the city according to the TicketSwitch database. This may only approximately coincide with reality.

<has_product>

This element will contain either ‘yes‘ or ‘no‘ depending on whether this city currently has any live product. Note that this flag is a global value across the entire product range, including product not generally available. Therefore it is possible for a city to have <has_product> set to ‘yes‘ without any particular feed from returning product from that city.

See [sec:xmlCityListExample] for an example of the XML returned in city_list mode.

32.31.3. Event media in feed output

[sec:eventMediaFormat]

As described in [sec:eventMediaParams] the feeds may be requested to return the data from raw media files. This section described the format of the data returned if this feature is enabled via request_media.

The structure and content of the elements described here is the same for the xml_feed as the rss_feed and atom_feed. The only difference is that the xml_feed does not use namespaces, so in that case the elements do not have the prefix. This section uses to the prefixed element names.

Each media file returned comes within a single <tsw:event_media> element. There may be zero of more <tsw:event_media> elements at the event level depending on the media files requested, and depending on the files present for the given event.

Each <tsw:event_media> element will contain exactly the two following child elements:

<tsw:name>

This element gives the file name of this media file being returned. This element is primarily for information purposes: it is usually more convenient for feed consumers to use a different file name, and it is perfectly possible for the returned information to be stored in a database rather than a static file.

Note that the combination of <tsw:event_token> and <tsw:name> is guaranteed to be unique, and may make a more suitable file name.

<tsw:data>

This element contains a representation raw data that makes up the media file to be returned.

The data are encoded as a single long string of uppercase hexadecimal. The content of this element is a long string made up entirely of of the 16 characters ‘0123456789ABCDEF‘. In particular, it contains no whitespace or lowercase letters.

Note that browsers like Firefox will truncate the content of <tsw:data> in their default ‘XML tree’ view because it contains a single extremely long ‘word’. Clearly using a truncated value will result in a corrupt image file. This unexpected behaviour has caused several people (myself included) a great deal of confusing when debugging code for converting the hex data back to an image file!

[sec:decodingHex] gives some guidance on how to reconstruct the original file from this encoded data.

32.32. Linking directly to event media

TicketSwitch does not allow affiliates to link directly to event media files on our web servers. This is a policy decision to prevent ‘hot-linking’, and is not likely to be changed.

Affiliates may notice the structure of event media URLs used by looking at the TicketSwitch buy-process. It is not permitted to make use of this structure, which may change at any time without notice. Even if URLs are generated that are correct within the structure, it is not possible for affiliates to determine which urls will return a media file, and which will return an HTTP 404 (file not found) error.

32.33. Other representations of event media

TicketSwitch recognises that it may be comparatively difficult for feed users to reconstruct the media files from the hex-encoded data. We are willing to discuss adding alternative representations such as Base64 encoding or data URLs (as defined by RFC2397) for cases where it is excessively hard for a feed user to make use of the current hexadecimal data.

Note that it is not possible to include the data directly within the XML structure event if it XML-encoded using numerical references. This is because there are several low-ASCII octets (such as NUL) that it is simply not possible to include in a well-formed XML1.0 document. [10]

See [sec:decodingHex] for some help on using the current representation in a common situations.

32.33.1. Event pricing in feed output

[sec:eventPricingFormat]

It is possible to request that the feeds return approximate event price ranges. The relevant input is use_prices, which is described in [sec:eventPricingParams].

Pricing is returned using the same elements in xml_feed as it is for rss_feed and atom_feed. In the last two cases, the elements are part of the extension (which must be enabled) so their names include that prefix. The xml_feed doesn’t use any namespace prefix.

When requested, the following item-level elements are returned for each event where pricing information is available. If there is no pricing data available for a particular event, none of these elements will be returned for that event.

<tsw:currency_code>

This element gives the lower case, three-letter ISO8601 currency code of the prices for this event. Note that a single TicketSwitch user_id may see different currencies for different events (particularly if they are on a different ticketing system) but all prices for a single event will always be in the same currency.

<tsw:min_comb_price>, <tsw:avg_comb_price>, <tsw:max_comb_price>

These elements contain machine-readable values of the minimum, average and maximum prices recently seen for this item.

The format of these elements is a decimal without any currency symbol, so it it most useful for numerical calculations and comparisons. It is not suitable for display to the customer without further processing because it is not guaranteed to use the correct number of decimal places, and because it does not include any currency symbols.

It is very important to use the <tsw:currency_code> element to determine the correct currency in which these prices are expressed. Implementations must not assume that prices are in any particular currency or that prices for two different events will be expressed in the same currency.

<tsw:min_comb_price_desc>, <tsw:avg_comb_price_desc>, <tsw:max_comb_price_desc>

These three elements hold human-readable versions of the previous three elements. The difference is that their content includes the appropriate currency symbol ($, €, £, etc.) before and/or after the value, and that it is guaranteed to use the correct number of decimal places for the given currency.

32.34. How feed pricing is calculated

In general there is no answer to the question ‘What is the price of this event?’ That is because the actual price paid may vary depending on several other factors, including:

• the selected performance (or usage date),
• the selected ticket type (usually the ‘part of house’ for theatre tickets),
• and any discount or promotional code applied.

Therefore even in an ideal world it would only be possible for the feeds to return a price range associated with each event.

Unfortunately it is far from an ideal world! Even given a single event, date, ticket type and discount code, it is a relatively ‘heavy’ operation for most backend ticketing systems to return an available price. Obtaining this information from the ticketing system is known as an ‘availability request’.

In the buy-process itself, once the customer has selected a performance, TicketSwitch does make availability requests to determine the prices and ticket types to display. However, in the case of a feed, it would be prohibitive to make live availability requests for all events returned, for every ticket type on every performance. Therefore, all prices returned by the feeds are calculated from data that is cached by TicketSwitch in a local database.

Every time an availability request is made to the live ticketing system (for instance when a customer browses the buy-process), the results are cached in this database. The cache is shared between different users as much as possible to improve its accuracy and coverage; it has a relatively long expiry time, typically of the order of one week, to improve coverage further. The prices returned by the feed for a given event are the minimum, average and maximum values taken over all the prices remaining in the cache.

The limitations of this approach are illustrated in the following section.

32.34.1. Event pricing caveats

All prices returned from the feeds come from TicketSwitch’s local database, which is a cache of previous availability requests to the ticketing backend. This means there that the minima and maxima may be returned by the feeds can be inaccurate under some circumstances:

1. The pricing setup may have recently been changed in the backend system.
2. There may no longer be availability at a particular price where there was recently.
3. [enum:noPrice] Our system may happen to have never seen a specially low or high price for a particular date.

An extreme (and temporary) case of [enum:noPrice] is where our system has never seen any prices at all for a particular event. In that case there will be no price information for that event in the feed. All implementations must be prepared to cope with this situation.

In practice the prices are reasonably reliable, especially from systems that are not performance based, for events that have only a single performance, and for events whose price does not vary depending on the performance. Nevertheless is is sensible to include a disclaimer on any site where feed-derived prices are displayed.

32.34.2. Event date usage modes in feed output

[sec:eventDateUsageModeFormat]

Different events sold use various different modes for requesting dates from the customer. For instance, theme park tickets often require a departure date and a usage date in case the customer is leaving the country some time before they intend to use their tickets. The usage dates and departure dates may be any value from within the valid range, Theatre events on the other hand, typically require a performance to be selected from a fixed list of possibilities.

The following elements are provided so that affiliates can distinguish between the various date usage modes. These elements are only expected to be of interest to implementations where the xml_feed is used as part of a full integration with the xml_core.

<need_departure_date>

This element will contain either ‘yes‘ or ‘no‘ to indicate whether the event requires the customer to specify a departure date before it can be sold.

<using_usage_date>

This element will contain either ‘yes‘ or ‘no‘ to indicate whether the event requires the customer to specify a date of usage from with a given date range.

<using_perf_list>

This element will contain either ‘yes‘ or ‘no‘ to indicate whether the event requires the customer to select a date from a fixed list of performances.

These elements are described above without a prefix as if returned from the xml_feed. When returned from the extension, they will use the ‘tsw:‘ prefix, but are otherwise identical.

Feed users may notice the following additional element returned by the xml_feed. This element describes the event’s lingo, which is used internally by TicketSwitch to control various cosmetic options affecting the buy-process for the given event. It is not anticipated that this element be of any use by feed users, but it is described here for completeness.

<lingo_code>

This element will contain the internal identifier of the given event’s lingo.

32.34.3. Feed error output

[sec:errorFormat]

In some rare cases a low-level error may prevent normal execution, and force the feed scripts to return a low level error. This will be expresses as a well formed XML1.0 document with the a root element <script_error>.

The <script_error> element will always contain exactly two child elements as follows:

<error_code>

This element will contain an integer describing the error that has occurred.

<error_desc>

This element will contain a short sentence describing the error.

There are eight possible error codes, which are described individually in the list below. Errors 4, 5 and 7 should never occur when attempting to request a feed. Errors 1 and 2 relate to the string provided as user_id and chan; error 3 may indicate a corrupted crypto_block or a bad user_passwd. Error 6 is the only error that is genuinely due to problems at TicketSwitch. If you get error 8 then the data you are attempting to provide to the script is corrupt and you should re-check your link very carefully against this document.

The errors are described below:

1. Bad username provided This error will be generated if the affiliate user_id parameter given was incorrect. This parameter may either be given as the slash-separated path component after the script name, or as an explicit user_id input variable.

   If no user_id is given, the default (non affiliate) user will be used. In that case this, no error will be generated, but sales may not be credited to the correct user.

2. Bad channel provided This error will be generated if the user_id requested is not permitted to use the given channel. The channel parameter may either be given as the second slash-separated path component after the script name, or as an explicit chan input variable.

   If no chan is specified, the default will be used. The default (normally ‘web’) is correct in most cases, and a value should only be specified if requested by TicketSwitch.

3. Authorisation failure This error will be generated when either because no authentication information (either a crypto_block or user_passwd) were given when required, or because incorrect information was given.

   The feeds no longer require any form of authentication for use by affiliates, but business-to-business users must give the correct password.

4. Failed to create backend This error will be generated when a feed fails to create a working connection to a remote ticketing system. Since feeds do not require a connection to any remote ticketing system, this error should never be returned in practice!

5. Host is on forbidden network This error will be returned when the request originates from a forbidden network or IP address range.

6. Failed to connect to database This error will be generated when there is a complete failure to connect to a TicketSwitch database. Virtually all feed content is derived from a database.

7. Membership authentication failed This error will be generated when there is a failure to log back in to a membership. It does not normally make sense to make a request for a feed involving customer membership information.

8. Bad data supplied This error is returned when there is a problem interpreting any CGI input parameters. Malformed crypto_block elements will cause this error to be returned.

32.34.4. The TicketSwitch event hierarchy

[sec:tswHier]

Fundamental to the concept of TicketSwitch’s data model is its hierarchical structure of events. At the lowest level is a number of distinct backend ticketing systems. Each backend system is divided into several ‘areas’ which are further divided into venues. Each venue may hold many different events.

The set of all events from a single backend system can be thought of as a tree, with the system itself represented by the trunk and individual events as the leaves.

A given event is always associated with a unique backend, area and venue. Therefore, the four ‘model codes’ together (s_src, s_area, s_ven, s_eve) always specify a single event. The search results are always represented as a list of events. Users of the xml_feed of extension have access to the four model codes as <src_code>, <area_code>, <venue_code> and <event_code>.

32.35. Enforced and unenforced venues

There is one blemish on TicketSwitch’s simple hierarchical event model. Some ticketing systems allow unrelated events to be set up at the same ‘venue’ when their actual venues are different. In this case TicketSwitch marks the fake venue as ‘unenforced’, which allows us to apply a different venue name (and other venue information) to the individual events.

This means that two events with the same <venue_code> may not actually take place at the same venue. Feed users must always use the venue names and information returned with individual events.

32.35.1. Languages

[sec:lang]

32.36. Translated and non-translated elements

Some of the data returned by the event feeds contains human-readable text, which should be translated into the most appropriate language for display. On the other hand, some of the elements returned are purely machine-readable and therefore do not change depending on language.

It is usually obvious to which elements this applies: for instance <guid>, <event_token> and <atom:link> need not vary depending on language, while <description> does. Elements whose content varies according to the language required are said to be ‘translated elements’.

There are some elements that are not actually translated even though they contain human-readable text. This applies to <event_desc>, <venue_desc> and <tsw:user_real_name> (and to any elements derived from them). In rss_feed and atom_feed it this applies to <title> and <atom:title> respectively. There may be other elements that are human readable but not actually translated. Lack of translation on human-readable elements is usually due to a technical limitation rather than a deliberate decision. It is anticipated that some or all of these elements will be translated in the future.

32.37. Language selection

There are two mechanisms in use by TicketSwitch to select the most appropriate language for any translated content. Both these mechanisms are used identically by all TicketSwitch scripts, not just the feeds.

HTTP defines an Accept-Language: header, which may be specified by the client. This allows the client to state its preference in terms of language. All TicketSwitch scripts make use of this header when it is set.

In addition to the mechanism specified by HTTP, it is possible to request a language by using an explicit CGI input. This is prepended to any list derived from Accept-Language:

• When present, this variable must contain a two letter ISO639 language code (and optional variant); it becomes the ‘most preferred’ language used to return translated content. Note that it is also possible to specify new_lang as the third path-info component. See [sec:pathInfo].

  This variable is used by the TicketSwitch buy-process to allow the customer to select their preferred language without adjusting (or even understanding) their browser’s language settings.

  Use of new_lang effectively defeats HTTP’s elegant content negotiation, so it should be used only when necessary.

TicketSwitch always has content available in English. To ensure that some content can always be returned, all scripts append English to the bottom of any the language preference list derived from Accept-Language: and new_lang if it is not already present. Therefore, feeds may return translated content in English even if English is not specified in either the Accept-Language: header or in new_lang.

32.38. Language returned

Because TicketSwitch applies the preference list of languages to individual pieces of content rather than to the feed as a whole, it is quite possible for the same feed to return content in multiple languages.

Nevertheless, the feeds (and all other TicketSwitch scripts) set a Content-Language: header in their HTTP response. This header gives the language with the greatest amount of content in the resource returned. It may not be the same as any new_lang input, or even the first preference from Accept-Language: because there may be little or no content returned in those languages.

In addition to returning the Content-Language: header, rss_feed sets a feed-level <language> element. Note that this element occurs in the rss_feed after most of the items have been produced. This is because its value cannot be known until the rest of the content has been produced.

The feeds do not currently use the mechanism built in to XML (<xml:lang>) to specify the language of any translated elements. This may change in the future.

32.38.1. Managing cached data

Unless using the correct fields, affiliates intending to cache the data returned by the feeds may find it a somewhat cumbersome process to try and match up the returned data each time with what is stored in a local database. New events must be identified and inserted, as well as finding dead events that are no longer appearing in the feed. To make managing this information easier there are two variables which may be applied to the feed in order to alter the information returned.

The first of these is the dead_only flag. If this variable exists in the input then the results from the search will return a list of dead events as opposed to live ones. As events are not usually deleted from the TicketSwitch database then this may be a very long list. This can be modified by use of the mod_since_hours variable. By setting this to an integer value then only events which have had their data modified within that number of hours will be returned. Thus a feed may be managed by always setting this variable to ‘24‘ so only the changes in the last day are returned. When combined with dead_only then only events which have been removed in the last day will be returned.

See [sec:dbUpdateParams] for a full description of dead_only and mod_since_hours.

32.38.2. Extracting media data from hexadecimal

[sec:decodingHex]

This section gives some brief guidance on how to recreate static image files from hex-encoded data returned by the feeds (in <tsw:data>). See [sec:eventMediaParams] for details of how to request the media data from the feeds, and [sec:eventMediaFormat] for details of the XML structure then returned.

32.39. PHP example

[sec:decodingHexPhp]

This is a very brief example showing how to decode a string of hexadecimal data like that returned by the xml_feed to represent event media. It uses PHP’s built in pack() function to interpret the hexadecimal, and fopen(), fclose() and fwrite() to create the image file on disc. The first argument to the pack() function, is a ‘format specifier’. The ‘H‘ consumes a single uppercase hexadecimal character; the ‘*‘ character causes the previous specifier (‘H‘) to be repeated until the end of the string.

An alternative to saving the data to disc would be to store the image data in a database.

This example assumes the ability to parse the feed’s XML and that the hexadecimal string has been placed into a PHP variable. A more realistic solution would need to handle possible errors, and to use a different file name for each media file.

hexpack.php.tex

32.40. perl example

[sec:decodingHexPerl] This section shows an equivalent example in perl. Again, the pack() function makes the task of extracting raw data from the hexadecimal string very simple. As before, this example is simplified and shows no error handling. The example uses open() and close() to write to the file on disk.

hexpack.perl.tex

32.41. C example

[sec:decodingHexC] This section shows a very basic C program for saving hexadecimal image data into a static file. Again, a real example would take the hex string from the feed, implement proper error handling etc. This version is more complicated than the PHP and perl versions above simply because there is no equivalent of PHP’s pack() in standard C. It uses open(), write() and close() to write to the image file on disk.

32.42. Examples in other languages

[sec:decodingHexOther] TicketSwitch is always grateful to hear of affiliates success making use of our event feeds. In particular, if you have any example code that you feel may be of benefit to other feed users, please submit it for inclusion in other versions of this document.

32.42.1. Example feed output

[sec:feedExamples]

This section gives some examples of typical output produced by the three kinds of TicketSwitch event feed. These examples are shown as returned by our web server with minor alterations for readability. Line breaks and indentations have been added to the output to aid readability. The actual xml returned by the feeds may contain no line breaks at all. Excessively long lines have been elided by inserting ‘\(\ldots\)‘.

32.42.2. Example rss_feed output

[sec:rssExample] This is an example of the output produced by the rss_feed. See [sec:rssFormat] for the specification of the format.

32.42.3. Example atom_feed output

[sec:atomExample] This is an example of the output produced by the atom_feed. See [sec:atomFormat] for the specification of the format.

32.42.4. Example xml_feed output

[sec:xmlExample] This is an example of the XML output produced by the xml_feed. See [sec:xmlFormat] for the specification of the format.

32.42.5. Example class_list output

[sec:xmlClassListExample]

This is an example of the XML output produced by the xml_feed when the class_list input parameter is specified.

32.42.5.1. Example city_list output

[sec:xmlCityListExample]

This is an example of the XML output produced by the xml_feed when the city_list input parameter is specified.

[1]

While Atom 1.0 has recently been approved by the IETF as RFC4287 and becomes an Internet ‘Proposed Standard’, RSS 2.0 has no official status at all and is poorly specified. Despite that, at the time of writing, RSS 2.0 is the most widely supported feed format. New implementations are encouraged to use Atom 1.0 rather than RSS 2.0 where possible.

[2]	Both RSS 2.0 and Atom have mechanisms allowing for extensions.

[3]	Please note that a space in a CGI parameter value in a URL must be encoded as ‘+‘.

[4]	Please note that a slash in a CGI parameter value in a URL must be encoded as ‘'%2F.

[5]	From feed history draft 5 the vast majority of TicketSwitch’s event feeds cannot do anything to support the . In any case, most of the elements from that draft are now made redundant by the use of the extension.

[6]	The only exception to this rule is where a <dc:…> element has a precise analogue in the native feed format. In that case, the Dublin Core version will be omitted.

[7]	Good aggregators can (and do) make use of elements from the Atom specification in RSS 2.0 feeds.

[8]	other than XML1.0 of course

[9]	Strictly speaking the same consideration applies to CGI parameter names, but in reality all parameter names used by TicketSwitch are safe to use un-encoded.

[10]

There is currently a W3C working group discussing a potential ‘Binary XML’ specification which would address these issues. That group is not yet close to producing a specification that is ready for implementation. Meanwhile individual applications of XML wishing to encode binary data must come up with ad-hoc conventions such as this one.