home > support > API > Marketplace API > API: tour search
Get a list of tours with basic information on each, intended for listing pages.
Only returns a subset of the information TourCMS holds on each tour, intended to be enough for a listing page. To get the full details on a specific tour (i.e. once a customer has made a selection) call Show Tour.
If you are importing tours into your own database you should use List Tours instead.
Paged, returns 75 tours per page by default (maximum 200 tours per page).
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 an 30 minutes. This helps you keep within API limits and to keep your site running fast. More on API caching.
Call | /p/tours/search /c/tours/search |
Formats | XML |
Example | /p/tours/search.xml?lat=56.82127&long=-6.09139&k=walking |
Verb | GET |
PHP examples use the PHP Client Library with SimpleXML
object search_tours ( [ string $params = "" [, int $channel = 0 ]] )
// Set the Channel ID
// For Operators this can be found in the API settings page
// For Agents 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
XmlDocument SearchTours ()
XmlDocument SearchTours (string queryString)
XmlDocument SearchTours (string queryString, int channelId)
// Set the Channel ID
// For Operators this can be found in the API settings page
// For Agents 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
XmlDocument SearchTours ()
XmlDocument SearchTours (string queryString)
XmlDocument SearchTours (string queryString, int channelId)
' Set the Channel ID
' For Operators this can be found in the API settings page
' For Agentss 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)
NodeJS examples use the NodeJS Wrapper
// Search for tours near a geographic point matching keyword "walking"
TourCMS.searchTours({
channelId: 3930,
qs: {
k: 'walking',
lat: '56.82127',
lng: '-6.09139'
},
callback: function(response) {
response.tour.forEach(function(tour) {
console.log(tour.tour_name_long);
})
}
});
Knoydart Peninsula Walking Adventure
Inner Hebrides Sailing & Walking Adventure
Looking for sample code in a different language? TourCMS and community provided API libraries
Implementing yourself? Check the REST info for this endpoint.
Enter your TourCMS API credentials below to call the Search Tours endpoint.
Parameter | Notes |
---|---|
tour_id not_tour_id | Limit the results to a set list of Tours by passing in a list of IDs (or exclude by using not_tour_id). Perhaps useful if presenting a list of the alternative tours returned by Tour Show with more detail than returned directly by that API. tour_id=10 (Tour ID 10 only) tour_id=10,12,15 (Tour IDs 10, 12 and 15 only) NB: Only works if searching in a specific Channel (e.g. an Operator/Supplier on their own site, or an Agent listing Tours from a certain Channel). Use channel_id_tour_id is the solution to limit to specific tour IDs over multiple channels. |
channel_id_tour_id not_channel_id_tour_id | Limit the results to a set list of Channels/Tours by passing in a list of IDs (or exclude by using not_channel_id_tour_id). Perhaps useful if presenting a list of the alternative tours returned by Tour Show with more detail than returned directly by that API. channel_id_tour_id=10_8 (Tour ID 8, from Channel ID 10 only) channel_id_tour_id=10_8,10_100,10_101 (Tour IDs 8, 100, 101 only, from Channel ID 10 only) |
k | Keyword - matches against Tour name, Location, Short description, Summary, Tour code |
k2 | Keyword #2 (When used with k will be OR) |
k3 | Keyword #3 (When used with k and k2 will be OR) |
k_type | Set k_type=AND to make k, k2, k3 work as an AND (default is OR) |
location | Search by "Primary location" text field (Part matches permitted) |
lat | Latitude of search point |
long | Longitude of search point |
geo_type | Set to end to search tour end point. By default will search tour start point |
geo_unit | Set to km to set unit for proximity search to kilometres. By default will be miles |
geo_distance | Define distance for proximity search. Default 50 |
has_sale | By default will only return tours that have at least one bookable date in the future. Set to all to return all tours |
has_offer | Set to 1 to return just tours with special offers / deals available. Combine with start_date_start and start_date_end to return tours with special offers available during a certain range of start dates, e.g. Christmas offers or School holiday offers. |
has_sale_month | e.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 |
404_tour_url | TourCMS checks the Product page URLs stored for each tour accessible via the API, by default only products with working Product page URLs will be returned. Set this parameter to override that behaviour: error - Return just those tours that are returning errors, handy if you are a tour operator / supplier and want to fix your URLs. all - Return all tours, regardless of whether their Product page URL is returning an error or not. Handy if you are building an entirely API driven website, or perhaps a mobile app, and have no need to link through to the supplier website for full details. |
start_date | Check availability on a specific date, date format YYYY-MM-DD |
start_date_start start_date_end | Check availability on a range of start dates, date format YYYY-MM-DD |
between_date_start between_date_end | Check availability where start date is after between_date_start and end date is before between_date_end, date format YYYY-MM-DD. Only use this when dealing with searches for multi-day product that starts and ends between a pair of dates, otherwise use start_date_start and start_date_end |
duration_min duration_max | Search by tour duration (Days) |
price_range_min | Minimum "From" price. Defaults to USD, use price_range_currency to specify a different currency to base ranged search on. |
price_range_max | Maximum "From" price. Defaults to USD, use price_range_currency to specify a different currency to base ranged search on. |
price_range_currency | Currency to base min/max price range searches on, defaults to USD. TourCMS will return prices in their original currency, however internally all prices plus the min/max range are converted to USD (using exchange rates from multiple sources) for range and ordering purposes. Due to this conversion, actual ranges may vary slightly |
min_priority | Minimum commercial priority. Set to medium to return either Medium or High priority tours, set to high to return only High priority tours only - perhaps to build a "Featured Tours". |
country | Search by country - two letter ISO country code |
not_country | EXCLUDE results featuring this country - two letter ISO country code |
not_accom | Set to 1 to EXCLUDE tour that include accommodation (Product types 1 & 3) Handy if you are featuring tours / activities on a hotel website |
accom | Set to 1 to ONLY RETURN products that include accommodation (Product types 1 & 3) Handy if you are featuring hotels on a tour/activity website |
accomrating | Search by accommodation rating - comma separated list e.g. to just search for comfortable/basic products search for accomrating=4,5 |
product_type | Search by product type - comma separated list e.g. to just search for products with accommodation search for product_type=1,3. List of possible types For transfers/transport (product_type 2), you can search by airport code by searching airport_code=LGW e.g. product_type=2&airport_code=LGW |
grade | Search by grade - comma separated list e.g. to just search for extreme/challenging products search for grade=4,5 |
tourleader_type | Search by tour leader type - comma separated list e.g. to just search for Independent / self drives search for tourleader_type=2 |
show_tour_tags | 1 to show tour tags. Something different than 1 will avoid returning tour tags. Unlike "show_tour" endpoint, will only return tags the tour has active. |
suitable_for_solo ¶ | Find Tours suitable for solo travellers (by setting to 1) or NOT suitable for solo travellers (by setting to 0) |
suitable_for_couples ¶ | Find Tours suitable for couples (by setting to 1) or NOT suitable for couples (by setting to 0) |
suitable_for_children ¶ | Find Tours suitable for children (by setting to 1) or NOT suitable for children (by setting to 0) |
suitable_for_groups ¶ | Find Tours suitable for groups (by setting to 1) or NOT suitable for solo travellers (by setting to 0) |
suitable_for_students ¶ | Find Tours suitable for students (by setting to 1) or NOT suitable for students (by setting to 0) |
suitable_for_business ¶ | Find Tours suitable for business travellers (by setting to 1) or NOT suitable for business travellers (by setting to 0) |
suitable_for_wheelchairs ¶ | Find Tours suitable for wheelchairs (by setting to 1) or NOT suitable for wheelchairs (by setting to 0) ¶ The seven suitable_for_ fields are new to TourCMS and may not be fully populated by all Channels (Tour Operators) yet, thus they may not be reliable currently. They will be made mandatory shortly at which point they can be relied on. |
health_and_safety_details | Set to 1 to return only tours where some extended health & safety checklist information has been provided. A detailed breakdown of the provided information is available via Show Tour. |
currency | Search 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) |
lang | Language that the tour description is loaded in. By default will return all products. If you just want tours loaded in the English language set to en |
lang_spoken | Languages spoken on the tour. Most commonly loaded for attractions that have audio guides or operate specific language groups. This is a relatively new field and not all tours will have it configured. Generally speaking we would not rely on using this search parameter currently, instead you may wish to just display the languages spoken where returned. |
video_service | Optionally search for only tours that have a video, or have a video hosted by a particular service. By default TourCMS will return all tours regardless of whether they have video or not, override this by passing: all - Just tours with videos (hosted anywhere) vimeo - Just tours with videos hosted by Vimeo youtube - Just tours with videos hosted by YouTube |
order |
Default orderBy default the results are returned in descending commercial priority followed by tour performance order, next bookable date order, "display points" value and finally alphabetically by tour name.If carrying out a proximity search the default ordering will by distance to the search point, closest first. To set back to the regular default order for proximity search results, set order=comm
Alphabetical: Set order=tour_name |
qc | Enable/disable "Quality control". Quality control can be switched on/off (default is off) within the Agent 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 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. Also ensures tours meet certain image and description length criteria. |
per_page | Number of results to return per page. Default is 75. Max is 200 |
page | Integer for which page number to return. Default is page 1 |
If API called by Tour Operator (not Marketplace Agent) | |
category ANDcategory ORcategory NOTcategory |
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 NOTcategory, can be used to tell TourCMS which products to exclude from the results,for example to search for all products that feature Rafting but not Hiking.... category=Rafting&NOTcategory=Hiking |
tour_tags ANDtour_tags ORtour_tags NOTtour_tags |
Tour Operators / Suppliers can define product tour tags to aid grouping products on their website. Example tour tags might include notes about what an activity is suitable for. There are three parameters that can be used to search these. If searching just a single tour_tags then any of the parameters can be used, however the most logical would be tour_tags e.g to search for animals use the following... tour_tags=animals To search for either animals OR romantic... ORtour_tags=animals|romantic To search for Tours that contain both animals AND romantic... ANDtour_tags=animals|romantic NOTtour_tags, can be used to tell TourCMS which products to exclude from the results,for example to search for all products that feature animals but not romantic... tour_tags=animals&NOTtour_tags=romantic |
booking_style |
Generally only useful for affiliates linking to the operator booking engine. If you are placing bookings via API as a Trusted Travel Agent you can omit this parameter. Affiliates may choose to set this parameter to booking to only return Tours from Channels (Operators) that take confirmed online bookings (e.g. will ignore Tours from any Channels who take online "bookings" as an Enquiry or Quotation stage of the process) |
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:
Keyword searching is NOT case-sensitive.
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_tour_count | Total number of tours 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.
|
Access the same tour search API method via a JavaScript widget. Information about widgets
1 tour