Upload
rezgo
View
648
Download
8
Embed Size (px)
DESCRIPTION
Reference manual for the Rezgo Tour & Activity Booking Software XML API. This reference guide details the REST request and XML response messages for the Rezgo API including all major messages.
Citation preview
Sentias Software Corp. Rezgo XML API
rezgo
XML Gateway API - Reference Manual
Reference Manual - Version 3.4Rezgo Version 4.8.0
Last Modified 12 Nov 2009
Copyright ©20081 of 39
Sentias Software Corp. Rezgo XML API
Revision HistoryPrimary Author Description Rezgo Version API Doc
VersionDate
Marc Raiser API Initial Draft ø 1.0 23 Jan 2007Jeffrey Qua Rezgo API – Revision 3.8.5 2.0 08 May
2008Jeffrey Qua Rezgo API – Revision 3.10.0 2.1 09 Jul 2008Jeffrey Qua Rezgo API – Major Revision 4.0.0 3.0 28 Oct 2008Jeffrey Qua Rezgo API – Minor Revision 4.1.4 3.1 02 Mar 2009Jeffrey Qua Rezgo API – Minor Revision 4.1.4 3.2 13 Mar 2009Jeffrey Qua Rezgo API – Revision/XML
Changes4.7.0 3.3 02 Nov 2009
Miyuki Shiomi Rezgo API – Revision/XML Changes
4.8.0 3.4 12 Nov 2009
Revision Notes
API v3.3, 3.4 - Rezgo Version 4.8.0 (XML changes)-group pricing, re-check item details on Booking Details page(4.8)-modifications to forms node in i=search_items query(4.7)-support for multiple/additional locations in i=search_items query(4.6.3)-support for i=region_list query on supplier site(4.6.2)-major change in structure of month query(4.3)-external XML queries now require use of valid API key (4.2)-generated time <gt> node added for all queries; denotes time taken by server to return results
API v3.1,3.2 - Rezgo Version 4.1.4 (minor revision; removal of deprecated functionality)
-removed i=category_image, and i=image instructions
API v3.0 - Rezgo Version 4.0 (major layout/functionality changes)-xml query no longer uses http://booking-server.com/xml-gate?; now using http://xml.rezgo.com/xml?-new additions in i=search_items query:
- common ids <com>, common_id returned and search by common_id functionality-latitude <lat> and longitude <lon> item geodata-schedule <schedule> info [<departs>, <unavailable>, <itinerary>, <pick_up>,
<drop_off>, <bring>]-details <details> info [<introduction>, <overview>, <inclusions>, <exclusions>,
<cancellation>, <description>]-starting price <start>-image gallery <image_gallery> and video gallery <video_gallery>
-new url structure using clean URLs with modrewrite-default search_items query now uses common_id <com> as the primary search target
Copyright ©20082 of 39
Sentias Software Corp. Rezgo XML API
Table of Contents
Before You Start............................................................................................................................................................... 4
Introduction...................................................................................................................................................................... 5
Instructions....................................................................................................................................................................... 5i=company........................................................................................................................................................................................ 5i=about............................................................................................................................................................................................... 7i=headers.......................................................................................................................................................................................... 8i=tags................................................................................................................................................................................................. 9 i=search_items............................................................................................................................................................................. 10 i=search_items – more examples .......................................................................................................................................... 16i=search_items – promotional code example ....................................................................................................................17i=month.......................................................................................................................................................................................... 19i=commit........................................................................................................................................................................................ 23i=search_bookings....................................................................................................................................................................... 26i=region_list................................................................................................................................................................................... 31
Instructions (Portals only)........................................................................................................................................ 32 i=classification_list...................................................................................................................................................................... 32i=modify_bookings (cancel_booking)................................................................................................................................... 32
Copyright NoticeThis document and the software to which it refers to is copyrighted by Sentias Software Corp. Use of this documentation and the software to which it refers is subject to the acceptance of the Terms of Use referenced in this documentation and available online at http://www.rezgo.com. All rights reserved. All other trademarks, and registered trademarks are the property of their respective owners.
Copyright ©20083 of 39
Sentias Software Corp. Rezgo XML API
Before You Start
Accessing the GatewayThe XML Gateway is located at http://xml.rezgo.com/xml?It can be queried with a standard HTTP Request. All gateway queries need at least two components, a transcode and an instruction. Any external queries also require a valid API key, and added with the key parameter.
TranscodeThe transcode is either the unique identifier of the Rezgo account holder (returned as cid in the response) or the unique identifier of a vendor prefixed by ‘p’ (eg., transcode=p4). The transcode/company id can be found in Rezgo Admin > Settings.
API KeyThe API Key is required for third-party parsers and can be located for each Rezgo client in Rezgo Admin > Settings.
InstructionThe following is a list of instructions that are described independently later in this document:
1) i=company2) i=about3) i=headers4) i=tags5) i=search_items6) i=month7) i=commit8) i=search_bookings9) i=region_list10) i=classification_list
Additional (optional) argumentsAlong with the required transcode and instruction, there are additional optional arguments that are supported. These arguments provide additional refinement to make the queries more specific. Arguments listed here are for retrieving information. We will include arguments for sending information (commit queries) in a later section.Items listed in {} braces are example values.
1) q : query (the search string, may contain * wildcards)2) t : target (the search target – a list of possible search targets is given in the search-items
section) {com, name, uid, category(tag)}3) d : date (Y-m-d format)4) a : additional arguments {image, active, group, featured} - skip image a true or false
additional identifier, (ie a=image, a=active, a=skip_cutoff), a=group only returns group info (Returns only 1 item from each group), a=skip_cutoff allows searches to ignore the cutoff date, use commas to separate multiple arguments, eg a=group,featured
5) f : search filter - an array for additional search criteria, see search-items, (ie f[keywords]=camping)
6) trigger_code: a promotional code used to apply/enable a rule.
Copyright ©20084 of 39
Sentias Software Corp. Rezgo XML API
Introduction
The gateway is your source for information stored in Rezgo. Gateway queries require a transcode and an instruction. All queries will also return with a generated time <gt> node to denote the time it takes for the server to generate a response to the query. (We will not include this in the examples)
Instructions
The instructions in this section are meant for individual Rezgo tour providers only. As such, the transcode must be a number and not a p of a vendor.
The following examples will use the following settings:Transcode of 1 : transcode=1 (required)
i=company
The company query returns information about the company associated with the submitted transcode. This query does not need any additional arguments.
Example query:
http://xml.rezgo.com/xml?key=REZGO_API_KEY&transcode=1&i=company
Query response:
<response><company_name><![CDATA[Booking Server Test]]></company_name><type>tour</type>
<domain>testcompany</domain>
<terms><![CDATA[These terms & conditions are for test purposes only.]]></terms><address_1><![CDATA[233 West 1st. Street]]></address_1><address_2><![CDATA[107w 1515]]></address_2><city>North Vancouver</city><state_prov>BC</state_prov><postal_code>V3J 3L7</postal_code><country>ca</country><phone>604 123 4567</phone><fax></fax><email>[email protected]</email><email_1></email_1><email_2></email_2><email_3></email_3><account_type>p</account_type><currency_symbol>$</currency_symbol><currency_separator>,</currency_separator><currency_decimals>2</currency_decimals><currency_base> CAD</currency_base>
Copyright ©20085 of 39
Sentias Software Corp. Rezgo XML API
<using_gateway>1</using_gateway><cards><![CDATA[MasterCard, Visa]]></cards><payment_methods><![CDATA[Credit Cards, PayPal, Cheques]]></payment_methods><paypal_email>[email protected]</paypal_email><get_cvv>1</get_cvv><date_format>M d, Y</date_format><time_format>+0</time_format><label_tour><![CDATA[Rezgo Tours]]></label_tour><sti_show>0</sti_show><sti_value>7.00</sti_value>
</response>
Company response definition:
The returned data corresponds to the company information for the account with the given transcode. Some of the fields may be wrapped in CDATA tags to allow special characters to be formatted in XML.
XML Tag Description of contents
company_name the name of the company
domain company’s registered subdomain (eg. subdomain.rezgo.com)
termsthe terms and conditions supplied by the company (may be HTML-formatted)
address_1 first address field
address_2 second address field
city city
state_prov state/province
postal_code postal code
country country
phone phone number
fax fax number
email primary e-mail address
email_1 primary alternate e-mail address - only applicable for suppliers
email_2 secondary alternate e-mail address - only applicable for suppliers
email_3 tertiary alternate e-mail address - only applicable for suppliers
account_type account type (f – free, p – pro) - only applicable for suppliers
currency_symbol currency symbol used by company (eg. $, £, €, ¥)currency_separator
symbol used as decimal point/indicator
currency_decimals
number of trailing decimal places to display
currency_base the base currency that the company uses
using_gateway indicates if the site is using a payment gateway
cards credit cards accepted by the company (eg. American Express,
Copyright ©20086 of 39
Sentias Software Corp. Rezgo XML API
MasterCard, Visa)payment_methods
accepted payment methods (eg. Credit Cards, PayPal, Cheques)
paypal_emaile-mail address to accept PayPal transfers (only if PayPal is selected as a payment method) - only applicable for suppliers
get_cvvindicate if company requires CVV to be passed for credit card payments (set to 0 or 1)
date_format date display format (eg. M d, Y)
time_format time zone difference from GMT (eg. +20, -8, +4)
label_tour custom label for tour module in menu
sti_showindicate if company would like to show STI carbon offset options on booking receipts (set to 0 or 1)
sti_value default amount in STI donation field
i=about
The about query returns HTML-encoded information about the company represented by the submitted transcode. This query does not need any additional arguments.
Example query:
http://xml.rezgo.com/xml? key=REZGO_API_KEY &transcode=1&i=about
Query response:
<response><intro><![CDATA[... HTML Code ...]]></intro><about><![CDATA[... HTML Code ...]]></about>
</response>
About response definition:
The returned data corresponds to the company introduction and descriptions for the account with the given transcode.
XML Tag Description of contents
intro HTML-formatted introduction text
about HTML-formatted about text
Copyright ©20087 of 39
Sentias Software Corp. Rezgo XML API
i=headers
The headers query returns HTML-encoded information about the company and currently active modules represented by the submitted transcode. This query does not need any additional arguments.
Example query:
http://xml.rezgo.com/xml?key=REZGO_API_KEY&transcode=1&i=headers
Query response:
<response><header><![CDATA[... HTML Code ...]]></header><footer><![CDATA[... HTML Code ...]]></footer><analytics_general><![CDATA[ ... HTML/JS Analytics code ...]]></analytics_general><book_now><![CDATA[Reserve Now]]></book_now><site_status>1</site_status><triggers>1</triggers>
</response>
Headers response definition:
The returned data corresponds to the template data, and specific site variables for the account with the given transcode.
XML Tag Description of contents
header HTML-formatted header template (at top of page)
footer HTML-formatted footer template (at bottom of page)analytics_general
HTML/Javascript code for analytics/stat tracking
book_now text for the ‘Book Now’ button label
site_status flag to indicate if site is turned on or not (0 or 1)
triggersflag to indicate if triggerable promotional codes are active (0 or 1) - only applicable for suppliers
Note: the triggers field is only returned only for supplier queries as triggerable promo codes are not enabled for vendors
Copyright ©20088 of 39
Sentias Software Corp. Rezgo XML API
i=tags
The tags query returns information about tags, the tag id number, and the number of products in each. This helps to divide tags into how popular they are.
Example query:
http://xml.rezgo.com/xml?key=REZGO_API_KEY&transcode=1&i=tags
Query response:
<response><total>2</total>
<tag><num>1</num><name><![CDATA[Walking Tours]]></name><uid>872</uid><count>0</count>
</tag>
<tag><num>2</num><name><![CDATA[Daily Tours]]></name><uid>873</uid><count>2</count>
</tag></response>
Tags response definition:
The returned data corresponds to the tag information for the account with the given transcode.
XML Tag Description of contents
total total number of found tags
tag XML node of tag data
num the i-th node of the i=tags response
name tag name
uid unique numerical tag ID
count the number of tour options correlated to the tag
Copyright ©20089 of 39
Sentias Software Corp. Rezgo XML API
i=search_items
The search_items query returns information about tours that match the search parameters. The tours returned are from the company represented by the submitted transcode. This query has multiple additional arguments that help refine the search of found tours. All these optional arguments are independent of each other.
Optional arguments:1) q : query (the search string, may contain * wildcards).2) t : target {com, name, uid, category(tag)} - the search target.3) d : date {Y-m-d format} – search for tours that are available on this date.4) a : additional arguments {image, active, group, featured} - skip image a true or false
additional identifier, (ie a=image, a=active, a=skip_cutoff), a=group only returns group info (Returns only 1 item from each group), a=skip_cutoff allows searches to ignore the cutoff date, use commas to separate multiple arguments, eg a=group,featured
5) f : search refinement {f[search_parameter] = search_pattern} - an array for additional search criteria (ie f[keywords]=camping).
6) trigger_code: a promotional code used to apply/enable a rule.
The following illustrates a request for a list of all tours. We run a search_items query for items that has a name or common id matching * (wildcard), so we return all tours. The price data for a certain date is only returned if a date is given.
Example query:
http://xml.rezgo.com/xml?key=REZGO_API_KEY &transcode=1&i=search_items&t=name&q=* &d=2008-05-01http://xml.rezgo.com/xml?key=REZGO_API_KEY &transcode=1&i=search_items&t=com&q=* &d=2008-05-01
Query response:
<response><total>21</total>
<item><num>1</num><uid>1663</uid><com>1663</com><name><![CDATA[Guided Tour & Cruise]]></name><time><![CDATA[1:30PM - 9:30PM]]></time><category>50</category><classification>None</classification><starting>2.00</starting><group>require</group><per>2</per><cutoff>2</cutoff><duration><![CDATA[8 hours]]></duration><date value="2008-05-01">
<active>1</active><availability>25</availability><price_adult>25</price_adult><price_child></price_child>
Copyright ©200810 of 39
Sentias Software Corp. Rezgo XML API
<price_senior></price_senior><price4></price4><price5></price5><price6></price6><price7></price7><price8></price8><price9></price9>
</date><adult_label><![CDATA[Adult]]></adult_label><child_label><![CDATA[Child]]></child_label><senior_label><![CDATA[Senior]]></senior_label><price4_label><![CDATA[Price 4]]></price4_label><price5_label><![CDATA[Price 5]]></price5_label><price6_label><![CDATA[Price 6]]></price6_label><price7_label><![CDATA[Price 7]]></price7_label><price8_label><![CDATA[Price 8]]></price8_label><price9_label><![CDATA[Price 9]]></price9_label><adult_required>1</adult_required><child_required>0</child_required><senior_required>0</senior_required><price4_required>0</price4_required><price5_required>0</price5_required><price6_required>0</price6_required><price7_required>0</price7_required><price8_required>0</price8_required><price9_required>0</price9_required><currency_symbol>$</currency_symbol><currency_separator>,</currency_separator><currency_decimals>2</currency_decimals><currency_base> CAD</currency_base><city>Vancouver</city><state>BC</state><country>ca</country><additional_locations>
<location><loc_country>ca</loc_country><loc_state>ab</loc_state><loc_city>Calgary</loc_city>
</location><location>
<loc_country>ca</loc_country><loc_state>on</loc_state><loc_city>Toronto</loc_city>
</location></additional_locations><lat></lat><lon></lon><zoom>13</zoom><taxes>12%</taxes><tax_calc>0</tax_calc><start_date>1181890800</start_date><end_date>1213426800</end_date><total_adult>25</total_adult><total_child>0</total_child><total_senior>0</total_senior><total_price4>0</total_price4><total_price5>0</total_price5>
Copyright ©200811 of 39
Sentias Software Corp. Rezgo XML API
<total_price6>0</total_price6><total_price7>0</total_price7><total_price8>0</total_price8><total_price9>0</total_price9><overall_total>0</overall_total><deposit></deposit><deposit_value></deposit_value><total_availability>25</total_availability><forms>
<total_forms>2</total_forms><form num=”1”>
<id>1233</id><show>primary</show><type>text</type><label><![CDATA[Special requests]]></label><require>0</require><value></value><comments><![CDATA[Do you have any special needs you would like us
to provide?]]></comments></form><form num=”2”>
<id>1234</id><show>group</show><type>checkbox</type><label><![CDATA[Deluxe Dinner]]></label><require>1</require><price>+20</price><value></value><comments><![CDATA[The deluxe dinner for the cruise requires a
preparation fee]]></comments></form>
</forms><schedule>
<departs></departs><unavailable></unavailable><itinerary></itinerary><pick_up></pick_up><drop_off></drop_off><bring></bring>
</schedule><details>
<introduction><![CDATA[The sights and scenery of beautiful Vancouver]]></introduction>
<overview><![CDATA[The sights and scenery of beautiful Vancouver...]]></overview>
<inclusions></inclusions><exclusions></exclusions><cancellation></cancellation><description><![CDATA[<div>A guided tour & cruise of beautiful downtown
Vancouver. Enjoy an afternoon of shopping in the heart of Vancouver in the Robson shopping district. Then set sail on a sunset cruise into English Bay and a scenic voyage around Stanley Park.</div><img width="140" height="94" src="/i/1/38.jpg" alt="" title="">]]></description>
</details><image_gallery value=”1”>
<image value=”1-1663-1.jpg”></image></image_gallery>
Copyright ©200812 of 39
Sentias Software Corp. Rezgo XML API
<video_gallery value=”1”><video value=”http://www.youtube.com/watch?v=kdTdp7Ep6AM”>
<caption></caption><image>youtube-kdTdp7Ep6AM.jpg</image>
</video></video_gallery><cid>1</cid><exists>1</exists><image>1</image>
</item><item>
<num>2</num><uid>160</uid><com>160</com><name><![CDATA[Guided Tour & Cruise]]></name>
...</item>
</response>
Copyright ©200813 of 39
Sentias Software Corp. Rezgo XML API
i=search_items – more examples
In the previous section we have not set a=group and so, we would get back results for ALL options. If we only want tour results and not all tour options for the previous example, we would use the following queries:
http://xml.rezgo.com/xml?key=REZGO_API_KEY &transcode=1&i=search_items&t=name&q=*&a=group &d=2008-05-01http://xml.rezgo.com/xml?key=REZGO_API_KEY &transcode=1&i=search_items&t=com&q=*&a=group &d=2008-05-01
Some example queries
Search for all tours with name “summer”http://xml.rezgo.com/xml?key=REZGO_API_KEY &transcode=1&i=search_items&t=name&q=summer&a=group
Search for all tour options with a common id of 64http://xml.rezgo.com/xml? key=REZGO_API_KEY &transcode=1&i=search_items&t=com&q=64
Search for tour option with uid 95 with prices for Jan 1 2010http://xml.rezgo.com/xml?key=REZGO_API_KEY &transcode=1&i=search_items&t=uid&q=95&d=2010-01-01
Practical examples
Main page (All products)http://xml.rezgo.com/xml?key=REZGO_API_KEY &transcode=1&i=search_items&t=com&q=*&a=group Main vendor page (Featured Products)http://xml.rezgo.com/xml?key=REZGO_API_KEY & transcode=1&i=search_items&t=name&a=group,featured&q=* Tour page (Get all tour options for a given tour identified by [common id]) http://xml.rezgo.com/xml? key=REZGO_API_KEY & transcode=1&i=search_items&t=com&q=* Tour info for given date(Get all tour options AND price data for a given tour identified by [common id]) http://xml.rezgo.com/xml?key=REZGO_API_KEY & transcode=1&i=search_items&t=com&q=*&d=2010-01-01 Search for all tours matching the keyword “city tour” (only applicable to vendors)http://xml.rezgo.com/xml?key=REZGO_API_KEY &transcode=p4&i=search_items&t=name&a=group&q=*&f[description]=*c ity+tour*
Copyright ©200814 of 39
Sentias Software Corp. Rezgo XML API
i=search_items – promotional code example
The search_items query can include the trigger_code variable to enable a special rule to affect availability or prices. Any changes in prices will create the base_prices node in the date node. The following illustrates a request for a specific tour using a trigger code to enable a special rule. We apply the promotional code discount20 which decreases price1/adult by 20 percent. The base prices node includes nodes for all prices that have been changed and has the value of the original price.
Example query:
http://xml.dev.rezgo.com/xml?key=REZGO_API_KEY &transcode=1&l=tour&i=search_items&t=com&q=6573 &d=2009-03-31&trigger_code=discount20
Query response:
<response><total>2</total>
<item><num>1</num><uid>6573</uid><com>6573</com><name><![CDATA[Awesome Tour]]></name><time><![CDATA[12:00]]></time><category>873</category><classification>None</classification><starting>1999.99</starting><group>request</group><per>1</per><cutoff>0</cutoff><duration><![CDATA[5 minutes]]></duration><date value="2009-03-31">
<active>1</active><availability>25</availability><price_adult>12.79</price_adult><price_child>2.50</price_child><price_senior/><price4>24</price4><price5>25</price5><price6>26</price6><price7/><price8/><price9/><base_prices>
<price_adult>19.99</price_adult></base_prices>
</date>...<total_adult>12.79</total_adult><total_child>2.5</total_child><total_senior>0</total_senior>
Copyright ©200815 of 39
Sentias Software Corp. Rezgo XML API
<total_price4>24</total_price4><total_price5>25</total_price5><total_price6>26</total_price6><total_price7>0</total_price7><total_price8>0</total_price8><total_price9>0</total_price9><overall_total>0</overall_total>
</item>...
Copyright ©200816 of 39
Sentias Software Corp. Rezgo XML API
Search_items response definition:
The returned data corresponds to the information for matching tours of the company with the given transcode.
XML Tag Description of contents
total total number of found tours
item an item node of matched tours
num position of the item node in the item array
uid unique numerical item ID
com common ID that groups tour options together
name tour name
time time description text
category unique numerical category ID that this tour belongs to
classificationtour classification {None, Adventure Tours, City Bus Tours} – used for searching on vendor sites
starting submitted starting price for tour
grouprequire group/passenger information {request, require, hide} – request: optional; require: required; hide: do not show
per minimum number of people required for booking to be allowed
cutoff minimum number of days in advance that booking must be made
duration text description of duration of the tour
dateXML node of prices for the day in the value attribute(in Y-m-d format) – refer to date node definition; only returned if there is availability for the given date
adult_label label for adult price option; only returned if date is specified
child_label label for child price option; only returned if date is specified
senior_label label for senior price option; only returned if date is specifiedprice4_label – price9_label
label for (price4 – price9) price option; only returned if date is specified
adult_requiredflag to indicate if adult price option is required (0 or 1); only returned if date is specified
child_requiredflag to indicate if child price option is required (0 or 1); only returned if date is specified
senior_requiredflag to indicate if senior price option is required (0 or 1); only returned if date is specified
price4_required – price9_required
flag to indicate if (price4 - price9) price option is required (0 or 1); only returned if date is specified
currency_symbol currency symbol used by company (eg. $, £, €, ¥)currency_separator
symbol used as decimal point/indicator
currency_decimals
number of trailing decimal places to display
currency_base the base currency that the company uses – this is for use in portals
Copyright ©200817 of 39
Sentias Software Corp. Rezgo XML API
city location of tour - city
state location of tour - state
country location of tour - country
lat geotag latitude
lon geotag longitude
zoom geotag map zoom level
taxespercentage value for taxes (eg. 7%, 12%) or flat value that is added to the sub-total of the order (eg. 5.45)
tax_calccalculated tax value (returned with a value when passenger info has been passed)
start_date UNIX timestamp of tour start date
end_date UNIX timestamp of tour end date
total_adult the total cost sum of adult price option; only returned if date is specified
total_child the total cost sum of child price option; only returned if date is specified
total_seniorthe total cost sum of senior price option; only returned if date is specified
total_price4 – total_price9
the total cost of (price4 – price9) price option; only returned if date is specified
overall_totalthe total cost of the booking (only returned when passenger info has been passed); only returned if date is specified
depositdeposit amount required upon booking, discrete value or percentage or amount required to be paid as deposit upon booking; only returned if date is specified
deposit_value currently not used
total_availabilitytotal number of available spots for this tour on that day; only returned if date is specified
formsXML node of forms given during booking – refer to forms node definition; only returned if date is specified
schedule XML node of scheduling info – refer to schedule node definition
details XML node of detailed info – refer to details node definition
image_galleryXML node of images – refer to image_gallery node definition; number of results found included in the value attribute
video_galleryXML node of videos – refer to video_gallery node definition; number of results found included in the value attribute
cid unique numerical ID to identify the company that supplies this item
imageflag to indicate if image for this item exists – get image using http://images.rezgo.com/items/(company_id)-(common_id).jpg
Copyright ©200818 of 39
Sentias Software Corp. Rezgo XML API
Date node definition:
XML Tag Description of contents
availability total number of available spots for this tour on that day
price_adult cost for adult price option
price_child cost for child price option
price_senior cost for senior price option
price4 - price9 cost for (price4 – price9) price option
base_pricesXML node of original prices – refer to base_prices node definition; only returned if promotional code given adjusts any of 9 pricing
Base_prices node definition:
XML Tag Description of contents
price_adultoriginal cost for adult price option; only returned if promotional code given adjusts adult price option
price_childoriginal cost for child price option; only returned if promotional code given adjusts child price option
price_seniororiginal cost for senior price option; only returned if promotional code given adjusts senior price option
price4 - price9original cost for (price4 – price9) price option; only returned if promotional code given adjusts each price option
Forms node definition:
XML Tag Description of contents
total_forms total number of forms attached
form_x x-th form node
id unique numerical form ID
showflag to indicate whether to show form for all passengers, or just the person booking {group: show for all passengers, primary: just show once for whole group}
type forms type of input
label form label
require flag to indicate if form is required to be filled (0 or 1)
priceprice of the option (either added or subtracted for enabling this option) – only enabled for checkbox forms
optionsvalues accepted by the system for this form separated by commas. This is for select or multi-select form types only
value value passed by user
comments text description to describe the form’s purpose
Copyright ©200819 of 39
Sentias Software Corp. Rezgo XML API
Schedule node definition:
XML Tag Description of contents
departs text – departure info
unavailable text – unavailable days info
itinerary text – itinerary info (HTML-formatted)
pick_up text – pick up info (HTML-formatted)
drop_off text – drop off info (HTML-formatted)
bring text – what to bring info (HTML-formatted)
Details node definition:
XML Tag Description of contents
introduction text - introduction of tour
overview text – tour overview (HTML-formatted)
inclusions text – inclusion info
exclusions text – exclusion info
cancellation text – cancellation info
description text – description of item (HTML-formatted)
Image_gallery node definition:
XML Tag Description of contents
image contains the filename of the image included in the value attribute
Video_gallery node definition:
XML Tag Description of contents
videocontains the filename of the original video included in the value attribute
caption caption for image
image filename of the video thumbnail image
Copyright ©200820 of 39
Sentias Software Corp. Rezgo XML API
i=month
The month query returns availability information for a specified tour. This query has one required argument in order to find specific month availability. There are two optional arguments that can provide access to all the items in the group and/or a date to indicate which month to check availability for. The uid pattern match is set to q=160 in the following example.
Required arguments:1) q : uid – uid of tour option to search for
Optional arguments:1) g : group {1} – if this is set to 1, then return all matching items/tour options in the same
tour; else it will only return results for that tour option2) d: date {Y-m-d format} – if this is set, then the search will be for the given month, else it
will search the current month3) trigger_code: a code used to apply/enable a rule
Example query
http://xml.rezgo.com/xml?key=REZGO_API_KEY&transcode=1&i=month&g=1&q=160&d=2008-05-01
Query response:
<response><month>May</month>
<day value="1" condition="p"></day><day value="2" condition="p"></day><day value="3" condition="p"></day><day value="4" condition="p"></day><day value="5" condition="p"></day><day value="6" condition="a">
<item value="15"><uid>5</uid><name><![CDATA[0900 - 1700]]></name>
</item><item value="15">
<uid>6</uid><name><![CDATA[0930 - 1700]]></name>
</item><item value="45">
<uid>7</uid><name><![CDATA[0130-0445]]></name>
</item><item value="25">
<uid>8</uid><name><![CDATA[sup & name]]></name>
</item>Copyright ©200821 of 39
Sentias Software Corp. Rezgo XML API
<item value="25"><uid>9</uid><name><![CDATA[test1234]]></name>
</item><item value="24">
<uid>10</uid><name><![CDATA[test2222222]]></name>
</item><item value="25">
<uid>11</uid><name><![CDATA[test three]]></name>
</item></day>... Other days ...<day value="31" condition="a">>
<item value="25"><uid>4</uid><name><![CDATA[1:30PM - 9:30PM]]></name>
</item><item value="15">
<uid>5</uid><name><![CDATA[0900 - 1700]]></name>
</item><item value="15">
<uid>6</uid><name><![CDATA[0930 - 1700]]></name>
</item><item value="45">
<uid>7</uid><name><![CDATA[0130-0445]]></name>
</item><item value="25">
<uid>8</uid><name><![CDATA[sup & name]]></name>
</item><item value="25">
<uid>9</uid><name><![CDATA[test1234]]></name>
</item><item value="24">
<uid>10</uid><name><![CDATA[test2222222]]></name>
</item></day>
</response>
Copyright ©200822 of 39
Sentias Software Corp. Rezgo XML API
i=month – promotional code example
The month query can include the trigger_code variable to enable a special rule to affect availability or prices. Any changes in availability will affect the value attribute of the i te m node. The following illustrates a request for a specific tour using a trigger code to enable a special rule. We apply the promotional code space20 which increases spot availability 20.
Example query:
http://xml.rezgo.com/xml? key=REZGO_API_KEY &transcode=1&i= month & g=1 &q= 160 &d=200 8 - 0 5 - 0 1 &trigger_code= space20
Query response:
<response><month>May</month>
<day value="1" condition="p"></day><day value="2" condition="p"></day><day value="3" condition="p"></day><day value="4" condition="p"></day><day value="5" condition="p"></day><day value="6" condition="a">
<item value="35"><uid>5</uid><name><![CDATA[0900 - 1700]]></name>
</item><item value="35">
<uid>6</uid><name><![CDATA[0930 - 1700]]></name>
</item><item value="65">
<uid>7</uid><name><![CDATA[0130-0445]]></name>
</item><item value="45">
<uid>8</uid><name><![CDATA[sup & name]]></name>
</item><item value="45">
<uid>9</uid><name><![CDATA[test1234]]></name>
</item><item value="44">
<uid>10</uid><name><![CDATA[test2222222]]></name>
</item><item value="45">
<uid>11</uid>
Copyright ©200823 of 39
Sentias Software Corp. Rezgo XML API
<name><![CDATA[test three]]></name></item>
</day>... Other days ...<day value="31" condition="a">>
<item value="45"><uid>4</uid><name><![CDATA[1:30PM - 9:30PM]]></name>
</item><item value="35">
<uid>5</uid><name><![CDATA[0900 - 1700]]></name>
</item><item value="35">
<uid>6</uid><name><![CDATA[0930 - 1700]]></name>
</item><item value="65">
<uid>7</uid><name><![CDATA[0130-0445]]></name>
</item><item value="45">
<uid>8</uid><name><![CDATA[sup & name]]></name>
</item><item value="45">
<uid>9</uid><name><![CDATA[test1234]]></name>
</item><item value="44">
<uid>10</uid><name><![CDATA[test2222222]]></name>
</item></day>
</response>
Copyright ©200824 of 39
Sentias Software Corp. Rezgo XML API
Month response definition:
The returned data corresponds to the availability information of the requested group or item provided by the company with the given transcode.
XML Tag Description of contents
month the returned month in full text format
day
XML node of availability for day of the month in the value attribute; the value attribute holds the availability for the day; it has multiple possible values {i: inactive, item availability reduced to 0 without bookings; u: unavailable, item is outside the availability window; p: past date, date is in the past; c: cutoff, the date is no longer available to be booked because it has passed the booking cutoff; h: hidden, the availability for this item is hidden, but there are still spots available} – refer to day node definition
Day node definition:
XML Tag Description of contents
itemavailability information containing the name of the item - the value attribute holds the spot availability for the item; (number): number of spots available, if 0, it is fully booked} – refer to item node definition
Item node definition:
XML Tag Description of contents
uid tour option sku
name tour option name
Copyright ©200825 of 39
Sentias Software Corp. Rezgo XML API
i=commit
The commit query processes the booking data in order to create a booking. This query should be transferred as secure data using https. Required arguments must be enough to identify an item and the booking details. There are other required/optional arguments depending on the item. The variables sent must be urlencoded.
Required arguments:1) date : booking date {Y-m-d format date}2) book : item uid - uid3) price_options to be booked4) tour contact information
Optional arguments:1) trigger_code: a code used to apply/enable a rule
Example query
The necessary arguments are highlighted in the following request. Some variables such as other price options, do not need to be sent as they will be assumed to be 0.
https://xml.rezgo.com/xml? key=REZGO_API_KEY &transcode=1 &i=commit&book_action=complete&book_confirm=confirm&cat=Guided+Tours&date=2008-05-06&book=1663&adult_num=2&tour_first_name=John&tour_last_name=Smith&tour_address_1=1234+Sesame+Street&tour_address_2=&tour_city=Vancouver&tour_stateprov=BC&tour_country=ca&tour_postal_code=A1A2B2&tour_phone_number=%28123%29456-7890&tour_email_address=elmo%40tickles.com&tour_group[adult][1][first_name]=Elmo&tour_group[adult][1][last_name]=E&tour_group[adult][1][phone]=&tour_group[adult][1][email]=&tour_group[adult][1][forms][1234]=on&tour_group[adult][2][first_name]=Big&tour_group[adult][2][last_name]=Bird&tour_group[adult][2][phone]=&tour_group[adult][2][email]=&tour_group[adult][2][forms][1234]=on&tour_forms[1233]=Can+you+tell+me+how+to+get+to+Sesame+Street%3F+&agree_terms=1
Copyright ©200826 of 39
Sentias Software Corp. Rezgo XML API
Commit query definition:
The returned data corresponds to the availability information of the requested group or item provided by the company with the given transcode.
Argument Description of contents
date booking date
book item uid to book for
adult_num number of spots to book for adult
child_num number of spots to book for child
senior_num number of spots to book for seniorsprice4_num – price9_num
number of spots to book for {price4 – price9}
tour_first_name Billing info - First name
tour_last_name Billing info - Last name
tour_address_1 Billing info – Address
tour_address_2 Billing info – Address 2 (Optional)
tour_city Billing info – City
tour_stateprov Billing info – State/Province
tour_country Billing info – Country
tour_postal_code Billing info – Postal Codetour_phone_number
Billing info – Phone Number
tour_email_address
Billing info – E-mail address
tour_group[price_option][x][field]
Passenger info for x-th price option passenger (these could be required/optional depending on form field settings for the item) – these fields should not be shown if group is set to hide (in the item info)
tour_group[price_option][x][forms][form_field]
Form info for x-th price option passenger for form field named form_field (these could be required/optional depending on form field settings for the item) – these are presented to each passenger
tour_forms[form_field]
Form info for group (shown only once per booking, when the form is set to show=primary)
agree_terms this must be set to 1 to confirm that the user has agreed to the terms
Copyright ©200827 of 39
Sentias Software Corp. Rezgo XML API
Query response:
This is an example of a successful booking
<response><message>Booking complete</message><trans_num>1B4M7R2K1K</trans_num><txid>1</txid><analytics_convert>... HTML/Javascript Analytics Code ...</analytics_convert>
</response>
This is an example of a booking with a payment declined problem, such as an invalid credit card
<response><message>payment declined by gateway</message>
</response>
Commit response definition:
The returned data corresponds to the result of the commit query attempt at creating a booking.
XML Tag Description of contents
message
the status of the booking{Booking complete: booking is successful,payment declined by gateway: error with gateway transaction,Fatal error: error description: error in booking and description of problem}
trans_num transaction reference number
txid the transaction IDanalytics_convert
HTML/Javascript code for booking conversion tracking (or transaction analytics) (returned only if set in backend)
Copyright ©200828 of 39
Sentias Software Corp. Rezgo XML API
i=search_bookings
The search_booking query returns transaction information matching the passed transaction code. This query has one required argument q=(transaction code) in order to find the transaction to be returned. The transaction code pattern match is set to q=1B4M7R2K1K in the following example.
Required arguments:1) q : transaction code – code of transaction to search for
Example query
http://xml.rezgo.com/xml?key=REZGO_API_KEY&transcode=1&i=search_bookings&q=1B4M7R2K1K
Query response:
This is an example of a booking retrieval for a transaction code that is not in the system
<response><total>0</total>
</response>
This is an example of a successful booking retrieval
<response><total>1</total>
<item_id>1663</item_id><tour_name>Test Tour</tour_name><option_name>Morning Departure</option_name><date>1210057200</date><date_range>1210057200</date_range><date_purchased>1209757083</date_purchased>
<prices><price_adult>25</price_adult>
</prices><adult_num>2</adult_num><child_num>0</child_num><senior_num>0</senior_num><price4_num></price4_num><price5_num></price5_num><price6_num></price6_num><price7_num></price7_num><price8_num></price8_num><price9_num></price9_num>
<adult_label><![CDATA[Adult]]></adult_label><child_label><![CDATA[Child]]></child_label><senior_label><![CDATA[Senior]]></senior_label><price4_label><![CDATA[Price 4]]></price4_label><price5_label><![CDATA[Price 5]]></price5_label>
Copyright ©200829 of 39
Sentias Software Corp. Rezgo XML API
<price6_label><![CDATA[Price 6]]></price6_label><price7_label><![CDATA[Price 7]]></price7_label><price8_label><![CDATA[Price 8]]></price8_label><price9_label><![CDATA[Price 9]]></price9_label>
<fees>12%</fees>
<triggered_fees><total_triggered_fees>1</total_triggered_fees><triggered_fee_1>
<label><![CDATA[Deluxe Dinner]]></label><amount>+20</amount><total_amount>40</total_amount>
</triggered_fee_1></triggered_fees>
<first_name><![CDATA[John]]></first_name><last_name><![CDATA[Smith]]></last_name><address_1><![CDATA[1234 Sesame Street]]></address_1><address_2><![CDATA[]]></address_2><city><![CDATA[Vancouver]]></city><stateprov><![CDATA[BC]]></stateprov><country>ca</country><postal_code>A1A2B2</postal_code><phone_number>(123)456-7890</phone_number><email_address>[email protected]</email_address>
<adult_1><first_name>Elmo</first_name><last_name>E</last_name><phone_number></phone_number><email_address></email_address><total_forms>1</total_forms><form_1>
<type>checkbox</type><question><![CDATA[Deluxe Dinner]]></question><answer><![CDATA[on]]></answer>
</form_1></adult_1><adult_2>
<first_name>Big</first_name><last_name>Bird</last_name><phone_number></phone_number><email_address></email_address><total_forms>1</total_forms><form_1>
<type>checkbox</type><question><![CDATA[Deluxe Dinner]]></question><answer><![CDATA[on]]></answer>
</form_1></adult_2>
<price_range><![CDATA[price_adult, price_child, price_senior, price4, price5, price6, price7, price8, price9]]></price_range><date value="2008-05-06">
<price_adult>25</price_adult><price_child></price_child>
Copyright ©200830 of 39
Sentias Software Corp. Rezgo XML API
<price_senior></price_senior><price4></price4><price5></price5><price6></price6><price7></price7><price8></price8><price9></price9>
</date>
<tax_calc>6</tax_calc><overall_total>96</overall_total><trigger_code></trigger_code><payment_method><![CDATA[PayPal]]></payment_method><status>Payment Pending</status><checkin_status></checkin_status><ticketing>0</ticketing><trans_num>1B4M7R2K1K</trans_num><class>tour</class>
<primary_forms><total_forms>2</total_forms><form_1>
<type>text</type><question><![CDATA[Special requests]]></question><answer><![CDATA[Can you tell me how to get to Sesame
Street? ]]></answer></form_1>
</primary_forms>
</response>
Search_bookings response definition:
The returned data corresponds to the result of the search_bookings query retrieving booking information
XML Tag Description of contents
total returns 1 if transaction is found, else returns 0
item_id the item uid
date UNIX timestamp of item booking date
date_range UNIX timestamp of item booking date
date_purchased UNIX timestamp of date when booking was made
pricesXML node of prices agreed upon for the booking – refer to prices node definition
adult_num number of spots booked for adult
child_num number of spots booked for child
senior_num number of spots booked for seniorsprice4_num – price9_num
number of spots booked for {price4 – price9}
adult_label label for adult price option
Copyright ©200831 of 39
Sentias Software Corp. Rezgo XML API
child_label label for child price option
senior_label label for senior price optionprice4_label – price9_label
label for (price4 – price9) price option
fees tax percentage charged on booking
triggered_feesXML node of triggerable fees/prices agreed upon for the booking – refer to triggered_fees node definition
first_name Billing info - First name
last_name Billing info - Last name
address_1 Billing info – Address
address_2 Billing info – Address 2 (Optional)
city Billing info – City
stateprov Billing info – State/Province
country Billing info – Country
postal_code Billing info – Postal Code
phone_number Billing info – Phone Number
email_address Billing info – E-mail address
price_option_xthe passenger information for the x-th price_option passenger (ie. adult_1, adult_2, child_1, etc.) – refer to the passenger node definition
price_range list of price options
dateXML node of prices for the day in the value attribute(in Y-m-d format) – refer to date node definition
tax_calc total amount of tax cost after calculation
overall_total total cost of booking
deposit amount of deposit; only shown if deposits are required
trigger_codetrigger/coupon code used with this booking; only shown if a trigger code is submitted
payment_method
payment method used {PayPal}
card_type type of credit card used; only used if paid with credit card
card_name name on credit card used; only used if paid with credit card
card_number number on credit card used; only used if paid with credit card
status status of payment {Payment Pending}
trans_numtransaction code / transaction number of this booking (alphanumeric characters)
class type of item {tour}
primary_formsgroup forms, these forms are only filled once for each booking – refer to Passenger/Group form node definition
Prices node definition:
XML Tag Description of contents
Copyright ©200832 of 39
Sentias Software Corp. Rezgo XML API
price_adult cost for adult price option
price_child cost for child price option
price_senior cost for senior price option
price4 - price9 cost for (price4 – price9) price option
Copyright ©200833 of 39
Sentias Software Corp. Rezgo XML API
Triggered_fees/Triggered_fee node definition:
XML Tag Description of contentstotal_triggered_fees
total number of triggered fees for item
triggered_fee_x x-th triggered fee node, refer to following lines for node definition
label name of triggerable fee
amount cost for each instance this fee is triggered
total_amount total amount of cost that this fee has triggered
Passenger node definition:
XML Tag Description of contents
first_name passenger info - first name
last_name passenger info - last name
phone_number passenger info – phone number
email_address passenger info – e-mail address
total_forms total number of forms attached to this passenger
form_xx-th form attached to this passenger, refer to passenger/group form node definition
Passenger/Group form node definition:
XML Tag Description of contents
form_x x-th form attached to this passenger/group
total_forms total number of forms for this group
type input type {checkbox, select, textbox, …}
question question text
answer selected/entered response value {on}
Date node definition:
XML Tag Description of contents
price_adult cost for adult price option
price_child cost for child price option
price_senior cost for senior price option
price4 - price9 cost for (price4 – price9) price option
Copyright ©200834 of 39
Sentias Software Corp. Rezgo XML API
i=region_list
The region_list query returns a list of regions accepted by the filter set by the supplier/vendor corresponding to the transcode. This query does not need any additional arguments.
Example query:
http://xml.rezgo.com/xml?key=REZGO_API_KEY&transcode=p4&i=region_list
Query response:
This is an example of a returned region list (of region codes)
<response><countries total="181" all="1">
<country>CF</country><country>AL</country><country>AS</country><country>AD</country><country>AI</country><country>AG</country><country>AR</country><country>AM</country><country>AW</country>
...</countries>
</response>
Region_list response definition:
The returned data corresponds to the result of the region_list query retrieving a list of regions that are being accepted by the vendor’s filter
XML Tag Description of contents
countriesXML node of returned countries, attributes of total contain a count of the number of returned countries, and all is set to 1 if all the countries are being returned
country country code
state_provincesXML node of returned states/provinces, attributes of total contain a count of the number of returned states/provinces, and all is set to 1 if all the states/provinces are being returned
state_province state/province code
citiesXML node of returned cities, attributes of total contain a count of the number of returned cities, and all is set to 1 if all the cities are being returned
city city name
Copyright ©200835 of 39
Sentias Software Corp. Rezgo XML API
Copyright ©200836 of 39
Sentias Software Corp. Rezgo XML API
Instructions (Portals only)
The instructions in this section are meant for vendors only. As such, the transcode must start with a p or these instructions will not respond accordingly. Please note that the queries to the vendor gateway uses the same gateway at http://xml.rezgo.com/xml?
The following examples will use the following settings:Transcode of p4 : transcode=p4 (required)
i=classification_list
The classification_list query returns a list of item classifications accepted by the filter set by the vendor corresponding to the transcode. This query does not need any additional arguments.
Example query:
http://xml.rezgo.com/xml?key=REZGO_API_KEY&transcode=p4&i=classification_list
Query response:
This is an example of a returned classification list
<response><classifications total="71" all="1">
<classification>Adventure Tours</classification><classification>Aerial Tours</classification><classification>Attraction</classification><classification>Biking</classification><classification>Bike Tours</classification><classification>Birding / Bird Watching</classification><classification>Boating</classification>...
</classifications></response>
Classification_list response definition:
The returned data corresponds to the result of the classification_list query retrieving a list of classifications that are being accepted by the vendor’s filter
XML Tag Description of contents
classificationsXML node of returned classifications, attributes of total contain a count of the number of returned classifications, and all is set to 1 if all the classifications are being returned
classification classification title
Copyright ©200837 of 39
Sentias Software Corp. Rezgo XML API
i=modify_bookings
The modify_bookings query is used to cancel valid bookings that have not been checked in yet. This query cancels one booking which relates to the corresponding cancel code AND voucher code. This query has three required arguments, the cancel action, cancellation code, and the voucher code. The cancellation and voucher codes will be unique to each transaction and must match in order for the cancellation to be successfully processed.
Required arguments:1) a: action – action (a=cancel)2) cancel_code : cancellation code – cancellation code of transaction (found in
i=search_bookings response)3) q: voucher code – voucher code (found on voucher page)
Example query:
http://xml.rezgo.com/xml?key=REZGO_API_KEY&transcode=p4&i=modify_bookings&a=cancel&q=ABC123&cancel_code=CANCEL123
Query response:
This is an example of a returned successful cancellation
<response><message>Cancellation complete</message><cancel_amount>20.25</cancel_amount>
</response>
This is an example of a returned failed cancellation
<response><message>Instruction invalid for this transit code.</message>
</response>
This is an example of a failed cancellation because of an invalid booking
<response><message>Booking not found.</message>
</response>
Copyright ©200838 of 39
Sentias Software Corp. Rezgo XML API
Modify_bookings/cancellation response definition:
The returned data corresponds to the result of the classification_list query retrieving a list of classifications that are being accepted by the vendor’s filter
XML Tag Description of contents
message text message that describes the result of the cancellation query
cancel_amount amount of money that is successfully returned on the cancellation
Copyright ©200839 of 39