home > support > API > Marketplace API > API: tour/hotel dates and deals
Tour/Hotel Dates and Deals
| Purpose | Retrieve dates and deals on a particular tour |
| Notes | N/A |
| REST info |
Call | /c/tour/datesprices/datesndeals/search |
| Formats | XML |
| Example | /c/tour/datesprices/datesndeals/search.xml?id=123 |
| Verb | GET |
| Code |
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
14th October 2011 to 21st October 2011 £1020 £820 ** SPECIAL **
21st October 2011 to 28th October 2011 £1020
C# examples use the .Net Client Library
This is a brand new API method, an example will be added here shortly.
VB examples use the .Net Client Library
This is a brand new API method, an example will be added here shortly.
|
Querystring parameters
Querystring parameters
| Parameter | Notes |
| id | Tour/Hotel 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 |
| 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 |
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 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/Hotel ID |
dates_and_prices |
The dates_and_prices node contains the following:
| XML Node | Notes |
| date |
There will be a date note for each date found containing:
| XML Node | Notes |
| start_date | Start date for this date |
| end_date | End date for this date |
| start_time | Start time / Opening time for the Tour/Hotel 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_time | End time / Closing time for the Tour/Hotel on this particular "date" in 24 hour local time format (e.g. "17:00"). See start_time above for full explanation |
| date_code | This 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. |
| note | Product note |
| sale_currency | Three letter representation of the currency for the prices, e.g. EUR |
| min_booking_size | Minimum number of people required per booking, e.g. 1 |
| spaces_remaining | Number of people that can still book for this date. Generally numeric however could contain the text UNLIMITED |
| special_offer_type | Type 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 |
| status | Whether an agent should just take a booking - or whether should ask 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 TourCMS will hide "ASKFIRST" dates from the Marketplace and only return those dates that are "OPEN", however some Tour Operators can choose to display "ASKFIRST" dates in their booking engine at which point they will also be distributed via the Marketplace. For Tour Operators are using the API on their own website "ASKFIRST" dates will always be returned. |
| book_url | Link to the online booking engine for this tour/hotel |
| price_1 | Price for 1 person. E.g 100.00 |
| price_1_display | Display version of the price for 1 person including currency symbol / code. E.g €100.00 |
| price_2 | Price 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_display | Display 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_datetime | Date and tine the special offer was created. Format YYYY-MM-DD HH:MM:SS |
| special_offer_note | Text note on the special offer, e.g. "20% off early bookings" |
| original_price_1 | The original price for 1 person (before the discount was applied). E.g. 120.00 |
| original_price_1_display | Display version of the original price for 1 person (before the discount was applied). Includes currency symbol / code. E.g. €120.00 |
| original_price_2 | The original price for 2 people (before the discount was applied). E.g. 200.00 |
| original_price_2_display | Display version of the original price for 2 people (before the discount was applied). Includes currency symbol / code. E.g. €200.00 |
|
|
More information