API Documentation

» API Documentation

World Travel And Tours

API Documentation

  • Created: 03/10/2011
  • latest Update: 05/13/2011
  • By: Grant Norman

This is the documentation for the WTT API.

Form Construction

Form Construction Guidelines

The purchase process is initiated by having the user submit a form. This form should use the POST method and post the data to one of the following URLs:

  • http://worldtravelandtours.com/singlepage/checkout.php for a single-page check-out
  • http://worldtravelandtours.com/consumer/checkout.php for a multi-page check-out

The following fields are required:

  • AffiliateID: Your affiliate ID (6)
  • ProviderID: The provider ID of the desired tour
  • TourID: The tour ID of the desired tour
  • Date: The date of tour being booked. Please use the format YYYY-MM-DD

At least one of the following fields must be submitted and non-zero:

  • S1 - Seats for Price Class 1 desired
  • S2 - Seats for Price Class 2 desired
  • S3 - Seats for Price Class 3 desired
  • S4 - Seats for Price Class 4 desired
  • S5 - Seats for Price Class 5 desired

If the tour includes addons, you can set a field named AddonXXXX, where XXXX is the addon's ID Code (see API info) for each addon desired. Normally, you'd implement this by having a checkbox named AddonXXXX, but you may wish to "force" specific addons on specific purchase pages.

If the tour is set up to have multiple sessions, please present them in a dropdown or radio button and pass the chosen session's name in the variable Session.

The following field is optional:

  • SubaffiliateID - A freeform string you can provide. It will appear in the accounting logs next to your affiliate ID, so it can be used for tracking sales performance of this form versus others.

API Options

API Samples

All API calls are made by basic HTTP requests. The URL to request is

http://worldtravelandtours.com/api.php

Paramaters and calls are passed following the HTTP GET convention. We reccomend, for best reliability, passing them in a URL-friendly form (replacing spaces with %20, for example)

Each API call returns an XML document. Some fields may be packaged as a CDATA item, because they may include HTML, such as video or map embedding code, designed to be displayed unmodified.

Your affiliate ID is 6 and must be sent with all calls with the parameter name AffiliateID.

* TourTypeList

This call returns a list of all tour types. Useful for populating drop-down menus. It has no optional paramaters.

Example URL:

  • http://worldtravelandtours.com/api.php?AffiliateID=6&Call=TourTypeList - All tours you can sell.

Output Format:

<?xml version="1.0" encoding="UTF-8"?>
<results>
<ActivityType>FIRST ACTIVITY TYPE</ActivityType>
...
<ActivityType>LAST ACTIVITY TYPE</ActivityType>
</results>

 

* AllTours

This call returns the names of every tour you can sell. This can be valuable for setting up cross-sell relationships or accounting summaries.

Example URLs:

  • http://worldtravelandtours.com/api.php?AffiliateID=6&Call=AllTours - All tours you can sell.

Output Format:

<?xml version="1.0" encoding="UTF-8"?>
<results>
<tour>
<ProviderID>PROVIDER ID</ProviderID>
<TourID>TOUR ID</TourID>
<Name>TOUR NAME</Name>
</tour>
<tour>
<ProviderID>PROVIDER ID</ProviderID>
<TourID>TOUR ID</TourID>
<Name>TOUR NAME</Name>
</tour>
...
</results>

Notes:

  • This does not restrict you to tours currently available to book, or in your usual regions
  • The tours are grouped by the provider ID

* SearchTours

This call returns summary info for all tours matching a given set of restrictions. This is ALWAYS filtered to tours you're eligible to book, and with sessions in the future. By default, it is also constrained to regions you have selected through this control panel. You can add several optional paramaters to filter the results or limit the number returned:

  • AtHotel - Only show tours picked up at the given hotel ID. Ideal for a kiosk or custom website for a hotelier.
  • Region - Limit the search to a specific region. This overrides the "Default Regions" you configure in the control panel.
  • RegionList - Limit the search to a specific set of regions, seperated with a "|". This overrides the "Default Regions" you configure in the control panel.
  • ActivityType - Limit searches to a specific activity type.
  • ActivityTypeList - Limit searches to the list of activity types provided. Activities are seperated with a "|".
  • Text - Limit the search to only tours containing the given text in the name, brief blurb, or description.
  • ProviderID - Limit the search to only a specific provider ID.
  • TourID - Limit the search to a specific tour ID. Usually used with ProviderID
  • ExcludeTourID - Return tours except for those with that tour ID. This does not filter by ProviderID by itself. Again, usually used with ProviderID, to do a "Other Tours By This Company" list.
  • RejectTour - Given a tour ID in the form Provider-Tour, it will block only that tour. Generally used for an "Other tours in general" list
  •  
  • TourNoList - Restrict the search to only a list of specific provider and tour IDs. The format is as follows:

    ProviderID 1-Tour ID 1|Provider ID 2-Tour ID 2|...

    Example:
    sampletours-30|sampletours-30A|testcorp-150

    This is helpful for creating a list of very specific products, such as alternatives for a specific tour or upsell versions of the same event. It overrides "Limit" to show all specified products.
  • OrderRegions - Place tours in these regions to the top. Region list seperated by a "|".
  • OrderList - Specify a list of specific provider and tour IDs to appear first in the search results. Much like the tour number list, the format is as follows:

    ProviderID 1-Tour ID 1|Provider ID 2-Tour ID 2|...

    Example:
    acmecorp-1A|samplecorp-50|examplefirm-D3

    This custom sort order can be used to promote tours you have special interest in, without limiting other search.
  • Price - Return tours costing less than or equal to this amount
  • Base - Skip how many tours? Useful for showing "results 30-40"
  • Limit - Retrieve info on how many tours? Again, useful for showing results 10 at a time
  • Sort - Order your results in a certain way. The default is by Name, but you can specify
    • Price
    • Region
    • Provider
    • Random

Example URLs:

  • http://worldtravelandtours.com/api.php?AffiliateID=6&Call=SearchTours - All tours you can sell.
  • http://worldtravelandtours.com/api.php?AffiliateID=6&Call=SearchTours&OrderRegions=AZ-Phoenix|AZ-Grand%20Canyon - All tours you can sell, with Phoenix ones first, then Grand Canyon
  • http://worldtravelandtours.com/api.php?AffiliateID=6&Call=SearchTours&ActivityTypeList=Camping|Hiking|Rockclimbing - All Camping, Hiking, or Rockclimbing tours you can sell.
  • http://worldtravelandtours.com/api.php?AffiliateID=6&Call=SearchTours&Region=AZ-Phoenix - All tours in the AZ-Phoenix region you can sell
  • http://worldtravelandtours.com/api.php?AffiliateID=6&Call=SearchTours&ActivityType=Hiking&Price=75&Sort=Price - All Hiking Tours $75 or below you can book, cheapest first
  • http://worldtravelandtours.com/api.php?AffiliateID=6&Call=SearchTours&ProviderID=foocorp&ExcludeTourID=06&Base=10&Limit=5 - From the tours provided by the firm "foocorp" you can sell, except #06, skip the first 10, and list the next 5, giving items 11-15

Output Format:

<?xml version="1.0" encoding="UTF-8"?>
<results>
<total>TOTAL NUMBER OF MATCHING TOURS</total>

<tour>
<ProviderID>PROVIDER ID</ProviderID>
<TourID>TOUR ID</TourID>
<Name>TOUR NAME</Name>
<Region>REGION NAME</Region>
<ActivityType1>MAIN ACTIVITY TYPE</ActivityType1>
<ActivityType2>SECONDARY ACTIVITY TYPE</ActivityType2>
<ActivityType3>TERITARY ACTIVITY TYPE</ActivityType3>
<StartingPoint>MAIN DEPARTURE LOCATION</StartingPoint>
<Duration>DURATION</Duration>
<ApproximateTime>DEPARTURE TIME</ApproximateTime>
<Blurb>BRIEF SUMMARY</Blurb>
<PassengerType>PASSENGER TYPE THE SAMPLE PRICE APPLIES TO</PassengerType>
<Price>SAMPLE PRICE</Price>
<Photo>URL FOR A PHOTO REPRESENTING THE TOUR</Photo>
</tour>
...
<tour>
<ProviderID>PROVIDER ID</ProviderID>
<TourID>TOUR ID</TourID>
<Name>TOUR NAME</Name>
<Region>REGION NAME</Region>
<ActivityType1>MAIN ACTIVITY TYPE</ActivityType1>
<ActivityType2>SECONDARY ACTIVITY TYPE</ActivityType2>
<ActivityType3>TERITARY ACTIVITY TYPE</ActivityType3>
<StartingPoint>MAIN DEPARTURE LOCATION</StartingPoint>
<Duration>DURATION</Duration>
<ApproximateTime>DEPARTURE TIME</ApproximateTime>
<Blurb>BRIEF SUMMARY</Blurb>
<PassengerType>PASSENGER TYPE THE SAMPLE PRICE APPLIES TO</PassengerType>
<Price>SAMPLE PRICE</Price>
<Photo>URL FOR A PHOTO REPRESENTING THE TOUR</Photo>
</tour>

</results>

Notes:

  • Prices are in US Dollars
  • The "Total" field refers to the search query ignoring Base and Limit-- so you can know if you're seeing 1-10 of 10 results, or 1-10 of 500 results.
  • One tour element will be returned for each tour that matched the search.
  • If Base is defined, Limit will default to 10 unless specified. Otherwise, there's no limit unless you specify one.
  • In ordering results, OrderList is given priority over OrderRegions, which is given priority over the normal Sort selection.

* ProviderInfo

Returns basic contact information for a specific tour provider. You must pass the provider's ID in the paramater ProviderID. Example:

  • http://worldtravelandtours.com/api.php?AffiliateID=6&Call=ProviderInfo&ProviderID=testcorp - Get more info on the provider with ID "testcorp".

Output Format:

<?xml version="1.0" encoding="UTF-8"?>
<results>
<Name>COMPANY NAME</Name>
<Address>ADDRESS</Address>
<City>CITY</City>
<State>STATE</State>
<Country>COUNTRY</Country>
<Disclaimer><![CDATA[DISCLAIMER TEXT]]></Disclaimer>
</results>

Notes:

  • The Disclaimer is wrapped as CDATA because the tour operators may wish to include HTML, such as links to a more complete legal document or licensing info.

* TourInfo

Return the full information for a specific tour. You must pass the provider ID as ProviderID and the tour ID as TourID. Example:

  • http://worldtravelandtours.com/api.php?AffiliateID=6&Call=TourInfo&ProviderID=testcorp&TourID=100X - Get more info on "testcorp"'s tour "100X".

Output Format:

<?xml version="1.0" encoding="UTF-8"?>
<results>
<ProviderID>PROVIDER ID</ProviderID>
<TourID>TOUR ID</TourID>
<Title>TITLE</Title>
<Region>REGION</Region>
<Duration>TOUR DURATION</Duration>
<ApproximateTime>START TIME</ApproximateTime>
<Capacity>SEATING CAPACITY</Capacity>
<MKeywords><![CDATA[RECCOMENDED HTML META KEYWORDS VALUE]]></MKeywords>
<MDescription><![CDATA[RECCOMENDED HTML META DESCRIPTION VALUE]]></MDescription>
<MapEmbed><![CDATA[EMBEDDABLE HTML CODE FOR A MAP]]></MapEmbed>
<Description><![CDATA[FULL HTML DESCRIPTION]]></Description>
<Group1>PRICE GROUP 1 NAME</Group1>
<Group2>PRICE GROUP 2 NAME</Group2>
<Group3>PRICE GROUP 3 NAME</Group3>
<Group4>PRICE GROUP 4 NAME</Group4>
<Group5>PRICE GROUP 5 NAME</Group5>
<Price1>PRICE GROUP 1 PRICE</Price1>
<Price2>PRICE GROUP 2 PRICE</Price2>
<Price3>PRICE GROUP 3 PRICE</Price3>
<Price4>PRICE GROUP 4 PRICE</Price4>
<Price5>PRICE GROUP 5 PRICE</Price5>
<DisplayPrice1>PRICE GROUP 1 MSRP</DisplayPrice1>
<DisplayPrice2>PRICE GROUP 2 MSRP</DisplayPrice2>
<DisplayPrice3>PRICE GROUP 3 MSRP</DisplayPrice3>
<DisplayPrice4>PRICE GROUP 4 MSRP</DisplayPrice4>
<DisplayPrice5>PRICE GROUP 5 MSRP</DisplayPrice5>
<Photo>PHOTO URL</Photo>
<Commission1>PRICE GROUP 1 COMMISSION</Commission1>
<Commission2>PRICE GROUP 2 COMMISSION</Commission2>
<Commission3>PRICE GROUP 3 COMMISSION</Commission3>
<Commission4>PRICE GROUP 4 COMMISSION</Commission4>
<Commission5>PRICE GROUP 5 COMMISSION</Commission5>
</results>

Notes:

  • If a Price Group has a blank name, it is not supported for this specific tour. It is reccomended that you always use the group names provided by the API, because some tour operators may have their own rules for age or special-offer segmentation
  • Display of the MSRP info is optional

* Schedule

Retrieve a month's schedule for a given tour. Required parameters are the Tour ID (TourID) and ProviderID (ProviderID).

If you specify a Month or Year, it will override the default of current month and year.

If you select a tour that does not currently have any future dates scheduled, you will recieve an error message back: Examples:

  • http://worldtravelandtours.com/api.php?AffiliateID=6&Call=Schedule&ProviderID=testcorp&TourID=100X - Get this month's schedule for "testcorp"'s tour "100X".
  • http://worldtravelandtours.com/api.php?AffiliateID=6&Call=Schedule&ProviderID=testcorp&TourID=100X&Month=6&Year=2010 - Get the June, 2010 schedule for "testcorp"'s tour "100X".

Output Format:

<?xml version="1.0" encoding="UTF-8"?>
<results>

<date>
<number>DAY OF MONTH</number>
<available>AVAILABLE SEATS</available>
</date>
...
<date>
<number>DAY OF MONTH</number>
<available>AVAILABLE SEATS</available>
</date>

</results>

Notes:

  • Only dates where the tour is actually offered will be returned - one date element each
  • Valid, but sold-out dates will be represented by an "available" value of zero or less

* ExtraPhotos

Returns additional photos for use on the tour detail page. Requires a Provider ID (ProviderID) and a Tour ID (TourID). Example:

  • http://worldtravelandtours.com/api.php?AffiliateID=6&Call=ExtraPhotos&ProviderID=testcorp&TourID=100X - Get extra photos for "testcorp"'s tour "100X".

Output Format:

<?xml version="1.0" encoding="UTF-8"?>
<results>

<Photo>URL OF PHOTO</Photo>
...
<Photo>URL OF PHOTO</Photo>

</results>

Note:

  • There will be one Photo element for each additional photo, so there could be zero or more in total

* Videos

Returns video assets for a tour. Requires a Provider ID (ProviderID) and a Tour ID (TourID). Example:

  • http://worldtravelandtours.com/api.php?AffiliateID=6&Call=Videos&ProviderID=testcorp&TourID=100X - Get videos for "testcorp"'s tour "100X".

Output Format:

<?xml version="1.0" encoding="UTF-8"?>
<results>
<FLV>URL FOR FLV VIDEO FILE</FLV>
<EmbedCode><![CDATA[HTML CODE FOR EMBEDDING A VIDEO]]></EmbedCode>
</results>

Note:

  • The FLV and EmbedCode items will only appear if there is a video of the appropriate type.
  • FLV videos require a player built into your site
  • The EmbedCode may need processing to adjust the size or style to fit your site.

* Sessions

Some tour operators want to offer the same basic product with a choice of starting times. In this case, a session choice will be mandatory. You can retrieve the list of selections with this call. It takes the Provider ID (Provider ID) and Tour ID (TourID), and returns a list of session names. Example:

  • http://worldtravelandtours.com/api.php?AffiliateID=6&Call=Sessions&ProviderID=testcorp&TourID=100X - Get session list for "testcorp"'s tour "100X".

Output Format:

<?xml version="1.0" encoding="UTF-8"?>
<results>
<Session>TIME OR SESSION NAME</Session>
<Session>TIME OR SESSION NAME</Session>
...
</results>

Notes:

  • Some tours will not have multiple sessions. In this case, the call will return an error, or a blank session list. Either way, we reccomend showing the approximate time in that spot instead.
  • A tour with specific pickup times will not have multiple sessions

* AddOns

Tour operators can offer additional features to be sold alongside their tours. These are listed as "Addons". The "Addons" call returns pricing and detail information about available addons.

You must pass a Provider ID (ProviderID) and a Tour ID (TourID). Example:

  • http://worldtravelandtours.com/api.php?AffiliateID=6&Call=Addons&ProviderID=testcorp&TourID=100X - Get add-on products for "testcorp"'s tour "100X".

Output Format:

<?xml version="1.0" encoding="UTF-8"?>
<results>
<addon>
<AddonID>ADDON ID CODE</AddonID>
<Name>NAME</Name>
<Description><![CDATA[HTML DESCRIPTION]]></Description>
<Price1>PRICE FOR GROUP 1 PASSENGERS</Price1>
<Price2>PRICE FOR GROUP 2 PASSENGERS</Price2>
<Price3>PRICE FOR GROUP 3 PASSENGERS</Price3>
<Price4>PRICE FOR GROUP 4 PASSENGERS</Price4>
<Price5>PRICE FOR GROUP 5 PASSENGERS</Price5>
<PricePerOrder>PRICE FOR EACH ORDER</PricePerOrder>
</addon>
<addon>
<AddonID>ADDON ID CODE</AddonID>
<Name>NAME</Name>
<Description><![CDATA[HTML DESCRIPTION]]></Description>
<Price1>PRICE FOR GROUP 1 PASSENGERS</Price1>
<Price2>PRICE FOR GROUP 2 PASSENGERS</Price2>
<Price3>PRICE FOR GROUP 3 PASSENGERS</Price3>
<Price4>PRICE FOR GROUP 4 PASSENGERS</Price4>
<Price5>PRICE FOR GROUP 5 PASSENGERS</Price5>
<PricePerOrder>PRICE FOR EACH ORDER</PricePerOrder>
</addon>
...

</results>

Notes:

  • If the passenger group name is not defined in the TourInfo call, do not display the addon price for that group.
  • The "Price for each order" is added once, but the "Price for group X passenger" is added once per passenger in that group.