SearchGeoLocationRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/entur/main/json-schema/entur-search-geo-location-request-schema.json",
  "title": "SearchGeoLocationRequest",
  "description": "A request used to search for fare products between stop places or zones. If two stopPlaces are provided, Offers are calculated for each set of FareZones sharing the same codespace. For any other combination, the common codespace is selected. In either case, transport mode and authority can be used to further refine which Offers are returned. Some combinations of stop places may result in offers that cover parts of the distance. As an example, let's say the \"from\" stop place is A, and the \"to\" stop place is C. There may not be a ticket that is valid from A to C, but tickets that are valid from A to B, and B to C. In that case you will receive offers that are valid for A to B and B to C. If you only want offers that cover the whole distance, set \"offersForWholeTripOnly\" to true.",
  "x-generated": "2026-10-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/entur-offers-partner-openapi.yml#/components/schemas/SearchGeoLocationRequest",
  "type": "object",
  "properties": {
    "travelDate": {
      "type": "string",
      "format": "date-time",
      "description": "The specific time for when the ticket should be activated. For most purposes it is recommended to use the current time as travel date. That is because most period tickets are activated immediately on purchase. If you want to get a period ticket that should be activated some time in the future, specify the future date."
    },
    "from": {
      "type": "string",
      "description": "The id of the origin stop place or zone.",
      "pattern": "^[A-Z]{3}:FareZone:.+$|^NSR:StopPlace:.+$",
      "x-pattern-message": "Wrong format for NeTEx id. Must be on the format \"XXX:FareZone:___\" or \"NSR:StopPlace:___\"."
    },
    "to": {
      "type": "string",
      "description": "The id of the destination stop place or zone.",
      "pattern": "^[A-Z]{3}:FareZone:.+$|^NSR:StopPlace:.+$",
      "x-pattern-message": "Wrong format for NeTEx id. Must be on the format \"XXX:FareZone:___\" or \"NSR:StopPlace:___\"."
    },
    "via": {
      "type": "array",
      "description": "Optional sequence of via locations. Mostly useful for zone based searches.",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "pattern": "^[A-Z]{3}:FareZone:.+$|^NSR:StopPlace:.+$",
      "x-pattern-message": "Wrong format for NeTEx id. Must be on the format \"XXX:FareZone:___\" or \"NSR:StopPlace:___\"."
    },
    "travellers": {
      "type": "array",
      "description": "The travellers the offer should be valid for.",
      "items": {
        "$ref": "#/$defs/Traveller"
      },
      "minItems": 1
    },
    "recommendationConfig": {
      "$ref": "#/$defs/RecommendationConfig"
    },
    "offersForWholeTripOnly": {
      "type": "boolean",
      "default": false,
      "description": "Set this flag to true if you only want tickets that are valid all the way between the stop-places specified in the \"from\" and \"to\" field. When set to false, you will receive additional offers that are  valid for parts of the trip with one of the stop places covered."
    },
    "authority": {
      "type": "string",
      "description": "Optional authority ID, to further refine search. The returned Offers will only contain products allowing or requiring the provided Authority. In the case of two rail stopPlaces, Authority is set from pre-defined rules and this parameter will be ignored.",
      "pattern": "^[A-Z]{3}:Authority:.+$",
      "x-pattern-message": "Wrong format for NeTEx id. Must be on the format \"XXX:Authority:___\"."
    },
    "transportMode": {
      "type": "string",
      "description": "Optional transport mode, to further refine search. Most useful when there is a specific use case where there may be overlapping Offers, for instance high speed ferry or rail."
    }
  },
  "required": [
    "from",
    "to",
    "travelDate",
    "travellers"
  ],
  "$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"
      ]
    },
    "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"
      ]
    },
    "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"
      ]
    },
    "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"
      ]
    }
  }
}