Recommendations Guide

Table of Contents

1. Introduction
2. Grouping configuration
3. Algorithm configuration
4. Recommendation response

Introduction

(back to Table of contents)

Each search-endpoint that takes in any kind of information about geography, has the option to supply recommendations. Recommendations groups offers based on certain attributes, matching the specified recommendationConfig object of the request. This can be a particularly useful feature if you are looking for a specific type of offer, but are not sure which one to choose. It also includes for which travellers and what part of the journey/area the recommendation is valid for.

Grouping configuration

(back to Table of contents)

Each recommendation is categorized by different attributes. The client may provide which attributes they would like to group the recommendations by. Note that each offer may be recommended in more than one combination of grouping attributes. Attributes for recommendations are divided into flexibility, duration type, fare class and facility set, and are specified in the categorySpec part of the recommendationConfig.

• Flexibility - how flexible the offer is in terms of exchangeability and refundability. This is requested by the typesOfRecommendation array, where the last option CHEAPEST ignores the flexibility but selects the cheapest offer that fits the other requested attributes.
  • NON_FLEXIBLE no refund or exchange options
  • SEMI_FLEXIBLE can refund or exchange but not both
  • FLEXIBLE both refundable and exchangeable
• DurationType - the duration of the period ticket the offers describes. The most typical values are:
  • SINGLE_TRIP valid for one trip
  • DAY_PASS valid for a day
  • WEEKLY_PASS valid for a week
  • MONTHLY_PASS valid for a month
  • SEASON_TICKET valid for a season or a year
  • CARNET valid for a number of trips
• FareClass - the class of the product offered. i.e. PREMIUM_CLASS or STANDARD_CLASS
• FacilitySet - to request recommendation for offers with specific facilities that goes beyond a simple right of travel such as SEATING, RECLINING_SEAT, SLEEPER or COUCHETTE

In addition to specific attributes provided in categorySpec, it is also possible to specify wildcard values for most of the attributes such as ANY for fareClasses or ANY_FACILITY_SET for facilitySet. This allows for combining recommendations that point to offers that have a specific attribute, but also recommend the cheapest options when not taking the attribute into consideration. Typically useful for grouping offers for e.g. sleeper and non-sleeper, but still recommending the cheapest option within each grouping. If any of facilitySet, fareClass or durationType is not specified, it will implicitly act as a wild card and the recommendation will include all offers that fit the other specified attributes. typesOfRecommendation always has to contain at least one value.

Detailed examples

Below follows some detailed examples showing the result of applying a subset of the available grouping attributes.

All examples below show examples of classification of the following example Offers

Cheapest overall

• typeOfRecommendation: CHEAPEST

Cheapest across flexibility

• typesOfRecommendation: CHEAPEST, NON_FLEXIBLE, SEMI_FLEXIBLE, FLEXIBLE

Cheapest across FacilitySets

• typesOfRecommendation: CHEAPEST
• facilitySet: ANY_FACILITY_SET, SEATING, COUCHETTE, SLEEPER

Cheapest across FacilitySets and flexibility

• typesOfRecommendation: CHEAPEST, NON_FLEXIBLE, SEMI_FLEXIBLE, FLEXIBLE
• facilitySet: ANY_FACILITY_SET, SEATING, COUCHETTE, SLEEPER

Note that the combinations of NON_FLEXIBLE + SLEEPER, SEMI_FLEXIBLE + COUCHETTE and FLEXIBLE + SEATING are not recommended due to no available offers in those combinations of attributes

Cheapest across durationType

• typesOfRecommendation: CHEAPEST
• durationType: SINGLE_TRIP, WEEKLY_PASS, MONTHLY_PASS

Algorithm configuration

(back to Table of contents)

For more control over how the recommendations are calculated, you can specify rules in the ruleSpec part of the recommendationConfig:

• journeyOrganizeAlgorithm - how the recommendations are created for parts of a composite journey, where a leg is identified by a service journey id. The available options are (with an example journey of 3 legs; SJ1, SJ2 and SJ3):
  • SUBSEQUENT_COMBINATIONS - all possible subsequent combinations of legs, i.e. recommendations for SJ1, SJ2, SJ3, SJ1+SJ2, SJ2+SJ3 and SJ1+SJ2+SJ3
  • COMBINATIONS_FROM_OFFERS - all unique journey combinations covered by offers in the response
  • FOR_EACH_AND_GROUPED_COMBINATIONS - one for each individual part of the journey in addition to the entire trip, i.e. recommendations for SJ1, SJ2, SJ3 and SJ1+SJ2+SJ3
• priceComparisonAlgorithm - how the price of the offers are compared when picking offers to buy for a recommendation. The default is TOTAL_PRICE which compares the actual price for the offer. The other option is BEFORE_SDR which compares the price of the offer before a discount to the product is applied. BEFORE_SDR can be useful if the traveller has an entitlement that gives them offers with greatly reduced prices, but the original price matter in terms of later taxation, or other considerations.
• onlyIncludeRecommendedOffers - if set to true, only offers that are recommended will be included in the response. The default is false.
• onlyIncludeRecommendationsWithOffersToBuy - if set to true, only recommendations which actually points to offers to buy will be included in the response. Often it does not exist offers such that every criterion in the requested recommendation config can point to an offer to buy, so this can be used to filter out recommendations that can be considered void. The default is true.
• mixinOffersWithHigherFlexibility - if set to true, offers with higher flexibility will be included in the response. F.ex. if FLEXIBLE recommendations are requested and there exists a FLEXIBLE offer that is cheaper than a NON_FLEXIBLE offer, with this parameter set to true the FLEXIBLE offer will be recommended in the recommendation with category NON_FLEXIBLE. The default is true.

Recommendation response

(back to Table of contents)

The Recommendation object in the response from Offers contains the categories the recommendation is given fore, which matches the categorySpec in the request. In addition, it contains geographicalValidityCovered - the geographical area the recommended offers are valid for. This can be specific service journeys, validity between two stop places or zonal validity. Which fields are present depends on the search endpoint used to get the recommendations and the products offered. offersToBuy lists the ids of the offers that needs to be reserved in the Sales API to cover the travellers in the recommendation. selectableProductIds might be populated and refer to selectable ids of optional products (found in the response entity under the field optionalProducts) that has to be reserved in combination with the offer to achieve the fare class of the recommendation, f.ex. premium where the optional product is a premium upgrade. Selectable ids are parts of the request to the Sales API.

TravellerMapping

The possibleTravellerIds field lists the ids of the travellers that are valid for each offer recommended. Note that each offer may have restrictions on how many travellers can be assigned to each offer, described by its travellerMapping. Each offer may be used by minNumberOfTravellers and maxNumberOfTravellers per userType. Note the difference between the last two examples.