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.

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 2018 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
FormatsXML
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
VerbGET

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.

Querystring parameters
ParameterNotes
idTour ID. If using one of the wrapper client libraries this is passed as the second parameter
dateDate to search. Format YYYY-MM-DD (Include leading zeros e.g. 2018-01-31)
 
If not provided then the default value of todays date will be used.
hdurInteger 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_orderThe 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

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
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:

NodeNotes
component

A component node detailing one of the available tour rates / hotel rooms / other units that are available.
 
User interfaces for selecting between the available components should at a minimum show dates, times and "note" field where they differ between the components returned.

NodeNotes
start_date Start date for the component. YYYY-MM-DD
end_date End date for the component. YYYY-MM-DD
start_time Start time for the component, may not be supplied. 24 hour format, HH:MM
end_time End time for the component, may not be supplied. 24 hour format, HH:MM
date_code Alphanumeric
 
Depending on how the product is priced this will be either the Departure code, the Freesale season code or the board basis code
date_id Numeric
 
Either the departure id, freesale season id or hotel rate id
date_type 'departure', 'freesale' or 'hotel'
sale_currency Currency for the total_price, e.g. "EUR"
sale_quantity_rulePERSON - price is per person
GROUP - price is per group
total_price Numeric total price, e.g. "100.00"
total_price_
display
Display version of the total price, e.g. "€100"
net_price Numeric net price, e.g. "100.00"

If you are a travel agent, this is the approximate value that you will be invoiced by the supplier for the booking (i.e. the total_price minus your commission, or the true net rate). The reason it is approximate is because a few factors can adjust the price subsequent to this individual price quote: booking fees, credit card fees, promo codes, discounts for putting two tours on the same booking.

The true value a travel agent will be invoiced will be sales_price_due_ever on the return from Booking start API
price_
breakdown

A breakdown of how the total_price for this component is calculated, including:

NodeNotes
price_row There will be a price_row node for each element that contributes to the total_price of the component
 
E.g. "(1) €100"
note Freetext note providing extra information regarding this date. If provided this should be shown. If provided and different to the note field on other components this could be vital in helping the customer choose between results.
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 A language node for each tour guide language supported on this departure, 2 digit, e.g. "fr".
special_
offer_note
Text note if there is a special offer, e.g. "20% off early bookings"
component_
key
A unique identifier that can be used to book this particular component via the Start new booking API method
questions

If any questions are configured then a questions node will be returned containing:

XML NodeNotes
q

There will be an q node for each question configured on the Tour

XML NodeNotes
question_keyWhen passing the answers to Start New Booking, Add Booking Component or Update Booking Component the key will be used to identify which question is being answered.
questionThe primary question text to display to the customer, e.g. Please provide the approximate weights for each member of your party in kilograms (Kg)
explanationAdditional explanation text for the question, perhaps detailing why it is being requested or how it will be used
placeholderPlaceholder text, usually an example of the type of input required
question_internalA shortened label for the text, largely intended for staff use, e.g. Weight (kg)
repeatInteger. How many answers are expected. Some questions should be answered once per tour booking, others should be answered once per person, this field will display the correct number of answers expected, e.g. "2"
repeat_typeString. The value of the setting that drives the quantity, currently either 'Q' (if the question is set to be answered per person/quantity) or '1' (if the question is set to be answered once per tour booking)
answer_typeAn indication of the type of input expected, e.g. 'text', 'number', 'date' (and possibly more in future). Note that as far as the API goes this a suggestion only, TourCMS does not validate that the correct type of data is provided in an answer.
answer_mandatoryWhether the answer is mandatory (required). Note that as far as the API goes this is a suggestion only, TourCMS allows mandatory questions to be omitted or left unanswered
options

If any options (ancillary items) are available 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
- Available during the booking period

XML NodeNotes
option_idUnique ID
option_nameOption name
short_
description
Short description (HTML tags removed)
local_
payment
Local payments are payable locally and not taken into account on the main booking total. Possibly charged in a different currency to the channel / booking.
sale_quantity_ruleWhether the price will be multiplied by the quantity:
 
PERSON - price is per person
GROUP - price is per group
duration_ruleWhether the price will be multiplied by the duration:
 
Q - Price will NOT be multiplied by duration (default)
D - Price will be multiplied by duration in days
N - Price will be multiplied by duration in nights
extension Textual representation of the effect the option has on the start/end date of the tour. E.g. "4 nights".
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"
option_
group_radio
ONE_FROM_GROUP = Options of this group are mutually exclusive, e.g. can only book one of them
 
ANY_FROM_GROUP = Can book any combination of the Options from this group, they are not mutually exclusive.
per_text Label to show next to the price, e.g. per "Person", "Group" etc
quantities_
and_prices

Containing:

XML NodeNotes
selection

A selection node for each possible quantity, containing:

XML NodeNotes
quantity Quantity
price Price
price_
display
Display Price
component_
key
Pass to Start new booking API
pickup_on
_request_key
This will be set if the Customer can provide a free-text pickup point, will be empty if the Customer _can not_ provide a free-text pickup point.
 
A pickup key (either this one if taking a free-text pickup point, or a key from the list of possible pickups that may be defined in the pickup_points section below) can be passed to the Start new booking API method.
 
Regardless of the setting here, there may be a predefined list of available pickup points in the pickup_points node.
pickup_
points

If any pickup points are available for this date/time then a pickup_points node will be returned containing:

XML NodeNotes
pickup

A pickup node for each pickup point for this date/time (ordered by time of pickup - if set - earliest first) containing:

XML NodeNotes
pickup_keyIf you are using the API to build a booking you can pass the pickup_key to the Start new booking API method to indicate which pickup the customer has chosen.
timeIf set this will indicate the pickup time. HH:MM format (24hr).
pickup_nameText name for the point (e.g. a hotel or bus stop name)
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
If API called by Tour Operator, not accessible to Travel Agents
supplier_noteSupplier note (can be used for holding date specific IDs from 3rd party reservation systems)

More information