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 |
| Formats | XML |
| Example | /c/tour/datesprices/datesndeals/search.xml?id=123 |
| Verb | GET |
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
Try it
Enter your TourCMS API credentials below to call the Dates & Deals endpoint.
Querystring parameters
| Parameter | Notes |
|---|---|
| id | Tour 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 those that start during a specified date period (when the tours end is not considered) either both of these parameters must be supplied or neither. Often used for displaying datepickers/calendars on websites Format YYYY-MM-DD |
| between_date_start between_date_end | Optionally restrict results to those that start AND FINISH within the searched period. Often used when you know the dates someone will be in resort and looking to complete tours during that period. Format YYYY-MM-DD |
| start_time | Receive just the departures with a matching "Start Time", must be 24 hour format (HH:MM) e.g. "09:00" |
| has_offer | By 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. |
| order | By 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_dates | Set 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 |
| supplier_note | TourCMS will return just the departures where the supplier note matches, e.g. "EN|01" |
| supplier_note_like |
Part match supplier notes, use "_" to match one character, "%"" to match multiple characters: "E%" (or "E_") will match "ES" or "EN". "E%" will match "English". To match supplier notes that contain a "_" or "%" first escape them, e.g. "EN\_%" will match "EN_1430" but not "EN1430". |
| code | Filter departures based on the departure code |
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
| XML Node | Notes | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 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:
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||