Searching for offers with TripSpecification
- Sverker Östman
- Kevin Lindgren
- Hillevi Lönnerberg
Some organisations may have their own journey planner (i.e. SJ and SilverRail for now) and will use TripSpecifications when calling NDS for offers. In TripSpecification all legs in a trip are specified with enough information to find a match in the corresponding IMS. The source for the information in the journey planner must be Samtrafiken traffic data for sales channels (NeTEx).
The picture below shows the TripSpecification definition in OSDM v 3.0.2. Fields marked with a red star is mandatory in OSDM. In the Samtrafiken ACCESS implementation the mandatory fields are extended to the fields marked with yellow.
For detailed information on how Samtrafiken NeTEx files ar structured see Samtrafiken NeTEx export and NeTEx format adjustments - Samtrafiken sales export.
start
The stop and time for the start of the the trip.
In the Samtrafiken ACCESS API, the codelist for stops will contain all Samtrafiken’s sellable national stop IDs (known as “rikshållplatser”). The stop IDs contain 9 digits and they will be used according to the codelist urn:x_swe:stn:nnnnnnnnn, where nnnnnnnnn is the stop ID.
TimeTabledTime should be in local time
The stops to use in Samtrafiken ACCESS can be found in stops.xml in the daily NeTEx export from Samtrafiken.
See Codelist: Stops for more info and examples.
NeTEx - File: _stops.xml StopPlace.KeyValue.rikshallplatsNummer
end
The stop and time for the end of the the trip.
In the Samtrafiken ACCESS API, the codelist for stops will contain all Samtrafiken’s sellable national stop IDs (known as “rikshållplatser”). The stop IDs contain 9 digits and they will be used according to the codelist urn:x_swe:stn:nnnnnnnnn, where nnnnnnnnn is the stop ID.
timeTabledtime should be in local time
The stops to use in Samtrafiken ACCESS can be found in stops.xml in the daily NeTEx export from Samtrafiken.
See Codelist: Stops for more info and examples.
NeTEx - File: _stops.xml StopPlace.KeyValue.rikshallplatsNummer
mode
The transport mode for the leg. Use the OSDM ptMode enum. The list of transport modes used in Samtrafiken ACCESS with the corresponding NeTEx value:
Codelist: ptMode (transport modes)
NeTEx - ServiceJourney.TransportMode
productCategory
In the Samtrafiken ACCESS API, the product categories are used according to the code list urn:x_swe:sbc:xx where xx is the product category code (service brand code).
NeTEx - ServiceJourney.KeyValue.productCode
vehicleNumbers
The vehicleNumber should be the published train number when possible. For buses without unique id:s use the line number. If the bus needs a unique published id, then use that value. In Samtrafiken’s NeTEx dataset, the value is (almost) always found in the ServiceJourney.PublicCode element.
Trains: NeTEx - TrainNumber.ForAdvertisment
Buses and other traffic: NeTEx - ServiceJourney.PublicCode
There is an exception for this, and that is for trains that change their train numbers during their journey. In those cases it must be taken into consideration that the train number will be different depending on the departure stop of the TripSpecification.
For these trains the vehicleNumber should be the train number that is advertised at the stop of the departure.
In Samtrafiken’s NeTEx dataset, trains that change their train numbers during their journey is expressed as a single ServiceJourney with multiple JourneyParts that refer to TrainNumber-elements with different ForAdvertisment values. The corresponding ForAdvertisment value from these JourneyParts should be used as the vehicleNumber, in this exceptional case.
carriers
In the Samtrafiken ACCESS API, the carrier IDs are used according to the codelist urn:x_swe:carrier:nnn, where nnn is the carrier ID.
NeTEx - Line.KeyValue.salesAuthorityNumber
publishedServiceName
Optional and not used today to identify trips. If the field is filled in, it must contain the same value as vehicleNumbers.
lineNumbers
Optional and not used today to identify trips. If the field is filled in, it must contain the same value as vehicleNumbers.
attributes
When the tickets are created by NDS attributes must be sent in the request to be shown on the tickets.
Codelist: Attributes (service properties)
Example SJ X2000 train Stockholm - Göteborg
{
"objectType": "OfferCollectionRequest",
"tripSpecifications": [
{
"externalRef": "05ba799b-2f92-4c23-9336-a625795006ad|0|48ee70c7-99db-4c12-bfe6-422a30afc069",
"legs": [
{
"externalRef": "leg1",
"timedLeg": {
"start": {
"stopPlaceRef": {
"stopPlaceRef": "urn:x_swe:stn:740000001",
"objectType": "stopPlaceRef" },
"serviceDeparture": {
"timetabledTime": "2023-09-15T06:27:00+02:00" }
},
"end": {
"stopPlaceRef": {
"stopPlaceRef": "urn:x_swe:stn:740000002",
"objectType": "stopPlaceRef" },
"serviceArrival": {
"timetabledTime": "2023-09-15T09:35:00+02:00" }
},
"service": {
"vehicleNumbers": [
"421" ],
"mode": {
"ptMode": "HIGH_SPEED_TRAIN"
},
"productCategory": {
"name": "Snabbtåg",
"shortName": "Snabbtåg",
"productCategoryRef": "urn:x_swe:sbc:ST"
},
"carriers": [
{
"ref": "urn:x_swe:carrier:74",
"name": "SJ" }
]
}
}
}
],
"isPartOfInternationalTrip": false
}
],
"offerSearchCriteria": {
"offerMode": "INDIVIDUAL",
"currency": "SEK" },
"anonymousPassengerSpecifications": [
{
"externalRef": "Adult",
"type": "PERSON"
}
],
"corporateCodes": [],
"promotionCodes": []
}Example SL subway
{
"tripSpecifications": [
{
"externalRef": "05ba799b-2f92-4c23-9336-a625795006ad|0|48ee70c7-99db-4c12-bfe6-422a30afc069",
"legs": [
{
"externalRef": "8dff6e54-4444-4749-8a74-789281057f12|0|0",
"timedLeg": {
"start": {
"stopPlaceRef": {
"stopPlaceRef": "urn:x_swe:stn:740020757",
"objectType": "stopPlaceRef" },
"serviceDeparture": {
"timetabledTime": "2023-10-03T12:38:00+02:00"
}
},
"end": {
"stopPlaceRef": {
"stopPlaceRef": "urn:x_swe:stn:740021650",
"objectType": "stopPlaceRef" },
"serviceArrival": {
"timetabledTime": "2023-10-03T13:35:00+02:00"
}
},
"service": {
"vehicleNumbers": [
"13" ],
"mode": {
"ptMode": "UNDERGROUND",
"name": "Underground"
},
"productCategory": {
"name": "County traffic",
"shortName": "LT",
"productCategoryRef": "urn:x_swe:sbc:LT"
},
"carriers": [
{
"ref": "urn:x_swe:carrier:275",
"name": "SL" }
]
}
}
}
],
"isPartOfInternationalTrip": false
}
],
"offerSearchCriteria": {
"offerMode": "INDIVIDUAL",
"currency": "SEK" },
"anonymousPassengerSpecifications": [
{
"externalRef": "443a49be-3ff3-47a3-8efb-1def96c2be29",
"type": "PERSON"
}
],
"corporateCodes": [],
"promotionCodes": []
}
Example SL bus line 212
{
"tripSpecifications": [
{
"externalRef": "05ba799b-2f92-4c23-9336-a625795006ad|0|48ee70c7-99db-4c12-bfe6-422a30afc069",
"legs": [
{
"externalRef": "leg1",
"timedLeg": {
"start": {
"stopPlaceRef": {
"stopPlaceRef": "urn:x_swe:stn:740024784",
"objectType": "stopPlaceRef" },
"serviceDeparture": {
"timetabledTime": "2023-11-10T14:21:00+01:00" }
},
"end": {
"stopPlaceRef": {
"stopPlaceRef": "urn:x_swe:stn:740020757",
"objectType": "stopPlaceRef" },
"serviceArrival": {
"timetabledTime": "2023-11-10T14:38:00+01:00" }
},
"service": {
"vehicleNumbers": [
"212" ],
"mode": {
"ptMode": "BUS",
"name": "Bus"
},
"productCategory": {
"name": "County traffic",
"shortName": "LT",
"productCategoryRef": "urn:x_swe:sbc:LT"
},
"carriers": [
{
"ref": "urn:x_swe:carrier:275",
"name": "SL" }
]
}
}
}
],
"isPartOfInternationalTrip": false
}
],
"offerSearchCriteria": {
"offerMode": "INDIVIDUAL",
"currency": "SEK" },
"anonymousPassengerSpecifications": [
{
"externalRef": "Adult",
"type": "PERSON"
}
],
"corporateCodes": [],
"promotionCodes": []
}