Used by 400 Specialist Tour & Activity Operators worldwide
home > support > API > Marketplace API > booking creation > check tour availability
Check Tour Availability
Check live availability & price for a Tour on a given date and quantity.
Intended for use when transfering an existing booking, or when a customer is about to make a booking and has selected the product, date and quantity they desire. Not intended for use speculatively, if you are would like to populate a cache of dates to show the customer prio to booking you may call Dates and Deals or Show Tour Departures (Product/tour specific) or Tour Search (Multi product).
Notes
You will provide TourCMS with a date and quantities, TourCMS responds with any available components. E.g. a search for 2 adults , 1 child on 1st January 2020 will either return a no availability response, or one or more matching components.
Each component returned could be a different time, route, duration etc available for those quantities and starting on that date.
The response includes the calculated total price for the selection, which is then guaranteed not to change for the life of the component (see the "component_key_valid_for" XML node). However, no places/seats are held for the customer, until a temporary booking is created.
If you are building a shopping cart you will want to store the "component_key" for the component the customer picks from the list returned, alongside sufficient information (rate selections and dates) to check availability again should the amount of time between checking availability and checking out be longer than component_key_valid_for.
REST info
Endpoint | /c/tour/datesprices/checkavail |
Formats | XML |
Examples | /c/tour/datesprices/checkavail.xml?id=33&date=2011-10-26&r1=4&r3=7 /c/tour/datesprices/checkavail.xml?id=114&date=2012-01-01&ad=2&ch=2&inf=0&hdur=2 |
Verb | GET |
Code samples
PHP examples use the PHP Client Library with SimpleXML
Description
object check_tour_availability ( string $params, int $tour, int $channel )
Parameters
- $params
- Querystring parameters (see table below)
- $tour
- ID for the Tour to check
- $channel
- ID for the Channel (supplier) - required as Tour IDs are not unique
Example
// Set the ID number for the Tour we are checking
$tour = 1;
// Set the channel this Tour belongs to
$channel = 3930;
// Add the desired date to the querystring
$qs = "date=2012-10-29";
// If this Tour used Hotel type pricing we'd append a duration
// $qs .= "&hdur=7";
// Append the number of people for each rate
// Rate details obtained via "Show Tour" API
// Numbers of people likely via user input
// Here we just want 2 people on rate "r1"
$qs .= "&r1=2";
// Query the TourCMS API
$result = $tourcms->check_tour_availability($qs, $tour, $channel);
// See how many available components TourCMS has returned
if(isset($result->available_components->component))
$num_components = count($result->available_components->component);
else
$num_components = 0;
// If there are components display them, otherwise display "no availability"
if($num_components>0)
{
// We have some components, loop through them
foreach ($result->available_components->component as $component)
{
print $component->date_code . " ";
print $component->total_price_display . "<br />";
}
} else {
// The components we searched for are not available
print "Sorry, no availability";
}
09:00-12:30 £100
13:00-16:30 £110
C# examples use the .Net Client Library
Overload list
XmlDocument CheckTourAvailability (String queryString, int tourId, int channelId)
Parameters
- queryString
- See querystring parameters table below
- tourId
- Id number for the Tour we want to check availability for
- channelId
- The channel the Tour belongs to
VB examples use the .Net Client Library
Overload list
XmlDocument CheckTourAvailability (String queryString, Integer tourId, Integer channelId)
Parameters
- queryString
- See querystring parameters table below
- tourId
- Id number for the Tour we want to check availability for
- channelId
- The channel the Tour belongs to
NodeJS examples use the NodeJS Wrapper
Example
// Check availability for 2x Rate 1, 1st Jan 2017 on Tour ID 6
TourCMS.checkTourAvailability({
channelId: 3930,
qs: {
id: 6,
date: '2017-01-01',
r1: 2
},
callback: function(response) {
//Loop through each component and output its component key
response.available_components.component.forEach(function(component) {
console.log(component.component_key);
}
});
Outputs the component key for each result
Looking for sample code in a different language? TourCMS and community provided API libraries
Querystring parameters
You must include the id, and at least one of the various rates; you should also provided the date - although it will default to todays date if not supplied. When searching for hotels hdur should be provided, although it will default to the default duration for each Hotel - however that may give differing results if default durations vary between hotels in the results.
Parameter | Notes |
---|---|
id | Tour ID. If using one of the wrapper client libraries this is passed as the second parameter |
date | Date to search. Format YYYY-MM-DD (Include leading zeros e.g. 2020-01-31) If not provided then the default value of todays date will be used. |
hdur | Integer representing the duration to search, either days or nights. Only required if checking hotel type pricing. Whether the Tour is using Hotel type pricing and if so whether hdur should be days or nights can be determined by checking the Show Tour API method) Defaults to the default duration for each hotel If you are a travel agent distribution partner, most product you are taking are tours, not hotels, so disregard this field |
(various rates) | Various parameters describing the number of people to check availability for, broken down by rate (pricing tier). The actual querystring parameter(s) used will depend on the rates offered by a particular Tour and should be the rate_id as returned by the Show Tour API method. For example if the Show Tour API described an "Standard" rate with the rate_id "r1" and a "Premium" rate with the rate_id "r2" the querystring snippet to specify two standards and one premium would be: r1=2&r2=1 |
pickup_order | The order pickup points (if available) should be returned pickup_time (or leave blank - default) pickup_name |
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 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
channel_id | Channel ID | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
account_id | Account ID | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tour_id | Tour ID | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tour_name | Tour Name - Short | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
tour_name_ long |
Tour Name - Long | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
component_ key_valid_for |
How long (in seconds) the returned component keys will be valid for. While valid TourCMS will hold the price (but not the availability). If this time period elapses prior to booking, a new component-key should be retrieved. Currently will always return 3600 seconds (1 hour) however TourCMS may adjust this value in the future |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
available_ components |
As long as the Tour is found there will be an available_components node, it may be empty if there's no availability, otherwise it will contain:
|