home > support > API > Marketplace API > API: tour information

Show Tour

Return full information about a specific Tour.

Caching

If you are calling the API directly from your website (i.e. rather than populating your own database with tour data) we would recommend caching this API for around an hour. This helps you keep within API limits and to keep your site running fast. More on API caching.

REST info

Call/c/tour/show
FormatsXML
Example/c/tour/show.xml?id=92
VerbGET

Code

PHP examples use the PHP Client Library with SimpleXML

Description

object show_tour ( int $tour, int $channel [ , string $querystring = "" ] )


Parameters

$tour
ID for the Tour
$channel
ID for the Channel (Operator) - required as Tour IDs are not unique
$querystring
See table below


Example

// ID for the Tour we want the details for
$tour = 152;

// Channel (Operator) ID of the Tour
$channel = 6;

// Query the TourCMS API
$result = $tourcms->show_tour($tour, $channel);

// Go straight to the tour node
$tour = $result->tour;

// Print out the tour name and lead in price
print $tour->tour_name.' - from only '.$tour->from_price_display;
Nile Family Adventure - from only £650

C# examples use the .Net Client Library

Overload list

XmlDocument ShowTour (int tourId, int channelId)
XmlDocument ShowTour (int tourId, int channelId, string queryString)


Parameters

tourId
ID for the Tour
channelId
ID for the Channel (Operator) - required as Tour IDs are not unique
queryString
See table below


Example

// ID for the Tour we want the details for
int tourId = 152;

// Channel (Operator) ID of the Tour
int channelId = 6;

// Query the TourCMS API
XmlDocument doc = myTourCMS.ShowTour(tourId, channeId);

// Display the tour name and lead in price
string tourName = doc.SelectSingleNode("//tour/tour_name").innerText;
string tourPrice =
			doc.SelectSingleNode("//tour/from_price_display").innerText;

Console.WriteLine(tourName + " - from only " + tourPrice);
Nile Family Adventure - from only £650

VB examples use the .Net Client Library

Overload list

XmlDocument ShowTour (Integer TourId, Integer ChannelId)
XmlDocument ShowTour (Integer TourId, Integer ChannelId, String QueryString)


Parameters

TourId
ID for the Tour
ChannelId
ID for the Channel (Operator) - required as Tour IDs are not unique
QueryString
See table below


Example

' ID for the Tour we want the details for
Dim tourId As Integer = 152

' Channel (Operator) ID of the Tour
Dim channelId As Integer = 6

' Query the TourCMS API
Dim doc As XmlDocument = myTourCMS.ShowTour(tourId, channeId)

' Display the tour name and lead in price
Dim tourName As String = doc.SelectSingleNode("//tour/tour_name").innerText
Dim tourPrice As String =
		doc.SelectSingleNode("//tour/from_price_display").innerText

Console.WriteLine(tourName & " - from only " & tourPrice)
Nile Family Adventure - from only £650

NodeJS examples use the NodeJS Wrapper


Example

// Show Tour with ID 1 on Channel 3930
TourCMS.showTour({
channelId: 3930,
  tourId: 1,
  callback: function(response) {
    console.log(response.tour.tour_name_long);
  }
});
Knoydart Peninsula Walking Adventure

Looking for sample code in a different language? TourCMS and community provided API libraries


Querystring parameters

Querystring parameters
ParameterNotes
idTour ID. If using a wrapper library this will be passed as a separate argument.
show_optionsSet to 1 if you would like TourCMS to return information on the Options (ancillary items / upgrades) available for booking via the API on this Tour
show_offersSet to 1 if you would like TourCMS to return information on the soonest and most recently loaded special offer for this tour (if any), essentially the same data as returned for each tour in Tour Search API. A full list of offers for a particular tour can be obtained via the Dates and deals API.
orderAny alternative tours returned (see alternative_tours section below) can be ordered using the same values as the Tour Search API


The Channel ID is also passed via the request header, this is required as Tour IDs are unique within a particular channel (Operator) rather than being unique system wide.

Response fields

Response fields
NodeNotes
request Confirmation of the request that you sent
error Any error message returned, if there is no error this will just contain the text OK
tour

The tour node contains the following child nodes.

NodeNotes
channel_idChannel ID
account_idAccount ID
tour_idTour ID
tour_name Tour name - Short (Max. 50 characters)
tour_name_long Tour name - Long (Max. 100 characters)
start_timeStart time for the Tour
 
May be a 24 hour time value in local time (e.g. "09:00").
 
If there are multiple start times per day or the start time varies by day then the value will be "MULTI"
end_timeEnd time for the Tour/Hotel.
 
Possible values as per start_time above.
has_sale1 - Future product on sale
0 - No future product on sale
has_d1 - Has a tour departure loaded
0 - No tour departure loaded
has_f1 - Has a tour freesale loaded
0 - No tour freesale loaded
has_h1 - Has a hotel product type loaded
0 - No hotel product type loaded
created_dateWhen the tour was created, date format YYYY-MM-DD
descriptions_last_updatedWhen the tour text descriptions were last updated, date format YYYY-MM-DD
next_bookable_dateFirst date the tour is bookable, date format YYYY-MM-DD
last_bookable_dateLast date the tour is bookable, date format YYYY-MM-DD
has_sale_jan
has_sale_feb
has_sale_mar
has_sale_apr
has_sale_may
has_sale_jun
has_sale_jul
has_sale_aug
has_sale_sep
has_sale_oct
has_sale_nov
has_sale_dec
1 - Future product on sale (by the month)
0 - No future product on sale (by the month
quantity_ruleWhether the prices loaded in the system are multiplied by the quantity booked.
 
For example 2 adults booking a tour with a price of $99 might come to $198 if the quantity_rule is "q" or $99 if the quantity_rule is "1". Generally speaking you don't need to worry about this as you will be given the full calculated price for the group when you call Check availability.
 
1 - price x 1 (for group pricing)
q - price x quantity (per person pricing)
tour_codeTour code (only returned if set)
from_priceLead in price
from_price_displayLead in price - display version (Includes HTML entity currency code and no decimals)
from_price_jan
from_price_feb
from_price_mar
from_price_apr
from_price_may
from_price_jun
from_price_jul
from_price_aug
from_price_sep
from_price_oct
from_price_nov
from_price_dec
Lead in price by the month
Use to create a nice seasonal price chart

There are also _display versions that work the same way as from_price_display
from_price_unitLead in price unit

0 - per person (default)
1 - per couple
2 - per vehicle
3 - per room

This field is for display purposes only e.g. to show, next to a lead in price, what the price relates to
sale_currencySale currency (for the lead in price). Currency is set by channel
priorityHIGH, MEDIUM, LOW - Commercial priority
addressPostal address
geocode_startLat,Long geocode for start point
geocode_endLat,Long geocode for end point
geocode_midpoints

If any midpoints are configured then an geocode_midpoints node will be returned. Could be showing a tour route map, or in the case of hop on / hop off tours it show bus stops. Contains:

XML NodeNotes
midpoint

There will be a midpoint node for each midpoint (tour route map, hop on / hop off point etc) on this Tour

XML NodeNotes
geocodelat,lng geocode point
labelText label for the point (e.g. a place or building name)
can_start_end_here Where the customer can start/end the Tour/Itinerary at this point.
 
0 = No (could just be a tour map calling point)
1 = Yes (could be a hop on / hop off bus stop)
pickup_on_request 1 - Customer can provide a freetext pickup point
0 - Customer cannot provide a freetext pickup point
 
Regardless of the setting here, there may be a predefined list of available pickup points in the pickup_points node.
pickup_on_request_key If this tour supports pickups on request, this will contain the key to provide to Start New Booking to select pickup on request. Also returned as part of Check Availability.
pickup_points

If any pickup points are configured then a pickup_points node will be returned containing:

XML NodeNotes
pickup

A pickup node for each pickup point for this Tour (ordered by pickup_name) containing the items listed below.
 
Please note that this is an overall list of the pickup points available on the tour.
 
As the list of pickup points offered and the times of those pickups can vary by departure the actual selection including any times can be presented to the customer when they check availability for a specific date.

XML NodeNotes
pickup_nameText name for the point (e.g. a hotel or bus stop)
 
This is the only mandatory field.
description Any extra information for the client, e.g. "Meet in the reception lounge"
address1 First line of the address
address2 Second line of the address
postcode Postcode
geocode Lat,Lng geographic point
documents

If any documents are uploaded then a documents node will be returned containing:

XML NodeNotes
document

A document node for each document for this Tour, containing:

XML NodeNotes
document_descriptionDescription for an uploaded document related to the Tour.
E.g. could be "Route map" or "Transfer Zones".
document_urlURL for an uploaded document
grade 1 - All ages / Not applicable
2 - Moderate
3 - Fit
4 - Challenging
5 - Extreme
accomrating 1 - No accommodation / Not applicable
2 - Luxury
3 - Moderate
4 - Comfortable
5 - Basic
6 - Various levels
product_type 1 - Accommodation (hotel/campsite/villa/ski chalet/lodge)
2 - Transport/Transfer
3 - Tour/cruise including overnight stay
4 - Day tour/trip/activity/attraction (No overnight stay)
5 - Tailor made
6 - Event
7 - Training/education
8 - Other
9 - Restaurant / Meal alternative
 

In the case of "2" (Transport/Transfer) there will be an attribute on the XML element indicating the direction of travel.
 
0 - Other / not set
1 - Airport to City
2 - City to Airport
3 - Two way return
 
E.g. for a return transfer <product_type direction="3">2<product_type>

Also there may be an airport code
E.g. for London Gatwick <product_type direction="3" airport_code="LGW">2<product_type>
tourleader_type 1 - Tour guide / driver
2 - Independent / self drive
3 - Not applicable (e.g. accommodation / event)
suitable_for_solo ¶Tour is suitable for solo travellers (1 - Yes, 0 - No)
suitable_for_couples ¶Tour is suitable for couples (1 - Yes, 0 - No)
suitable_for_children ¶Tour is suitable for children (1 - Yes, 0 - No)
suitable_for_groups ¶Tour is suitable for groups (1 - Yes, 0 - No)
suitable_for_students ¶Tour is suitable for students (1 - Yes, 0 - No)
suitable_for_business ¶Tour is suitable as a business trip extension for business travellers (1 - Yes, 0 - No)
suitable_for_wheelchairs ¶Tour is suitable for wheelchair users (1 - Yes, 0 - No)
 
The seven suitable_for_ fields are new to TourCMS and may not be fully populated by all Channels (Tour Operators) yet. They will be made mandatory shortly.
languages_spokenLanguages spoken on the tour. Comma separated list. E.g. "en,pt" for English & Portuguese. Quite likely to be blank on many tours at the moment as this is a relatively new field.
locationPrimary location - Perhaps a city name, national park name or region
summarySummary - Includes primary activity if not clear from tour name
countryList of countries the tour takes place - 2 digit ISO code format, comma separated. The order is NOT the order the tour goes to the listed countries
durationDuration (Days)
 
Automatically calculated based on the dates and prices loaded
duration_descText description for duration (e.g. 1 week)
 
Free text field edited by tour operator staff users. Human readable but not necessarily consistent across accounts.
availableText description for when available (e.g. March to September)
shortdescShort description (NO HTML)
longdescLong description
itineraryItinerary
expRather than facts, this description should focus on the experience e.g. a wonderful hill walk with great vistas
pickHotel pickup instructions
redeemVoucher redemption instructions
incIncluded
exExcluded
essentialEssential information - What to bring, accommodation details, single supplements, solo travellers
extrasExtras / upgrades
restRestrictions - e.g. Pets, minimum age / children permitted, whether requires a preexisting skill etc
tour_urlURL for the tour detail page
tour_url_trackedURL for the tour detail page - via agent tracking mechanism
Not returned for /c/tours/search
book_urlURL to booking engine / live availability display (can be iframed onto your site)
 
It is possible to disable the standard booking engine, so on some accounts this may be blank.
images

The images node will contain between 1 and 6 image nodes.

NodeNotes
image

The first image node will contain a thumbnail attribute with the value true, this indicates that it is the image that would likely have been used if the Tour was viewed in a list along side other Tours; to maintain consistency you may wish to ensure this image is displayed first / most prominently.

Each image node contains a url node and image_desc node, it may also contain other url_ nodes for alternative image sizes, as detailed below. The default url is the only size that is guaranteed, other sizes will be returned if the original uploaded image was sufficiently large.

NodeNotes
url_thumbnail URL (web address) for thumbnail image size (max 342 pixels wide)
url URL (web address) for the default image size (max 800 pixels wide)
url_large URL (web address) for large image size (max 1500 pixels wide)
url_xlarge URL (web address) for extra large image size (max 1920 pixels wide)
image_desc Description / caption for image
videos

The videos node will contain a video node for any videos that are associated with the tour (currently only 1 video can be associated with each tour).

NodeNotes
video

There will be a video node for each video associated with the tour, containing:

XML NodeNotes
video_service Video service used to host the video. Currently will be either vimeo or youtube.
 
If embedding use this combined with the video_id to determine if/how to embed the video. Or use this handy PHP script.
video_id Service-specific ID for the video (if any)
video_url URL to a web page containing the video
min_booking_sizeThe minimum (num people/quantity) required per booking this tour.
 
Individual dates may have a higher minimum booking size, for example last minute dates may require a certain minimum for the tour to depart.
max_booking_sizeThe maximum (num people/quantity) allowed per booking on this tour.
 
Individual dates may have a lower maximum booking size, for example if there are only a few spaces remaining. The spaces remaining on a certain date are returned in the dates and deals API.
new_booking

Information to help those building their own booking engine using the API. Includes data that might be useful if designing a booking form:

NodeNotes
people_selection

Information on the various rates (pricing tiers) offered, including min/max numbers of people

NodeNotes
rate

There will be a rate node for each individual pricing tier offered on this Tour containing:

NodeNotes
rate_id Identifier for the rate
label_1 Main customer facing descriptor for this rate, e.g. "Adults".
 
May be blank in which case display text such as "Number of people"
label_2 Secondary customer facing descriptor for this rate, e.g. "(16plus)"
minimum Minimum number of people per booking on this rate
maximum Maximum number of people per booking on this rate
agecat Age category (s-senior, a-adult, y-youth, c-child, i-infant)
agerange_min
agerange_max
Years. If blank, first check agecat, secondly assume is adult
from_price Lead in price for the rate
from_price_display Display version of the lead in price, includes currency information
rate_code Tour operators only. Additional field for cross sytem mapping
date_selection

Information on how dates & durations are calculated for this Tour, useful for determining how to present date / duration selection.

NodeNotes
date_type - DATE
Tour type availability
 
- DATE_DAYS
Hotel type availability, duration in days
 
- DATE_NIGHTS
Hotel type availability, duration in days
duration_minimum The minimum duration that must be booked for this Tour. Only shows if date_type is either DATE_DAYS or DATE_NIGHTS.
duration_maximum The maximum duration that must be booked for this Tour. Only shows if date_type is either DATE_DAYS or DATE_NIGHTS.
alternative_tours

Tours from the same Channel that the Operator has indicated as alternatives to the main Tour being shown (if any exist - max 10).

NodeNotes
tour

There will be a tour node for each alternative tour returned (max 10), containing:

NodeNotes
tour_id Tour ID
tour_name Tour name - Short
(Max. 50 characters)
tour_name_long Tour name - Long
(Max. 100 characters)
tour_code Tour code (only returned if set)
location Primary location - Perhaps a city name, national park name or region
tour_urlURL for the tour detail page
tour_url_trackedURL for the tour detail page - via agent tracking mechanism
Not returned for /c/tours/search
book_urlURL to booking engine / live availability display (can be iframed onto your site)
from_priceLead in price
from_price_displayLead in price - display version (Includes HTML entity currency code and no decimals)
thumbnail_imageURL for thumbnail image. Will be based on the first image for the Tour, resized to maximum 342 pixels wide.
product_type Product type (see notes above for field explanation)
options

NB: Options are only returned if show_options=1 is passed to this API method (see "Querystring parameters" above)
 
If any options (ancillary items) are configured then an options node will be returned containing:

XML NodeNotes
option

There will be an option node for each option configured on the Tour matching the following criteria:
- Set to "Public"
- Don't require any "Answers"
- Not mandatory / must include, options
- Must have a future bookable date on sale

XML NodeNotes
option_idOption ID
option_nameOption name
short_descriptionShort description (HTML tags removed)
from_price Lead in price for the Option
from_price_display Display version of the lead in price, includes currency information
group ID number for the group that the Option belongs to (see below)
group_title Title for the group that the Option belongs to. E.g. "General", "Attractions", "Upgrades"
soonest_special_offer

NB: Special offers are only returned if show_offers=1 is passed to this API method (see "Querystring parameters" above)
 
If any special offers / deals are loaded for this Tour then a soonest_special_offer node will be returned containing the soonest (i.e. closest to start/departure date) special offer via the below child nodes. If you are ordering the results by offer_soonest then this is probably the offer you want to display.

XML NodeNotes
start_dateStart date for this date
end_dateEnd date for this date
start_timeStart time for the Tour on this particular offer in 24 hour local time format (e.g. "09:00").
 
If the start time is not known or is irrelevant for the item type then this field will be blank
end_timeEnd time for the Tour on this particular offer in 24 hour local time format (e.g. "17:00").
 
If the start time is not known or is irrelevant for the item type then this field will be blank
date_codeThis is the "Departure code" from a Tour Operators perspective, may be empty
noteProduct note
min_booking_sizeMinimum number of people required per booking, e.g. 1
spaces_remainingNumber of people that can still book for this date. Generally numeric however could contain the text UNLIMITED
special_offer_typeType of special offer / deal on this date
 
1 - Date specific special price
2 - Late booking discount
3 - Early booking discount
4 - Duration specific discount
price_1Price for 1 person. E.g 100.00
price_1_displayDisplay version of the price for 1 person including currency symbol / code. E.g €100.00
price_2Price for 2 people. E.g. 180.00 (It can often be cheaper and so preferable to show a per person price based on the price for 2 people sharing).
price_2_displayDisplay version of the price for 2 people including currency symbol / code. E.g €180.00 (It can often be cheaper and so preferable to show a per person price based on the price for 2 people sharing).
special_offer_datetimeDate and tine the special offer was created. Format YYYY-MM-DD HH:MM:SS
special_offer_noteText note on the special offer, e.g. "20% off early bookings"
original_price_1The original price for 1 person (before the discount was applied). E.g. 120.00
original_price_1_displayDisplay version of the original price for 1 person (before the discount was applied). Includes currency symbol / code. E.g. €120.00
original_price_2The original price for 2 people (before the discount was applied). E.g. 200.00
original_price_2_displayDisplay version of the original price for 2 people (before the discount was applied). Includes currency symbol / code. E.g. €200.00
recent_special_offer

NB: Special offers are only returned if show_offers=1 is passed to this API method (see "Querystring parameters" above)
 
If any special offers / deals are loaded for this Tour then a recent_special_offer node will be returned featuring the most recently created special offer via the below child nodes. If you are ordering the results by offer_recent then this is probably the offer you want to display.

XML NodeNotes
start_dateStart date for this date
end_dateEnd date for this date
start_timeStart time for the Tour on this particular offer in 24 hour local time format (e.g. "09:00").
 
If the start time is not known or is irrelevant for the item type then this field will be blank
end_timeEnd time for the Tour on this particular offer in 24 hour local time format (e.g. "17:00").
 
If the start time is not known or is irrelevant for the item type then this field will be blank
date_codeThis is the "Departure code" from a Tour Operators perspective, may be empty
noteProduct note
min_booking_sizeMinimum number of people required per booking, e.g. 1
spaces_remainingNumber of people that can still book for this date. Generally numeric however could contain the text UNLIMITED
special_offer_typeType of special offer / deal on this date
 
1 - Date specific special price
2 - Late booking discount
3 - Early booking discount
4 - Duration specific discount
price_1Price for 1 person. E.g 100.00
price_1_displayDisplay version of the price for 1 person including currency symbol / code. E.g €100.00
price_2Price for 2 people. E.g. 180.00 (It can often be cheaper and so preferable to show a per person price based on the price for 2 people sharing).
price_2_displayDisplay version of the price for 2 people including currency symbol / code. E.g €180.00 (It can often be cheaper and so preferable to show a per person price based on the price for 2 people sharing).
special_offer_datetimeDate and tine the special offer was created. Format YYYY-MM-DD HH:MM:SS
special_offer_noteText note on the special offer, e.g. "20% off early bookings"
original_price_1The original price for 1 person (before the discount was applied). E.g. 120.00
original_price_1_displayDisplay version of the original price for 1 person (before the discount was applied). Includes currency symbol / code. E.g. €120.00
original_price_2The original price for 2 people (before the discount was applied). E.g. 200.00
original_price_2_displayDisplay version of the original price for 2 people (before the discount was applied). Includes currency symbol / code. E.g. €200.00
If API called by Tour Operator (not Marketplace Agent)
supplier_idThe internal reference number for the supplier
supplier_tour_codeThe supplier set tour code. This field is ideal if you are syncronising TourCMS with an external reservation system as this could be the external reservation system tour ID.
staff_noteStaff notes
operational_noteDefault operational instructions
custom_fields

If any custom fields are configured then a custom_fields node will be returned containing the following:

XML NodeNotes
field

There will be a field node for each custom field, containing:

XML NodeNotes
nameCustom field name
valueValue for the custom field
categories

If any categories are configured then a categories node will be returned containing the following:

XML NodeNotes
group

There will be a group node for each grouping of values (e.g. "Activity type") containing:

XML NodeNotes
nameThe name for the group, e.g. "Activity type"
values

A values node containing:

XML NodeNotes
valueA value node for each value selected for this tour. For example "Rafting" or "Hiking".

Sample XML Response

/c/tour/show.xml?id=92

More information