home > support > API > Marketplace API > API: tour dates and deals

Tour Dates and Deals

Retrieve dates and deals on a particular tour, good for populating a database or for live use on a website displaying a calendar control.


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 30 minutes. This helps you keep within API limits and to keep your site running fast. More on API caching.

REST info

Endpoint/c/tour/datesprices/datesndeals/search
FormatsXML
Example/c/tour/datesprices/datesndeals/search.xml?id=123
VerbGET

Code samples

PHP examples use the PHP Client Library with SimpleXML

Description

object show_tour_datesanddeals( int $tour, int $channel [, string $qs ] )


Parameters

$tour
ID for the Tour
$channel
ID for the channel this Tour belongs to
$qs
Query string, used to filter the results (see table below)

Example

// Set ID for the Tour we want dates for
$tour = 12345;

// Set the Channel ID this Tour belongs to
$channel = 3;

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

foreach($result->dates_and_prices->date as $date) {

		// Get and format the start date
		$start_date = strtotime($date->start_date);
		$start_date_display = date("jS F Y", $start_date);

		// Get and format the end date
		$end_date = strtotime($date->end_date);
		$end_date_display = date("jS F Y", $end_date);

		// Get the offer type, 0 = no offer (standard price
		// Numbers over zero indicate different offer types
		// (see table below)
		$offer_type = (int)$date->special_offer_type;

		// If we have a special offer, output was/now pricing
		// Otherwise just output the regular price
		if($offer_type>0) {
			print $start_date_display." to ".$end_date_display;
			print " <del>".$date->original_price_1_display."</del> ";
			print $date->price_1_display. " ** SPECIAL **<br>";
		} else {
			print $start_date_display." to ".$end_date_display." ";
			print $date->price_1_display."<br />";
		}
}
7th October 2011 to 14th October 2011 £1020<br>
14th October 2011 to 21st October 2011 <del>£1020</del> £820 ** SPECIAL **<br>
21st October 2011 to 28th October 2011 £1020<br>

C# examples use the .Net Client Library

Overload list

XmlDocument ShowTourDatesAndDeals (int tourId, int channelId)


Parameters

tourId
Id number for the Tour we want to get dates for
channelId
The channel the Tour belongs to

VB examples use the .Net Client Library

Overload list

XmlDocument ShowTourDatesAndDeals (Integer tourId, Integer channelId)


Parameters

tourId
Id number for the Tour we want to get dates for
channelId
The channel the Tour belongs to

NodeJS examples use the NodeJS Wrapper


Example

// Display the number of possible dates for Tour ID 1 on Channel 3930
TourCMS.showTourDatesDeals({
	channelId: 3930,
	tourId: 1,
	qs: {
	  has_offer: 1,
	  distinct_start_dates: 1
	},
	callback: function(response) {
	  console.log("Found " + response.dates_and_prices.date.length + " dates.");
	}
});
Found 20 dates.

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

Querystring parameters

Querystring parameters
ParameterNotes
idTour ID, this parameter must be supplied.
 
If using one of the API wrappers this will be passed as the first parameter
startdate_start
startdate_end
Optionally restrict results to a certain start/arrival date period, either both of these parameters must be supplied or neither. Format YYYY-MM-DD
between_date_start
between_date_end
Optionally restrict results to a certain start date / end date period. Format YYYY-MM-DD
has_offerBy default the API will retrieve all dates and deals however it's possible to filter to just dates containing specific types of deals:
 
blank/not supplied - All dates regardless of whether they have an offer
all - Return just dates with some discount/offer
1 - Dates with a specific discount on that date
2 - Dates with late booking discounts
3 - Dates with early booking discounts
4 - Dates with duration specific discounts
 
The numeric values can be combined, e.g. has_offer=2,3 for early and late booking discounts.
orderBy default the API will return the dates in start_date order (i.e. those nearest to their start date / soonest first), however if has_offer is set to only show offers, the default result order will be date offer created most recent first
 
The order parameter lets you override this default ordering:
 
start_date - Order by start date (soonest first)
offer_date - Order by offer created (most recently first)
distinct_start_datesSet to 1 to only return one entry per date, this is useful when building an availability calendar or similar where the only desired information is a list of dates which have some form of availability on them


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

Response fields

Response fields
XML 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
total_date_count Total number of dates returned
channel_id Channel ID
account_id Account ID
tour_id Tour ID
dates_and_prices

The dates_and_prices node contains the following:

XML NodeNotes
date

There will be a date note for each date found containing:

XML NodeNotes
start_dateStart date for this date
end_dateEnd date for this date
start_timeStart time for the Tour on this particular "date" 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
 
Note there may be multiple "date" nodes with the same start_date and end_date so if you are displaying all "dates" then you may want to display the start and end times too
end_timeEnd time for the Tour on this particular "date" in 24 hour local time format (e.g. "17:00").
 
See start_time above for full explanation
date_codeThis is the "Departure code" from a Tour Operators perspective, may be empty however may also refer to something like the time of departure (e.g "10:00") so may be worth displaying, especially if there are multiple dates with the same start/end date.
noteMay contain a note for this specific date
guide_language

If guide languages have been loaded on this departure (if this node doesn't exist, none have been loaded, asssume all languages from the tour level are supported on this departure) a guide_language node will be returned containing the following:

XML NodeNotes
language Tour guide language, 2 digit, e.g. "fr".
sale_currencyThree letter representation of the currency for the prices, e.g. EUR
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
 
0 - No special offer (regular price)
1 - Date specific special price
2 - Late booking discount
3 - Early booking discount
4 - Duration specific discount
statusWhether a booking should be entered or whether the tour operator needs to be asked first.
 
OPEN - This is the normal status, book as usual
ASKFIRST - Ask prior to booking to ensure availability
 
Normally ask first status appears when very few spaces remain or when the it is a last minute booking.
 
By default "ASKFIRST" dates are hidden, however some Tour Operators can choose to allow booking of "ASKFIRST" dates in their booking engine at which point they will also be distributed via the Marketplace.
book_urlLink to the online booking engine for this tour (possibly date specific)
 
It is possible to disable the standard booking engine, so on some accounts this may be blank.
 
If you have used distinct_start_dates=1, perhaps to build a calendar, you should not link the date to this departure specific booking engine URL, as it may only link to the first departure available on that date. Instead use the regular booking_url that is returned as part of either "Show Tour" or "Search Tours", optionally appending the month_year parameter to default the booking engine to the correct month.
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).
If special_offer_type is not 0
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

More information