Seating Services (legacy)

Service announcement:

We are announcing end of life for the seating services API. This service will be deprecated as soon as all consumers of the service have migrated to the seating manager API. We plan for migrating all consumers during 2024 and we will contact each consumer to plan the migration together.

We have migrated all train departures with seat reservations from Plads90 to new services, called Entur Plass. Next work in line is to replace the seating services API with seating manager API.

If you experience anything unexpected with seat reservations, please let us know. To be continued!

Reserving my first seat

Seating services deals with seat reservations and seat allocation. A seat is a physical seat in some sort of transport. A seat has a seat type, which gives the seat some special traits. It could either be an upgraded seat type, or it could be a zone in the transport for special purposes. The information about the seats and seat types should be defined in the seat allocation system, Plads 90.

Authentication

Seating services requires a Bearer Token in the Authorization header created by the Entur Authentication server for every request.

Checking Capacity

The simplest way to check the capacity is to find all available seats on a departure between two stops. The identification of the departure is the original dated service journey that is created in the timetable module. The stops are given on the format from the Nasjonalt Stoppestedsregister.

In this example we use the departure ENT:DatedServiceJourney:2838, the origin NSR:StopPlace:337 (Oslo) and the destination NSR:StopPlace:548 (Bergen).

GET /v1/dated-service-journeys/ENT:DatedServiceJourney:2838/seats?origin=NSR:StopPlace:337&destination=NSR:StopPlace:548

We receive a 200 Ok, and a list of all the different seats available with their associated information. The seats are grouped into railcars, with an id and a type, which is information from Plads90. Each of the railcars are again grouped into compartments, and here the available seats are listed. In this response we have three different railcars, with different seat types in each of them.

Reserving a Seat

There are different ways of reserving seats. The example request here reserve some specific targeted seats. For other reservation methods see REF. For all reservations one must define on what departure one wishes to reserve seats, between which stop places, and also what status the seat should have. In addition the request needs to have information that tells us which seats to reserve.

POST /v1/reservations/specific-seats

In this example we use the same departure, origin and destination as we used when we checked the capacity. The status is set to CONFIRMED to make a hard reservation. We choose the first seat in the capacity we got above, from railcar 1, with seatTypeId 36, and the seatNumber 3. The response returns a 201 Created, and information of the reservation that was made.

Guides

Seat types

A seat type is a specific type of seat in Plads90, standard, comfort, dog free zone etc. SeatTypeId is the ID created in Plads90, and Seating services use this for different purposes, for example when making a reservation and to present more meta data about the seats.

API

Prerequisite

• Fully configured Plads90
• International code which is used by other foreign operator. (Hermes)

Seat types

Seat allocation rules

Seating Services supports automatic seat allocation based on products, both preassigned fare- and supplement-products. This is achieved by creating different attributes for the products. These attributes define what seat a product is given and how many.

API

Prerequisites

The product attributes defined work together with seat types in Seating services and Plads90. As discussed earlier, the seat types defined in Seating services needs to be the same as in Plads90, or else the rules will not work as intended.

Concepts

Product Attributes define how seats should be allocated when a traveller buys a specific product or a combination of products. It is a connection between productIds from the product module to seat types, with attributes determining how the products interact with each other. An attribute consists of four values; "addSeat", "replaceMainSeat", "productType", "companionGuard" and "seatTypePriorities".

"addSeat" describes how many seats the traveller should be allocated by the product. Typically a product would add one seat, but it's possible to set a value of more or even zero.

The "productType" is an enum describing what type of product the product is. Seating services supports two types of products; MAIN or SUPPLEMENT. When reserving seats for a collection of products there can only be one Main product in the collection.

"replaceMainSeat" describes whether the product should override the allocation of the main product. This attribute only applies if the product is a SUPPLEMENT type. For example a supplement product upgrading the travellers seat would have a value of zero set to "addSeat" and "replaceMainSeat" set to True. If the product should, in addition to replacing the main product, add more seats the "addSeat" value must be set. In a collection of products to reserve there can only be one supplement product at the time with this attribute set to True.

The list of seatTypes a product can be allocated is defined by "seatTypePriorities". This is a list of seatTypes and the priority in which the system should try to allocate seats to the traveller for the product. A product can have several seatTypes in this list as long as they have different priorities.

The last attribute "companionGuard" defines whether or not the seats allocated for this product should be changeable by to the companion rules. When set to true the seats will not change, no matter what other seats where allocated in the reservation request.

Companion rules

In addition to product attributes, the system also supports rules that allocate seats based off of what other seats were allocated in the request. A typical use case for this is to keep travellers who bought more than one ticket gathered together, even though the product attributes dictates that they should be given two different seatTypes in different cabins.

API

Prerequisites

These rules are only respected when reserving seats with products, so the product attributes must exists for the companion rules to work.

Concepts

Similarly to the product attributes, the companion rules define a list of prioritized seats. The system use this list to determine if some of the allocated seats dictate that the other seats must be changed. For example the seat for wheelchair can be configured to dictate that the other seats in the reservations should be changed to a seat type close to the wheelchair seat. This rule is based around seat type instead of products.

Available seats/capacity

The capacity/availability API gives information about capacity for departures. This includes seat status, seat type (kupè type), litra code for the railcar and railcar info. The API supports a set of different ways to track a seat/railcar availability and offers a specific search for available seats by seat type.

Prerequisites

Fully configured Plads90 available (lines, trains, seat types, departures etc.). This is not self service, it has to be done in cooperation with Entur.

Core concepts:

• A seat is an item which can be reserved for a specific departure in the Plads90 system. A seat will contain information on seat type, seat number and seat placement.

• A railcar is a reference to a train consisting of a single coach (carriage, car), with a driver's cab at one or both ends.

• A compartment is a space within a railcar. In Plads90 each seat type will have a compartment space from 2, 4, 6 and 8 seats depends on railcar setting.

• A dated-service-journey is a reference for allocate departure info. Dated-service-journey will contain the private id, service journey id and departure date time.

• A requestScrolling - F is an inquiry on the specific train/coach, B is paging from the mentioned coach to the next one.

Departure capacity

Total seat capacity will give default capacity (disregarding availability) for all seat types on a specific date-service-journey given origin station and destination station.

Seat capacity will give available capacity for each seat types with applicable products for a specific dated-service-journey.

Available railcars and litra info

Available railcars of a departure

Available railcars will give a list of all available railcars to a specific date-service-journey, origin station and destination station.

A list of railcars with litra code to a specific date-service-journey. This service is needed because Seatmap service does not contains any information about vehicle material for a specific date-service-journey.

Available seats

Available seats of a departure can be searched by 3 different way.

The first way is given by a dated-service-journey, railcarId, origin station and destination station. It will return a list of available seats for the specific railcar number.

The second way is given by a dated-service-journey, origin station and destination station. It will return all available seats for the specific dated-service-journey (train).

The third way is using seat type. Plads90 will try to find the best combination by number of travelers and seat type and return 2-3 different suggested available seats in a railcar. It is a limitation in the second search method because different departures has different compartment setting (ref. core concepts).

Even it is available seats in Plads90 for that departure, but the number of travelers have exceeded the maximum compartment space, the "Get list of best available seats" might return error or no available seats.

Reservations

The reservations part of the seating service offers services to create (draft and confirmed), read/get, update/change and delete/cancel a reservation, and a service to get all reservations on a given departure.

Prerequisites

• Fully configured Plads90 available (lines, trains, seat types, departures etc.). This is not self service, it has to be done in cooperation with Entur.
• Available seat(s) to reserve.

Make a Reservation

A reservation can consist of one or multiple seat reservations, of one or multiple seat types on one departure between a origin and a destination. Seats can be reserved in three different ways with two different statuses. The first option is to get assigned seats automatically, the second option is to reserve by product and the third option is to reserve specific seats. One and only one of the reservation types must be used in a single reservation. All three ways can be reserved with status "DRAFT" or "CONFIRMED".

Draft vs. confirmed

If a reservation is made with status set to "CONFIRMED" the seats are reserved immediately and an confirmation of the booking with an reservation id is given as the response. If a reservation is made with status set to "DRAFT" an confirmation of a "soft booking" with an reservation id is given as the response. Unless an update to the specific soft reservation with status update to "CONFIRMED" for all seats in the reservation using the reservation id from the response happens within a given time the reservation will be set to status "EXPIRED", and the seats in question will be released for others to reserve. How long an reservation will live as "DRAFT" is controlled by a sales component called Session Manager.

Reserve - automatic assignment of seats

This is the simplest way to reserve seats on a given train (datedServiceJourney), between a given origin and a given destination. Reservations can be done on multiple seat types for a given number of travelers. The response will among other things consist of a reservation id and information about assigned seat(s) (railcar, seat number, control id etc.). The reservation id and control id(s) can be used later if one wishes to read information about, change or cancel a reservation or specific seats, i.e change a reservation from draft to confirmed.

Reserve - seats assigned by product

Seats may also be reserved by product(s). Like with automatic assignment train, origin and destination has to be given as well as information about wanted product(s), the amount of that/these product(s) and possible supplement products. Reserve by product has two possible endpoints depending on what response is wanted. The least verbose (/v1/reservations/by-products) response will give reservation id and control id(s) that must be used if one wishes to read information about, change or cancel a reservation or specific seats later. The other alternative (/v1/reservations/by-products-return-with-products) will give the same response as mentioned and in addition, it will give a list with information on which product a seat in the reservation corresponds to.

While ordering seats based on product(s), the control of the reservation(s) is being transferred to an automatic assignment of seats. This means that for an order, all the seats will be in the same railcar (if possible), but not necessarily placed next to another if there are different seatTypes. In the event of an order for; one of a product that responds with two seats required on sitting beside each other and two standard seats without any additional rules, the dependant seats will always be seated next to each other, while the other passengers might not sit beside the dependant seats if there are no more seats of the given seatType available. Albeit, all seats of the same seatType will be seated next to each other, resulting in the standard seatTypes being seated together as well, although not necessarily at the same seatType as initially specified, seatTypes can change in order to be sat together or to be placed in the same railcar. If all seats of the same seatType can't be seated next to each other, the reservation will not go through.

Reserve specific seat(s)

To reserve one or several specific seats, in addition to information about train, origin and destination, one have to give information about railcar, seat type and seat number. The latter are information available through capacity services. Like with automatic assignment of seats the response will give reservation id and control id(s) that must be used if one wishes to read information about, change or cancel a reservation or specific seats later.

Get information about a specific reservation

Information about a specific reservation can be retrieved using the reservation id given from reserving seats in one of the above mentioned methods. If a valid reservation id is given a reservation response is returned, this response hold information about the reservation and the seats reserved. If the reservation id given is not valid, the requester is not allowed to read the information or something else went wrong an error response is given.

Update reservation

To update a reservation one needs to send the reservation model with updated information as the request body. The update reservation service will return the updated Reservation and a http status on how the request went.

Attributes which can be changed under update reservation:

• seatNumber - Allowed to change to a available seat number
• seatTypeId - Allowed to change to another seatTypeId based on the specific seat number
• railcarNumber - Allowed to change to available railcar number based on seat number and seatTypeId
• status - Allowed status changes are, draft to confirmed, draft to expired, draft to cancelled and confirmed to cancelled.

SeatCode will be automatic updated by the new choosen seat number. Changed a seat number which already exists in same reservation is allowed and will not affect Plads90. Seat(s) which are no longer used in reservation will be automatically cancelled by application.

Update a reservation is only allowed to changing seats and status and can not be used to add new seats. Please use 'Reserve API' which is mentioned above to add new seats.

Update specific seat attributes and status

To change a specific seat can use the update seat patch endpoint, where seat id is given in the path and body of the request gives what attributes want to change. Information about the changed seat is returned.

Attributes which can be changed under update seat:

• seatNumber - Allowed to change to a available seat number
• seatTypeId - Allowed to change to another seatTypeId based on the specific seat number
• railcarNumber - Allowed to change to available railcar number based on seat number and seatTypeId
• status - Allowed status changes are, draft to confirmed, draft to expired, draft to cancelled and confirmed to cancelled.

Cancel seat(s)

The cancel seat(s) method in seating service are used to cancel seat(s) that are booked from outside seating services, through the Hermes reservation system. Canceling of seat(s) reserved through seating service can be cancelled by updating a reservation or specific seat(s), through the above mentioned service methods. The request consists of a list of CancelSeat, containing control number, departure id, date of departure and a flag(true/false) telling whether this is a sitting seat or not. Except from http status nothing is returned.

Get information about all reservations on a specific departure

All reservations on a departure can be found by calling the get all seat reservations method with the departures datedServiceJourney as input. The response will consist of a list of reservations.

Exception handling

If something goes not according to plan, bad request, requested resource not found or something else, in seating service a CommonError object is returned, with as much information as possible about what went wrong.

API Reference

See the API reference on the Swagger Petstore