TravelSearch 3 - Search Api

This document describes all the functions that the TravelSearch supports and describes every used object and their fields.

Service communicating
Functions
Objects

Service communicating

All service communication is performed using the JSON format.

Search service endpoint

The service can be reached at https://search.qenner.com using the default port 443.

Authentication

Authentication us performed using an HTTP Authentication header, using an Api-Key provided by Qenner. Example header:

Authorization: ApiKey QEN1-DE7D5606-111225FA-FFC7C2B6-740B8FED

Localization

The service supports multiple languages, provide an 'Accept-Language' header to indicate the language to support. Note that while not providing this header will work, we cannot ensure that the resulting language stays the same.

Accept-Language: it-IT

Resultcode

Correct calls result in a statuscode of 200.
Validation problem result in a 400 Bad Request. When these occur you should evaluate the resulting ErrorResponse, containing a validation object.
Other problems result in a 500 Server error. When these occurs you've stumbled on a bug on our side. And the resulting ErrorResponse might not be completely helpful to you.

Functions

getCriterionTypes()

Returns all supported CriterionTypes and details regarding there usability.

Path: /criterionTypes
Method: GET
Returns: CriterionTypesResponse

getCriteria(CriteriaRequest)

Used to retrieve all possible Criterion's of the desired CriterionTypes within the current selection.

Path: /criteria
Method: POST
Returns: CriteriaResponse

search(SearchRequest)

Used to retrieve all search results for the current selection, paginated.

Path: /search
Method: POST
Returns: SearchResponse

getAutoComplete(AutoCompleteRequest)

Used to retrieve criteria suggestions for a given search text. Validates the search string against beginning of all words of all criteria.

Path: /autoComplete
Method: POST
Returns: AutoCompleteResponse

getPrices(PricesRequest)

Used to retrieve all prices for the given selection.

Path: /prices
Method: POST
Returns: PricesResponse

getAccommodationInfo(AccommodationInfoRequest)

Used to retrieve accommodation info, including images.

Path: /accommodationInfo
Method: POST
Returns: AccommodationInfoResponse

getReviewInfo()

Used to retrieve information about a given accommodation.

Path: /reviewInfo
Method: POST
Returns: ReviewInfoResponse

getAccountInformation()

Used to retrieve information about the current account.

Path: /accountInformation
Method: GET
Returns: AccountInformationResponse

Objects

This section tries to describe every object and its contents. This document uses Map to describe an object with predetermined keys. Technically this will also be json objects.

Messages
Criterion and Search related objects
Price objects
PriceCalculation objects
TransportDetails objects
AccommodationInfo Objects
Review and Rating objects
Other Objects

Messages

Request and responses for communicating with the service.

TravelSearchRequest

Every request object inherits from this object. They contain the following optional field.

travelSearchOptions Map[TravelSearchOption: Value]

CriteriaRequest

selectedCriteria Array[Criterion]
requestedCriterionTypes Array[CriterionType]

SearchRequest

selectedCriteria Array[Criterion]
returningCriterionTypes Array[CriterionType]
sortCriteria Array[CriterionType]
pageSize integer (min. 1)
pageNumber integer (min. 1, max. 50)

AutoCompleteRequest

text string (min. 3 characters)
transportType strings|null
count integer (max 50)

PricesRequest

selectedCriteria Array[Criterion]

AccommodationInfoRequest

selectedCriteria Array[Criterion]

ReviewInfoRequest

selectedCriteria Array[Criterion]
pageSize integer (min. 1)
pageNumber integer (min. 1, max. 50)

TravelSearchResponse

Every response object inherits from the TravelSearchResponse object. They contain the following optional fields:

request TravelSearchRequest, the original request echoed back.
info Map[String, Object]

When the Server added some default values or restrictions to your request, the changes will be visible here.

At this moment the info contents are a "validation" key with Validation object.

CriterionTypesResponse

The CriterionTypesResponse contain a definition of all currently supportred CriterionTypes.

criterionTypeDefinitions Array[CriterionTypeDefinition]

This is the only response object that does not echo a request;

CriteriaResponse

The CriteriaResponse contains the overall resultcount of the current selection, and every requested criterion set.

resultCount integer
criterionSets Array[CriterionSet]

SearchResponse

The SearchResponse contains the overall resultcount of the current selection, and all the search results. private int resultCount;

resultCount integer
searchResults Array[SearchResult]

AutoCompleteResponse

The AutoCompleteResponse contain the criteria that correspond with your request.

criteria Array[AutoCompleteCriterion]

PricesResponse

The PricesResponse contains a structured overview of all the prices.

accommodations Array[PriceAccommodation]

AccommodationInfoResponse

The AccommodationInfoResponse contains one or more AccommodationInfo objects for the requested accommodation.

accommodationInfoObjects Array[AccommodationInfo]

ReviewInfoResponse

The ReviewInfoResponse contains a ReviewInfo object containing one or more reviews.

information ReviewInfo

AccountInformationResponse

The AccountInformationResponse contains a AccountInformation object for the current account.

accountInformation AccountInformation

ErrorResponse

An error response is returned in case an error or validation problem occurs. When available the validation object in the response may help you resolve this error.

code = integer
message = string

CriterionType

This is an enumeration of strings. There existence can be dynamically determined using the getCriterionTypes function. Currently the following CriterionTypes are supported: Check the search overview Search Overview / Supported criteria for more details on the supported criteria and their usage.

TravelSearchOption

This is an enumeration of strings. The current supported TravelSearchOptions are:

IncludeCriterionResultCounts boolean
IncludePriceCalculation boolean
IncludeTransportDetails boolean
SearchResultLevel string, one of AccommodationId, OsiCode, - TextSearchIncludeAccommodations boolean
TextSearchIncludeLocations boolean
TextSearchIncludeTravelCharacteristics boolean
TextSearchIncludeShortDescriptions boolean
AllowShortDescriptionLanguageFallback boolean
AllowShortDescriptionTourOperatorFallback boolean
AllowThumbnailTourOperatorFallback boolean
IncludePackageInfo boolean
IncludeAdditionalCosts boolean

Criterion

A Criterion is combination of a CriterionType and a value. It is enough to indicate a selection.

type CriterionType(which is a string)
value string

NamedCriterion

Extends the Criterion object, by adding a localized user readable name. It will mostly be NamedCriterion's used in CriterionSets and SearchResults.

type CriterionType(which is a string)
value string
name string

CountedCriterion

Extends the NamedCriterion object. When supported and requested some of the Criterion's used in CriterionSets will be CountedCriterion, it adds a resultCount to the individual criterion.

type CriterionType(which is a string)
value string
name string
resultCount integer

ContentCriterion

Extends the NamedCriterion object. The Thumbnail and ShortDescription criterion with use this type in the SearchResults.

type CriterionType(which is a string)
value string
name string
provider string
providerName string
languageCode string

PricePerPersonCriterion

A CriterionType (PricePerPerson) specific object used in SearchResults. It extends the NamedCriterion with a PriceCalculation object.

type CriterionType(which is a string)
value string
name string
priceCalculation PriceCalculation
packageInfo PackageInfo (optional)
priceInfo PriceInfo (optional)
deprecated fields:
- additionalCosts Array[AdditionalCost] (optional) moved to be part of PriceInfo

TransportsCriterion

A CriterionType (Transports) specific object used in SearchResults. It extends the NamedCriterion with a TransportDetails object.

type CriterionType(which is a string)
value string
name string
transportDetails TransportDetails

RatingCriterion

A CriterionType (Rating) specifiy object used in SearchResults. It extends the NamedCriterion with a RatingDetails object.

type CriterionType(which is a string)
value string
name string
ratingDetail ratingDetails

AutoCompleteCriterion

The criterion objects resulting from a autocomplete request. It extends the NamedCriterion and add related criteria.

type CriterionType(which is a string)
value string
name string
relatedCriteria Array[NamedCriterion]

CriterionSet

A criterionset contains a collection of criterions for a specific types. i.e. All Criterion items of the Country CriterionType.

type CriterionType
name string
criteria Array[NamedCriterion], this can be CountedCriterion items based on request options and type.

SearchResult

id string
criteria Array[NamedCriterion], depending on type this can also be a PricePerPerson or a TransportsCriterion object.

Price objects

Objects used in the getPrices function.

PriceAccommodation

Representing a unique bookable accommodation.

name string
id string
tourOperatorName string
tourOperator string
accommodationProvider
accommodationProviderName
accommodationType string
options Array[PriceOption]

PriceOption

Representing a unique travel configuration within a PriceAccommodation

transportType string
boardType string
nightCount integer
departureAirport string
arrivalAirport string
dates Array[PriceDate]

PriceDate

A combination of dates and there prices within a PriceOption. Note that a startDate isn't unique within its array, as there could be multiple flight options on the same date. Use the optional transportDetails object to find the actual difference between 2 or more prices on the same date.

startDate integer (yyyymmdd)
price integer (cents)
transportCode string (optional)
priceCalculation PriceCalculation (optional, use TravelSearchOption IncludePriceCalculation)
transportDetails TransportDetails (optional, use TravelSearchOption IncludeTransportDetails)
packageCode string (optional)
packageInfo PackageInfo (optional)
priceInfo PriceInfo (optional)
deprecated fields:
- additionalCosts Array[AdditionalCost] (optional) moved to be part of PriceInfo

PackageInfo

An object describing a package, with code and name and optional flags.

name string
code string
flags Array[string] (IncludingTransfer,ExcludingTransfer,IncludingCarRental,IncludingSkiPass)

PriceInfo

An object with more information on the provided price.

price integer The price per person in cents
includedInPrice Array[String] what is already included in the standard price, values:
- Base a base price, always available
- Sqr, indicates that the base price contains the Sgr fund
- CalamityFund, indicated that the base price contains the Calamity fund
- ReservationCosts, indicate that the base price contains the reservation costs
- AdministationCosts, indicates that the base price contains the administration costs
- TouristTax, indicates that the base price contains the tourist tax
priceIncludingAdditionalCosts The price per person in cents, containing all required additional costs
addtionalCosts: Array[AdditionalCost] contains all specif additional require costs.

AdditionalCost

An object describing extra online costs, that aren't included in the search price.

type string (Sgr,CalamityFund,ReservationCosts,AdministrationCosts,Other,TouristTax)
name string
cents integer
currency String
perPerson boolean
perNight boolean
perDay boolean

PriceCalculation objects

Contains the price calculation that describes how the PricePerPerson is calculated, using component prices and price rules. This is not for end-user (at least never for consumer) display.

PriceCalculation

totalPrice integer
components Array[PriceCalculationComponent]

PriceCalculationComponent

totalComponentPrice integer
product PriceCalculationProduct
rules Array[PriceCalculationRule]
userId String (not used)

PriceCalculationProduct

type string, one of Accommodation, Flight or PackageCombination
id string
price integer (cents)
count integer (always 1)

PriceCalculationRule

A rule that should be applied in order to come to the total price. Many fields may be 'null' indicating this rule isn't explicitely restricted to that field.

markupFactor double
markupCents integer
provider string, may be null
country integer, may be null, only used for Accommodation and PackageCombination 'products'.
osiCode string, may be null, only used for Accommodation products.
departureAirport, may be null, only used for Flight 'products'
arrivalAirport, may be null, only used for Flight 'products'
description, may be null, internal description, inputted in the backend.

In order to calculate a products price. You need to take it's base price and apply a rule in order. To apply a rule first multiple the result with the markupFactor then add the markup cents.

For PackageCombination there isn't a base price. Instead you need to start with the calculated prices of the other components.

TransportDetails objects

A TransportDetails object, part of the search-results or price response.

TransportDetails

Describes the transport details for a given item.

outbound Array[TransportDetailsItem]
inbound Array[TransportDetailsItem]

TransportDetailsItem

Describes an specific transport component of the trip. It depends on the type which information available which fields are filled.

Please note that even for a dynamically associated flight, still not all information might be available.

type string, currently supported PackagedTransport and Flight. In case of PackagedTransport none of the other fields will be available.
departureAirport string
departureAirportName string
arrivalAirport string
arrivalAirportName string
departureDate integer (yyyymmdd)
departureTime integer (hhmm)
arrivalDate integer (yyyymmdd)
arrivalTime integer (hhmm)
transportProvider string
transportProviderName string
carrier string
carrierName string
flightNumber string
flightLegs Array[FlightLeg]

Carrier and Flight numbers

The carrier and carrierName fields, are only filled with valid info if all flight's legs are of the same carrier. In case of multiple legs, the flightNumber is set to the number of the first leg.

FlightLeg

Describes a flight leg. A flight consists out of 1 or more legs. Please note that not all information might be available.

departureAirport
departureAirportName
arrivalAirport
arrivalAirportName
carrier
carrierName
flightNumber

AccommodationInfo Objects

Used to describe an accommodation with content and pictures.

AccommodationInfo

id string
name string
osiCode string
osiCodeName string
accommodationType string
accommodationTypeName string
accommodationProvider string
accommodationProviderName string
countryName string
districtName string
placeName string
starClassification integer (10 * stars, e.g 4.5 stars is 45)
pictureUrls Array[string]
xmlDescription string

The xml description contains the content (and pictures) of the acccommodation, in the qenner accommodationinfo format. This format can be downloaded at: accommodation.xsd

Review and Rating objects

Used to describe an accommodations rating and its reviews.

RatingDetails

Used to describe average Rating and details of an Accommodation

mainRating int, The main rating 0-100
baseCount int, The number of reviews that led to this rating
ratingSpread Array(int), a weighted percentile spread of all ratings 0,0,0,20,80 means 20* rated 6-10, 80% of the people rated a 8-10.
recommendationPercentage int
provider string, provider
detailRatings Array(int), named array with values 0-100 per subject
viewReviewsUrl string, link to this accommodations page on the providers site.

ReviewInfo

Object containing a set of reviews

reviewCount int, total number of reviews for the accommodation
ratingDetails RatingDetails, base RatingDetails for the accommodation
reviews Array(Reviews), the requested set of reviews
terminology Array(string), named array with the name various keys used in the review.

Review