Rezgo XML API Reference

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


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



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.



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.



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>



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



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.


intro HTML-formatted introduction text

about HTML-formatted about text



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.


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



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.


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



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:


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



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



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



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



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*



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:


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



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



Search_items response definition:

The returned data corresponds to the information for matching tours of the company with the given transcode.


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



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



Date node definition:


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:


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:


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



Schedule node definition:


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:


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:


image contains the filename of the image included in the value attribute

Video_gallery node definition:


videocontains the filename of the original video included in the value attribute

caption caption for image

image filename of the video thumbnail image



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>


<uid>7</uid><name><![CDATA[0130-0445]]></name>


<uid>8</uid><name><![CDATA[sup & name]]></name>

</item>Copyright ©200821 of 39


<item value="25"><uid>9</uid><name><![CDATA[test1234]]></name>


<uid>10</uid><name><![CDATA[test2222222]]></name>


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

</response>



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>












<uid>11</uid>



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

</response>



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.


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:


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:


uid tour option sku

name tour option name



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



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



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.


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)



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>

This is an example of a successful booking retrieval


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



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



<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


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



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:










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:


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:


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:








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


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





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


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



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>



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


message text message that describes the result of the cancellation query

cancel_amount amount of money that is successfully returned on the cancellation


Documents

Rezgo XML API Reference