openapi.yaml

openapi: 3.1.0
info:
  title: MOTIS API
  description: This is the MOTIS routing API.
  contact:
    email: felix@triptix.tech
  license:
    name: MIT
    url: https://opensource.org/license/mit
  version: v1
externalDocs:
  description: Find out more about MOTIS
  url: https://triptix.tech
servers:
  - url: https://demo.triptix.tech
paths:
  /api/v1/reverse-geocode:
    get:
      tags:
        - geocode
      summary: Translate coordinates to the closest address(es)/places/stops.
      operationId: reverseGeocode
      parameters:
        - name: place
          in: query
          required: true
          description: latitude, longitude in degrees
          schema:
            type: string
      responses:
        200:
          description: A list of guesses to resolve the coordinates to a location
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Match'

  /api/v1/geocode:
    get:
      tags:
        - geocode
      summary: Autocompletion & geocoding that resolves user input addresses including coordinates
      operationId: geocode
      parameters:
        - name: text
          in: query
          required: true
          description: the (potentially partially typed) address to resolve
          schema:
            type: string

        - name: language
          in: query
          required: false
          description: |
            language tags as used in OpenStreetMap
            (usually ISO 639-1, or ISO 639-2 if there's no ISO 639-1)
          schema:
            type: string

      responses:
        200:
          description: A list of guesses to resolve the text to a location
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Match'

  /api/v1/plan:
    get:
      tags:
        - routing
      summary: Computes optimal connections from one place to another.
      operationId: plan
      parameters:
        - name: fromPlace
          in: query
          required: true
          description: latitude, longitude, level tuple in degrees or stop id
          schema:
            type: string

        - name: toPlace
          in: query
          required: true
          description: latitude, longitude, level tuple in degrees or stop id
          schema:
            type: string

        - name: date
          in: query
          required: false
          description: |
            Optional. Defaults to the current date.
            
            Departure date ($arriveBy=false) / arrival date ($arriveBy=true), format: 06-28-2024
          schema:
            type: string

        - name: time
          in: query
          required: false
          description: |
            Optional. Defaults to the current time.
            
            Meaning depending on `arriveBy`
              - Departure time for `arriveBy=false`
              - Arrival time for `arriveBy=true`
            
            Format:
              - 12h format: 7:06pm
              - 24h format: 19:06
          schema:
            type: string

        - name: maxTransfers
          in: query
          required: false
          description: |
            The maximum number of allowed transfers.
            If not provided, the routing uses the server-side default value
            which is hardcoded and very high to cover all use cases.
            
            *Warning*: Use with care. Setting this too low can lead to
            optimal (e.g. the fastest) journeys not being found.
            If this value is too low to reach the destination at all,
            it can lead to slow routing performance.
          schema:
            type: integer

        - name: maxHours
          in: query
          required: false
          description: |
            The maximum travel time in hours.
            If not provided, the routing to uses the value
            hardcoded in the server which is usually quite high.
            
            *Warning*: Use with care. Setting this too low can lead to
            optimal (e.g. the least transfers) journeys not being found.
            If this value is too low to reach the destination at all,
            it can lead to slow routing performance.
          schema:
            type: number

        - name: minTransferTime
          in: query
          required: false
          description: Minimum transfer time for each transfer.
          schema:
            type: integer

        - name: transferTimeFactor
          in: query
          required: false
          description: Factor to multiply transfer times with.
          schema:
            type: integer
            default: 1

        - name: wheelchair
          in: query
          description: Whether the trip must be wheelchair accessible.
          required: false
          schema:
            type: boolean
            default: false

        - name: mode
          in: query
          required: false
          description: |
            A comma separated list of allowed modes.
            
            Default if not provided: `WALK,TRANSIT`
          schema:
            default:
              - WALK
              - TRANSIT
            type: array
            minItems: 1
            items:
              $ref: '#/components/schemas/Mode'
          explode: false

        - name: numItineraries
          in: query
          required: false
          description: |
            The minimum number of itineraries to compute.
            This is only relevant if `timetableView=true`.
            The default value is 5.
          schema:
            type: integer
            default: 5

        - name: pageCursor
          in: query
          required: false
          description: |
            Use the cursor to go to the next "page" of itineraries.
            Copy the cursor from the last response and keep the original request as is.
            This will enable you to search for itineraries in the next or previous time-window.
          schema:
            type: string

        - name: timetableView
          in: query
          required: false
          description: |
            Optional. Default is `true`.
            
            Search for the best trip options within a time window.
            If true two itineraries are considered optimal
            if one is better on arrival time (earliest wins)
            and the other is better on departure time (latest wins).
            In combination with arriveBy this parameter cover the following use cases:
            
            `timetable=false` = waiting for the first transit departure/arrival is considered travel time:
              - `arriveBy=true`: event (e.g. a meeting) starts at 10:00 am,
                compute the best journeys that arrive by that time (maximizes departure time)
              - `arriveBy=false`: event (e.g. a meeting) ends at 11:00 am,
                compute the best journeys that depart after that time
            
            `timetable=true` = optimize "later departure" + "earlier arrival" and give all options over a time window:
              - `arriveBy=true`: the time window around `date` and `time` refers to the arrival time window
              - `arriveBy=false`: the time window around `date` and `time` refers to the departure time window
          schema:
            type: boolean
            default: false

        - name: arriveBy
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: |
            Optional. Default is `false`.
            
              - `arriveBy=true`: the parameters `date` and `time` refer to the arrival time
              - `arriveBy=false`: the parameters `date` and `time` refer to the departure time

        - name: searchWindow
          in: query
          required: false
          description: |
            Optional. Default is 2 hours which is `7200`.
            
            The length of the search-window in seconds. Default value two hours.
            
              - `arriveBy=true`: number of seconds between the earliest departure time and latest departure time
              - `arriveBy=false`: number of seconds between the earliest arrival time and the latest arrival time
          schema:
            type: integer
            default: 7200
            minimum: 0

        - name: maxPreTransitTime
          in: query
          required: false
          description: |
            Optional. Default is 15min which is `900`.
            Maximum time in seconds for the first street leg.
          schema:
            type: integer
            default: 900
            minimum: 0

        - name: maxPostTransitTime
          in: query
          required: false
          description: |
            Optional. Default is 15min which is `900`.
            Maximum time in seconds for the last street leg.
          schema:
            type: integer
            default: 900
            minimum: 0

      responses:
        '200':
          description: routing result
          content:
            application/json:
              schema:
                type: object
                required:
                  - requestParameters
                  - debugOutput
                  - date
                  - from
                  - to
                  - itineraries
                  - previousPageCursor
                  - nextPageCursor
                properties:
                  requestParameters:
                    description: "the routing query"
                    type: object
                    additionalProperties:
                      type: string
                  debugOutput:
                    description: "debug statistics"
                    type: object
                    additionalProperties:
                      type: string
                  date:
                    description: "The time and date of travel"
                    type: integer
                  from:
                    $ref: '#/components/schemas/Place'
                  to:
                    $ref: '#/components/schemas/Place'
                  itineraries:
                    description: list of itineraries
                    type: array
                    items:
                      $ref: '#/components/schemas/Itinerary'
                  previousPageCursor:
                    description: |
                      Use the cursor to get the previous page of results. Insert the cursor into the request and post it to get the previous page.
                      The previous page is a set of itineraries departing BEFORE the first itinerary in the result for a depart after search. When using the default sort order the previous set of itineraries is inserted before the current result.
                    type: string
                  nextPageCursor:
                    description: |
                      Use the cursor to get the next page of results. Insert the cursor into the request and post it to get the next page.
                      The next page is a set of itineraries departing AFTER the last itinerary in this result.
                    type: string

components:
  schemas:
    Area:
      description: Administrative area
      type: object
      required:
        - name
        - admin_level
        - matched
      properties:
        name:
          type: string
          description: Name of the area
        admin_level:
          type: number
          description: |
            [OpenStreetMap `admin_level`](https://wiki.openstreetmap.org/wiki/Key:admin_level)
            of the area
        matched:
          type: boolean
          description: Whether this area was matched by the input text
        default:
          type: boolean
          description: Whether this area should be displayed as default area (area with admin level closest 7)

    Token:
      description: Matched token range (from index, length)
      type: array
      minItems: 2
      maxItems: 2
      items:
        type: number

    Match:
      description: GeoCoding match
      type: object
      required:
        - type
        - name
        - id
        - lat
        - lon
        - tokens
        - areas
        - score
      properties:
        type:
          description: location type
          type: string
          enum:
            - ADDRESS
            - PLACE
            - STOP
        tokens:
          description: list of non-overlapping tokens that were matched
          type: array
          items:
            $ref: '#/components/schemas/Token'
        name:
          description: name of the location (transit stop / PoI / address)
          type: string
        id:
          description: unique ID of the location
          type: string
        lat:
          description: latitude
          type: number
        lon:
          description: longitude
          type: number
        street:
          description: street name
          type: string
        house_number:
          description: house number
          type: string
        zip:
          description: zip code
          type: string
        areas:
          description: list of areas
          type: array
          items:
            $ref: '#/components/schemas/Area'
        score:
          description: score according to the internal scoring system (the scoring algorithm might change in the future)
          type: number

    Mode:
      description: |
        # Street modes
        
          - `WALK`: Walking some or all of the way of the route.
          - `BIKE`: Cycling for the entirety of the route or taking a bicycle onto the public transport (if enabled) and cycling from the arrival station to the destination.
          - `BIKE_RENTAL`: Taking a rented, shared-mobility bike for part or the entirety of the route.
          - `BIKE_TO_PARK`: Leaving the bicycle at the departure station and walking from the arrival station to the destination. This mode needs to be combined with at least one transit mode otherwise it behaves like an ordinary bicycle journey.
          - `CAR`: Driving your own car the entirety of the route. This can be combined with transit, where will return routes with a Kiss & Ride component. This means that the car is not parked in a permanent parking area but rather the passenger is dropped off (for example, at an airport) and the driver continues driving the car away from the drop off location.
          - `CAR_PARK` | `CAR_TO_PARK`: Driving a car to the park-and-ride facilities near a station and taking publictransport. This mode needs to be combined with at least one transit mode otherwise, it behaves like an ordinary car journey.
          - `CAR_HAILING`: Using a car hailing app like Uber or Lyft to get to a train station or all the way to the destination.
          - `CAR_PICKUP`: Walking to a pickup point along the road, driving to a drop-off point along the road, and walking the rest of the way. This can include various taxi-services or kiss & ride.
          - `CAR_RENTAL`: Walk to a car rental point, drive to a car rental drop-off point and walk the rest of the way. This can include car rental at fixed locations or free-floating services.
          - `FLEXIBLE`: Encompasses all types of on-demand and flexible transportation for example GTFS Flex or NeTEx Flexible Stop Places.
          - `SCOOTER_RENTAL`: Walking to a scooter rental point, riding a scooter to a scooter rental drop-off point, and walking the rest of the way. This can include scooter rental at fixed locations or free-floating services.

        # Transit modes

          - `TRANSIT`: translates to `RAIL,SUBWAY,TRAM,BUS,FERRY,AIRPLANE,COACH`
          - `TRAM`: trams
          - `SUBWAY`: subway trains
          - `FERRY`: ferries
          - `AIRPLANE`: airline flights
          - `BUS`: short distance buses (does not include `COACH`)
          - `COACH`: long distance buses (does not include `BUS`)
          - `RAIL`: translates to `HIGHSPEED_RAIL,LONG_DISTANCE_RAIL,NIGHT_RAIL,REGIONAL_RAIL,REGIONAL_FAST_RAIL`
          - `METRO`: metro trains
          - `HIGHSPEED_RAIL`: long distance high speed trains (e.g. TGV)
          - `LONG_DISTANCE`: long distance inter city trains
          - `NIGHT_RAIL`: long distance night trains
          - `COACH`: long distance buses
          - `REGIONAL_FAST_RAIL`: regional express routes that skip low traffic stops to be faster
          - `REGIONAL_RAIL`: regional train
      type: string
      enum:
        # === Street ===
        - WALK
        - BIKE
        - CAR
        - BIKE_RENTAL
        - BIKE_TO_PARK
        - CAR_TO_PARK
        - CAR_HAILING
        - CAR_SHARING
        - CAR_PICKUP
        - CAR_RENTAL
        - FLEXIBLE
        - SCOOTER_RENTAL
        # === Transit ===
        - TRANSIT
        - TRAM
        - SUBWAY
        - FERRY
        - AIRPLANE
        - METRO
        - BUS
        - COACH
        - RAIL
        - HIGHSPEED_RAIL
        - LONG_DISTANCE
        - NIGHT_RAIL
        - REGIONAL_FAST_RAIL
        - REGIONAL_RAIL
        - OTHER

    VertexType:
      type: string
      description: |
        - `NORMAL` - latitude / longitude coordinate or address
        - `BIKESHARE` - bike sharing station
        - `BIKEPARK` - bike parking
        - `TRANSIT` - transit stop
      enum:
        - NORMAL
        - BIKESHARE
        - BIKEPARK
        - TRANSIT

    Place:
      type: object
      required:
        - name
        - lat
        - lon
      properties:
        name:
          description: name of the transit stop / PoI / address
          type: string
        stopId:
          description: The ID of the stop. This is often something that users don't care about.
          type: string
        lat:
          description: latitude
          type: number
        lon:
          description: longitude
          type: number
        arrivalDelay:
          type: integer
          description: |
            The offset from the scheduled arrival time of the boarding stop in this leg.
            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.
            Scheduled time of departure at boarding stop = startTime - departureDelay
        arrival:
          description: arrival time, format = unixtime in milliseconds
          type: integer
        departure:
          description: departure time, format = unixtime in milliseconds
          type: integer
        track:
          description: track/platform information, if available
          type: string
        vertexType:
          $ref: '#/components/schemas/VertexType'

    RelativeDirection:
      type: string
      enum:
        - DEPART
        - HARD_LEFT
        - LEFT
        - SLIGHTLY_LEFT
        - CONTINUE
        - SLIGHTLY_RIGHT
        - RIGHT
        - HARD_RIGHT
        - CIRCLE_CLOCKWISE
        - CIRCLE_COUNTERCLOCKWISE
        - ELEVATOR
        - UTURN_LEFT
        - UTURN_RIGHT

    AbsoluteDirection:
      type: string
      enum:
        - NORTH
        - NORTHEAST
        - EAST
        - SOUTHEAST
        - SOUTH
        - SOUTHWEST
        - WEST
        - NORTHWEST

    StepInstruction:
      type: object
      required:
        - relativeDirection
        - absoluteDirection
        - distance
        - streetName
        - exit
        - stayOn
        - area
        - lon
        - lat
      properties:
        relativeDirection:
          $ref: '#/components/schemas/RelativeDirection'
        absoluteDirection:
          $ref: '#/components/schemas/AbsoluteDirection'
        distance:
          description: The distance in meters that this step takes.
          type: number
        streetName:
          description: The name of the street.
          type: string
        exit:
          description: When exiting a highway or traffic circle, the exit name/number.
          type: string
        stayOn:
          description: |
            Indicates whether or not a street changes direction at an intersection.
          type: boolean
        area:
          description: |
            This step is on an open area, such as a plaza or train platform,
            and thus the directions should say something like "cross"
          type: boolean
        lon:
          description: The longitude of start of the step
          type: number
        lat:
          description: The latitude of start of the step
          type: number

    FeedScopedId:
      type: object
      required:
        - feedId
        - id
      properties:
        feedId:
          type: string
        id:
          type: string

    EncodedPolyline:
      type: object
      required:
        - points
        - length
      properties:
        points:
          description: The encoded points of the polyline.
          type: string
        length:
          description: The number of points in the string
          type: integer

    LevelEncodedPolyline:
      type: object
      required:
        - from_level
        - to_level
        - polyline
      properties:
        from_level:
          description: level where this segment starts, based on OpenStreetMap data
          type: number
        to_level:
          description: level where this segment starts, based on OpenStreetMap data
          type: number
        osm_way:
          description: OpenStreetMap way index
          type: integer
        polyline:
          $ref: '#/components/schemas/EncodedPolyline'

    Leg:
      type: object
      required:
        - mode
        - startTime
        - endTime
        - departureDelay
        - arrivalDelay
        - realTime
        - distance
        - duration
        - from
        - to
        - legGeometry
      properties:
        mode:
          $ref: '#/components/schemas/Mode'
          description: Transport mode for this leg
        from:
          $ref: '#/components/schemas/Place'
        to:
          $ref: '#/components/schemas/Place'
        duration:
          description: Leg duration in seconds
          type: integer
        startTime:
          type: integer
          description: leg departure time, format = unixtime in milliseconds
        endTime:
          type: integer
          description: leg arrival time, format = unixtime in milliseconds
        departureDelay:
          type: integer
          description: |
            The offset from the scheduled departure time of the boarding stop in this leg.
            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.
            Scheduled time of arrival at boarding stop = endTime - arrivalDelay
        realTime:
          description: Whether there is real-time data about this leg
          type: boolean
        distance:
          description: 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:
          type: string
        agencyId:
          type: string
        tripId:
          type: string
        serviceDate:
          type: string
        routeShortName:
          type: string
        source:
          description: Filename and line number where this trip is from
          type: string
        intermediateStops:
          description: |
            For transit legs, intermediate stops between the Place where the leg originates
            and the Place where the leg ends. For non-transit legs, null.
          type: array
          items:
            $ref: "#/components/schemas/Place"
        legGeometry:
          $ref: '#/components/schemas/EncodedPolyline'
        legGeometryWithLevels:
          description: Like `legGeometry`, but split at level changes
          type: array
          items:
            $ref: "#/components/schemas/LevelEncodedPolyline"
        steps:
          description: |
            A series of turn by turn instructions
            used for walking, biking and driving.
          type: array
          items:
            $ref: '#/components/schemas/StepInstruction'

    Itinerary:
      type: object
      required:
        - duration
        - startTime
        - endTime
        - walkTime
        - transitTime
        - waitingTime
        - walkDistance
        - transfers
        - legs
      properties:
        duration:
          description: journey duration in seconds
          type: integer
        startTime:
          type: integer
          description: journey departure time, format = unixtime in milliseconds
        endTime:
          type: integer
          description: journey arrival time, format = unixtime in milliseconds
        walkTime:
          type: integer
          description: How much time is spent walking, in seconds.
        transitTime:
          type: integer
          description: How much time is spent on transit, in seconds.
        waitingTime:
          type: integer
          description: How much time is spent waiting for transit to arrive, in seconds.
        walkDistance:
          type: integer
          description: How far the user has to walk, in meters.
        transfers:
          type: integer
          description: The number of transfers this trip has.
        legs:
          description: Journey legs
          type: array
          items:
            $ref: '#/components/schemas/Leg'