home > support > API > Marketplace API > API: tour search
| Purpose | Create a search results page, a page listing all tours or a category page | |
|---|---|---|
| Notes | Can 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 |
| Formats | XML | |
| Example | /p/tours/search.xml?lat=56.82127&long=-6.09139&k=walking | |
| Verb | GET | |
| Code |
PHP examples use the PHP Client Library with SimpleXML Description
Parameters
Example
C# examples use the .Net Client Library Overload list
Parameters
Example
VB examples use the .Net Client Library Overload list
Parameters
Example
|
|
| Parameter | Notes |
|---|---|
| k | Keyword - matches against Tour name, Location, Short description, Summary |
| 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 location (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/hotels that have at least one bookable date in the future. Set to all to return all tours/hotels |
| has_offer | Set to 1 to return just Tours/Hotels with special offers / deals available |
| 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 |
| 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 dates, date format YYYY-MM-DD |
| duration_min duration_max | Search by tour duration (Days) |
| min_priority | Minimum 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. |
| 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/hotels 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 |
| grade | Search by grade - comma separated list e.g. to just search for extreme/challenging products search for grade=4,5 |
| 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: By default will return all products. If you just want English set to en |
| order | Default 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) |
| qc | Enable/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_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 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 |
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/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.
|
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
Access the same tour search API method via a JavaScript widget. Information about widgets
1 tour© 2003-2012 Travel UCD Limited. All rights reserved. TourCMS® is a registered trademark of Travel UCD Limited, United Kingdom. View Privacy policy.