Passenger Forecast: Simulation API

Measure Simulation

The /paxforecast/apply_measures API can be used to simulate a list of measures (both real-time updates and announcements).

Simulations must be run in a separate paxmon universe. It is not possible to undo simulations - create (and destroy!) multiple universes if necessary. See Passenger Monitoring API for information about universes and APIs to create and destroy them.

The API request is of type PaxForecastApplyMeasuresRequest and takes these parameters:

• universe (u32): Paxmon universe ID
• measures (list of measures): A list of measures to simulate. See below for a list of supported measure types and their properties. Each entry in the list has this format:
  • measure_type (string): Type of the measure (see below)
  • measure (object): Properties of the measure (depending on the measure type)
• replace_existing (true): If set to true, only simulate the measures given in this API call. If set to false, measures from previous calls are kept and merged with the new measures for this simulation. Should always be set to true for now.
• include_before_trip_load_info (bool): If set to true, before_edges in the response (in PaxMonUpdatedTrip) is set, otherwise it will be empty. It contains load information for all trip edges before any changes were made. (Note that if the trip route is modified using real-time updates, this contains the state of the trip before any of those changes were applied.)
• include_after_trip_load_info (bool): If set to true, after_edges in the response (in PaxMonUpdatedTrip) is set, otherwise it will be empty. It contains load information for all trip edges after all changes were made. (Note that if the trip route is modified using real-time updates, this contains the state of the trip after any of those changes were applied.)

The API returns a PaxForecastApplyMeasuresResponse message in case of success and a MotisError message otherwise.

Example API call (see below for examples for the different measure types):

{
  "destination": { "type": "Module", "target": "/paxforecast/apply_measures" },
  "content_type": "PaxForecastApplyMeasuresRequest",
  "content": {
    "universe": 1,
    "measures": [
      {
        "measure_type": "RtUpdateMeasure",
        "measure": {
          "recipients": {
            "trips": [],
            "stations": [
              "8000123"
            ]
          },
          "time": 1643806800,
          "type": "RIBasis",
          "content": "{\n  \"meta\": {\n    \"id\": \"636fb640-c935-4c57-baeb-1c3e597cb47e\",\n ..."
        }
      }
    ],
    "replace_existing": true,
  },
  "id": 0
}

Measures

Common properties

All measures have the following shared properties:

• time (unix timestamp): Time at which the measure takes effect and passengers are made aware of it. Note that the time is not forwarded to this point during the simulation, i.e. no real-time updates (other than those specified as rt update measures) are applied during the simulation. If a call to /paxforecast/apply_measures contains measures with different timestamps, a simulation is run for each unique timestamp. All measures with the same timestamp are applied in one step.
• recipients: Select a subset of passengers that is made aware of the measure (e.g. using an announcement)
  • trips (list of trip ids): Select passengers that are in one of the listed trips at time
  • stations (list of station ids): Select passengers that are at one of the listed stations at time (not in a trip)

Measure types

The following measure types are supported by the simulation:

Trip load information (TripLoadInfoMeasure)

Communicate the expected load/occupancy of a trip.

• recipients: See above
• time: See above
• trip (trip id): Id of the trip
• level (string): Expected occupancy level of the trip. The following occupancy levels are supported:
  • Low: Low load, seats available
  • NoSeats: High load, no seats available (only standing room)
  • Full: Trip is full, boarding not possible
  • Unknown: No information (default value for all trips where no other load information is specified, should not be used as an input in the API)

Example: Announcement at 2022-02-02T13:00:00Z: Trip 789 is full. The announcement is made at the station with id "8000123".

{
  "measure_type": "TripLoadInfoMeasure",
  "measure": {
    "recipients": {
      "trips": [],
      "stations": [
        "8000123"
      ]
    },
    "time": 1643806800,
    "trip": {
      "station_id": "8000456",
      "train_nr": 789,
      "time": 1569317280,
      "target_station_id": "8000012",
      "target_time": 1569338460,
      "line_id": "42"
    },
    "level": "Full"
  }
}

Trip recommendation (TripRecommendationMeasure)

• recipients: See above
• time: See above
• planned_trips (list of trip ids): Passengers that have at least one of the planned trips in their current journey should use the recommended trip
• planned_destinations (list of station ids): Passengers that have one of the listed stations as their planned destination should use the recommended trip
• recommended_trip (trip id): Passengers selected using the planned... fields above should switch to a journey containing this trip

Real-time update (RtUpdateMeasure)

• recipients: See above
• time: See above
• type (string): Format of the real time update message. Currently supported:
  • RIBasis
  • RISML
• content (string): The real time update message in the format specified by type. The real-time message should have the same timestamp (e.g. created field in RI Basis) as the measure (time field of this object).

Example: Apply an RI Basis update and re-run the behavior simulation for the specified recipients.

{
  "measure_type": "RtUpdateMeasure",
  "measure": {
    "recipients": {
      "trips": [],
      "stations": [
        "8000123"
      ]
    },
    "time": 1643806800,
    "type": "RIBasis",
    "content": "{\n  \"meta\": {\n    \"id\": \"636fb640-c935-4c57-baeb-1c3e597cb47e\",\n ..."
  }
}