Seating services

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 have 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.

Check 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).

 

[
    {
        "railcarId": 1,
        "railcarType": "A7-1",
        "compartments": [
            {
                "compartmentNumber": 1,
                "seatTypeId": 36,
                "targetGroup": "EG",
                "classType": 2,
                "smokingCode": 2,
                "seats": [
                    {
                        "seatNumber": 3,
                        "seatCode": 1
                    },
                    {
                        "seatNumber": 4,
                        "seatCode": 3
                    }
                ]
            },
            {
                "compartmentNumber": 2,
                "seatTypeId": 36,
                "targetGroup": "EG",
                "classType": 2,
                "smokingCode": 2,
                "seats": [
                    {
                        "seatNumber": 9,
                        "seatCode": 3
                    },
                    {
                        "seatNumber": 10,
                        "seatCode": 1
                    }
                ]
            }
        ]
    }
    {
        "railcarId": 4,
        "railcarType": "B7-6",
        "compartments": [
            {
                "compartmentNumber": 1,
                "seatTypeId": 15,
                "targetGroup": "EG",
                "classType": 2,
                "smokingCode": 2,
                "seats": [
                    {
                        "seatNumber": 3,
                        "seatCode": 1
                    },
                    {
                        "seatNumber": 4,
                        "seatCode": 3
                    }
                ]
            }
        ]
    },
    {
        "railcarId": 6,
        "railcarType": "B7-4",
        "compartments": [
            {
                "compartmentNumber": 2,
                "seatTypeId": 4,
                "targetGroup": "EG",
                "classType": 2,
                "smokingCode": 2,
                "seats": [
                    {
                        "seatNumber": 7,
                        "seatCode": 1
                    },
                    {
                        "seatNumber": 8,
                        "seatCode": 3
                    }
                ]
            },
            {
                "compartmentNumber": 3,
                "seatTypeId": 4,
                "targetGroup": "EG",
                "classType": 2,
                "smokingCode": 2,
                "seats": [
                    {
                        "seatNumber": 13,
                        "seatCode": 3
                    },
                    {
                        "seatNumber": 14,
                        "seatCode": 1
                    }
                ]
            }
        ]
    }
]

 

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 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.

 

{
  "datedServiceJourneyId": "ENT:DatedServiceJourney:16343",
  "origin": "NSR:StopPlace:337",
  "destination": "NSR:StopPlace:548",
  "status": "CONFIRMED",
  "reservedTargetSeats" : [
    {
      "railcarId" : 1,
      "seatWithSeatTypes" : [
        {
        "seatTypeId": 36,
        "seatNumber" : 3
        }
      ]
    }
  ]
}
{
    "reservationId": "bbec3ae8-d589-40c7-b0ae-ba27f528ea9d",
    "sessionId": "",
    "created": "2018-11-27T09:34:59.918489Z",
    "createdBy": "SEATING_SERVICES",
    "departureId": "63",
    "departureTime": "2018-12-04T14:43:00.887Z",
    "arrivalTime": "2018-12-04T21:21:00.887Z",
    "origin": "NSR:StopPlace:337",
    "destination": "NSR:StopPlace:548",
    "organisationId": 1,
    "datedServiceJourneyId": "ENT:DatedServiceJourney:16339",
    "seats": [
        {
            "seatId": "3396ec89-76b6-4a44-8608-4bd5500e6ae7",
            "reservationId": "bbec3ae8-d589-40c7-b0ae-ba27f528ea9d",
            "seatNumber": "3",
            "seatType": "36",
            "seatCode": "1",
            "railcarId": "1",
            "created": "2018-11-27T09:34:59.918402Z",
            "createdBy": "SEATING_SERVICES",
            "status": "CONFIRMED",
            "controlId": "760087345910"
        }
    ]
}

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 seatTypeIs 36, and the seatNumber 3. The response returns a 201 Created, and information of the reservation that was made.

Table of contents


Seat rules

Available seats/capacity

Reservations

Seat types

Seatmap

Seat rules


In the seat allocation system plads90, the trains, and seat types are defined. To be able to automatically assign seats based on a product, as well as know how many seats are available for the given product, one needs some accompanying rules. These should be defined in seating services' seat rules.

API

 

 

 

Prerequisites

The seating rules defined works together with the seat information in plads90. The seat types defined here needs to be the same as in plads90, or else the rules will not work as intended.

Concepts

A seat type is a specific seat type in the transport. The seat type could have special traits, e.g. upgraded seats, or it could be sections of the transport ment for a specific crowd, e.g. family friendly sections. The seat type has an id, a number, and a description. The description is only there for readability, whereas the id is used against the reservation system (plads 90). 

Product Attributes are where the seat rules are defined. It is a connection between productIds from the product module to the seat types, with attributes on how the product affects the seating. There exists four attributes for now, "addSeat", "replaceMainSeat", "productType" and "seatTypePriorities".

The "addSeat" is one of the attributes a product has in regard of seating. It is an integer, and tells us if there needs to be added a seat for this type of product, if the seat type required is available on the departure. E.g. does regular products add a seat, whereas upgrades usually do not add additional seats.

The "replaceMainSeat" attribute tells you if the purchase of this products results in the main seat changing its seat types. For upgraded seat products this would be set to true, as the purchase of this product should result in a change of the original seat type.

The "productType" describes what type of product we have, and is an enum. For now it can have the values MAIN or SUPPLEMENT, but this is due to change as new product types with "seatAttributes" are created.

The "seatTypePriorities" attribute says something about what seat types the product is allowed to use, and in what prioritised order they are to be used by. The prioritised order is used when automatically assigning seats, whereas all seat types that are allowed for a product are used when calculating the available seat capacity for a given product.

Available seats/capacity


The capacity and available seats is a module part of Plads90 system that given a track on a specific seat(s) availability of departure. This include seat status, seat type (kupè type), litra code for railcar and railcar info. The module will supports a set of different way to track a seat/railcar availability and offers a specific search for available seats by seat type. For setup and maintaining this module requires access to Plads90 main system.

API

 

 

 

 

Prerequisite

  • 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 a item which can be reserved for a specific departure in 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

Departure capacity will give a overall capacity for all seat types including the amount to a specific dated-service-journey.

Available seats

Available seats of a departure can be searched by 2 different way. The first way is given by a dated-service-journey, (railcarId), origin station and destination station. The second 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 cause 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.

​API

 

 

 

 

 

 

Reservation

A reservation can consist of one or multiple seats reservation, 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 simples way to reserve seats on a given train (datedServiceJourney), between an 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 an 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 and in addition information about wanted product(s), and the amount of that/these product(s) and possible supplement products must be given. 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.

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 (for the time being only seat status can be updated??) one needs to send the reservation model with updated information as the request body, and . The update reservation service will return the updated Reservation and a http status on how the request went. Allowed status changes are, draft to confirmed, draft to expired, draft to cancelled and confirmed to cancelled.

Update specific seat status

The status of a specific seat can be changed using the update seat status patch endpoint, where seat id is given in the path and body of the request gives what status change to do. Allowed status changes are the same as above, draft to confirmed, draft to expired, draft to cancelled and confirmed to cancelled. Information about the changed seat is returned.

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.

Seat types


The seat type is stored mainly in Plads90 and seatingservices application. Seatingservices seat type is a duplicate list of Plads90 and is a helping list for seat requirement rules.

API

 

 

 

 

Prerequisite

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

Current available seat type






Id
Description
Plads90 code
Text on ticket
International
2, 4 Standard seat (2nd class) ST Standard plass Yes
6 Wheelchair seat/space RS Rullestol Yes
9 Sleeper HK Hel kupe Yes
10 Family compartment BF Familie Yes
15 Dyrefri/Allergiker DF Dyrefri/Allergiker Yes
31 Baby carriage BP Barnevognplass Yes
36 Comfort seat (1st class) KO NSB KOMFORT Yes
41 Large animal (+40cm/dog) DT Tillat for dyr Yes
107 Adjecent seat LB NSB Familie No
136 Night KN Komfort Natt No
141 Small animal (-40cm/dog) OD Ordinær/Dyr tillatt No
202 New comfort seat (1st class) SR Setereservasjon No
211 Bicycle RY Bagasje sykkel No
998 Reserve compartment (only train conductor allow to reserve) TK Tjenestekupe No
999 Reserve compartment (only train conductor allow to reserve) RK Reservekupe No

Seatmap


Forutsetning

  • Kart er tegnet

Oppsett

  • Legge inn kart

Kjøpsløp

  • Hente ut setekart

Forvaltning

  • Endre setekart

 

Setekart: Bruksanvisning

1.        Åpne orginaler (AI filer) i Adobe Illustrator.

2.        Behold detaljene til omrisset, og fjern layers fra filen som ikke skal eksportes ut til SVG (f.eks Symboler, tekst etc)

3.        Gå over farger til setekartet og legg til de riktige fargekodene som skal brukes på kartene. (NSB: Kan f.eks bruke en tidligere eksportert SVG-fil som referanse for å dobbelsjekke at fargene er konsis og stemmer overens med profilen.)

4.        All whitespace rundt togvognen må trimmes bort i svg-filen.

5.        Når redesignet er gjort; roter vognen slik at den står i vertikal retning. Sjekk med produkteier hvilken retning toget skal ligge (Bruk Rotate Tool i verktøymenyen eller Object -> Transform -> Rotate).

6.        Tilslutt, eksporter AI-filen til SVG kode ved å klikke på File -> Eksport -> Eksport As > Velg Format: SVG -> Eksport; Nytt vindu med SVG Options dukker opp -> Nederst til venstre i vinduet; Klikk på “Show Code”.

7.        En SVG kode vil dukke opp i “TextEdit”, ta vare på denne koden.

8.        Logg inn på SeatMapserver. Spør produkteier om tilgang.

9.        I hovedmenyen klikk på “Togvogner” -> Opprett ny 

10.     Fyll inn: litra kode, beskrivelse og SVG innhold

11.     I SVG innhold skal SVG koden limes inn.

12.     Følgende kode skal limes foran SVG-koden man fikk eksportert tidligere;
<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" width="90px" height="729.299px" viewBox="0 0 90 729.299" enable-background="new 0 0 90 729.299" xml:space="preserve">

13.     Dersom man ikke får frem alle detaljer eller noe blir “kuttet” så kan man prøve å justere på “width” for å endre bredden på vognen, eller “height” for å justere høyde.

14.     Ta alltid vare på kildefilene for designet på et egnet filområde. Hvis Illustrator brukes bør man ta vare på .ai filene.

The API reference(s) can be found here: