API Changes - 2013
===================

style_map
---------

Sample input

.. code-block:: xml

  <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

.. code-block:: xml

  <?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:

.. code-block:: xml
  
  <event_token_list>1VLG,1YYO,209C,226B,22AS,25DR,2569</event_token_list>


event_search
------------

Note that this returns the same as extra_info, but there are four requests needed in event_search for extra info that is sent by default from extra_info.
cost_range
The following should be noted for the cost_range data:

* Use min_combined as the "from" price
* Use the range_currency info to:
  o Display a pre symbol before the amount, and a post symbol after the amount
  o Use currency_places to determine how many decimal places to display


Reviews
------------

In any event object you now get this:

.. code-block:: xml

    <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:

.. code-block:: xml

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


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)


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

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:

.. code-block:: xml

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


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

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

.. code-block:: xml

    <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

.. code-block:: xml

    <?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>



availability_options
--------------------

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

#) ticket_type_code, price_band_code and despatch_code have been added.

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

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

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

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

#) 

  Sample output

.. code-block:: xml

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



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.


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.

.. code-block:: xml

    <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

.. code-block:: xml

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


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


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

.. code-block:: xml

  <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

.. code-block:: xml

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



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.