Passenger Monitoring API

The passenger monitoring module (paxmon) tracks passenger groups and provides load information for trips based on capacity data and the tracked passenger groups.

This page describes parts of the paxmon API.

The passenger forecast module (paxforecast) offers a simulation API based on paxmon, see Passenger Forecast: Simulation API.

Parallel Universes

In order to allow simulation of different scenarios, paxmon offers the ability to freeze and copy the current system state (tracked passenger groups and optionally the real-time schedule as well). The system state is called a universe and multiple parallel universes can be created.

Each universe has an ID (currently a 32 bit unsigned integer). The main universe has ID 0 and can not be destroyed. All MOTIS APIs use the main universe unless they have a universe or schedule parameter. Simulations should always be run on a forked universe, never on the main universe.

Universe Creation

To create a new universe, use the /paxmon/fork_universe API with a request of type PaxMonForkUniverseRequest. It has the following fields:

• universe (u32): ID of the base universe. This is the universe that is copied. Specify 0 to copy the main universe or a forked universe to create a fork of that universe. The base universe can be destroyed before universes forked from it are destroyed, i.e. forked universes don't depend on their base universe once forked (note that the main universe can't be destroyed).
• fork_schedule (bool): If set to true, the schedule is frozen and copied as well. This is required for the simulation of real-time updates or if MOTIS is run in live mode where real-time updates may be applied before the universe is destroyed. If set to false, reuse the schedule of the base universe. Normally, this should always be set to true.
• ttl (u32): Time to live of the new universe, in seconds. The universe is automatically destroyed when it is not accessed for at least ttl seconds. Each universe access (including keep alive requests) resets the remaining time to live.
  • If set to 0 the universe never expires and must be destroyed manually.
  • The server limits the allowed range of the ttl value based on its configuration. There is an upper limit and unlimited universes (ttl = 0) may be disabled. The actual time to live for the newly created universe is returned in the API response.

The API returns a PaxMonForkUniverseResponse with the following fields:

• universe (u32): ID of the new universe. Use this for further paxmon and paxforecast API calls. Remember to destroy the universe once it is no longer needed.
• schedule (u64): Schedule ID of the new universe. Use this for API calls to other modules such as /routing. Note that only some API calls accept a schedule parameter (most API calls only support the main universe/schedule).
• ttl (u32): The time to live assigned by the server, in seconds. Can be 0 if the universe never expires.

Example API request:

{
  "destination": { "type": "Module", "target": "/paxmon/fork_universe" },
  "content_type": "PaxMonForkUniverseRequest",
  "content": {
    "universe": 0,
    "fork_schedule": true,
    "ttl": 120
  },
  "id": 0
}

Example API response:

{
  "destination": { "type": "Module", "target": "" },
  "content_type": "PaxMonForkUniverseResponse",
  "content": {
    "universe": 1,
    "schedule": 5,
    "ttl": 120
  },
  "id": 0
}

Universe Destruction

A parallel universe must be destroyed when it is no longer needed. To destroy a universe, use the /paxmon/destroy_universe API with a request of type PaxMonDestroyUniverseRequest. It has the following field:

• universe (u32): ID of the universe to destroy.

Note that the main universe (ID 0) can't be deleted. The API will return an error in that case or if the universe with the given ID is not found.

If the schedule was forked when creating the universe, the schedule copy is automatically destroyed once all universes using it are destroyed.

Example API request:

{
  "destination": { "type": "Module", "target": "/paxmon/destroy_universe" },
  "content_type": "PaxMonDestroyUniverseRequest",
  "content": {
    "universe": 1
  },
  "id": 0
}

Example API response:

{
  "destination": { "type": "Module", "target": "" },
  "content_type": "MotisSuccess",
  "content": {
  },
  "id": 0
}

If a universe has a ttl > 0 and is not used for at least ttl seconds, it is destroyed automatically by the server. Universes with a ttl > 0 can also be destroyed using the API at any time.

Trip Load Information

To request load information for a trip, use the /paxmon/trip_load_info API with a request of type PaxMonGetTripLoadInfosRequest with the following fields:

• universe (u32): Paxmon universe ID
• trips (list of trip IDs): List of trips for which load information should be returned

The API will return a PaxMonGetTripLoadInfosResponse with the following fields:

• load_infos (array of PaxMonTripLoadInfo objects): Load information for each requested trip, in the same order as in the request (i.e. the first entry in this array is the load information for the first trip in the request and so on)
  • tsi (TripServiceInfo object): Trip information
    • trip (TripId object): The trip ID
    • primary_station (Station object): The primary trip station (usually the first scheduled stop)
    • secondary_station (Station object): The secondary trip station (usually the last scheduled stop)
    • service_infos (array of ServiceInfo objects): Information about train numbers, categories and lines used by this trip
  • edges (array of PaxMonEdgeLoadInfo objects): Load information for each trip section
    • from (Station object): Departure station of this section
    • to (Station object): Arrival station of this section
    • departure_schedule_time (unix timestamp): Scheduled departure time
    • departure_current_time (unix timestamp): Current (real-time) departure time
    • arrival_schedule_time (unix timestamp): Scheduled arrival time
    • arrival_current_time (unix timestamp): Current (real-time) arrival time
    • capacity_type (string): Type of capacity information for this section
      • Known: Known capacity (see capacity field)
      • Unknown: No capacity information for this section available
      • Unlimited: Unlimited capacity
    • capacity (u32): Capacity (max. number of passengers) (can only be used if capacity_type is Known)
    • dist (PaxMonDistribution object): Information about the predicted number of passengers for this section
      • min (u32): Minimum predicted number of passengers
      • max (u32): Maximum predicted number of passengers
      • q5 (u32): 5% quantile
      • q50 (u32) Median (50% quantile) predicted number of passengers
      • q95 (u32): 95% quantile
      • pdf (array of PaxMonPdfEntry objects): Probability density function (PDF) of the predicted passenger distribution for this section. The list is sorted in ascending order by number of passengers, i.e. the first entry gives the predicted minimum number of passengers and the last entry gives the predicted maximum number of passengers.
        • n (u32): Number of passengers
        • p (float): Probability
    • updated (bool): Not used for this API
    • possibly_over_capacity (bool): True if this section may be over capacity, false if the maximum number of passengers predicted is within the capacity limits
    • prob_over_capacity (float): Probability of the number of passengers being over capacity
    • expected_passengers (u32): Number of passengers according to planned journeys

Example API request:

{
  "destination": { "type": "Module", "target": "/paxmon/trip_load_info" },
  "content_type": "PaxMonGetTripLoadInfosRequest",
  "content": {
    "universe": 0,
    "trips": [
      {
        "station_id": "8000456",
        "train_nr": 789,
        "time": 1569317280,
        "target_station_id": "8000012",
        "target_time": 1569338460,
        "line_id": "42"
      }
    ]
  },
  "id": 0
}

Passenger Groups

Passenger groups are represented using the PaxMonGroup type in the API. It has the following fields:

• id (u64): Internal ID of the group, automatically generated by MOTIS
• source (PaxMonDataSource object): External ID of the group, given by the external source that added the group. There may be exactly one group per external ID. Typically, primary_ref is set to the ID used in the external source and secondary_ref is used as a counter if more than one paxmon passenger group is created for the external group (e.g. because the external group is split into multiple smaller groups).
  • primary_ref (u32): First part of the ID assigned by an external source
  • secondary_ref (u32): Second part of the ID assigned by an external source
• passenger_count (u32): Number of passengers
• routes (array of PaxMonGroupRoute objects): Each group has a list of possible group routes. At least one route is always present (the originally planned route). Each route has a probability, and the sum of probabilities over all the routes should be ~100%.
• reroute_log (array of PaxMonRerouteLogEntry objects): Records information about all changes to the group routes.