Transport - Mountain Railway

• OpenAPI Documentation (opens new window)
• JAMES Proxy (opens new window)

1. Get Stations

Specific stations can be retrieved via two different calls. Via the station ID or by adding the name as an query parameter. Both options return the same result.

/transport/stations?name=Andermatt (opens new window)

GET /transport/stations?name=Andermatt

GET /transport/stations?name=Nätschen

GET /transport/stations/1553741

GET /transport/stations/1554353

{
  "results": [
    {
      "id": 1553741,
      "name": "Andermatt",
      "mode": [
        "train"
      ],
      "frequentlyRequested": true
    }
  ],
  "total": 1
}

{
  "results": [
    {
      "id": 1554353,
      "name": "Nätschen",
      "mode": [
        "train"
      ],
      "frequentlyRequested": true
    }
  ],
  "total": 1
}

Making a request to /transport/stations without any parameter, gives back a list of frequently requested stations.

2. Get Routes

After selecting two stations, we need to specify the departureStationId, arrivalStationId, the travelClass and the outwardTravelDate.

If we want to get the routes for a Two Way Ticket, we need to specify also the returnTravelDate.

WARNING

Be aware that this call can be expensive depending on the amount of possible routes between two stations.

POST /transport/routes

Request Body

{
  "departureStationId": 1553741,
  "arrivalStationId": 1554353,
  "travelClass": "second",
  "outwardTravelDate": {
    "date": "2021-05-26",
    "type": "departure"
  },
	"returnTravelDate": {
    "date": "2021-05-26",
    "type": "departure"
  }
}

{
  "stations": [
    {
      "id": 1553741,
      "name": "Andermatt",
      "mode": [
        "train"
      ],
      "frequentlyRequested": true
    },
    {
      "id": 1554353,
      "name": "Nätschen",
      "mode": [
        "train"
      ],
      "frequentlyRequested": true
    }
  ],
  "outward": [
    [
      {
        "id": "I3N5c3RlbT1zYmIjZnJvbT1BbmRlcm1hdHQjdG89TsOkdHNjaGVuI3ZpYT1BbmRlcm1hdHQgLSBOw6R0c2NoZW4jdHJpcFR5cGU9VCN0cmF2ZWxDbGFzcz1zZWNvbmQjdHJhaW5UeXBlPSNyZXNlcnZhdGlvblByaWNlPTAjcmVzZXJ2YXRpb25UeXBlPSNkYXl0cmlwSWQ9I2NvbmZpZ3VyYWJsZUlkPSNyZXNlcnZEYXl0cmlwSWQ9I3RpbWVzdGFtcD0xNjIxOTg3MjAwI2RlcGFydHVyZVRpbWU9I2Fycml2YWxUaW1lPSN0cmFpbk5yPSN0cmF2ZWxUeXBlPU91dHdhcmRUcmF2ZWwjc2VnbWVudHM9Iz1BbmRlcm1hdHQjPU7DpHRzY2hlbg==",
        "departureStationId": 1553741,
        "arrivalStationId": 1554353,
        "via": "Andermatt - Nätschen",
        "price": {
          "value": 23,
          "currency": "CHF"
        },
        "segmentsId": "91f8f95232e94afdbc793f1e0edb66fe",
        "segments": [
          {
            "id": "1",
            "departureStationId": 1553741,
            "arrivalStationId": 1554353,
            "travelClass": "second",
            "mode": "train",
            "reservation": "unavailable"
          }
        ]
      }
    ]
  ],
  "return": [
    [
      {
        "id": "I3N5c3RlbT1zYmIjZnJvbT1Ow6R0c2NoZW4jdG89QW5kZXJtYXR0I3ZpYT1Ow6R0c2NoZW4tQW5kZXJtYXR0I3RyaXBUeXBlPVQjdHJhdmVsQ2xhc3M9c2Vjb25kI3RyYWluVHlwZT0jcmVzZXJ2YXRpb25QcmljZT0wI3Jlc2VydmF0aW9uVHlwZT0jZGF5dHJpcElkPSNjb25maWd1cmFibGVJZD0jcmVzZXJ2RGF5dHJpcElkPSN0aW1lc3RhbXA9MTYyMTk4NzIwMCNkZXBhcnR1cmVUaW1lPSNhcnJpdmFsVGltZT0jdHJhaW5Ocj0jdHJhdmVsVHlwZT1SZXR1cm5UcmF2ZWwjc2VnbWVudHM9Iz1Ow6R0c2NoZW4jPUFuZGVybWF0dA==",
        "departureStationId": 1554353,
        "arrivalStationId": 1553741,
        "via": "Nätschen-Andermatt",
        "segmentsId": "e337dd7421f3ea4c043f0fe9687205a3",
        "segments": [
          {
            "id": "1",
            "departureStationId": 1554353,
            "arrivalStationId": 1553741,
            "travelClass": "second",
            "mode": "train",
            "reservation": "unavailable"
          }
        ]
      }
    ]
  ]
}

2.1 Get Variants ( Optional )

Calling the variants endpoint with the selected route will return filter options that can be displayed (e.g. media restrictions, age groups, seat restrictions [this includes restrictions to connections]), those possible filter options can be also retrieved from the offers, by getting them beforehand one would be able to (depending on the UI) to save effort for subsequent offer requests by maybe also caching filter options for some time, expect this call to be nearly as expensive as creating offers, the value of it comes in with caching, one can expect that this call does not lead to some tickets already being reserved in a external system

POST /transport/variants

{
	"routeId": "I3N5c3RlbT1zYmIjZnJvbT1BbmRlcm1hdHQjdG89TsOkdHNjaGVuI3ZpYT1BbmRlcm1hdHQgLSBOw6R0c2NoZW4jdHJpcFR5cGU9VCN0cmF2ZWxDbGFzcz1zZWNvbmQjdHJhaW5UeXBlPSNyZXNlcnZhdGlvblByaWNlPTAjcmVzZXJ2YXRpb25UeXBlPSNkYXl0cmlwSWQ9I2NvbmZpZ3VyYWJsZUlkPSNyZXNlcnZEYXl0cmlwSWQ9I3RpbWVzdGFtcD0xNjIxOTg3MjAwI2RlcGFydHVyZVRpbWU9I2Fycml2YWxUaW1lPSN0cmFpbk5yPSN0cmF2ZWxUeXBlPU91dHdhcmRUcmF2ZWwjc2VnbWVudHM9Iz1BbmRlcm1hdHQjPU7DpHRzY2hlbg=="
}

{
  "ageRestrictions": [],
  "mediaRestrictions": [
    {
      "value": "keycard",
      "label": "Keycard"
    },
    {
      "value": "voucher",
      "label": "voucher"
    },
    {
      "value": "swisspass",
      "label": "SwissPass"
    }
  ],
  "reductionRestrictions": [
    {
      "value": "600.F",
      "label": "Erwachsener"
    },
    {
      "value": "600.K",
      "label": "Kind (6-15 Jahre)"
    },
    {
      "value": "600.S",
      "label": "Senior"
    }
  ],
  "seatRestrictions": [],
  "validityRestrictions": []
}

3. Offers

Retrieving offers that can be put into cart (they also have prices), offers are persisted in the (external) system and expire after some (given) time, expect generating offers to be rather expensive. You will get offer variants and necessary personalization

POST /transport/offers

Request Body

{
  "outwardIds": [
    "I3N5c3RlbT1zYmIjZnJvbT1BbmRlcm1hdHQjdG89TsOkdHNjaGVuI3ZpYT1BbmRlcm1hdHQgLSBOw6R0c2NoZW4jdHJpcFR5cGU9TyN0cmF2ZWxDbGFzcz1zZWNvbmQjdHJhaW5UeXBlPSNyZXNlcnZhdGlvblByaWNlPTAjcmVzZXJ2YXRpb25UeXBlPSNkYXl0cmlwSWQ9I2NvbmZpZ3VyYWJsZUlkPSNyZXNlcnZEYXl0cmlwSWQ9I3RpbWVzdGFtcD0xNjIxOTg3MjAwI2RlcGFydHVyZVRpbWU9I2Fycml2YWxUaW1lPSN0cmFpbk5yPSN0cmF2ZWxUeXBlPU91dHdhcmRUcmF2ZWwjc2VnbWVudHM9Iz1BbmRlcm1hdHQjPU7DpHRzY2hlbg=="
  ],
  "returnIds": [
   "I3N5c3RlbT1zYmIjZnJvbT1Ow6R0c2NoZW4jdG89QW5kZXJtYXR0I3ZpYT1Ow6R0c2NoZW4tQW5kZXJtYXR0I3RyaXBUeXBlPVQjdHJhdmVsQ2xhc3M9c2Vjb25kI3RyYWluVHlwZT0jcmVzZXJ2YXRpb25QcmljZT0wI3Jlc2VydmF0aW9uVHlwZT0jZGF5dHJpcElkPSNjb25maWd1cmFibGVJZD0jcmVzZXJ2RGF5dHJpcElkPSN0aW1lc3RhbXA9MTYyMTk4NzIwMCNkZXBhcnR1cmVUaW1lPSNhcnJpdmFsVGltZT0jdHJhaW5Ocj0jdHJhdmVsVHlwZT1SZXR1cm5UcmF2ZWwjc2VnbWVudHM9Iz1Ow6R0c2NoZW4jPUFuZGVybWF0dA=="
  ],
  "persons": [
    {
      "media": "voucher"
    }
  ]
}

{
  "offers": [
    [
      {
        "id": "93265da2-2c30-488c-a44c-49a42a40a888",
        "validUntil": "2021-05-26T15:10:11+00:00",
        "routeIds": [
          "I3N5c3RlbT1zYmIjZnJvbT1BbmRlcm1hdHQjdG89TsOkdHNjaGVuI3ZpYT1BbmRlcm1hdHQgLSBOw6R0c2NoZW4jdHJpcFR5cGU9TyN0cmF2ZWxDbGFzcz1zZWNvbmQjdHJhaW5UeXBlPSNyZXNlcnZhdGlvblByaWNlPTAjcmVzZXJ2YXRpb25UeXBlPSNkYXl0cmlwSWQ9I2NvbmZpZ3VyYWJsZUlkPSNyZXNlcnZEYXl0cmlwSWQ9I3RpbWVzdGFtcD0xNjIxOTg3MjAwI2RlcGFydHVyZVRpbWU9I2Fycml2YWxUaW1lPSN0cmFpbk5yPSN0cmF2ZWxUeXBlPU91dHdhcmRUcmF2ZWwjc2VnbWVudHM9Iz1BbmRlcm1hdHQjPU7DpHRzY2hlbg==",
          "I3N5c3RlbT1zYmIjZnJvbT1Ow6R0c2NoZW4jdG89QW5kZXJtYXR0I3ZpYT1Ow6R0c2NoZW4tQW5kZXJtYXR0I3RyaXBUeXBlPVQjdHJhdmVsQ2xhc3M9c2Vjb25kI3RyYWluVHlwZT0jcmVzZXJ2YXRpb25QcmljZT0wI3Jlc2VydmF0aW9uVHlwZT0jZGF5dHJpcElkPSNjb25maWd1cmFibGVJZD0jcmVzZXJ2RGF5dHJpcElkPSN0aW1lc3RhbXA9MTYyMTk4NzIwMCNkZXBhcnR1cmVUaW1lPSNhcnJpdmFsVGltZT0jdHJhaW5Ocj0jdHJhdmVsVHlwZT1SZXR1cm5UcmF2ZWwjc2VnbWVudHM9Iz1Ow6R0c2NoZW4jPUFuZGVybWF0dA=="
        ],
        "variants": [
          {
            "id": "f7de6012-7e23-498f-8e4a-234f686594f9/127",
            "name": "Bergbahn Ticket Andermatt - Nätschen",
            "price": {
              "value": 13,
              "currency": "CHF"
            },
            "mediaRestrictions": [
              {
                "value": "voucher",
                "label": "voucher"
              }
            ],
            "reductionRestrictions": [
              {
                "value": "600.F",
                "label": "Erwachsener"
              }
            ]
          },
          {
            "id": "ba3d6874-aff1-47f4-b8b3-8f8eca954f99/142",
            "name": "Bergbahn Ticket Andermatt - Nätschen",
            "price": {
              "value": 7,
              "currency": "CHF"
            },
            "mediaRestrictions": [
              {
                "value": "voucher",
                "label": "voucher"
              }
            ],
            "reductionRestrictions": [
              {
                "value": "600.K",
                "label": "Kind (6-15 Jahre)"
              }
            ]
          },
          {
            "id": "6291b72a-f167-4e7e-a00c-c4cf42f1a226/128",
            "name": "Bergbahn Ticket Andermatt - Nätschen",
            "price": {
              "value": 10,
              "currency": "CHF"
            },
            "mediaRestrictions": [
              {
                "value": "voucher",
                "label": "voucher"
              }
            ],
            "reductionRestrictions": [
              {
                "value": "600.S",
                "label": "Senior"
              }
            ]
          }
        ],
        "personalization": [
          {
            "validation": {
              "required": true,
              "type": "unspecified"
            },
            "id": "firstname",
            "label": "Vorname",
            "value": "string",
            "type": "text"
          },
          {
            "validation": {
              "required": true,
              "type": "unspecified"
            },
            "id": "lastname",
            "label": "Nachname",
            "value": "string",
            "type": "text"
          },
          {
            "validation": {
              "required": true,
              "type": "birthdate"
            },
            "id": "birthdate",
            "label": "Geburtstag",
            "value": "string",
            "type": "birthdate"
          }
        ]
      }
    ]
  ]
}

4. Add to Cart

Putting the selected offer and its variants into cart alongside with the necessary personalization values

POST /transport/cart

Request Body

[
  {
    "offerId": "93265da2-2c30-488c-a44c-49a42a40a888",
    "variants": [
      {
        "variantId": "f7de6012-7e23-498f-8e4a-234f686594f9/127",
        "personalization": [
          {
            "id": "firstname",
            "value": "John"
          },
          {
            "id": "lastname",
            "value": "Doe"
          },
          {
            "id": "birthdate",
            "value": "1980-05-01"
          }
        ]
      }
    ]
  }
]

HTTP Code: 204 - No Content
// Successfully added to Cart

Glossary

station - a defined place where you can start or end your journey or can transfer, a station can serve one or more modes

route - a defined way how to travel from the departure to the arrival station, a route may contain segments

variant - sub-part of an offer, a price is attached to it, while certain parameters of the offer are fixed across all variants (e.g. departure and arrival station) others change (e.g. route, media type)

addon - additional service and/or product that is available for a offer variant e.g. additional catering at the seat

mode - means of transport classification which describes how fast this means is, how often there are stops, how dynamic routes are etc. (e.g. bus, train, tram)

media - the available possibilities which can be used as medium for tickets (e.g. SwissPass, paper ticket)

offer - the possibility to buy a certain combination of tickets (those being offered) in a specified amount of time until the offer expires, when buying offers in the specified amount of time one can expect that this will be successful, requesting offers could lead to some sort of reservation being made

personalization - the process of tailoring a ticket to a specific person, the amount of data needed for personalization of a ticket can vary, it can also be possible that a ticket is unpersonalized i.e. anonymous

segment - part of a route or a connection, where at the beginning or at the end (or at both) a transfer is necessary, between segments the means of transport could change, within a segment there is no transfer