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.
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.
Example input
~~~~~~~~~~~~~
.. code-block:: xml
ftbo
U_--vkpf9kC9pU5Ob-grofd1tGwcNPYj3ecsj3DY16jQkO0YWnDvmTKhsA3p_xUq7RLFyDc5-Rd1f6KqfuYIqgAFsev8QgopuCRwO4r_Dm3LIEQyqrEjq89lr2PIn93DkwglY
25DR
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.
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.
.. code-block:: xml
no
s_--3BtridHm2GvWNi0T3-HGFnVtzaem1388zJjxVA-2ZWz5O6e5lZXXZw_l9-osvDvBJgemas4uvne4VMfE2jh9HryY-ON9hDEokcUDf4kH70TD-rL5DCXBtzZuveeIfRVQJz1NMMXmLB6x8UjwtHTqRZbywcIojoEZ
no
no
7
13.25
80.75
67.5
13.25
67.5
67.5
0.0
16
107.75
13.25
80.75
67.5
13.25
67.5
67.5
0.0
16
90.0
17.75
42.5
8.25
50.75
42.5
8.25
42.5
42.5
0.0
16
42.5
0.0
13.25
80.75
67.5
13.25
67.5
67.5
0.0
16
107.75
13.25
80.75
67.5
13.25
67.5
67.5
0.0
16
90.0
17.75
47.5
9.25
56.75
47.5
9.25
47.5
47.5
0.0
16
47.5
0.0
1
2
3
4
5
6
7
gbp
100
826
2
£
13.25
80.75
67.5
13.25
67.5
67.5
0.0
16
1
2
3
4
5
6
7
gbp
100
826
2
£
13.25
80.75
67.5
13.25
67.5
67.5
0.0
16
Tue, 24th November 2015
0
1448393400
20151124
yes
no
25DR-42L
yes
20036438
s---ERVzwUevoi8qCrIMQXAfrm7j7pnCTzp7jNXk7dgp1DnaIr3qRZdGJGfgbClCxxdLc4mtPXPNxl7-Y
739855
7.30 PM
193000
10
13.25
80.75
67.5
13.25
67.5
67.5
0.0
16
67.5
13.25
80.75
67.5
13.25
67.5
67.5
0.0
16
67.5
0.0
35.0
6.75
41.75
35.0
6.75
35.0
35.0
0.0
16
35.0
0.0
13.25
80.75
67.5
13.25
67.5
67.5
0.0
16
67.5
13.25
80.75
67.5
13.25
67.5
67.5
0.0
16
67.5
0.0
42.5
8.25
50.75
42.5
8.25
42.5
42.5
0.0
16
42.5
0.0
1
2
3
4
5
6
7
8
9
10
gbp
100
826
2
£
13.25
80.75
67.5
13.25
67.5
67.5
0.0
16
1
2
3
4
5
6
7
8
9
10
gbp
100
826
2
£
13.25
80.75
67.5
13.25
67.5
67.5
0.0
16
Wed, 25th November 2015
0
1448461800
20151125
yes
no
25DR-42M
yes
20036438
s---nbWR_3uRkj2WnkyGnXcYk23Xo0ygQhHBuEcscPrVFPqaIr3qRZdGJqrRSz1_Va4Uc4mtPXPNxl7-Y
739874
2.30 PM
143000
WE
West End
196
london-uk
London
theatre
Theatre
yes
theatre/
yes
theatre/kids
kids
Family
no
theatre/musicals
musicals
Musicals
14.25
86.75
72.5
14.25
72.5
72.5
0.0
16
167.15
14.25
86.75
72.5
14.25
72.5
72.5
0.0
16
139.5
27.65
35.0
6.75
41.75
35.0
6.75
35.0
35.0
0.0
16
35.0
0.0
14.25
86.75
72.5
14.25
72.5
72.5
0.0
16
167.15
14.25
86.75
72.5
14.25
72.5
72.5
0.0
16
139.5
27.65
39.5
8.25
50.75
42.5
8.25
42.5
42.5
0.0
16
39.5
0.0
1
2
3
4
5
6
7
8
9
10
gbp
100
826
2
£
14.25
86.75
72.5
14.25
72.5
72.5
0.0
16
1
2
3
4
5
6
7
8
9
10
gbp
100
826
2
£
14.25
86.75
72.5
14.25
72.5
72.5
0.0
16
uk
United Kingdom
80
Sun, 2nd October 2016
3600
1475415000
20161002
Tue, 24th November 2015
0
1448393400
20151124
175
The Lion King
25DR
theatre
live
51.511784
-0.119622
yes
no
no
yes
WC2E 7RQ
0.0
yes
atg_disney
Ambassador Theatre Group
LYC/T
The Lyceum
1
2
3
4
5
6
7
8
9
10
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.
.. code-block:: xml
M_--3KyQLySr7WclRgqbXGBcoZeAPiXU8unG2vFyCP63ds5fRi4
egU56PXoH8-U8HC1a5qGD8kqYCI80NZfANDAM4ilg_RKlkDLxN0qR5ovB1K7VVkIN
EtehA_--Y
no
20030220
Thu, 20th February 2003
20030420
Sun, 20th April 2003
20030303
Mon, 3rd March 2003
20030315
Sat, 15th March 2003
20030327
Thu, 27th March 2003
20030408
Tue, 8th April 2003
2
Tuesday
5
Friday
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