Installation
Features
API Building Blocks
API Endpoints
Publications

Intermodal Routing Request

This is the intermodal routing API. Intermodal here means that start as well as destination can be either a coordinate (latitude and longitude) or a public transport station (given by its name and/or ID). This request enables the search algorithm in the backend to use all transport modes specified in the request.

  • start_type required

    Specifies the type of the start parameter. See Start.

  • start required

    See Start.

  • start_modes required

    The transport modes allowed at the start. See Modes.

  • destination_type required

    Specifies the type of the destination parameter. See Destination.

  • destination required

    See Destination.

  • destination_modes required

    The transport modes allowed at the destination. See Modes.

  • search_type optional, default is Default

    This parameter specifies the set of optimization criteria to use.

    • Default: optimize travel time and number of transfers. This computes the Pareto set using multi-criteria optimization.
    • SingleCriterion: optimizes a weighted sum where every transfer counts 20 minutes.
    • SingleCriterionNoIntercity: the same as SingleCriterion - excluding all long distance (intercity) trains
  • search_dir optional, default is Forward

    The search direction. This defines whether the algorithm searches from departure to arrival (forward in time) or from arrival to departure (backward in time). Thus, start is either specifying the source (search_dir=Forward) or the destination (search_dir=Backward).

    • Forward: the start parameter specifies the departure of the journey. The destination parameter specifies the arrival of the journey.
    • Backward: the start parameter specifies the arrival of the journey. The destination parameter specifies the departure of the journey.

Start

Start defines the entry point from where to start the search. If the search direction search_dir is set to Forward, this the beginning of the journey (departure). However, if search_dir is set to Backward, this is the end of the journey (arrival) because then, the algorithm searches starting from the arrival station / location.

  • start_type required

    The type of the struct of the start entry.

    • IntermodalOntripStart: single departure/arrival (depending on search_dir) time with start coordinates.
    • IntermodalPretripStart: departure/arrival (depending on search_dir) time interval with start coordinates
    • PretripStart: departure/arrival (depending on search_dir) time interval with start station
    • OntripStationStart: single departure/arrival (depending on search_dir) time with station
    • OntripTrainStart: specifies the train the user is currently in. Time and location are determined automatically.

Intermodal Ontrip Start

For “ontrip” queries, the travel time is the time between the given departure_time (which is actually the arrival time when search_dir is set to Forward) and the departure/arrival at the search destination.

  • position required

    The departure coordinates for search_dir=Forward or arrival coordinates for search_dir=Backward. See Position.

  • departure_time required

    The time to start the search at. The search does only consider arrivals before (if search_dir is Backward) or departures after (if search_dir is Forward) this point in time. See Times.

OnTrip Station Start

This query is useful if the traveller is currently at a station (or planning to be at a station) and wants to compute optimal journeys to their destination (station or location). For “ontrip” queries, the travel time is the time between the given departure_time (which is actually the arrival time when search_dir is set to Forward) and the departure/arrival at the search destination.

  • station required

    The departure station for search_dir=Forward or arrival station for search_dir=Backward. See InputStation.

  • departure_time required

    The time to start the search at. The search does only consider arrivals before (if search_dir is Backward) or departures after (if search_dir is Forward) this point in time. See Times.

OnTrip Train Start

This start type is useful if the user is currently in a train. The search algorithm first locates the train and considers all feasible options: at each next stop, the user can either stay in the train or alight. After alighting, the user can either be at their destination, change to another train or walk to another station. Note that the OnTrip Station Start has not the same effect as it will not count the transfer time to other trains.

  • trip required

    The trip to search from. See Trip ID.

  • station required

    Station to start searching from (one of the stops of the trip). Should be the first station, the user can alight. See Input Station.

  • arrival_time required

    The arrival time to assume at the station. See Times.

Intermodal PreTrip Start

Pretrip journey planning considers all departures/arrivals in a time interval (depending on the search_dir). Therefore, the Pareto optimization criteria are not travel time and number of transfers but “later departure”, “earlier arrival” and number of transfers. This means that the result set may contain a longer journey with more transfers if its departure is later or its arrival is earlier.

Note that this API does not return journeys that are superseded by journeys arriving (search_dir=Forward) or departing (search_dir=Backward) outside of the interval. This way, the union of journey Pareto-sets with disjunct search intervals are still Pareto-sets where every connection stays optimal. This property is important to deliver coherent results for the “search earlier” and “search later” functionality in a user interface.

If a client application provides the functionality to scroll through connections (search for earlier or later connections) it is recommended to use the extend_interval_earlier and extend_interval_later parameters: since the search backend of MOTIS is stateless, it is the task of the client to keep track bounds of the interval that has been considered. Therefore, it is important to store the interval_begin and interval_end attributes from the routing response. For the first request, set extend_interval_earlier as well as extend_interval_later to true. For subsequent requests set extend_interval_earlier if searching for earlier connections and extend_interval_later for later connections.

  • position required

    The departure coordinates for search_dir=Forward or arrival coordinates for search_dir=Backward. See Position.

  • interval required

    The (initial) time interval to consider to depart / arrive. This time interval may be extended by the search algorithm if the min_connection_count cannot be reached with non-Pareto-dominated connections departing/arriving within the interval. See Interval.

  • min_connection_count optional integer, default is 0

    This requires interval extension to be enabled. Thus, extend_interval_earlier || extend_interval_later needs to be true. Otherwise, min_connection_count does not have an effect. The search extends the interval in the specified direction until there are min_connection_count Pateto-optimal connections in the result set. Note: if there are less than min_connection_count journeys in the result set, this means that the interval bounds have been reached. If the interval has been extended, the response contains the new bounds.

  • extend_interval_earlier optional boolean, default is false

    Extend the interval to search for earlier connections until min_connection_count is reached.

  • extend_interval_later optional boolean, default is false

    Extend the interval to search for later connections until min_connection_count is reached.

PreTrip Start

This start type is similar to the Intermodal PreTrip Start. The only difference is that the position is a station here. So for this start type, the search is restricted to start from this station.

The search will only consider footpaths from the timetable data (HAFAS Rohdaten or GTFS). In contrast to the Intermodal PreTrip Start, equivalent stations (see HAFAS Rohdaten documentation “Meta Station”) are considered as start stations, too.

Destination

If the search direction search_dir is set to Forward, this the end of the journey (arrival). However, if search_dir is set to Backward, the is the begin of the journey (departure) because then, the algorithm searches starting from the arrival station / location.

  • destination_type required

    The type of the struct of the destination entry.

Modes

The start_modes and destination_modes lists determine which transport modes are used in conjunction with Intermodal OnTrip Start, Intermodal PreTrip Start and InputPosition destination type. If a station is specified as start / destination, the modes have no effect and should be left empty.

Both, start_modes and destination_modes are arrays that contain the following data structures:

  • mode_type required
    • Foot: walking within a specified duration
    • Bike: riding a bicyle within a specified duration
    • Car: driving a case within a specified duration
    • FootPPR: walking within a specified duration (with profile parameter)
    • CarParking: like car but uses a parking place near the station
  • mode required

    See blow.

  • duration required

    Maximal duration to walk in minutes.

Bike

  • duration required

    Maximal duration to ride in minutes.

Car

  • duration required

    Maximal duration to drive in minutes.

Foot PPR

Car Parking

  • max_car_duration required, type integer

    Maximal duration to drive in minutes.

  • ppr_search_options required

    Used for the section from the parking place to the station. See PPR Search Profile.

Routing Response

The routing response contains all Pareto-optimal connections.

  • connections array of Connections

    Array of all optimal connections.

  • interval_begin type integer

    The interval that was searched. This might differ from the initial interval given in the request if min_connection_count was set to a value greater than zero.

  • interval_end type integer

    The end of the interval that was searched.

Intermodal Routing Request Example 
{
  "destination": {
    "type": "Module",
    "target": "/intermodal"
  },
  "content_type": "IntermodalRoutingRequest",
  "content": {
    "start_type": "PretripStart",
    "start": {
      "station": {
        "name": "Zürich, Stampfenbachplatz",
        "id": "8591379"
      },
      "interval": {
        "begin": 1586078940,
        "end": 1586086140
      },
      "min_connection_count": 5,
      "extend_interval_earlier": true,
      "extend_interval_later": true
    },
    "start_modes": [
      {
        "mode_type": "FootPPR",
        "mode": {
          "search_options": {
            "profile": "default",
            "duration_limit": 900
          }
        }
      }
    ],
    "destination_type": "InputStation",
    "destination": {
      "name": "Olten",
      "id": "8500218"
    },
    "destination_modes": [
      {
        "mode_type": "FootPPR",
        "mode": {
          "search_options": {
            "profile": "default",
            "duration_limit": 900
          }
        }
      }
    ],
    "search_type": "Accessibility",
    "search_dir": "Forward"
  }
}
Intermodal Routing Response Example 
{
  "content_type": "RoutingResponse",
  "content": {
    "connections": [
      {
        "stops": [
          {
            "station": {
              "id": "8591379",
              "name": "Zürich, Stampfenbachplatz",
              "pos": {
                "lat": 47.380292,
                "lng": 8.542776
              }
            },
            "arrival": {
              "track": "",
              "schedule_track": ""
            },
            "departure": {
              "time": 1586006460,
              "schedule_time": 1586006460,
              "track": "",
              "schedule_track": "",
              "valid": true
            },
            "enter": true
          },
          {
            "station": {
              "id": "8587349",
              "name": "Zürich, Bahnhofquai/HB",
              "pos": {
                "lat": 47.37756,
                "lng": 8.541741
              }
            },
            "arrival": {
              "time": 1586006580,
              "schedule_time": 1586006580,
              "track": "",
              "schedule_track": "",
              "valid": true
            },
            "departure": {
              "time": 1586006580,
              "schedule_time": 1586006580,
              "track": "",
              "schedule_track": "",
              "valid": true
            },
            "exit": true
          },
          {
            "station": {
              "id": "8503000",
              "name": "Zürich HB",
              "pos": {
                "lat": 47.378177,
                "lng": 8.540212
              }
            },
            "arrival": {
              "time": 1586007000,
              "schedule_time": 1586007000,
              "track": "",
              "schedule_track": "",
              "valid": true
            },
            "departure": {
              "time": 1586007000,
              "schedule_time": 1586007000,
              "track": "32",
              "schedule_track": "32",
              "valid": true
            },
            "enter": true
          },
          {
            "station": {
              "id": "8500218",
              "name": "Olten",
              "pos": {
                "lat": 47.351935,
                "lng": 7.907699
              }
            },
            "arrival": {
              "time": 1586008800,
              "schedule_time": 1586008800,
              "track": "3",
              "schedule_track": "3",
              "valid": true
            },
            "departure": {
              "track": "",
              "schedule_track": ""
            },
            "exit": true
          }
        ],
        "transports": [
          {
            "move_type": "Transport",
            "move": {
              "range": {
                "from": 0,
                "to": 1
              },
              "category_name": "T",
              "category_id": 2,
              "clasz": 7,
              "train_nr": 12083,
              "line_id": "14",
              "name": "T 14",
              "provider": "Verkehrsbetriebe Zürich INFO+",
              "direction": "Zürich, Triemli"
            }
          },
          {
            "move_type": "Walk",
            "move": {
              "range": {
                "from": 1,
                "to": 2
              },
              "mumo_id": -1,
              "mumo_type": ""
            }
          },
          {
            "move_type": "Transport",
            "move": {
              "range": {
                "from": 2,
                "to": 3
              },
              "category_name": "IC",
              "category_id": 23,
              "clasz": 1,
              "train_nr": 1526,
              "line_id": "5",
              "name": "IC 5",
              "provider": "Schweizerische Bundesbahnen SBB",
              "direction": "Lausanne"
            }
          }
        ],
        "trips": [
          {
            "range": {
              "from": 0,
              "to": 1
            },
            "id": {
              "station_id": "8591354",
              "train_nr": 12083,
              "time": 1586005440,
              "target_station_id": "8503610",
              "target_time": 1586007660,
              "line_id": "14"
            },
            "debug": "FPLAN:1814564:1814599"
          },
          {
            "range": {
              "from": 2,
              "to": 3
            },
            "id": {
              "station_id": "8506302",
              "train_nr": 1526,
              "time": 1586002020,
              "target_station_id": "8501120",
              "target_time": 1586015100,
              "line_id": "5"
            },
            "debug": "FPLAN:86300:86327"
          }
        ],
        "attributes": [
          {
            "range": {
              "from": 2,
              "to": 3
            },
            "code": "Businesszone in 1. Klasse",
            "text": "BZ"
          },
          {
            "range": {
              "from": 2,
              "to": 3
            },
            "code": "Ruhezone in 1. Klasse",
            "text": "RZ"
          }
        ],
        "free_texts": [],
        "problems": []
      }
    ],
    "interval_begin": 1586006280,
    "interval_end": 1586013480,
    "direct_connections": []
  },
  "id": 1
}