Search Overview

TravelSearch 3 - Search Overview

The Travel Search 3 service is search service, containing support for packaged and dynamically combined assortment.

Conceptional it tries not to move not too much away from the TravelSearch 2 version. However many elements have changed; either to be more functional or to better support the dynamic character of this assortment.

This service will eventually contain much more assortment than previous versions, since it constantly needs to combine accommodation and flights. Therefore more restrictions had to be put on the client when using the services.

Contents

Assortment structure

OsiCode

The OsiCode is the code for a physical accommodation, it is the main identifier for your search results, If multiple tour operators provide the same accommodation, they will share the same OsiCode, but have different AccommodationId's. When searching, you will get one result per OsiCode. This behavior can be altered by using the TravelSearchOption 'SearchResultLevel'.

Choosing between OsiCode and AccommodationId

In order to book, you need to have an AccommodationId. Instead of letting a user select an accommodationId from a list, you might want to let them choose implicitly by narrowing down further using StartDate, TransportType, Boardtype and the NightCount. Then its up to you to simply use the cheapest option or provide the user with even more options:

  • Use TravelSearchOption 'IncludePackageInfo' to include more package information in the search results.
  • This way you can differentiate by:
    • TourOperator
    • AccommodationType if there are multiple options for the same OsiCode.
    • PackageFlags, indicating Transfer or Car-rental inclusion.
    • PackageName/Code, although these not always have a meaningful or user-friendly name.

It is very important to work with and show accommodation related information when going to the book-process. Don't use the Osi-name or Osi-level images, but use the information related to the AccommodationId, as this is what you will be booking on. This is especially important when working with multiple tour operators for the same accommodation, as they can have different names and images for the same OsiCode.

Another reason for importancy, is that OsiCodes are mostly determined automatically, therefore, there is a change that an AccommodationId actually represents a different accommodation than the OsiCode it is related to. This can for example when our matching process fails, or when a tour operators supplies us with inappropriate meta-information. Showing the correct accommodation name, location and images can prevent your user from mistakenly booking a different accommodation than they expected.

Functional steps

Functional the search process will be the same as previously in the TravelSearch 2.

  1. The getCriteria function is called 1 or more time in order to drill down to compose a desired selection.
  2. The Search function is called with the selection composed in the previous step.
  3. Optionally the search function is called more times, for different pages or different selections.
  4. The getAccommodationInfo function is used to retrieve and display accommodation information.
  5. The getPrices function is used to retrieve a set of prices.
  6. Step to book-process. Use information retrieved from the search-service and call the booking-service.

.

Assortment restrictions

  • The TravelSearch 3 strictly supports 1 price for its assortment, this is a per person (adult) price, based on 2 persons (where possible).
  • Only Flights and accommodations from 1 - 28 nights are supported.

.

Selection requirements

This describes the minimum required selections a call expects.

Selection requirements for Criteria

  • None

There are no longer any selection requirements for search. Note that when providing a MinimumStartDate and no MaximumStartDate, a MaximumStartDate of 7 days later will be provided.

  • Sorting on GpsDistance is only allowed when GpsLocation is one of the selected criterions.

Selection requirements for Prices

  • Exactly 1 AccommodationId OR 1 OsiCode criterion must be selected.
  • A Startdate period must be provided, either by supplying 1 StartMonth selection, by supplying 1 through 8 StartDate selections, or by supplying a Minimum- and a MaximumStartDate selection with a range of maximum 8 dates.

Selection requirements for AccommodationInfo

  • Exactly 1 AccommodationId OR 1 OsiCode criterion must be selected.
  • For future compatibility with for example season dependent content, you may also want supply a valid StartDate or StartMonth selection.

.

Criteria workings

  • A Requested CriterionSet contains all criteria of the requested type, based on the current selection.
  • A selection of the requested type is ignored, e.g. when requesting all countries the current selected Country is ignored, when requesting NightCount current selected (Minimum-/Maximum-)NightCount is ignored.
  • When requesting a CriterionSet for a criterion types with FilterType 'and' the existing selections of that type are not ignored (i.e Characteristic).
  • When requesting a StartMonth or StartDate CriterionSet existing selections regarding StartDate are not ignored.

CriterionTypes

Use the criterionTypes method, to find all supported CriterionTypes. Selectable CriterionType are divided into 2 types, those with FilterType.And and those with FilterType.Or

  • FilterType.Or
    • This is the most common type. When adding multiple selections of the same CriterionType with FilterType.Or, a search-result must match with 1 of these. (e.g. select 2 countries, one must match.)
  • FilterType.And
    • When adding multiple selections of the same CriterionType with FilterType.And, a search-result must match with all of them. (e.g. select 2 characteristics, both must match.)
  • FilterType.na
    • These types may only be selected once, or not at all.

Check Supported criteria for all supported CriterionTypes and their FilterType.

Implicit restrictions

  • When requesting Country; the Place and District selections are ignored
  • When requesting District; the Place selections are ignored
  • The Place CriterionSet will be empty if no Country is selected
  • The District CriterionSet will be empty if no Country or Region is selected
  • The OsiCode CriterionSet will be empty if no Place is selected
  • The AccommodationId CriterionSet will be empty if no OsiCode is selected
  • ArrivalAirport and Carrier CriterionSet will be empty of no Country, District, Place, OsiCode or AccommodationId is selected;

Criteria resultCount

A criterionSet contains NamedCriterion objects. These are contain all possible values of that Criterion type within the current selection. To enhance performance they no longer contain per value resultCounts as in previous versions. You can use the TravelSearchOption 'IncludeCriterionResultCounts' to return CountedCriterion objects instead of NamedCriterion's, these also contain a resultCount field, however, this is not supported for all CriterionTypes. Check the 'criterionTypes' method to verify which CriterionTypes support resultcounts.

The CriterionTypes that currently support resultcounts in a criteria call are:

  • Country
  • District
  • Place
  • Region

Supported criteria

The following is an overview of the currently supported CriterionTypes.

  • Request, means you can request a CriterionSet of this type using getCriteria
  • Select, means you can select on this type on the various methods, including search and criteria
  • Result, means this type can be part of the search result, use as returningCriterionTypes in search method
  • Sort, means you can sort on this type in the search method, use as sortType in search method
  • Multiple, means you can select multiple values of this type, and the filterType for this
    • or means in case of multiple selections, a search-result must match with 1 of these
    • and means in case of multiple selections, a search-result must match with all of these
    • n/a means items of this type cannot be selected or only once
    • Max. indicates the maximum number of items of this type that can be selected
Type Request Select Result Sort Multiple Max.
AccommodationFacility true true true false and 99
AccommodationId true true true true or 50
AccommodationProvider true true true false n/a 10
AccommodationType true true true false n/a 1
ArrivalAirport true true true false or 10
BoardType true true true false or 10
Carrier true true true false or 10
Chain false false true false or 99
Characteristic true true true false and 99
Country true true true true or 10
DepartureAirport true true true false or 10
District true true true true or 10
EndDate true true true true or 8
GiataID* false false true false or 50
GpsDistance false true true true n/a 1
GpsLocation false true true false n/a 1
LeisureFacility true true true false and 99
MaximumBoardType false true false false n/a 1
MaximumEndDate false true false false n/a 1
MaximumFlightLegs true true false false n/a 1
MaximumNightCount false true false false n/a 1
MaximumPricePerPerson false true false false n/a 1
MaximumRating false true false false n/a 1
MaximumStarClassification false true false false n/a 1
MaximumStartDate false true false false n/a 1
MinimumBoardType false true false false n/a 1
MinimumEndDate false true false false n/a 1
MinimumNightCount false true false false n/a 1
MinimumPricePerPerson false true false false n/a 1
MinimumRating false true false false n/a 1
MinimumStarClassification false true false false n/a 1
MinimumStartDate false true false false n/a 1
NightCount true true true true n/a 1
OsiCode true true true true or 50
Place true true true true or 10
PricePerPerson true true true true n/a 1
Rating true true true true n/a 1
Region true true true false or 3
RoomFacility true true true false and 99
ShortDescription false false true false n/a 0
StarClassification true true true true n/a 1
StartDate true true true true or 8
StartMonth true true true false n/a 1
Text false true false false n/a 1
Thumbnail false false true false n/a 1
TourOperator true true true false or 10
TransportProvider true true true false n/a 1
Transports false false true false n/a 1
TransportType true true true false n/a 1
TravelType true true true false and 99
  • Not available by default

Sorting

Directional sorting is not supported, a fixed direction is set per sort type.

  • StartDate, from past to future.
  • PricePerPerson, NightCount from low to high.
  • All others are alphabetically.
  • Sorting is a little less accurate when using a StartMonth instead of StartDates.

.

Text Search & AutoComplete

AutoComplete

Autocomplete is possible by using the AutoComplete method. The request requires a text of at least 3 characters long to function, and supports a predetermined TransportType.

The TravelSearch matches the text with the start of all criterion names, ignoring case, punctuation and special characters.

The autocomplete matches with the following source groups of information:

  • Locations: Country, District, Place
  • Accommodations: OsiCode (name of the accommodation)
  • TravelCharacteristics: AccommodationType, Characteristic, TravelType

Use TravelOptions to change in which groups the TravelSearch searches.

For some criteria extra criteria is returned to provide some context for the resulting criterion:

  • OsiCode: Place, District, Country, AccommodationType
  • Place: District, Country
  • District: Country

Text Search

Searching on text is possible by selecting the Text criterion, which also has a 3 character minimum.

When searching using the Text criterion the TravelSearch matches with whole words, ignoring case, punctuation and special characters).

When searching using the Text criterion an extra source group of information is available:

  • ShortDescriptions: ShortDescription

By default the Text search searches in all 4 groups, this can also be changed by using the same text search related TravelSearchOptions.

.

Reviews & Ratings

Currently the TravelSearch only supports Ratings and Reviews provided by Travel Trust It. Rating as well as Review support are additional features which are not enabled by default.

Ratings

Ratings can be requested as part of your search-results and search upon using the (Minimum/Maximum)Rating criterion-types. The RatingCriterium contains a RatingDetails object, containing detailed sub-ratings, as well as other rating information.

Reviews

Reviews can be request using a new getReviewInfo function, on a per accommodation base. All available reviews can be requested on a per page based.

.

Request validation

Every request gets validated and validation results are placed in the response. (->info->validation). A validation response, contains a list of errors, warnings and notes. All of these are to improve the client development process. Note that when the validation contains one or more errors, the validation may not be completed and not all warnings or expected notes may be included.

Api-users can use the validation results to alter and improve their implementation. The goal is to work to remove all warnings. The validation messages are not for end-user display, and should not be used as part of a websites functionality, use the warnings during development to better restrict your interface and logic; warnings and their format may change without notice.

.

TravelSearchOptions

You can add TravelSearchOptions to every request. It depends on the method whether they can be used.

  • IncludeCriterionResultCounts, used with the 'criteria' method, when the CriterionType supports it, resultCounts per item are added. (value true)
  • IncludePriceCalculation, used with the 'price' and 'search' method, per price a PriceCalculation object is added. (value true)
  • IncludeTransportDetails, used with the 'price' and 'search' method, per price a TransportDetails object is added. (value true)
  • IncludePackageInfo, used with the 'price' and 'search' method, a PackageInfo object is added when appropriate. (value true)

  • IncludeAdditionalCosts, used with the 'price' and 'search' method, a list of AdditionalCosts is added when appropriate. (value true)

  • ExcludeDescriptionlessAssortment, assortment without a shortdescription and probably no AccommodationInfo will be omitted

  • ExcludeThumblessAssortment, assortment without a thumbnail will be omitted.
  • ExcludeGpslessAssortment, assortment without gps info will be omitted.
  • SearchResultLevel, used with the 'criteria' and 'search' method. By default the Search Service returns one result per OsiCode. Use the following values to alter this behavior:
    • AccommodationId, One search-result per bookable accommodation.
    • OsiCode, One search-result per unique (physical) accommodation.
    • AccommodationType, One search-result per unique (physical) accommodation in combination with accommodation type. The same Accommodation may result in a Hotel search-result and a Apartment search-result, with the same Osicode.
  • TextSearchInclude*, used with 'criteria' and 'search' and 'autoComplete' methods. Used to specify in which information group the TravelSearch should search. By default it searches in all available groups. Specify one or more of these options to override the default setting (value true):
    • TextSearchIncludeAccommodations: Searches in accommodation names (AutoComplete returns OsiCodes)
    • TextSearchIncludeLocations: Searches in location names (AutoComplete results Country, District, Place)
    • TextSearchIncludeTravelCharacteristics: Searches in names of AccommodationType, Characteristic and TravelType (AutoComplete returns these criterion types).
    • TextSearchIncludeShortDescriptions: When searching the ShortDescription of every accommodation gets searched, this option is not supported for the AutoComplete.

  • GpsDistanceMode, used when searching on GpsLocation and GpsDistance. By default the Search Service search in a radial distance around the GpsLocation; use one of the following values to alter the behavior:

    • Radial, search in a radius of GpsDistance around the GpsLocation
    • Square, search in a square box with a radius of GpsDistance around the GpsLocation, the box is sized, as to exactly fit in a circle with the GpsDistance radius.

  • Content fall back, used with search 'method', fallbacks on other content, not specific to the current result or language, but still the same accommodation.

    • AllowShortDescriptionLanguageFallback: When not available in the current language, a short description in an other language may be resulted.
    • AllowShortDescriptionTourOperatorFallback: When not available for the current touroperator, a short description in an from an other (within you assormment) may be resulted.
    • AllowThumbnailTourOperatorFallback: When not available for the current touroperator, the thumbnail for the same accommodation, but supplied bt an other touroperator may be resulted. .

Best Practices, Caching & Performance

The Search Service is dynamically finding flights fit for all accommodations, this requires lots of time and energy. So, more than before it is important to not request what is not used.

Some of the steps the Search Service does to increase performance:

  • By default resultcounts are not included in criteria requests.
  • Sorting is less accurate when not using the ((Minimum-/Maximum) StartDate) criteria.
  • Criteria results may be a little less accurate when requesting, although continuous effort is performed to increase accuracy without affecting performance.
  • Adding minimal requirements to search requests, which are StartDate/Month, NightCount(-ranges) and TransportType.

Important steps you can do to increase and uphold performance

The following is a list of suggestions you can do to increase performance. It would be advised to enforce some of these in your interface and not allow for an alternate path.

  • Only request criteria you are using, regarding criteria and search calls.
  • Use StartMonth for browsing, instead of StartDate (ranges), it allows for more results and is more optimized on service level.
  • Prefer not to use per criteria resultcounts.
  • Try to add as much criteria to a selection before you start searching.
  • Offer the user as many presets as possible on a 'start page'. As StartDate/Month, and NightCount(-ranges) and TransportType are required, we suggest pre-select these and don't allow for an 'all-option'.
  • Try to course the user to destination as soon as possible.
  • Requesting criteria with with price selections is quite intensive, try to avoid this, or only allow it with more than the minimum selection criteria.

Technically possible, although not advised

Some criteria are provided, but are extremely intensive. Important: Further restrictions may be imposed later.

  • TransportProvider; this criteria is slow and it not is not advised for usage in generic conditions, especially without any other selections.

Caching

Caching Travel Search responses can help increase your site's performance, but can reduce the quality of information.

  • AccommodationInfo, this doesn't change very often. Local caching could be done for 24h.
  • Criteria, criteria and their options change minimal during the day. A medium long cache (<=30min) is advised. Note that a more specific selection, may require a shorter cache as chances on criteria changes may be greater.
  • Search results, often sorted on price, change dependent on price changes, and thus may change often. A short cache (<=5min) is advised.
  • Prices, can change very often. A very short cache (<=2min) if any is advised. Prices are much faster to retrieve than in previous versions. They are even faster when they are restricted by criteria.

Front page caching

It is strongly advised to always use local caches for your home page, or other service starting point.

Web-Search-Engine recognition

Please be careful when making your website crawl-able by web-search-engine (i.e. Google). These can make many calls on your website, which can in turn do many TravelSearch calls.

When possible you may want to prevent TravelSearch calls initiated by webcrawlers; whether you are bound to a look-to-book ratio or otherwise a maximum number of calls, these calls will count towards your total calls and can negatively impact the TravelSearch.

Distribution dependencies

Using the Qenner Dashboard, the assortment enabled for a search channel can be updated, this can impact the response. Keep this in mind with your caching strategies. Not only will this affect the results, but also affect AccommodationInfo when requested using an OsiCode selection.

.

Advancing to the Booking service

To make the jump to the Booking service for the products found using this Search service, a bookRequest must be created using information found on various points in the getPrices response:

PriceAccommodation

  • id to be used as accommodationId

PriceOption

  • nightCount
  • boardType
  • transportType
  • departureAirport (optional)
  • arrivalAirport (optional)

PriceDate

  • startDate
  • transportCode to be used as preferredTransportCode (optional)
  • packageCode to be used as preferredPackageCode (optional)

The required countAdults, countChildren and countBabies field, should be provided by yourself, and not something the TravelSearch can provide. The birthdates, are optional, but preferred, should contain the birthdates of your travelers.

.

Special considerations

Dynamic Pricing

For each user, various pricing rules can be added to the assortment. The PricePerPerson item returned with search results contain a priceCalculation object (Optionally also available in the prices function). This object contains a worked out overview of how the price is build up. This is of course not for consumer display. But can help in debugging the shown price or give professional users an insight in how the price is build up.

Dynamic TourOperator

The QD touroperator can have a different name and logo depending on the used account, use the Taxonomy function to obtain the correct logo.

Caching

The various taxonomy functions describe a cache refresh suggestion. Use the shared cache identifier available in account information to improve shared caches.