-
Notifications
You must be signed in to change notification settings - Fork 47
Passenger Forecast: Simulation API
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 (inPaxMonUpdatedTrip
) 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 (inPaxMonUpdatedTrip
) 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
}
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 attime
-
stations
(list of station ids): Select passengers that are at one of the listed stations attime
(not in a trip)
-
The following measure types are supported by the simulation:
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"
}
}
-
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 theplanned...
fields above should switch to a journey containing this trip
-
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 bytype
. 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 ..."
}
}