9. The date_time_options method

All events may require some kind of date and time information associated with them. For performance based products such as theatre or concert tickets then this corresponds to the date and time of a particular performance of the event. For products such as theme park entrance tickets then the estimated date of usage of the ticket may be required as not all tickets are valid on all dates. In addition, to aid ticket despatch, it may be necessary to know what date the customer is intending to depart, in order that the tickets may be shipped to them before they leave. For users of the XML feed this method may be combined with starting a session rather than stepping through the “start_session” and “event_search” methods as the event token is produced directly in the feed. Alternatively it may be specified using the “crypto_block” from the “full_query” element of the feed or by using the ( “s_src”, “s_area”, “s_ven”, “s_eve” ) tuple.

For a given event, specified by an event token from the search method, this method specifies what date and time information should be collected for the event in question, along with any restrictions on that data. A usage date is always mutually exclusive with selection of a date and time from a list, but a departure date may be required for either of them, or even on its own. Certain products may require no date or time information to be collected from the customer. All possibilities should be handled by the user of this method. When a usage date is required then restrictions on the usage date will be specified by this method, and these should be enforced when collecting the information from the customer.

For performance based events a set of optional elements may be provided which will restrict the list of performances returned, this can considerably reduce the amount of data being returned from the script.

9.1. Required inputs

The “crypto_block” from the “event_search” output is required, or the “user_id” and “user_passwd”. An “event_token” element is also required. If a date bounded search is required then the elements “earliest_date” and “latest_date” may also be provided. Both are optional and have no effect if a performance list would not be returned. The format is “YYYYMMDD” for the dates.

You can optionally specify to retrieve cost ranges, to retrieve detail of the from prices and whether special offers are available for each performance. These can be retrieved using “request_cost_range”.

If this method is being used to start a session on a specific event, then you can supply the “crypto_block” from within the “full_query” element for the event in the XML feed. Note that this is only valid if the core is being run with the same user as the XML feed from which the data was obtained. Alternatively a “user_passwd” plus all four “s_src”, “s_area”, “s_ven” and “s_eve” may be specified, but all of these need to be supplied in order for this to work.

9.1.1. Example input

<date_time_options>
  <user_id>ftbo</user_id>
  <crypto_block>U_--vkpf9kC9pU5Ob-grofd1tGwcNPYj3ecsj3DY16jQkO0YWnDvmTKhsA3p_xUq7RLFyDc5-Rd1f6KqfuYIqgAFsev8QgopuCRwO4r_Dm3LIEQyqrEjq89lr2PIn93DkwglY</crypto_block>
  <event_token>25DR</event_token>
  <request_cost_range/>
</date_time_options>

9.2. Output data

The output data consists of the “crypto_block” to be used for the next script, plus one or two other elements, depending on what date and time information needs to be collected.

For events where a performance needs to be selected from a list then an element “using_perf_list” will be present. This contains a number of “performance” elements, each representing a single selectable performance of the event. A “performance” element contains a “perf_token” to be carried through to the next stage of the process, plus information about the date and time of the performance. Each is represented in machine readable YYYYMMDD and HHMMSS format in the “date_yyyymmdd” and “time_hhmmss” elements, plus also in human readable form in the “date_desc” and “time_desc” elements. As some events have performances where the time is not relevant, the two time variables will not necessarily always be present.

We return times in ISO 8601 standard (“iso8601_date_and_time”) and UTC times (“date_utc_offset” and “date_utc_seconds” - these two fields should be used together).

Some performances will also have a “perf_name” element containing extra human readable description of the performance. This is typically used where performances of an event differ significantly in more than just date and time. One will not always be present, but if it is, it must be shown to the customer.

The element “is_limited” is also present, containing a boolean value of “yes” or “no” to indicate those performances where the supply of tickets is known to be extremely limited. This is usually taken to be fewer than four remaining, though not all ticket sources provide this information. Where the information is not available the flag will always be set to “no”. If no valid performances can be found then the performance list will be present but empty.

If “request_cost_range” was used then a “cost_range” is returned for each performance. This contains a “min_seatprice” (the face value of the lowest priced ticket), “min_surcharge” (the booking fee of the lowest priced ticket), and a “min_combined” (the total price of the lowest priced ticket). There are also equivalent max values. Four types of offers are returned - these are useful in case there are offers across multiple ticket prices: “best_value_offer” (the offer with the highest percentage saving); “max_saving_offer” (the offer with the highest absolute saving); “min_cost_offer” (the offer with the lowest cost); ; “top_price_offer” (the offer with the highest cost). Valid quantities for the performance are returned as part of the cost range in “quantity_options”. A “no_singles_cost_range” is also included - this contains cost ranges excluding single tickets. These values are useful when your customer has indicated they would like to purchase more than one ticket before you display a calendar.

A single element “need_departure_date” is always present, containing a boolean value of “yes” or “no” depending on whether a departure is required. No extra information is given regarding a departure date as it is essentially unrestricted.

If the method is being used to start a session by going directly to an event using the data from the XML feed then there is a possibility that the event may no longer be valid. If this is the case then the only output from the script will be the single element “event_not_found”. The lack of an event is indicated this way rather than using an error code as it is a result which may happen during the correct operation of the system. If data from the XML feed is being cached then this response indicates that the cached data should be refreshed.

For events where a usage date is required then a “using_usage_date” element will be present. As usage dates are restricted then this element will always contain information indicating the periods within which a usage date may be selected. The validity of a ticket is held as the first date on which it is valid, plus the last date on which it is valid. Within this period there may be ranges of dates where the ticket is not valid. These are held as separate ranges, indicated by the first invalid day and the last invalid day. Finally it is also possible that certain products will not be valid on individual days of the week, for example an attraction which is never open on a Sunday.

All of this information is available within the “using_usage_date ” element. The overall range within which the usage date must be chosen is given by four elements, these being “first_valid_date_yyyymmdd” and “first_valid_date_desc” plus “last_valid_date_yyyymmdd” and “last_valid_date_desc”. As with performances all dates are presented with both a machine readable YYYYMMDD format and a descriptive text format suitable for direct display. If there are any periods of invalidity within this range then these are indicated by “invalid_range” elements. Each of these contains a similar set of four elements to the valid range, except that they use “invalid” rather than “valid” in the element name. Any invalid days of the week are represented by “invalid_weekday” elements. These contain a “weekday_number” and “weekday_name”. The days of the week are numbered with zero representing Sunday and six representing Saturday. The full weekday names appear in the “weekday_name” elements.

It is possible that a given event may have extra pieces of text which should be displayed when collecting a departure date, usage date or performance. These pieces of text are used to carry item specific information which is only relevant to the customer at the point where the date in question is being collected. Three optional elements are used to hold such text, being “collect_depart_text”, “collect_perf_text” and “collect_usage_text”, and each corresponding to the obvious piece of information. Within these elements will be one or more “collect_text” elements holding the actual text to be displayed. It is important to note that there may be more than one piece of text associated with each piece of information to be collected.

9.2.1. Example output

The following example data is for a theatre event requiring the selection of one of a list of performances. No departure date is required. The full set of performances here has been trimmed as they all follow the same format.

<date_time_options_result>
    <subdomain_user_is_bad>no</subdomain_user_is_bad>
    <crypto_block>s_--3BtridHm2GvWNi0T3-HGFnVtzaem1388zJjxVA-2ZWz5O6e5lZXXZw_l9-osvDvBJgemas4uvne4VMfE2jh9HryY-ON9hDEokcUDf4kH70TD-rL5DCXBtzZuveeIfRVQJz1NMMXmLB6x8UjwtHTqRZbywcIojoEZ</crypto_block>
    <need_departure_date>no</need_departure_date>
    <has_perf_names>no</has_perf_names>
    <using_perf_list>
        <performance>
            <cached_max_seats>7</cached_max_seats>
            <cost_range>
                <best_value_offer>
                    <absolute_saving>13.25</absolute_saving>
                    <full_combined>80.75</full_combined>
                    <full_seatprice>67.5</full_seatprice>
                    <full_surcharge>13.25</full_surcharge>
                    <offer_combined>67.5</offer_combined>
                    <offer_seatprice>67.5</offer_seatprice>
                    <offer_surcharge>0.0</offer_surcharge>
                    <percentage_saving>16</percentage_saving>
                </best_value_offer>
                <max_combined>107.75</max_combined>
                <max_saving_offer>
                    <absolute_saving>13.25</absolute_saving>
                    <full_combined>80.75</full_combined>
                    <full_seatprice>67.5</full_seatprice>
                    <full_surcharge>13.25</full_surcharge>
                    <offer_combined>67.5</offer_combined>
                    <offer_seatprice>67.5</offer_seatprice>
                    <offer_surcharge>0.0</offer_surcharge>
                    <percentage_saving>16</percentage_saving>
                </max_saving_offer>
                <max_seatprice>90.0</max_seatprice>
                <max_surcharge>17.75</max_surcharge>
                <min_combined>42.5</min_combined>
                <min_cost_offer>
                    <absolute_saving>8.25</absolute_saving>
                    <full_combined>50.75</full_combined>
                    <full_seatprice>42.5</full_seatprice>
                    <full_surcharge>8.25</full_surcharge>
                    <offer_combined>42.5</offer_combined>
                    <offer_seatprice>42.5</offer_seatprice>
                    <offer_surcharge>0.0</offer_surcharge>
                    <percentage_saving>16</percentage_saving>
                </min_cost_offer>
                <min_seatprice>42.5</min_seatprice>
                <min_surcharge>0.0</min_surcharge>
                <no_singles_cost_range>
                    <best_value_offer>
                        <absolute_saving>13.25</absolute_saving>
                        <full_combined>80.75</full_combined>
                        <full_seatprice>67.5</full_seatprice>
                        <full_surcharge>13.25</full_surcharge>
                        <offer_combined>67.5</offer_combined>
                        <offer_seatprice>67.5</offer_seatprice>
                        <offer_surcharge>0.0</offer_surcharge>
                        <percentage_saving>16</percentage_saving>
                    </best_value_offer>
                    <max_combined>107.75</max_combined>
                    <max_saving_offer>
                        <absolute_saving>13.25</absolute_saving>
                        <full_combined>80.75</full_combined>
                        <full_seatprice>67.5</full_seatprice>
                        <full_surcharge>13.25</full_surcharge>
                        <offer_combined>67.5</offer_combined>
                        <offer_seatprice>67.5</offer_seatprice>
                        <offer_surcharge>0.0</offer_surcharge>
                        <percentage_saving>16</percentage_saving>
                    </max_saving_offer>
                    <max_seatprice>90.0</max_seatprice>
                    <max_surcharge>17.75</max_surcharge>
                    <min_combined>47.5</min_combined>
                    <min_cost_offer>
                        <absolute_saving>9.25</absolute_saving>
                        <full_combined>56.75</full_combined>
                        <full_seatprice>47.5</full_seatprice>
                        <full_surcharge>9.25</full_surcharge>
                        <offer_combined>47.5</offer_combined>
                        <offer_seatprice>47.5</offer_seatprice>
                        <offer_surcharge>0.0</offer_surcharge>
                        <percentage_saving>16</percentage_saving>
                    </min_cost_offer>
                    <min_seatprice>47.5</min_seatprice>
                    <min_surcharge>0.0</min_surcharge>
                    <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>
                        <valid_quantity>7</valid_quantity>
                    </quantity_options>
                    <range_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>
                    </range_currency>
                    <top_price_offer>
                        <absolute_saving>13.25</absolute_saving>
                        <full_combined>80.75</full_combined>
                        <full_seatprice>67.5</full_seatprice>
                        <full_surcharge>13.25</full_surcharge>
                        <offer_combined>67.5</offer_combined>
                        <offer_seatprice>67.5</offer_seatprice>
                        <offer_surcharge>0.0</offer_surcharge>
                        <percentage_saving>16</percentage_saving>
                    </top_price_offer>
                </no_singles_cost_range>
                <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>
                    <valid_quantity>7</valid_quantity>
                </quantity_options>
                <range_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>
                </range_currency>
                <top_price_offer>
                    <absolute_saving>13.25</absolute_saving>
                    <full_combined>80.75</full_combined>
                    <full_seatprice>67.5</full_seatprice>
                    <full_surcharge>13.25</full_surcharge>
                    <offer_combined>67.5</offer_combined>
                    <offer_seatprice>67.5</offer_seatprice>
                    <offer_surcharge>0.0</offer_surcharge>
                    <percentage_saving>16</percentage_saving>
                </top_price_offer>
            </cost_range>
            <date_desc>Tue, 24th November 2015</date_desc>
            <date_utc_offset>0</date_utc_offset>
            <date_utc_seconds>1448393400</date_utc_seconds>
            <date_yyyymmdd>20151124</date_yyyymmdd>
            <has_pool_seats>yes</has_pool_seats>
            <is_limited>no</is_limited>
            <perf_id>25DR-42L</perf_id>
            <perf_is_visible>yes</perf_is_visible>
            <perf_subdata>20036438</perf_subdata>
            <perf_token>s---ERVzwUevoi8qCrIMQXAfrm7j7pnCTzp7jNXk7dgp1DnaIr3qRZdGJGfgbClCxxdLc4mtPXPNxl7-Y</perf_token>
            <perf_type_code>739855</perf_type_code>
            <time_desc>7.30 PM</time_desc>
            <time_hhmmss>193000</time_hhmmss>
        </performance>
        <performance>
            <cached_max_seats>10</cached_max_seats>
            <cost_range>
                <best_value_offer>
                    <absolute_saving>13.25</absolute_saving>
                    <full_combined>80.75</full_combined>
                    <full_seatprice>67.5</full_seatprice>
                    <full_surcharge>13.25</full_surcharge>
                    <offer_combined>67.5</offer_combined>
                    <offer_seatprice>67.5</offer_seatprice>
                    <offer_surcharge>0.0</offer_surcharge>
                    <percentage_saving>16</percentage_saving>
                </best_value_offer>
                <max_combined>67.5</max_combined>
                <max_saving_offer>
                    <absolute_saving>13.25</absolute_saving>
                    <full_combined>80.75</full_combined>
                    <full_seatprice>67.5</full_seatprice>
                    <full_surcharge>13.25</full_surcharge>
                    <offer_combined>67.5</offer_combined>
                    <offer_seatprice>67.5</offer_seatprice>
                    <offer_surcharge>0.0</offer_surcharge>
                    <percentage_saving>16</percentage_saving>
                </max_saving_offer>
                <max_seatprice>67.5</max_seatprice>
                <max_surcharge>0.0</max_surcharge>
                <min_combined>35.0</min_combined>
                <min_cost_offer>
                    <absolute_saving>6.75</absolute_saving>
                    <full_combined>41.75</full_combined>
                    <full_seatprice>35.0</full_seatprice>
                    <full_surcharge>6.75</full_surcharge>
                    <offer_combined>35.0</offer_combined>
                    <offer_seatprice>35.0</offer_seatprice>
                    <offer_surcharge>0.0</offer_surcharge>
                    <percentage_saving>16</percentage_saving>
                </min_cost_offer>
                <min_seatprice>35.0</min_seatprice>
                <min_surcharge>0.0</min_surcharge>
                <no_singles_cost_range>
                    <best_value_offer>
                        <absolute_saving>13.25</absolute_saving>
                        <full_combined>80.75</full_combined>
                        <full_seatprice>67.5</full_seatprice>
                        <full_surcharge>13.25</full_surcharge>
                        <offer_combined>67.5</offer_combined>
                        <offer_seatprice>67.5</offer_seatprice>
                        <offer_surcharge>0.0</offer_surcharge>
                        <percentage_saving>16</percentage_saving>
                    </best_value_offer>
                    <max_combined>67.5</max_combined>
                    <max_saving_offer>
                        <absolute_saving>13.25</absolute_saving>
                        <full_combined>80.75</full_combined>
                        <full_seatprice>67.5</full_seatprice>
                        <full_surcharge>13.25</full_surcharge>
                        <offer_combined>67.5</offer_combined>
                        <offer_seatprice>67.5</offer_seatprice>
                        <offer_surcharge>0.0</offer_surcharge>
                        <percentage_saving>16</percentage_saving>
                    </max_saving_offer>
                    <max_seatprice>67.5</max_seatprice>
                    <max_surcharge>0.0</max_surcharge>
                    <min_combined>42.5</min_combined>
                    <min_cost_offer>
                        <absolute_saving>8.25</absolute_saving>
                        <full_combined>50.75</full_combined>
                        <full_seatprice>42.5</full_seatprice>
                        <full_surcharge>8.25</full_surcharge>
                        <offer_combined>42.5</offer_combined>
                        <offer_seatprice>42.5</offer_seatprice>
                        <offer_surcharge>0.0</offer_surcharge>
                        <percentage_saving>16</percentage_saving>
                    </min_cost_offer>
                    <min_seatprice>42.5</min_seatprice>
                    <min_surcharge>0.0</min_surcharge>
                    <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>
                        <valid_quantity>7</valid_quantity>
                        <valid_quantity>8</valid_quantity>
                        <valid_quantity>9</valid_quantity>
                        <valid_quantity>10</valid_quantity>
                    </quantity_options>
                    <range_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>
                    </range_currency>
                    <top_price_offer>
                        <absolute_saving>13.25</absolute_saving>
                        <full_combined>80.75</full_combined>
                        <full_seatprice>67.5</full_seatprice>
                        <full_surcharge>13.25</full_surcharge>
                        <offer_combined>67.5</offer_combined>
                        <offer_seatprice>67.5</offer_seatprice>
                        <offer_surcharge>0.0</offer_surcharge>
                        <percentage_saving>16</percentage_saving>
                    </top_price_offer>
                </no_singles_cost_range>
                <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>
                    <valid_quantity>7</valid_quantity>
                    <valid_quantity>8</valid_quantity>
                    <valid_quantity>9</valid_quantity>
                    <valid_quantity>10</valid_quantity>
                </quantity_options>
                <range_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>
                </range_currency>
                <top_price_offer>
                    <absolute_saving>13.25</absolute_saving>
                    <full_combined>80.75</full_combined>
                    <full_seatprice>67.5</full_seatprice>
                    <full_surcharge>13.25</full_surcharge>
                    <offer_combined>67.5</offer_combined>
                    <offer_seatprice>67.5</offer_seatprice>
                    <offer_surcharge>0.0</offer_surcharge>
                    <percentage_saving>16</percentage_saving>
                </top_price_offer>
            </cost_range>
            <date_desc>Wed, 25th November 2015</date_desc>
            <date_utc_offset>0</date_utc_offset>
            <date_utc_seconds>1448461800</date_utc_seconds>
            <date_yyyymmdd>20151125</date_yyyymmdd>
            <has_pool_seats>yes</has_pool_seats>
            <is_limited>no</is_limited>
            <perf_id>25DR-42M</perf_id>
            <perf_is_visible>yes</perf_is_visible>
            <perf_subdata>20036438</perf_subdata>
            <perf_token>s---nbWR_3uRkj2WnkyGnXcYk23Xo0ygQhHBuEcscPrVFPqaIr3qRZdGJqrRSz1_Va4Uc4mtPXPNxl7-Y</perf_token>
            <perf_type_code>739874</perf_type_code>
            <time_desc>2.30 PM</time_desc>
            <time_hhmmss>143000</time_hhmmss>
        </performance>
    </using_perf_list>
    <event>
        <area_code>WE</area_code>
        <area_desc>West End</area_desc>
        <bigup_value>196</bigup_value>
        <city_code>london-uk</city_code>
        <city_desc>London</city_desc>
        <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/kids</search_key>
                <subclass_code>kids</subclass_code>
                <subclass_desc>Family</subclass_desc>
            </subclass>
            <subclass>
                <is_main_subclass>no</is_main_subclass>
                <search_key>theatre/musicals</search_key>
                <subclass_code>musicals</subclass_code>
                <subclass_desc>Musicals</subclass_desc>
            </subclass>
        </class>
        <cost_range>
            <best_value_offer>
                <absolute_saving>14.25</absolute_saving>
                <full_combined>86.75</full_combined>
                <full_seatprice>72.5</full_seatprice>
                <full_surcharge>14.25</full_surcharge>
                <offer_combined>72.5</offer_combined>
                <offer_seatprice>72.5</offer_seatprice>
                <offer_surcharge>0.0</offer_surcharge>
                <percentage_saving>16</percentage_saving>
            </best_value_offer>
            <max_combined>167.15</max_combined>
            <max_saving_offer>
                <absolute_saving>14.25</absolute_saving>
                <full_combined>86.75</full_combined>
                <full_seatprice>72.5</full_seatprice>
                <full_surcharge>14.25</full_surcharge>
                <offer_combined>72.5</offer_combined>
                <offer_seatprice>72.5</offer_seatprice>
                <offer_surcharge>0.0</offer_surcharge>
                <percentage_saving>16</percentage_saving>
            </max_saving_offer>
            <max_seatprice>139.5</max_seatprice>
            <max_surcharge>27.65</max_surcharge>
            <min_combined>35.0</min_combined>
            <min_cost_offer>
                <absolute_saving>6.75</absolute_saving>
                <full_combined>41.75</full_combined>
                <full_seatprice>35.0</full_seatprice>
                <full_surcharge>6.75</full_surcharge>
                <offer_combined>35.0</offer_combined>
                <offer_seatprice>35.0</offer_seatprice>
                <offer_surcharge>0.0</offer_surcharge>
                <percentage_saving>16</percentage_saving>
            </min_cost_offer>
            <min_seatprice>35.0</min_seatprice>
            <min_surcharge>0.0</min_surcharge>
            <no_singles_cost_range>
                <best_value_offer>
                    <absolute_saving>14.25</absolute_saving>
                    <full_combined>86.75</full_combined>
                    <full_seatprice>72.5</full_seatprice>
                    <full_surcharge>14.25</full_surcharge>
                    <offer_combined>72.5</offer_combined>
                    <offer_seatprice>72.5</offer_seatprice>
                    <offer_surcharge>0.0</offer_surcharge>
                    <percentage_saving>16</percentage_saving>
                </best_value_offer>
                <max_combined>167.15</max_combined>
                <max_saving_offer>
                    <absolute_saving>14.25</absolute_saving>
                    <full_combined>86.75</full_combined>
                    <full_seatprice>72.5</full_seatprice>
                    <full_surcharge>14.25</full_surcharge>
                    <offer_combined>72.5</offer_combined>
                    <offer_seatprice>72.5</offer_seatprice>
                    <offer_surcharge>0.0</offer_surcharge>
                    <percentage_saving>16</percentage_saving>
                </max_saving_offer>
                <max_seatprice>139.5</max_seatprice>
                <max_surcharge>27.65</max_surcharge>
                <min_combined>39.5</min_combined>
                <min_cost_offer>
                    <absolute_saving>8.25</absolute_saving>
                    <full_combined>50.75</full_combined>
                    <full_seatprice>42.5</full_seatprice>
                    <full_surcharge>8.25</full_surcharge>
                    <offer_combined>42.5</offer_combined>
                    <offer_seatprice>42.5</offer_seatprice>
                    <offer_surcharge>0.0</offer_surcharge>
                    <percentage_saving>16</percentage_saving>
                </min_cost_offer>
                <min_seatprice>39.5</min_seatprice>
                <min_surcharge>0.0</min_surcharge>
                <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>
                    <valid_quantity>7</valid_quantity>
                    <valid_quantity>8</valid_quantity>
                    <valid_quantity>9</valid_quantity>
                    <valid_quantity>10</valid_quantity>
                </quantity_options>
                <range_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>
                </range_currency>
                <top_price_offer>
                    <absolute_saving>14.25</absolute_saving>
                    <full_combined>86.75</full_combined>
                    <full_seatprice>72.5</full_seatprice>
                    <full_surcharge>14.25</full_surcharge>
                    <offer_combined>72.5</offer_combined>
                    <offer_seatprice>72.5</offer_seatprice>
                    <offer_surcharge>0.0</offer_surcharge>
                    <percentage_saving>16</percentage_saving>
                </top_price_offer>
            </no_singles_cost_range>
            <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>
                <valid_quantity>7</valid_quantity>
                <valid_quantity>8</valid_quantity>
                <valid_quantity>9</valid_quantity>
                <valid_quantity>10</valid_quantity>
            </quantity_options>
            <range_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>
            </range_currency>
            <top_price_offer>
                <absolute_saving>14.25</absolute_saving>
                <full_combined>86.75</full_combined>
                <full_seatprice>72.5</full_seatprice>
                <full_surcharge>14.25</full_surcharge>
                <offer_combined>72.5</offer_combined>
                <offer_seatprice>72.5</offer_seatprice>
                <offer_surcharge>0.0</offer_surcharge>
                <percentage_saving>16</percentage_saving>
            </top_price_offer>
        </cost_range>
        <country_code>uk</country_code>
        <country_desc>United Kingdom</country_desc>
        <critic_review_percent>80</critic_review_percent>
        <date_range_end>
            <date_desc>Sun, 2nd October 2016</date_desc>
            <date_utc_offset>3600</date_utc_offset>
            <date_utc_seconds>1475415000</date_utc_seconds>
            <date_yyyymmdd>20161002</date_yyyymmdd>
        </date_range_end>
        <date_range_start>
            <date_desc>Tue, 24th November 2015</date_desc>
            <date_utc_offset>0</date_utc_offset>
            <date_utc_seconds>1448393400</date_utc_seconds>
            <date_yyyymmdd>20151124</date_yyyymmdd>
        </date_range_start>
        <event_code>175</event_code>
        <event_desc>The Lion King</event_desc>
        <event_id>25DR</event_id>
        <event_lingo>theatre</event_lingo>
        <event_status>live</event_status>
        <event_subdata/>
        <geo_data>
            <latitude>51.511784</latitude>
            <longitude>-0.119622</longitude>
        </geo_data>
        <is_seated>yes</is_seated>
        <need_departure_date>no</need_departure_date>
        <need_duration>no</need_duration>
        <need_performance>yes</need_performance>
        <postcode>WC2E 7RQ</postcode>
        <search_distance_km>0.0</search_distance_km>
        <show_perf_time>yes</show_perf_time>
        <source_code>atg_disney</source_code>
        <source_desc>Ambassador Theatre Group</source_desc>
        <venue_code>LYC/T</venue_code>
        <venue_desc>The Lyceum</venue_desc>
    </event>
    <event_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>
        <valid_quantity>7</valid_quantity>
        <valid_quantity>8</valid_quantity>
        <valid_quantity>9</valid_quantity>
        <valid_quantity>10</valid_quantity>
    </event_quantity_options>
</date_time_options_result>

This example is for an event which requires a usage date. The event is valid from the 20th of February 2003 through to the 20th of April, though it cannot be booked between the 3rd and 15th of march and also from the 27th of March to the 8th of April. In addition the attraction is not open on Tuesdays and Fridays.

<date_time_options_result>
<crypto_block>M_--3KyQLySr7WclRgqbXGBcoZeAPiXU8unG2vFyCP63ds5fRi4
egU56PXoH8-U8HC1a5qGD8kqYCI80NZfANDAM4ilg_RKlkDLxN0qR5ovB1K7VVkIN
EtehA_--Y</crypto_block>
<need_departure_date>no</need_departure_date>
<using_usage_date>

<first_valid_date_yyyymmddd>
20030220
</first_valid_date_yyyymmddd>
<first_valid_date_desc>
Thu, 20th February 2003
</first_valid_date_desc>
<last_valid_date_yyyymmddd>
20030420
</last_valid_date_yyyymmddd>
<last_valid_date_desc>
Sun, 20th April 2003
</last_valid_date_desc>

<invalid_range>
<first_invalid_date_yyyymmddd>
20030303
</first_invalid_date_yyyymmddd>
<first_invalid_date_desc>
Mon, 3rd March 2003
</first_invalid_date_desc>
<last_invalid_date_yyyymmddd>
20030315
</last_invalid_date_yyyymmddd>
<last_invalid_date_desc>
Sat, 15th March 2003
</last_invalid_date_desc>
</invalid_range>

<invalid_range>
<first_invalid_date_yyyymmddd>
20030327
</first_invalid_date_yyyymmddd>
<first_invalid_date_desc>
Thu, 27th March 2003
</first_invalid_date_desc>
<last_invalid_date_yyyymmddd>
20030408
</last_invalid_date_yyyymmddd>
<last_invalid_date_desc>
Tue, 8th April 2003
</last_invalid_date_desc>
</invalid_range>

<invalid_weekday>
<weekday_number>2</weekday_number>
<weekday_name>Tuesday</weekday_name>
</invalid_weekday>

<invalid_weekday>
<weekday_number>5</weekday_number>
<weekday_name>Friday</weekday_name>
</invalid_weekday>

</using_usage_date>
</date_time_options_result>

9.3. Potential failure codes

  • 1 - the supplied crypto block was not generated by
    “event_search”
  • 2 - the requested “mime_text_type” was not a supported value
  • 201 - no “event_token” has been supplied
  • 202 - the supplied “event_token” is corrupt
  • 203 - the event specified could not be found in the database
  • 204 - the “earliest_date” element was badly formatted
  • 205 - the “latest_date” element was badly formatted