Search Tours

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

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.

Caching

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.

Code samples

Description

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 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)';
}

Querystring parameters

Querystring parameters

Parameter

Notes

tour_idnot_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.

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_idnot_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.

Set 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)

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_startstart_date_end

Check availability on a range of start dates, date format YYYY-MM-DD

between_date_startbetween_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_minduration_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

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.

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 Vimeoyoutube - Just tours with videos hosted by YouTube

order

Default order

By 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

Overriding the default order

Alphabetical: Set order=tour_name

Commercial priority [Default]: Set order=comm

Departure date: Set order=date_soonest to order by nearest bookable date (ideal if you have a list of events and you want to show in date order). Please note that if you are searching for tours available within a date range that this is the overall next bookable date and NOT the next bookable date within a supplied date range

Display points: Set order=display_points_up or order=display_points_down to order by the "Display points" field in the Tour setup page. display_points_up orders by the lowest number first, which matches the instructions in the TourCMS UI. Possibly useful for Tour Operators use on their own website, likely of little use to Agents.

Duration: Set order=duration_up or order=duration_down

Price: Set order=price_up or order=price_down. For Agents searching across multiple Channels the currencies in use may vary, TourCMS internally converts all prices to USD for ordering purposes (but does not expose the calculated USD price anywhere).

Special offer: To order by the most recently created special offers set to order=offer_recent, for tours with offers starting soonest then set to order=offer_soonest (use this for a "Late deals" type page).

Tour creation date: Set order=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 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.

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

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:

Response fields

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.

XML Node

Notes

channel_id

Channel ID

account_id

Account ID

tour_id

Tour ID

has_sale

1 - Future product on sale0 - No future product on sale

has_d

1 - Has a tour departure loaded0 - No tour departure loaded

has_f

1 - Has a tour freesale loaded0 - No tour freesale loaded

has_h

1 - Has a hotel product type loaded0 - No hotel product type loaded

next_bookable_date

First date the tour is bookable, date format YYYY-MM-DDIF a date based availability search then next_bookable_date will be the first date in the range that is bookable

next_bookable_date_norange

First date the tour is bookable, date format YYYY-MM-DDWill be the true (public) next bookable date, constant even if a date range search has been requested (i.e. may not be in the requested date range)

last_bookable_date

Last date the tour is bookable, date format YYYY-MM-DDDoes not change depending upon whether a date based search or not

If 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 on the booking. Not returned when a Marketplace Agent is using the API.

channel

The channel node contains the following child nodes.

XML Node

Notes

channel_name

Channel name (Company name)

logo_url

Channel logo URL

lang

Channel language.

Additional languages may be spoken on the tour, see "languages_spoken".

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

Notes

start_date

Start date for this date

end_date

End date for this date

start_time

Start time for the Tour 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_time

End time for the Tour 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_code

This is the "Departure code" from a Tour Operators perspective, may be empty

note

Product note

min_booking_size

Minimum number of people required per booking, e.g. 1

spaces_remaining

Number of people that can still book for this date. Generally numeric however could contain the text UNLIMITED

Display version of the price for 1 person including currency symbol / code. E.g €100.00

price_2

Price 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_display

Display 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_datetime

Date and tine the special offer was created. Format YYYY-MM-DD HH:MM:SS

special_offer_note

Text note on the special offer, e.g. "20% off early bookings"

original_price_1

The original price for 1 person (before the discount was applied). E.g. 120.00

original_price_1_display

Display version of the original price for 1 person (before the discount was applied). Includes currency symbol / code. E.g. €120.00

original_price_2

The original price for 2 people (before the discount was applied). E.g. 200.00

original_price_2_display

Display 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 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 Node

Notes

start_date

Start date for this date

end_date

End date for this date

start_time

Start time for the Tour 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_time

End time for the Tour 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_code

This is the "Departure code" from a Tour Operators perspective, may be empty

note

Product note

min_booking_size

Minimum number of people required per booking, e.g. 1

spaces_remaining

Number of people that can still book for this date. Generally numeric however could contain the text UNLIMITED

Display version of the price for 1 person including currency symbol / code. E.g €100.00

price_2

Price 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_display

Display 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_datetime

Date and tine the special offer was created. Format YYYY-MM-DD HH:MM:SS

special_offer_note

Text note on the special offer, e.g. "20% off early bookings"

original_price_1

The original price for 1 person (before the discount was applied). E.g. 120.00

original_price_1_display

Display version of the original price for 1 person (before the discount was applied). Includes currency symbol / code. E.g. €120.00

original_price_2

The original price for 2 people (before the discount was applied). E.g. 200.00

original_price_2_display

Display version of the original price for 2 people (before the discount was applied). Includes currency symbol / code. E.g. €200.00

dates_public_bookable

Upto 100 start dates that are public bookable

If a search by date range, these dates will be within the range, if a general search, will be next 100 dates.

XML Node

Notes

date

Start date for this date

dates_has_offer

Upto 100 start dates that are public bookable, and have a special offer,

If a search by date range, these dates will be within the range, if a general search, will be next 100 dates.

XML Node

Notes

date

Start date for this date

If API called by Tour Operator (not Marketplace Agent)

custom1

If any single line "Extra tour data fields" have been configured in TourCMS, this field will contain the value of the first one (ordered alphabetically).

Useful for displaying custom information or indicators against particular products, such as loading icons for particular activity types

custom2

If any single line "Extra tour data fields" have been configured in TourCMS, this field will contain the value of the second one (ordered alphabetically).

Useful for displaying custom information or indicators against particular products, such as loading icons for particular activity types

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