SearchTripPatternRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/entur/main/json-schema/entur-search-trip-pattern-request-schema.json",
  "title": "SearchTripPatternRequest",
  "description": "A request used to search for fare products for a specified trip.",
  "x-generated": "2026-10-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/entur-offers-partner-openapi.yml#/components/schemas/SearchTripPatternRequest",
  "type": "object",
  "properties": {
    "travellers": {
      "type": "array",
      "description": "The travellers.",
      "items": {
        "$ref": "#/$defs/Traveller"
      },
      "minItems": 1
    },
    "recommendationConfig": {
      "$ref": "#/$defs/RecommendationConfig"
    },
    "tripPattern": {
      "$ref": "#/$defs/TripPatternRequest"
    },
    "groupConfig": {
      "$ref": "#/$defs/GroupConfig"
    },
    "includeMultiTripOffers": {
      "type": "boolean",
      "default": false,
      "description": "Indicates whether multi-trip offers should be included in the response, such as monthly passes, day passes, and similar options."
    }
  },
  "required": [
    "travellers",
    "tripPattern"
  ],
  "$defs": {
    "AccommodationFacilityEnum": {
      "type": "string",
      "default": "ANY",
      "description": "Subset of AccommodationFacilityEnumeration from NeTEx facility support.",
      "enum": [
        "ANY",
        "SLEEPER",
        "SEATING",
        "COUCHETTE",
        "RECLINING_SEATS",
        "STANDING"
      ]
    },
    "BaggageTypeEnum": {
      "type": "string",
      "description": "Type of baggage. Subset of BaggageTypeEnumeration from NeTEx usage parameter luggage support.",
      "enum": [
        "HANDBAG",
        "HAND_LUGGAGE",
        "SMALL_SUITCASE",
        "SUITCASE",
        "TRUNK",
        "OVERSIZE_ITEM",
        "BICYCLE",
        "SPORTING_EQUIPMENT",
        "SKIS",
        "MUSICAL_INSTRUMENT",
        "PUSH_CHAIR",
        "MOTORIZED_WHEELCHAIR",
        "LARGE_MOTORIZED_WHEELCHAIR",
        "WHEELCHAIR",
        "SMALL_ANIMAL",
        "ANIMAL",
        "GAME",
        "MOTORCYCLE",
        "OTHER"
      ]
    },
    "CappingSpecification": {
      "type": "object",
      "description": "Configuration on how to configure the discount right. Requires a CustomerIdentity with source ABT.",
      "properties": {
        "cappedDiscountRightId": {
          "type": "string",
          "description": "Reference to a CappedDiscountRight.",
          "pattern": "^[A-Z]{3}:CappedDiscountRight:.+$",
          "x-pattern-message": "Wrong format for NeTEx id. Must be on the format \"XXX:CappedDiscountRight:___\"."
        },
        "minimumDurationBetweenAlternatives": {
          "type": "string",
          "format": "duration",
          "description": "To avoid too many similar alternatives you can specify a minimum period between the start date of each alternative."
        },
        "minimumAlternativeDuration": {
          "type": "string",
          "format": "duration",
          "description": "Specify a minimum alternative duration to avoid alternatives that doesn't last long enough in the future to be useful."
        }
      },
      "required": [
        "cappedDiscountRightId"
      ]
    },
    "CategorySpec": {
      "type": "object",
      "description": "How to categorise and group recommendations based on different categories. Recommendations will attempt to calculate categories from the combination of input parameters.",
      "properties": {
        "typesOfRecommendation": {
          "type": "array",
          "default": [
            "CHEAPEST"
          ],
          "description": "Which categories to use for flexibility grouping.",
          "items": {
            "$ref": "#/$defs/TypeOfRecommendationEnum"
          },
          "minItems": 1
        },
        "durationTypes": {
          "type": "array",
          "default": [
            "ANY"
          ],
          "description": "If not specified, all durationTypes will be considered.",
          "items": {
            "$ref": "#/$defs/DurationEnum"
          },
          "minItems": 1
        },
        "fareClasses": {
          "type": "array",
          "default": [
            "ANY"
          ],
          "description": "If not specified, all fareClasses will be considered. Be aware that if not specified, the fareClass attribute in the recommendation object will read \"fareClass\":\"ANY\". To get the actual fareClass you would have to look up the corresponding offer.",
          "items": {
            "$ref": "#/$defs/FareClassEnum"
          },
          "minItems": 1
        },
        "facilitySet": {
          "type": "array",
          "default": [
            "ANY"
          ],
          "description": "If not specified, all accommodations will be considered. Be aware that if not specified, the facilitySet attribute in the recommendation object will read \"facilitySet\":\"ANY\". To get the actual facilitySet you would have to look up the corresponding offer.",
          "items": {
            "$ref": "#/$defs/AccommodationFacilityEnum"
          },
          "minItems": 1
        }
      },
      "required": [
        "typesOfRecommendation"
      ]
    },
    "CustomerIdentity": {
      "type": "object",
      "description": "One or more references identifying the customer.",
      "properties": {
        "customerRef": {
          "type": "string",
          "description": "A reference to a customer."
        },
        "source": {
          "type": "string",
          "default": "CUSTOMERS",
          "description": "Which system the customer information can be found in.",
          "enum": [
            "CUSTOMERS",
            "ABT"
          ]
        }
      },
      "required": [
        "customerRef",
        "source"
      ]
    },
    "DurationEnum": {
      "type": "string",
      "default": "ANY",
      "description": "Validity duration. Subset of UsageValidityTypeEnumeration from NeTEx usage parameter travel support.",
      "enum": [
        "SINGLE_TRIP",
        "RETURN_TRIP",
        "CARNET",
        "DAY_PASS",
        "WEEKLY_PASS",
        "WEEKEND_PASS",
        "MONTHLY_PASS",
        "SEASON_TICKET",
        "PROFILE_MEMBERSHIP",
        "OPEN_ENDED",
        "OTHER",
        "ANY"
      ]
    },
    "FareClassEnum": {
      "type": "string",
      "default": "ANY",
      "description": "A type of FareClass. Subset of FareClassEnumeration from NeTEx service restrictions support.",
      "enum": [
        "FIRST_CLASS",
        "SECOND_CLASS",
        "THIRD_CLASS",
        "ECONOMY_CLASS",
        "BUSINESS_CLASS",
        "TURISTA",
        "PREFERENTE",
        "PREMIUM_CLASS",
        "ANY",
        "STANDARD_CLASS",
        "UNKNOWN"
      ]
    },
    "GroupConfig": {
      "type": "object",
      "description": "A configuration of how to group travellers in offers.",
      "properties": {
        "numberOfCompartments": {
          "type": "integer",
          "description": "Number of compartments to group travellers in. If we are unable to fit the given travellers in the specified amount of compartments, no offer will be returned."
        }
      },
      "required": [
        "numberOfCompartments"
      ]
    },
    "JourneyOrganizeAlgorithmEnum": {
      "type": "string",
      "default": "SUBSEQUENT_COMBINATIONS",
      "description": "There are two supported algorithms for organizing how we present each combination of journeys. Given three journeys in the trip pattern; SJ-1, SJ-2, SJ-3 the two algorithms will generate these combinations:\nSUBSEQUENT_COMBINATIONS: (SJ-1), (SJ-2), (SJ-3), (SJ-1, SJ-2), (SJ-2, SJ-3), (SJ-1, SJ-2, SJ-3)\nCOMBINATIONS_FROM_OFFERS: Will only organize by unique journey combinations covered by offers.",
      "enum": [
        "SUBSEQUENT_COMBINATIONS",
        "COMBINATIONS_FROM_OFFERS"
      ]
    },
    "LegRequest": {
      "type": "object",
      "description": "Leg request describing a part of a journey.",
      "properties": {
        "travelDate": {
          "type": "string",
          "format": "date",
          "description": "The date of departure from the source origin. In most cases, this is the same date as departure from fromStopPlace. However, in the case of a ServiceJourney spanning midnight and departure from fromStopPlace is after midnight, these two dates are not equal. The correct date to use is for the ServiceJourney."
        },
        "travelDateTime": {
          "type": "string",
          "format": "date-time",
          "description": "The specific time for the chosen journey at fromStopPlaceId as specified in JourneyPlanner."
        },
        "fromStopPlaceId": {
          "type": "string",
          "description": "Stop place id for the origin of the leg.",
          "pattern": "NSR:StopPlace:.+$",
          "x-pattern-message": "Wrong format for NeTEx id. Must be on the format \"NSR:StopPlace:___\"."
        },
        "toStopPlaceId": {
          "type": "string",
          "description": "Stop place id for the destination of the leg.",
          "pattern": "NSR:StopPlace:.+$",
          "x-pattern-message": "Wrong format for NeTEx id. Must be on the format \"NSR:StopPlace:___\"."
        },
        "serviceJourneyId": {
          "type": "string",
          "description": "Service journey id for the leg.",
          "pattern": "^[A-Z]{3}:ServiceJourney:.+$",
          "x-pattern-message": "Wrong format for NeTEx id. Must be on the format \"XXX:ServiceJourney:___\"."
        }
      },
      "required": [
        "fromStopPlaceId",
        "serviceJourneyId",
        "toStopPlaceId",
        "travelDate"
      ]
    },
    "OwnedRight": {
      "type": "object",
      "description": "A specification of preowned products or other entitlements that the customer already owns. They are taken into account when considering which products the user may need.",
      "properties": {
        "id": {
          "type": "string",
          "description": "The netex-id of the entity.",
          "pattern": "^[A-Z]{3}:.+:.+$",
          "x-pattern-message": "Wrong format for NeTEx id. Must be on the format \"XXX:___:___\"."
        },
        "zones": {
          "type": "array",
          "description": "The zones the existing ticket is valid for.",
          "items": {
            "type": "string"
          },
          "minItems": 1,
          "pattern": "^[A-Z]{3}:FareZone:.+$",
          "x-pattern-message": "Wrong format for NeTEx id. Must be on the format \"XXX:FareZone:___\"."
        },
        "cappingSpecification": {
          "$ref": "#/$defs/CappingSpecification"
        }
      },
      "required": [
        "id"
      ]
    },
    "PriceComparisonAlgorithmEnum": {
      "type": "string",
      "default": "TOTAL_PRICE",
      "description": "There are two supported algorithms for comparing offers; TOTAL_PRICE and BEFORE_SDR. TOTAL_PRICE: This is the default algorithm used if not specified, this only looks at the total price of the offers and finds the cheapest, if two offers have the same price, the one with the least amount of offers in the combination is chosen. BEFORE_SDR: This algorithm unapplies all sales discount rights in the offers before comparing prices, when the price of two combinations is the same, the combination containing the most amount of SDRs is chosen, thereafter if the amount is the same the combination with the least amount of offers in the combination is chosen.",
      "enum": [
        "TOTAL_PRICE",
        "BEFORE_SDR"
      ]
    },
    "RecommendationConfig": {
      "type": "object",
      "description": "Specify what types of recommendations are returned in the response. For a more in depth explanation of recommendations, see the guide for recommendations at TODO [INSERT NEW LINK].",
      "properties": {
        "categorySpec": {
          "$ref": "#/$defs/CategorySpec"
        },
        "ruleSpec": {
          "$ref": "#/$defs/RuleSpec"
        }
      }
    },
    "RuleSpec": {
      "type": "object",
      "description": "Determines what rules to apply when categorising and recommending offers for travellers.",
      "properties": {
        "journeyOrganizeAlgorithm": {
          "$ref": "#/$defs/JourneyOrganizeAlgorithmEnum"
        },
        "priceComparisonAlgorithm": {
          "$ref": "#/$defs/PriceComparisonAlgorithmEnum"
        },
        "onlyIncludeRecommendedOffers": {
          "type": "boolean",
          "default": true,
          "description": "Only keep Offers referenced by one or more Recommendations."
        },
        "onlyIncludeRecommendationsWithOffersToBuy": {
          "type": "boolean",
          "default": true,
          "description": "Only include Recommendations with OffersToBuy."
        },
        "mixInOffersWithHigherFlexibility": {
          "type": "boolean",
          "default": true,
          "description": "Only applicable to multi leg journeys. If part of the journey has no Offer for the required flexibility, Recommendations will mix in a higher flexibility if it matches other parameters."
        },
        "mixInOffersWithOtherFacilitySets": {
          "type": "boolean",
          "default": true,
          "description": "Only applicable to multi leg journeys. If part of the journey has no Offer for the required facility set, Recommendations will mix in the cheapest facility set that matches other parameters."
        },
        "onlyKeepUpgradeProductSalesPackages": {
          "type": "boolean",
          "default": false,
          "description": "When enabled, only offers containing exclusively upgrade products (e.g. seat reservations) are considered for recommendations. Offers containing base fare products are excluded."
        },
        "onlyIncludeMostCompleteInCategorySpec": {
          "type": "boolean",
          "default": false,
          "description": "BETA: This field is in beta and may change or be removed in future versions."
        }
      }
    },
    "Traveller": {
      "type": "object",
      "description": "A specification of a traveller. Either age or userType must be set.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Identifier for the traveller. The travellers id will be referenced in the response where natural. Specifying an id for each traveller can make it easier to determine the seating and for whom each product is intended. If no ID is specified, the traveller will be assigned a random ID, only valid for the particular offer."
        },
        "userType": {
          "$ref": "#/$defs/UserTypeEnum"
        },
        "age": {
          "type": "integer",
          "description": "Specify the travellers age, to let the system calculate the corresponding userType.",
          "minimum": 0
        },
        "baggageTypes": {
          "type": "array",
          "description": "A filter for what kind of luggage the traveller wants offers for. If, for example, a user wants to bring a bicycle along for the trip. \"BICYCLE\" can be specified in that array. Offers that can't fulfil the wish for a \"BICYCLE\" accommodation are still returned from our services.",
          "items": {
            "$ref": "#/$defs/BaggageTypeEnum"
          },
          "minItems": 1
        },
        "campaignCodes": {
          "type": "array",
          "description": "Campaign codes that may grant entitlements or discounts. Usually not connected to the identity of the Traveller.",
          "items": {
            "type": "string"
          },
          "minItems": 1
        },
        "travellerContext": {
          "$ref": "#/$defs/TravellerContext"
        }
      },
      "x-class-extra-annotation": "@org.entur.offers.config.validation.AtLeastOneParameter(parameters = {\"userType\", \"age\"})"
    },
    "TravellerContext": {
      "type": "object",
      "description": "Customer-specific context used to personalise and determine entitlements for a traveller.",
      "properties": {
        "customerIdentity": {
          "type": "array",
          "description": "One or more references to customer identities in different systems.",
          "items": {
            "$ref": "#/$defs/CustomerIdentity"
          },
          "minItems": 1
        },
        "ownedRights": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/OwnedRight"
          },
          "minItems": 1
        }
      },
      "required": [
        "customerIdentity"
      ]
    },
    "TripPatternRequest": {
      "type": "object",
      "description": "List of legs constituting a suggested sequence of rides and links for a specific trip.",
      "properties": {
        "legs": {
          "type": "array",
          "description": "Legs constituting a suggested sequence of rides and links for this trip.",
          "items": {
            "$ref": "#/$defs/LegRequest"
          },
          "minItems": 1
        }
      },
      "required": [
        "legs"
      ]
    },
    "TypeOfRecommendationEnum": {
      "type": "string",
      "default": "CHEAPEST",
      "description": "Describes the degree of flexibility in a recommendation (refundable vs non-refundable, exchangeable vs non-exchangeable). Whether the recommendation is the CHEAPEST - regardless of flexibility, or whether the recommendation is for a specified product.",
      "enum": [
        "FLEXIBLE",
        "SEMI_FLEXIBLE",
        "NON_FLEXIBLE",
        "CHEAPEST"
      ]
    },
    "UserTypeEnum": {
      "type": "string",
      "description": "A type of traveller. An offer for userType=CHILD, will naturally be different than an offer for userType=ADULT. Subset of UserTypeEnumeration from NeTEx usage parameter eligibility support.",
      "enum": [
        "ANYONE",
        "ADULT",
        "CHILD",
        "INFANT",
        "ANIMAL",
        "SENIOR",
        "GUIDE_DOG",
        "YOUNG_PERSON",
        "STUDENT",
        "MILITARY"
      ]
    }
  }
}