home > support > API > Marketplace API > API: tour search

Search Tours

PurposeCreate a search results page, a page listing all tours or a category page
NotesCan be used as a keyword search OR as a geographic search (with results ordered by proximity to a geocode) or a combination of both. No paramaters are mandatory
REST info Call/p/tours/search
/c/tours/search
FormatsXML
Example/p/tours/search.xml?lat=56.82127&long=-6.09139&k=walking
VerbGET
Code

PHP examples use the PHP Client Library with SimpleXML

Description

object search_tours ( [ string $params = "" [, int $channel = 0 ]] )

Parameters

$params
	Search querystring, see possible values in the table below
$channel
	Channel to search, 0/blank for all connected channels

Example

// Set the Channel ID
// For Suppliers this can be found in the API settings page
// For Partners this can be a specific Channel or 0 to search all
$channel = 3;

// Define search parameters
$params = "lat=56.82127&long=-6.09139&k=walking";

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

// Loop through each Tour and output the Tour name and distance
foreach($result->tour as $tour) {
	print $tour->tour_name.' ('.round($tour->distance).' miles)
'; }
Knoydart Peninsula Walking Adventure (16 miles)
Inner Hebrides Sailing & Walking Adventure (37 miles)

C# examples use the .Net Client Library

Overload list

XmlDocument SearchTours ()
XmlDocument SearchTours (string queryString)
XmlDocument SearchTours (string queryString, int channelId)

Parameters

queryString
	Search querystring, see possible values in the table below
channelId
	Channel to search, 0/blank for all connected channels

Example

// Set the Channel ID
// For Suppliers this can be found in the API settings page
// For Partners this can be a specific Channel or 0 to search all
int channelId = 0;

// Build Search querystring (see table below)
string queryString = "lat=56.82127&long=-6.09139&k=walking";

// Call the API
XmlDocument doc = myTourCMS.SearchTours(queryString, channelId);

// Display Tour list
XmlNodeList tourList = doc.GetElementsByTagName("tour");
foreach (XmlNode tour in tourList)
{
	string tourName = tour.SelectSingleNode("tour_name").InnerText;
	string tourDist = tour.SelectSingleNode("distance").InnerText;
    Console.WriteLine(tourName + " (" + tourDist + " miles)");
}
Knoydart Peninsula Walking Adventure (16 miles)
Inner Hebrides Sailing & Walking Adventure (37 miles)

VB examples use the .Net Client Library

Overload list

XmlDocument SearchTours ()
XmlDocument SearchTours (string queryString)
XmlDocument SearchTours (string queryString, int channelId)

Parameters

queryString
	Search querystring, see possible values in the table below
channelId
	Channel to search, 0/blank for all connected channels

Example

' Set the Channel ID
' For Suppliers this can be found in the API settings page
' For Partners this can be a specific Channel or 0 to search all
Dim channelId As Integer = 0

' Build Search querystring (see table below)
Dim queryString As String = "lat=56.82127&long=-6.09139&k=walking"

' Call the API
Dim doc As XmlDocument = myTourCMS.SearchTours(queryString, channelId)

' Display Tour list
Dim tourList As XmlNodeList = doc.GetElementsByTagName("tour")
For Each tour As XmlNode In tourList
	Dim tourName As String = tour.SelectSingleNode("tour_name").InnerText
	Dim tourDist As String = tour.SelectSingleNode("distance").InnerText
	Console.WriteLine(tourName & " (" & tourDist & " miles)")
Next
Knoydart Peninsula Walking Adventure (16 miles)
Inner Hebrides Sailing & Walking Adventure (37 miles)

Querystring parameters

Querystring parameters
ParameterNotes
kKeyword - matches against Tour name, Location, Short description, Summary
k2Keyword #2 (When used with k will be OR)
k3Keyword #3 (When used with k and k2 will be OR)
k_typeSet k_type=AND to make k, k2, k3 work as an AND (default is OR)
locationSearch by location (Part matches permitted)
latLatitude of search point
longLongitude of search point
geo_typeSet to end to search tour end point. By default will search tour start point
geo_unitSet to km to set unit for proximity search to kilometres. By default will be miles
geo_distanceDefine distance for proximity search. Default 50
has_saleBy default will only return tours/hotels that have at least one bookable date in the future. Set to all to return all tours/hotels
has_offerSet to 1 to return just Tours/Hotels with special offers / deals available
has_sale_monthe.g. has_sale_month=1,2 to return products with something on sale EITHER in January OR February. Can be multiple or just a single month. Use this to create a basic availability search
start_dateCheck availability on a specific date, date format YYYY-MM-DD
start_date_start
start_date_end
Check availability on a range of dates, date format YYYY-MM-DD
duration_min
duration_max
Search by tour duration (Days)
min_priorityMinimum commercial priority. Set to medium to return either Medium or High priority Tours/Hotels, set to high to return only High priority Tours/Hotels only - perhaps to build a "Featured Tours" or "Favourite Hotels" page.
countrySearch by country - two letter ISO country code
not_countryEXCLUDE results featuring this country - two letter ISO country code
not_accomSet to 1 to EXCLUDE tour/hotels that include accommodation (Product types 1 & 3)
Handy if you are featuring tours / activities on a hotel website
accomSet to 1 to ONLY RETURN products that include accommodation (Product types 1 & 3)
Handy if you are featuring hotels on a tour/activity website
accomratingSearch by accommodation rating - comma separated list e.g. to just search for comfortable/basic products search for accomrating=4,5
product_typeSearch by product type - comma separated list e.g. to just search for products with accommodation search for product_type=1,3
gradeSearch by grade - comma separated list e.g. to just search for extreme/challenging products search for grade=4,5
currencySearch by currency - three letter upper case currency code (USD / EUR / GBP etc) (Only bring back products selling in a particular currency. This is a filter to reduce products shown not an application of an exchange rate)
langLanguage: By default will return all products. If you just want English set to en
orderDefault results returned in descending commercial priority order then alphabetical by tour name
If a proximity search will first order by distance to the supplied geocode, nearest first
To override and ensure that always returns commercial priority order set order to comm, for alphabetical set order to tour_name, for Tours/Hotels with most recently created special offers set to offer_recent, for Tours/Hotels with offers starting (i.e. travel date) soonest then set to offer_soonest.
 
You can also order by price price_up or price_down but bear in mind this doesn't really make sense in a multi-currency scenario so do apply a currency restriction too!
 
Order by date_soonest to order by nearest bookable date (ideal if you have a list of events and you want to show in date order)
 
Order by created_recent to order by most recently created first (similar to a blog posting style where on a blog tend to show most recent blog posts first)
qcEnable/disable "Quality control". Quality control can be switched on/off (default is off) within the Partner control panel and also overriden using this querystring parameter.
Note: This setting has no impact when a tour operator uses this API method on their own website.
 
Quality control explanation:
If you are a web affiliate sending traffic through to the suppliers website then turn qc=on to only return tours/hotels where TourCMS is confident web tracking of bookings is in place. If - rather than sending traffic to the suppliers website - you are using the API to input web bookings or enquiries then you don't need to worry about leakage via insufficient web tracking, hence can leave the quality control off.
per_pageNumber of results to return per page. Default is 75. Max is 200
pageInteger for which page number to return. Default is page 1
If API called by Tour Operator (not Marketplace Partner)
category
ANDcategory
ORcategory
Tour Operators / Suppliers can define product Categories to aid grouping their products into Product filters (collections) for internal use in reporting, or for grouping products on their website. Learn more.
 
Example Categories might include "Activity type" (with possible values of "Rafting", "Mountain Biking", "Hiking") or for Hotel type products you might have "Accommodation rating" (with possible values of "5 Star", "3 Star" or "Boutique").
 
There are three parameters that can be used to search these. If searching just a single category then any of the parameters can be used, however the most logical would be category, e.g to search for Rafting use the following...
 
category=Rafting
 
...to search for either Rafting OR Hiking...
 
ORcategory=Rafting|Hiking
 
...to search for Tours that contain both Rafting AND Hiking...
 
ANDcategory=Rafting|Hiking
IF you are using tour search API to export tours into a 3rd party system AND the page limit of 200 is a problem (i.e. you are exporting more than 200 products) then please contact TourCMS support. We have an API parameter to remove the limit! But nope, we are not documenting it here :)

Searching by Keyword

As described in the table above there are two parameters (k and k2) that can be used to search Tours by keyword, here are a few examples of their use:

k=Rafting
Returns all Tours containing the text "Rafting"
k=Rafting&k2=Kayaking
Returns all Tours containing the text "Rafting" and/or the text "Kayaking"
k=White+water+rafting
Returns all Tours containing the text "White water rafting"

Keyword searching is NOT case-sensitive.

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_tour_count Total number of tours/hotels returned by the search (i.e. not just the number on this page)
tour

There will be one tour node for each result on this page.

Each tour node contains the following child nodes.

XML NodeNotes
channel_idChannel ID
account_idAccount ID
tour_idTour/Hotel ID
has_sale1 - Future product on sale
0 - No future product on sale
has_d1 - Has a tour departure loaded
0 - No tour departure loaded
has_f1 - Has a tour freesale loaded
0 - No tour freesale loaded
has_h1 - Has a hotel product type loaded
0 - No hotel product type loaded
next_bookable_dateFirst date the tour/hotel text is bookable, date format YYYY-MM-DD
has_sale_jan
has_sale_feb
has_sale_mar
has_sale_apr
has_sale_may
has_sale_jun
has_sale_jul
has_sale_aug
has_sale_sep
has_sale_oct
has_sale_nov
has_sale_dec
1 - Future product on sale (by the month)
0 - No future product on sale (by the month
tour_codeTour code (only returned if set)
from_priceLead in price
from_price_displayLead in price - display version (Includes HTML entity currency code and no decimals)
from_price_jan
from_price_feb
from_price_mar
from_price_apr
from_price_may
from_price_jun
from_price_jul
from_price_aug
from_price_sep
from_price_oct
from_price_nov
from_price_dec
Lead in price by the month
Use to create a nice seasonal price chart

There are also _display versions that work the same way as from_price_display
sale_currencySale currency (for the lead in price). Currency is set by channel
priorityHIGH, MEDIUM, LOW - Commercial priority
thumbnail_imageURL for thumbnail image. Image not reduced to thumbnail size
geocode_startLat,Long geocode for start point
geocode_endLat,Long geocode for end point
distanceIF a proximity search, the distance from the search point. Default is miles
Field not returned if not a proximity search
tour_nameTour name
start_timeStart time / Opening time for the Tour/Hotel.
 
May be a 24 hour time value in local time (e.g. "09:00").
 
If there are multiple start times per day or the start time varies by day then the value will be "MULTI".
 
Alternatively if start time is unknown / irrelevent then this field may be blank  (although the start time may be explained elsewhere in the Tour/Hotel description, e.g. in the pickup points section).
 
If any special offers have been found for the Tour/Hotel they may have their own start and end times.
end_timeEnd time / Closing time for the Tour/Hotel.
 
Possible values as per start_time above.
countryComma separated list of uppercase countries the tour takes place in
duration_descText description for duration (e.g. 1 week)
durationDuration (Days)
locationPrimary location - Perhaps a city name, national park name or region
summarySummary - Includes primary activity if not clear from tour/hotel name
shortdescShort description (NO HTML)
availableText description for when available (e.g. March to September)
tour_urlURL for the tour detail page
tour_url_trackedURL for the tour detail page - via agent tracking mechanism
Not returned for /c/tours/search
book_urlURL to booking engine / live availability display (can be iframed onto your site)
tourleader_type 1 - Tour guide / driver
2 - Independent / self drive
3 - Not applicable (e.g. accommodation / event)
grade 1 - All ages / Not applicable
2 - Moderate
3 - Fit
4 - Challenging
5 - Extreme
accomrating 1 - No accommodation / Not applicable
2 - Luxury
3 - Moderate
4 - Comfortable
5 - Basic
6 - Various levels
product_type 1 - Accommodation (hotel/campsite/villa/ski chalet/lodge)
2 - Transport
3 - Tour/cruise including overnight stay
4 - Day tour/trip/activity/attraction (No overnight stay)
5 - Tailor made
6 - Event
7 - Training/education
8 - Other
supplier_idIf a Tour Operator is using the API call directly then supplier_id will contain the internal reference number for the supplier on the main Tour/Hotel on the booking. Not returned when a Marketplace Partner is using the API.
channel

The channel node contains the following child nodes.

XML NodeNotes
channel_name Channel name (Company name)
logo_url Channel logo URL
lang Channel language
home_url URL website homepage
home_url_tracked URL website homepage (with agent tracking)
soonest_special_offer

If any special offers / deals are loaded for this Tour/Hotel then a soonest_special_offer node will be returned containing the soonest (i.e. closest to start/departure date) special offer via the below child nodes. If you are ordering the results by offer_soonest then this is probably the offer you want to display.

XML NodeNotes
start_dateStart date for this date
end_dateEnd date for this date
start_timeStart time / Opening time for the Tour/Hotel on this particular offer 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
end_timeEnd time / Closing time for the Tour/Hotel on this particular offer in 24 hour local time format (e.g. "17:00").
 
If the start time is not known or is irrelevant for the item type then this field will be blank
date_codeThis is the "Departure code" from a Tour Operators perspective, may be empty
noteProduct note
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
 
1 - Date specific special price
2 - Late booking discount
3 - Early booking discount
4 - Duration specific discount
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).
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
recent_special_offer

If any special offers / deals are loaded for this Tour/Hotel then a recent_special_offer node will be returned featuring the most recently created special offer via the below child nodes. If you are ordering the results by offer_recent then this is probably the offer you want to display.

XML NodeNotes
start_dateStart date for this date
end_dateEnd date for this date
start_timeStart time / Opening time for the Tour/Hotel on this particular offer 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
end_timeEnd time / Closing time for the Tour/Hotel on this particular offer in 24 hour local time format (e.g. "17:00").
 
If the start time is not known or is irrelevant for the item type then this field will be blank
date_codeThis is the "Departure code" from a Tour Operators perspective, may be empty
noteProduct note
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
 
1 - Date specific special price
2 - Late booking discount
3 - Early booking discount
4 - Duration specific discount
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).
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

Sample XML response

Search near a geographic point (in Scotland) filtering by keyword (Walking) This returns walking tours in Scotland, ordered by distance to the search point (Miles) Look at the distance field to see how far away from the point the tour starts from

/p/tours/search.xml?lat=57.19437&long=-3.828825&k=walking

Widgets

Access the same tour search API method via a JavaScript widget. Information about widgets

1 tour

Compact version including page navigation

More information

© 2003-2012 Travel UCD Limited. All rights reserved. TourCMS® is a registered trademark of Travel UCD Limited, United Kingdom. View Privacy policy.

Free 1 hour webinar - An introduction to TourCMS, 31st May @ 3pm GMT / 4pm BST (UK). Check in your timezone and register »