plan api changes (#646)

* plan api changes * adapt ui to new api * wip * wip * wip
motis-project · Nov 5, 2024 · 37b7dfa · 37b7dfa
1 parent 0a7b57b
commit 37b7dfa
Show file tree

Hide file tree

Showing 13 changed files with 425 additions and 317 deletions.
diff --git a/openapi.yaml b/openapi.yaml
@@ -268,6 +268,39 @@ paths:
           schema:
             type: string
 
+        - name: via
+          in: query
+          required: false
+          description: |
+            List of via stops to visit (only stop IDs, no coordinates allowed for now).
+            Also see the optional parameter `viaMinimumStay` to set a set a minimum stay duration for each via stop.
+          schema:
+            type: array
+            maxItems: 2
+            items:
+              type: string
+          explode: false
+
+        - name: viaMinimumStay
+          in: query
+          required: false
+          description: |
+            Optional. If not set, the default is `0,0` - no stay required.
+            
+            For each `via` stop a minimum stay duration in minutes.
+            
+            The value `0` signals that it's allowed to stay in the same trip.
+            This enables via stays without counting a transfer and can lead 
+            to better connections with less transfers. Transfer connections can
+            still be found with `viaMinimumStay=0`.
+          schema:
+            default: [ 0, 0 ]
+            type: array
+            maxItems: 2
+            items:
+              type: integer
+          explode: false
+
         - name: time
           in: query
           required: false
@@ -315,20 +348,24 @@ paths:
           in: query
           required: false
           description: |
-            Minimum transfer time for each transfer.
-            TODO: pass parameter to nigiri
+            Optional. Default is 0 minutes.
+            
+            Minimum transfer time for each transfer in minutes.
           schema:
             type: integer
+            default: 0
 
         - name: transferTimeFactor
           in: query
           required: false
           description: |
-            Factor to multiply transfer times with.
-            TODO: pass parameter to nigiri
+            Optional. Default is 1.0
+            
+            Factor to multiply minimum required transfer times with.
+            Values smaller than 1.0 are not supported.
           schema:
-            type: integer
-            default: 1
+            type: number
+            default: 1.0
 
         - name: wheelchair
           in: query
@@ -338,19 +375,71 @@ paths:
             type: boolean
             default: false
 
-        - name: mode
+        - name: transitModes
           in: query
           required: false
           description: |
-            A comma separated list of allowed modes.
+            Optional. Default is `TRANSIT` which allows all transit modes (no restriction).
+            Allowed modes for the transit part. If empty, no transit connections will be computed.
+            For example, this can be used to allow only `METRO,SUBWAY,TRAM`.
+          schema:
+            default:
+              - TRANSIT
+            type: array
+            items:
+              $ref: '#/components/schemas/Mode'
+          explode: false
+
+        - name: directModes
+          in: query
+          required: false
+          description: |
+            Optional. Default is `WALK` which will compute walking routes as direct connections.
+            
+            Modes used for direction connections from start to destination without using transit.
+            Results will be returned on the `direct` key.
+            
+            Note: Direct connections will only be returned on the first call. For paging calls, they can be omitted.
             
-            Default if not provided: `WALK,TRANSIT`
+            Note: Transit connections that are slower than the fastest direct connection will not show up.
+            This is being used as a cut-off during transit routing to speed up the search.
+            To prevent this, it's possible to send two separate requests (one with only `transitModes` and one with only `directModes`).
+            
+            Only non-transit modes such as `WALK`, `BIKE`, `CAR`, `BIKE_SHARING`, etc. can be used.
+          schema:
+            default:
+              - WALK
+            type: array
+            items:
+              $ref: '#/components/schemas/Mode'
+          explode: false
+
+        - name: preTransitModes
+          in: query
+          required: false
+          description: |
+            Optional. Default is `WALK`. Only applies if the `from` place is a coordinate (not a transit stop). Does not apply to direct connections (see `directModes`).
+            
+            A list of modes that are allowed to be used from the `from` coordinate to the first transit stop. Example: `WALK,BIKE_SHARING`.
+          schema:
+            default:
+              - WALK
+            type: array
+            items:
+              $ref: '#/components/schemas/Mode'
+          explode: false
+
+        - name: postTransitModes
+          in: query
+          required: false
+          description: |
+            Optional. Default is `WALK`. Only applies if the `to` place is a coordinate (not a transit stop). Does not apply to direct connections (see `directModes`).
+            
+            A list of modes that are allowed to be used from the last transit stop to the `to` coordinate. Example: `WALK,BIKE_SHARING`.
           schema:
             default:
               - WALK
-              - TRANSIT
             type: array
-            minItems: 1
             items:
               $ref: '#/components/schemas/Mode'
           explode: false
@@ -898,16 +987,6 @@ components:
         level:
           description: level according to OpenStreetMap
           type: number
-        arrivalDelay:
-          type: integer
-          description: |
-            The offset from the scheduled arrival time of the boarding stop in this leg (in milliseconds).
-            Scheduled time of arrival at boarding stop = endTime - arrivalDelay
-        departureDelay:
-          type: integer
-          description: |
-            The offset from the scheduled departure time of the boarding stop in this leg (in milliseconds).
-            Scheduled time of departure at boarding stop = startTime - departureDelay
         arrival:
           description: arrival time
           type: string
@@ -916,6 +995,14 @@ components:
           description: departure time
           type: string
           format: date-time
+        scheduledArrival:
+          description: scheduled arrival time
+          type: string
+          format: date-time
+        scheduledDeparture:
+          description: scheduled departure time
+          type: string
+          format: date-time
         scheduledTrack:
           description: scheduled track from the static schedule timetable dataset
           type: string
@@ -999,8 +1086,8 @@ components:
         - to
         - departure
         - arrival
-        - departureDelay
-        - arrivalDelay
+        - scheduledArrival
+        - scheduledDeparture
         - realTime
         - polyline
       properties:
@@ -1028,16 +1115,14 @@ components:
           description: arrival time
           type: string
           format: date-time
-        departureDelay:
-          type: integer
-          description: |
-            The offset from the scheduled departure time of the boarding stop in this leg (in milliseconds).
-            Scheduled time of departure at boarding stop = startTime - departureDelay
-        arrivalDelay:
-          type: integer
-          description: |
-            The offset from the scheduled arrival time of the boarding stop in this leg (in milliseconds).
-            Scheduled time of arrival at boarding stop = endTime - arrivalDelay
+        scheduledDeparture:
+          description: scheduled departure time
+          type: string
+          format: date-time
+        scheduledArrival:
+          description: scheduled arrival time
+          type: string
+          format: date-time
         realTime:
           description: Whether there is real-time data about this leg
           type: boolean
@@ -1088,8 +1173,6 @@ components:
         - exit
         - stayOn
         - area
-        - lon
-        - lat
       properties:
         relativeDirection:
           $ref: '#/components/schemas/Direction'
@@ -1161,10 +1244,9 @@ components:
         - mode
         - startTime
         - endTime
-        - departureDelay
-        - arrivalDelay
+        - scheduledStartTime
+        - scheduledEndTime
         - realTime
-        - distance
         - duration
         - from
         - to
@@ -1188,46 +1270,37 @@ components:
           type: string
           format: date-time
           description: leg arrival time
-        departureDelay:
-          type: integer
-          description: |
-            The offset from the scheduled departure time of the boarding stop in this leg (in milliseconds).
-            Scheduled time of departure at boarding stop = startTime - departureDelay
-        arrivalDelay:
-          type: integer
-          description: |
-            The offset from the scheduled arrival time of the boarding stop in this leg (in milliseconds).
-            Scheduled time of arrival at boarding stop = endTime - arrivalDelay
+        scheduledStartTime:
+          type: string
+          format: date-time
+          description: scheduled leg departure time
+        scheduledEndTime:
+          type: string
+          format: date-time
+          description: scheduled leg arrival time
         realTime:
           description: Whether there is real-time data about this leg
           type: boolean
         distance:
-          description: The distance traveled while traversing this leg in meters.
+          description: For non-transit legs the distance traveled while traversing this leg in meters.
           type: number
         interlineWithPreviousLeg:
           description: For transit legs, if the rider should stay on the vehicle as it changes route names.
           type: boolean
-        route:
-          description: |
-            For transit legs, the route of the bus or train being used.
-            For non-transit legs, the name of the street being traversed.
-          type: string
         headsign:
           description: |
             For transit legs, the headsign of the bus or train being used.
             For non-transit legs, null
           type: string
-        agencyName:
-          type: string
-        agencyUrl:
-          type: string
         routeColor:
           type: string
         routeTextColor:
           type: string
         routeType:
           type: string
-        routeId:
+        agencyName:
+          type: string
+        agencyUrl:
           type: string
         agencyId:
           type: string