30. API Changes - 2013

30.1. style_map

Sample input

<style_map>
   <user_passwd>testpass</user_passwd>
   <map_key>map_key_doesnt_exist</map_key>
   <map_key>web_finder-image_feature-items/uk</map_key>
</style_map>

In this example two event listings (map_keys) are specified. Note that the first one does not exist in the TicketSwitch database.

Sample output

<?xml version="1.0" encoding="UTF-8"?>
<style_map_result>
    <mapping>
        <map_key>map_key_doesnt_exist</map_key>
    </mapping>
    <mapping>
        <map_key>web_finder-image_feature-items/uk</map_key>
        <style_map>1VLG,1YYO,209C,226B,22AS,25DR,2569</style_map>
    </mapping>
</style_map_result>

In the output you see the first map key does not exist so you get no corresponding style_map data. The second one you get back a list of event IDs. These can then be passed to the event_search call so that you know all relevant details for the event, eg images. For now, you can test with web_finder-image_feature-items/uk, but I will send you the proper event listings, ie map_keys, later.

When you receive a list of event tokens back, you can pass them to event_search using this argument:

<event_token_list>1VLG,1YYO,209C,226B,22AS,25DR,2569</event_token_list>

30.3. Reviews

In any event object you now get this:

<user_review_percent>75</user_review_percent>
<critic_review_percent>21</critic_review_percent>

which are the average percentages. If there are no user reviews or no critic reviews then the corresponding element will be empty. On extra_info only you also get the individual reviews - ordered in reverse order of date (most recent first). These are inside a ‘reviews’ element and each one looks like this:

<review>
    <is_user_review>yes</is_user_review>
    <review_date_desc>Thu, 22nd September 2011</review_date_desc>
    <review_time_desc>12.00 PM</review_time_desc>
    <review_date_yyyymmdd>20110922</review_date_yyyymmdd>
    <review_time_hhmmss>120000</review_time_hhmmss>
    <review_title>Not a good show</review_title>
    <review_body>Didn't think much of this one...<review_body>
    <review_author>Pete French</review_author>
    <review_lang>en</review_lang>
</review>

30.4. Images

Use the <request_media> tag to request image files. Here are the images you can request:

  • <request_media>140x140</request_media> (used on event detail page, top left corner)
  • <request_media>220x115</request_media> (main image used in search results)
  • <request_media>700x300</request_media> (used in banner)
  • <request_media>460x346-1</request_media> (used on homepage and main event detail image)
  • <request_media>460x346-2</request_media> (optional)
  • <request_media>460x346-3</request_media> (optional)

30.5. Sort Order

  • s_top can already be specified to order by sales volume
  • To order by reviews you can use s_user_rating or s_critic_rating
  • To filter on an automatic date range, eg this weekend, use eg s_auto_range=”this_weekend”. The available values are: o today_only o this_weekend o next_week o this_month o next_month

30.6. Paging

We have added paging to the search results, the month list, and the perf list from date/time options. two variables used like this:

<page_length>10</page_length>
<page_number>4</page_number>

fairly self explanatory - the first page is ‘0’ by the way, not ‘1’.

30.7. Other additions

  • video_iframe has been added to build a YouTube (or other eg Vimeo) link
  • need_departure_date: indicates that this event will require the collection of a departure date in addition to the performance date/time. (functional spec item #60)
  • is_seated: flag to indicate if the event is seated. You shouldn’t talk about seats or display seat IDs if this is set to ‘no’. (Added to the functional spec spreadsheet.)
  • show_perf_time: flag to indicate if performances should have their time displayed or not. In practice I don’t actually think we output a time if one shouldn’t be displayed, but it is handy to have it explicitly flagged. (This should be used but is not yet in the functional spec.)
  • need_performance: indicates that we will need to collect a performance. Certain products are undated and will have this set to ‘no’ - note that you might still need to collect a departure date! (This should be used but is not yet in the functional spec.)
  • max_running_time and min_running_time are available even though they may not be useful for the some sites.

Sample input

<event_search>
    <user_passwd>testpass</user_passwd>
    <s_src>ext_test0</s_src>
    <event_token_list>6IE,6IF</event_token_list>
    <request_media>large.jpg</request_media>
    <request_media>small.jpg</request_media>
    <request_media>large-150x600.jpg</request_media>
    <request_source_info/>
    <request_extra_info/>
    <request_video_iframe/>
    <request_cost_range/>
</event_search>

Sample output

<?xml version="1.0" encoding="UTF-8"?>
<event_search_result>
   <crypto_block>U_--yIC208dEystCmz1y8UOHm7SCt-S9RVnTz3heV-LGmC4-tdpy1Cptw6UGRobF2d4My9MryqL_E0TQJxyjbUoopaJv0eQmeW4Q6hB4hFu2nsg_eUZlhG6y7QSaJeNKSBOsZ</crypto_block>
   <event>
      <area_code>EW</area_code>
      <area_desc>Everywhere</area_desc>
      <city_code>london-uk</city_code>
      <city_desc>Londres</city_desc>
      <class>
         <class_code>ballet</class_code>
         <class_desc>Ballet</class_desc>
         <is_main_class>no</is_main_class>
         <search_key>ballet/</search_key>
         <subclass>
            <is_main_subclass>no</is_main_subclass>
            <search_key>ballet/ballet</search_key>
            <subclass_code>ballet</subclass_code>
            <subclass_desc>Ballet</subclass_desc>
         </subclass>
      </class>
      <class>
         <class_code>theatre</class_code>
         <class_desc>Theatre</class_desc>
         <is_main_class>yes</is_main_class>
         <search_key>theatre/</search_key>
         <subclass>
            <is_main_subclass>yes</is_main_subclass>
            <search_key>theatre/dance</search_key>
            <subclass_code>dance</subclass_code>
            <subclass_desc>Dance</subclass_desc>
         </subclass>
         <subclass>
            <is_main_subclass>no</is_main_subclass>
            <search_key>theatre/kids</search_key>
            <subclass_code>kids</subclass_code>
            <subclass_desc>Family</subclass_desc>
         </subclass>
      </class>
      <cost_range>
         <range_currency>
            <currency_code>usd</currency_code>
            <currency_factor>100</currency_factor>
            <currency_number>840</currency_number>
            <currency_places>2</currency_places>
            <currency_post_symbol/>
            <currency_pre_symbol>$</currency_pre_symbol>
         </range_currency>

         <min_combined>71.0</min_combined>
         <min_combined_in_desired>55.61</min_combined_in_desired>
         <min_seatprice>68.0</min_seatprice>
         <min_seatprice_in_desired>53.26</min_seatprice_in_desired>
         <min_surcharge>3.0</min_surcharge>
         <min_surcharge_in_desired>2.35</min_surcharge_in_desired>

         <max_seatprice>68.0</max_seatprice>
         <max_seatprice_in_desired>53.26</max_seatprice_in_desired>
         <max_surcharge>3.0</max_surcharge>
         <max_surcharge_in_desired>2.35</max_surcharge_in_desired>
         <max_combined>71.0</max_combined>
         <max_combined_in_desired>55.61</max_combined_in_desired>

         <top_price_offer>
            <absolute_saving>9.0</absolute_saving>
            <absolute_saving_in_desired>7.05</absolute_saving_in_desired>
            <full_combined>80.0</full_combined>
            <full_combined_in_desired>62.66</full_combined_in_desired>
            <full_seatprice>75.0</full_seatprice>
            <full_seatprice_in_desired>58.74</full_seatprice_in_desired>
            <full_surcharge>5.0</full_surcharge>
            <full_surcharge_in_desired>3.92</full_surcharge_in_desired>
            <offer_combined>71.0</offer_combined>
            <offer_combined_in_desired>62.66</offer_combined_in_desired>
            <offer_seatprice>68.0</offer_seatprice>
            <offer_seatprice_in_desired>53.26</offer_seatprice_in_desired>
            <offer_surcharge>3.0</offer_surcharge>
            <offer_surcharge_in_desired>2.35</offer_surcharge_in_desired>
            <percentage_saving>11</percentage_saving>
         </top_price_offer>

         <max_saving_offer>
            <absolute_saving>9.0</absolute_saving>
            <absolute_saving_in_desired>7.05</absolute_saving_in_desired>
            <full_combined>80.0</full_combined>
            <full_combined_in_desired>62.66</full_combined_in_desired>
            <full_seatprice>75.0</full_seatprice>
            <full_seatprice_in_desired>58.74</full_seatprice_in_desired>
            <full_surcharge>5.0</full_surcharge>
            <full_surcharge_in_desired>3.92</full_surcharge_in_desired>
            <offer_combined>71.0</offer_combined>
            <offer_combined_in_desired>62.66</offer_combined_in_desired>
            <offer_seatprice>68.0</offer_seatprice>
            <offer_seatprice_in_desired>53.26</offer_seatprice_in_desired>
            <offer_surcharge>3.0</offer_surcharge>
            <offer_surcharge_in_desired>2.35</offer_surcharge_in_desired>
            <percentage_saving>11</percentage_saving>
         </max_saving_offer>

         <best_value_offer>
            <absolute_saving>9.0</absolute_saving>
            <absolute_saving_in_desired>7.05</absolute_saving_in_desired>
            <full_combined>80.0</full_combined>
            <full_combined_in_desired>62.66</full_combined_in_desired>
            <full_seatprice>75.0</full_seatprice>
            <full_seatprice_in_desired>58.74</full_seatprice_in_desired>
            <full_surcharge>5.0</full_surcharge>
            <full_surcharge_in_desired>3.92</full_surcharge_in_desired>
            <offer_combined>71.0</offer_combined>
            <offer_combined_in_desired>62.66</offer_combined_in_desired>
            <offer_seatprice>68.0</offer_seatprice>
            <offer_seatprice_in_desired>53.26</offer_seatprice_in_desired>
            <offer_surcharge>3.0</offer_surcharge>
            <offer_surcharge_in_desired>2.35</offer_surcharge_in_desired>
            <percentage_saving>11</percentage_saving>
         </best_value_offer>
      </cost_range>
      <country_code>uk</country_code>
      <country_desc>Grobritannien</country_desc>
      <critic_review_percent>21</critic_review_percent>
      <event_code>NUTCRACKER</event_code>
      <event_desc>Matthew Bourne's Nutcracker!</event_desc>
      <event_id>6IF</event_id>
      <event_info>Matthew Bourne's stunning production of Nutcracker! returns to Sadler's Wells having broken all box office records during last year's sell-out season.

            This festive treat is full of his trademark style of wit, pathos and theatrical magic. Nutcracker! follows Clara's journey from a bleak Christmas Eve at Dr.Dross' Orphanage, through a shimmering ice-skating wonderland and to thespectacular candy folk of Sweetieland.

            Oliver award-winning designer Anthony Ward and Tchaikovsky's much-loved score combined with sizzling choreography guarantee that Matthew Bourne's Nutcracker! is a fresh, lip-smacking, serving of traditional Christmas fare.

        Matthew Bourne has achieved both artistic and commercial success with his imaginative new versions of classical ballets. Last year his Play Without Words made for the Royal National Theatre, received two Olivier Awards and is shortly to be revived.</event_info>
      <event_media>
         <name>small.jpg</name>
         <path>/shared/event_media/ext_test0/EW/small.jpg</path>
      </event_media>
      <event_media>
         <name>large-150x600.jpg</name>
         <path>/shared/event_media/ext_test0/+system_ext_test0/large-150x600.jpg</path>
      </event_media>
      <event_token>6IF</event_token>
      <geo_data>
         <latitude>51.52961137</latitude>
         <longitude>-0.10601562</longitude>
      </geo_data>
      <lingo_code>theatre</lingo_code>
      <postcode>EC1R 4TN</postcode>
      <source_after_sales_email>customerservices@ingresso.co.uk</source_after_sales_email>
      <source_code>ext_test0</source_code>
      <source_desc>Test System Zero</source_desc>
      <source_desc_from_config>Test System Zero</source_desc_from_config>
      <source_enquiries_email>customerservices@ingresso.co.uk</source_enquiries_email>
      <source_international_fax>+44 203 1377412</source_international_fax>
      <source_international_phone>+44 203 1377420</source_international_phone>
      <source_local_fax>0203 1377412</source_local_fax>
      <source_local_phone>0203 1377420</source_local_phone>
      <source_postal_addr>Suite 75, Victoria Place, Wellwood Street, Belfast BT12 5FX</source_postal_addr>
      <source_system_class>ext_test</source_system_class>
      <source_t_and_c>For use as test data only.
        These are not real events and any attempts to purchase items from this supplier will be cancelled without notice.</source_t_and_c>
       <user_review_percent>75</user_review_percent>
      <venue_addr>Rosebery Avenue
            Islington
        London</venue_addr>
      <venue_code>SADLERSWELLS</venue_code>
      <venue_desc>Sadler's Wells</venue_desc>
      <venue_info>The world's No.1 venue dedicated to international dance - presenting dance in all forms from contemporary to flamenco, ballet to hip hop and more.

            Nearest Underground: Angel (Northern line)
            Nearest Rail: Kings Cross (Northern line to Angel)
        Turn left out of Angel station and cross the road at the crossroads for St John Street. Roseberry Avenue is on the right with the theatre about 100 metres down on the right.</venue_info>
      <video_iframe>
         <video_iframe_height>315</video_iframe_height>
         <video_iframe_host>www.youtube.com</video_iframe_host>
         <video_iframe_path>/embed/G1JpEHGizk4</video_iframe_path>
         <video_iframe_supports_https>yes</video_iframe_supports_https>
         <video_iframe_width>420</video_iframe_width>
      </video_iframe>
   </event>
</event_search_result>

30.8. availability_options

The input remains the same, but several items have been added to the output:

  1. ticket_type_code, price_band_code and despatch_code have been added.
  2. discount_code and discount_desc have been added. These will only be present if the availability is a non-default discount code, but should be displayed if present. A standard availability won’t have them, but lots of our product will.
  3. The special offer values are here - well, they always were, but I don’t think they were documented! The non_offer variables are always present, whether it is an offer or not, but when it is not an offer they will be the same as the standard sale variables.
  4. You now have the (standard) ‘seatprice’ as an alternative to ‘ticket_price’ in the output, plus the ‘combined’ value is now present where it wasn’t before.
  5. Desired currency is now calculated and displayed throughout the whole of the output, so that it appears where they is any kind of money value being output.
  6. Sample output
<availability_options_result>
  <crypto_block>M0--vKstMzcgtwtMzRMr__0SUU5kn5HoO77D_XGFGaNExhWQIlUBuVxA7FcGi2xnzRU0YTxfZcNoWVmv9Lll_wNeWZtzr9Sc4cStfynHdgOTGiiqIh1ud_Puaic4u1s4XEVHSPXYNkd4QzwB40zoPML5TVHf4dCxcXYx-lucUKX-nxoozSvNQUReBNggkpcT2xwoGTxyvXpcqC4-Z</crypto_block>
  <currency>
    <currency_code>usd</currency_code>
    <currency_factor>100</currency_factor>
    <currency_number>840</currency_number>
    <currency_places>2</currency_places>
    <currency_post_symbol/>
    <currency_pre_symbol>$</currency_pre_symbol>
  </currency>
  <desired_currency>
    <currency_code>gbp</currency_code>
    <currency_factor>100</currency_factor>
    <currency_number>826</currency_number>
    <currency_places>2</currency_places>
    <currency_post_symbol/>
    <currency_pre_symbol>?</currency_pre_symbol>
  </desired_currency>
  <availability>
    <ticket_type>
      <price_band>
        <band_token>E0--DWkRGiPZez-4a1rMzNorBL3Fx39vE5o5pyMKGcoZfrBJFO0lTTHDqfrzLHtgqw2n-n1WlGCWJJQQFOawZZfn3_uMqGqOvz9Uqwj5ir1JKuGsFd_sp4JexEgh-VtmffgtFmrUy4Hfx9PT5hrikJe3EgWao4pBNHdVwnclwZLlFz_Nw0DjEbmsMKwTyw9BV_z9Z</band_token>
        <absolute_saving>9.0</absolute_saving>
        <absolute_saving_in_desired>6.99</absolute_saving_in_desired>
        <combined>71.0</combined>
        <combined_in_desired>46.34</combined_in_desired>
        <discount_code>WEBOFF</discount_code>
        <discount_desc>Adult web offer rate</discount_desc>
        <is_offer>yes</is_offer>
        <non_offer_combined>80.0</non_offer_combined>
        <non_offer_combined_in_desired>52.21</non_offer_combined_in_desired>
        <non_offer_seatprice>75.0</non_offer_seatprice>
        <non_offer_seatprice_in_desired>48.95</non_offer_seatprice_in_desired>
        <non_offer_surcharge>5.0</non_offer_surcharge>
        <non_offer_surcharge_in_desired>3.26</non_offer_surcharge_in_desired>
        <non_offer_ticket_price>75.0</non_offer_ticket_price>
        <non_offer_ticket_price_in_desired>48.95</non_offer_ticket_price_in_desired>
        <number_available>6</number_available>
        <percentage_saving>11</percentage_saving>
  <price_band_code>A</price_band_code>
        <seatprice>68.0</seatprice>
        <seatprice_in_desired>44.38</seatprice_in_desired>
        <surcharge>3.0</surcharge>
        <surcharge_in_desired>1.96</surcharge_in_desired>
        <ticket_price>68.0</ticket_price>
        <ticket_price_in_desired>44.38</ticket_price_in_desired>
      </price_band>
      <ticket_type_code>PREF</ticket_type_code>
      <ticket_type_desc>Preferred seating</ticket_type_desc>
      <ticket_type_token>s---MHClviDyfFa3KClJn_VHATyLX8NwnvyLlRPi-4bsIyKrD01i4XLCqQaBL1Yf7n4niLd6sHidt96-Y</ticket_type_token>
    </ticket_type>
  </availability>
  <quantity_options>
    <valid_quantity>1</valid_quantity>
    <valid_quantity>2</valid_quantity>
    <valid_quantity>3</valid_quantity>
    <valid_quantity>4</valid_quantity>
    <valid_quantity>5</valid_quantity>
    <valid_quantity>6</valid_quantity>
  </quantity_options>
  <despatch_options>
    <despatch_method>
      <despatch_code>COBO</despatch_code>
      <despatch_cost>0.0</despatch_cost>
      <despatch_cost_in_desired>0.0</despatch_cost_in_desired>
      <despatch_desc>Collect from the venue</despatch_desc>
      <despatch_token>M_--iG6zpgBE__hILmK9H8wXucIfn-067rlCiSHTTASkA829zNpt3WCWtCHXW9mVkxdqa5ppgIR9oL_pCNqCzsZQKSLcm4p55FJ7jJh0MpS24CPIdPrWAXcKD0--Y</despatch_token>
      <despatch_type>collect</despatch_type>
    </despatch_method>
    <despatch_method>
      <despatch_code>POST</despatch_code>
      <despatch_cost>8.0</despatch_cost>
      <despatch_cost_in_desired>5.22</despatch_cost_in_desired>
      <despatch_desc>Post worldwide</despatch_desc>
      <despatch_token>E_--wlwADZo14flSx6Vj6KmLpN36qpcHpwQiHRIjdjkZRfSjY1-Io1iSlVFEd5f9dmztjCOF85wU-yTieVNgW85sMXfTVTtQY7MKFZiR9mAWOx6-Y</despatch_token>
      <despatch_type>post</despatch_type>
    </despatch_method>
  </despatch_options>
</availability_options_result>

30.9. make_reservation

make_reservation will now produce a ‘permitted_countries’ list at the reservation stage if a country menu needs to be displayed to the user. For anything other than a specific type of B2B sale this will always be the case. The format is identical to the list inside a send method, and the element is at the same level in the XML as the ‘acceptable_cards’ list is.

restricted view and seat messages should be available at this point, as you can get the full trolley description out of this method if you include the describe_trolley. If they do that, as specified in the docs, then they will get a full trolley description, including the seat IDs and any corresponding messages.

30.10. despatch_options

A new call has been added that will provide a list of despatch options (ie delivery methods). This must be called after date_time_options, but can be called at the same time as availability_options if desired. The output from this method will be passed into create_order (change still pending as at 26 Apr 2013). Sample input

it’s indentical to the input for availability_options, so all the usual request options apply beyond the sample input below.

  <despatch_options>
    <user_id>tswitch</user_id>
    <crypto_block>k_--QA6GtGMNIXGvyyP-4XbwPTKx3GAVY9p2kcsUGZjwLf49pF1Y4Vhw8qmm6a08w
  cVgyE61Vi5OeyCuUh-usMgH2XftgqmZlSA7yekL1LIz-MesPNmVxBbck09d_ljQlGpsHWoh4S1Aq2sCX
  GtlxxG4S_--Z</crypto_block>
    <perf_token>E_--gHO76ZD_JMnhxa3N5DJdU6lE0W__hc_7elYXhI0I5Le6hUbugx84l5sys6E3Mcdc
  hjC-Y7PRXUnZJSDXb97Obe3Zg-YdqJyD5YBUdtmllt0-Y</perf_token>
    <self_print_mode>html</self_print_mode>
  </despatch_options>

Sample output

<despatch_options_result>
  <despatch_options>
    <despatch_method>
      <despatch_code>COBO</despatch_code>
      <despatch_cost>0.0</despatch_cost>
      <despatch_cost_in_desired>0.0</despatch_cost_in_desired>
      <despatch_desc>Collect from the venue</despatch_desc>
      <despatch_token>M_--iG6zpgBE__hILmK9H8wXucIfn-067rlCiSHTTASkA829zNpt3WCWtCHXW9mVkxdqa5ppgIR9oL_pCNqCzsZQKSLcm4p55FJ7jJh0MpS24CPIdPrWAXcKD0--Y</despatch_token>
      <despatch_type>collect</despatch_type>
    </despatch_method>
    <despatch_method>
      <despatch_code>POST</despatch_code>
      <despatch_cost>8.0</despatch_cost>
      <despatch_cost_in_desired>5.22</despatch_cost_in_desired>
      <despatch_desc>Post worldwide</despatch_desc>
      <despatch_token>E_--wlwADZo14flSx6Vj6KmLpN36qpcHpwQiHRIjdjkZRfSjY1-Io1iSlVFEd5f9dmztjCOF85wU-yTieVNgW85sMXfTVTtQY7MKFZiR9mAWOx6-Y</despatch_token>
      <despatch_type>post</despatch_type>
    </despatch_method>
  </despatch_options>
</despatch_options_result>

30.11. create_order

create_order will now accept a despatch_token, and the despatch_token is now optional in discount_options (meaning that customers can be given the option to select their despatch method later in the booking process).

30.12. suggest_user

This method can be used to determine which country and continent a particular IP address is from. A suggested user is also returned; this can be used so that a USA IP address returns a user with product priced primarily in US Dollars, while a UK IP address returns a user with product priced primarily in British Pounds. Sample input

<suggest_user>
<user_id>tswitch</user_id>
<user_passwd>testpass</user_passwd>
<client_ip_address>2a02:b90:3002:e550:20e:cff:fedc:c380</client_ip_address>
</suggest_user>

Sample output

<suggest_user_result>
  <geo_lookup>
    <continent_code>eu</continent_code>
    <continent_desc>Europe</continent_desc>
    <country_code>uk</country_code>
    <country_desc>United Kingdom</country_desc>
  </geo_lookup>
  <suggested_user_id>tswitch</suggested_user_id>
</suggest_user_result>

Note that the lookup section won’t be there if the IP address couldn’t be looked up.

30.13. create_order_and_reserve

create_order_and_reserve compresses create_order, trolley_add_order and make_reservation into a single call. It takes the same parameters as “create_order” and can return any of the same error codes. If there are no errors then the output is the same as “make_reservation” - the only exception being that there are always the currency elements that “create_order” output present in the output.