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://github.com/motis-project/motis
servers:
  - url: https://europe.motis-project.de
paths:
  /api/v1/one-to-many:
    get:
      tags:
        - geocode
      summary: |
        Street routing from one to many places or many to one.
        The order in the response array corresponds to the order of coordinates of the \`many\` parameter in the query.
      operationId: oneToMany
      parameters:
        - name: one
          in: query
          required: true
          description: geo location as latitude,longitude
          schema:
            type: string
        - name: many
          in: query
          required: true
          description: geo locations as latitude;longitude,latitude;longitude,...
          schema:
            type: array
            items:
              type: string
        - name: mode
          in: query
          required: true
          description: |
            routing profile to use (currently supported: \`WALK\`, \`BIKE\`, \`CAR\`)
          schema:
            $ref: '#/components/schemas/Mode'
        - name: max
          in: query
          required: true
          description: maximum travel time in seconds
          schema:
            type: number
        - name: maxMatchingDistance
          in: query
          required: true
          description: maximum matching distance in meters to match geo coordinates to the street network
          schema:
            type: number
        - name: arriveBy
          in: query
          required: true
          description: |
            true = many to one
            false = one to many
          schema:
            type: boolean
      responses:
        200:
          description: |
            A list of durations.
            If no path was found, the object is empty.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Duration'

  /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/trip:
    get:
      tags:
        - timetable
      summary: Get a trip as itinerary
      operationId: trip
      parameters:
        - name: tripId
          in: query
          schema:
            type: string
          required: true
          description: trip identifier (e.g. from an itinerary leg or stop event)
      responses:
        200:
          description: the requested trip as itinerary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Itinerary'

  /api/v1/stoptimes:
    get:
      tags:
        - timetable
      summary: Get the next N departures or arrivals of a stop sorted by time
      operationId: stoptimes
      parameters:
        - name: stopId
          in: query
          schema:
            type: string
          required: true
          description: stop id of the stop to retrieve departures/arrivals for

        - name: time
          in: query
          required: false
          description: |
            Optional. Defaults to the current time.
          schema:
            type: string
            format: date-time

        - 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: direction
          in: query
          required: false
          schema:
            type: string
            enum:
              - EARLIER
              - LATER
          description: |
            This parameter will be ignored in case `pageCursor` is set.
            
            Optional. Default is
              - `LATER` for `arriveBy=false`
              - `EARLIER` for `arriveBy=true`
            
            The response will contain the next `n` arrivals / departures
            in case `EARLIER` is selected and the previous `n`
            arrivals / departures if `LATER` is selected.

        - name: mode
          in: query
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Mode'
            default:
              - TRANSIT
          description: |
            Optional. Default is all transit modes.
            
            Only return arrivals/departures of the given modes.

        - name: n
          in: query
          schema:
            type: integer
          required: true
          description: the number of events

        - name: radius
          in: query
          schema:
            type: integer
          required: false
          description: |
            Optional. Radius in meters.
            
            Default is that only stop times of the parent of the stop itself
            and all stops with the same name (+ their child stops) are returned.
            
            If set, all stops at parent stations and their child stops in the specified radius
            are returned.

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

      responses:
        200:
          description: A list of guesses to resolve the text to a location
          content:
            application/json:
              schema:
                type: object
                required:
                  - stopTimes
                  - previousPageCursor
                  - nextPageCursor
                properties:
                  stopTimes:
                    description: list of stop times
                    type: array
                    items:
                      $ref: '#/components/schemas/StopTime'
                  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 stop times BEFORE the first stop time in the 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 stop times AFTER the last stop time in this result.
                    type: string

  /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: 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
          description: |
            Optional. Defaults to the current time.
            
            Departure time ($arriveBy=false) / arrival date ($arriveBy=true),
          schema:
            type: string
            format: date-time

        - 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: maxTravelTime
          in: query
          required: false
          description: |
            The maximum travel time in minutes.
            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: integer

        - name: minTransferTime
          in: query
          required: false
          description: |
            Optional. Default is 0 minutes.
            
            Minimum transfer time for each transfer in minutes.
          schema:
            type: integer
            default: 0

        - name: additionalTransferTime
          in: query
          required: false
          description: |
            Optional. Default is 0 minutes.
            
            Additional transfer time reserved for each transfer in minutes.
          schema:
            type: integer
            default: 0

        - name: transferTimeFactor
          in: query
          required: false
          description: |
            Optional. Default is 1.0
            
            Factor to multiply minimum required transfer times with.
            Values smaller than 1.0 are not supported.
          schema:
            type: number
            default: 1.0

        - name: maxMatchingDistance
          in: query
          required: false
          description: |
            Optional. Default is 25 meters.
            
            Maximum matching distance in meters to match geo coordinates to the street network.
          schema:
            type: number
            default: 25

        - name: pedestrianProfile
          in: query
          required: false
          description: |
            Optional. Default is `FOOT`.
            
            Accessibility profile to use for pedestrian routing in transfers
            between transit connections, on the first mile, and last mile.
          schema:
            $ref: '#/components/schemas/PedestrianProfile'
            default: FOOT

        - name: useRoutedTransfers
          in: query
          required: false
          description: |
            Optional. Default is `false`.
            
            Whether to use transfers routed on OpenStreetMap data.
          schema:
            type: boolean
            default: false

        - name: detailedTransfers
          in: query
          required: true
          description: |
            - true: Compute transfer polylines and step instructions.
            - false: Only return basic information (start time, end time, duration) for transfers.
          schema:
            type: boolean
            default: true

        - name: transitModes
          in: query
          required: false
          description: |
            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.
            
            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
            type: array
            items:
              $ref: '#/components/schemas/Mode'
          explode: false

        - name: directRentalFormFactors
          in: query
          required: false
          description: |
            Experimental. Expect unannounced breaking changes (without version bumps).
            
            Optional. Only applies to direct connections.
            
            A list of vehicle type form factors that are allowed to be used for direct connections.
            If empty (the default), all form factors are allowed.
            Example: `BICYCLE,SCOOTER_STANDING`.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/RentalFormFactor'
          explode: false

        - name: preTransitRentalFormFactors
          in: query
          required: false
          description: |
            Experimental. Expect unannounced breaking changes (without version bumps).
            
            Optional. Only applies if the `from` place is a coordinate (not a transit stop). Does not apply to direct connections (see `directRentalFormFactors`).
            
            A list of vehicle type form factors that are allowed to be used from the `from` coordinate to the first transit stop.
            If empty (the default), all form factors are allowed.
            Example: `BICYCLE,SCOOTER_STANDING`.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/RentalFormFactor'
          explode: false

        - name: postTransitRentalFormFactors
          in: query
          required: false
          description: |
            Experimental. Expect unannounced breaking changes (without version bumps).
            
            Optional. Only applies if the `to` place is a coordinate (not a transit stop). Does not apply to direct connections (see `directRentalFormFactors`).

            A list of vehicle type form factors that are allowed to be used from the last transit stop to the `to` coordinate.
            If empty (the default), all form factors are allowed.
            Example: `BICYCLE,SCOOTER_STANDING`.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/RentalFormFactor'
          explode: false

        - name: directRentalPropulsionTypes
          in: query
          required: false
          description: |
            Experimental. Expect unannounced breaking changes (without version bumps).
            
            Optional. Only applies to direct connections.
            
            A list of vehicle type form factors that are allowed to be used for direct connections.
            If empty (the default), all propulsion types are allowed.
            Example: `HUMAN,ELECTRIC,ELECTRIC_ASSIST`.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/RentalPropulsionType'
          explode: false

        - name: preTransitRentalPropulsionTypes
          in: query
          required: false
          description: |
            Experimental. Expect unannounced breaking changes (without version bumps).
            
            Optional. Only applies if the `from` place is a coordinate (not a transit stop). Does not apply to direct connections (see `directRentalPropulsionTypes`).
            
            A list of vehicle propulsion types that are allowed to be used from the `from` coordinate to the first transit stop.
            If empty (the default), all propulsion types are allowed.
            Example: `HUMAN,ELECTRIC,ELECTRIC_ASSIST`.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/RentalPropulsionType'
          explode: false

        - name: postTransitRentalPropulsionTypes
          in: query
          required: false
          description: |
            Experimental. Expect unannounced breaking changes (without version bumps).
            
            Optional. Only applies if the `to` place is a coordinate (not a transit stop). Does not apply to direct connections (see `directRentalPropulsionTypes`).
            
            A list of vehicle propulsion types that are allowed to be used from the last transit stop to the `to` coordinate.
            If empty (the default), all propulsion types are allowed.
            Example: `HUMAN,ELECTRIC,ELECTRIC_ASSIST`.
          schema:
            type: array
            items:
              $ref: '#/components/schemas/RentalPropulsionType'
          explode: false

        - name: directRentalProviders
          in: query
          required: false
          description: |
            Experimental. Expect unannounced breaking changes (without version bumps).
            
            Optional. Only applies to direct connections.
            
            A list of rental providers that are allowed to be used for direct connections.
            If empty (the default), all providers are allowed.
          schema:
            type: array
            items:
              type: string

        - name: preTransitRentalProviders
          in: query
          required: false
          description: |
            Experimental. Expect unannounced breaking changes (without version bumps).
            
            Optional. Only applies if the `from` place is a coordinate (not a transit stop). Does not apply to direct connections (see `directRentalProviders`).
            
            A list of rental providers that are allowed to be used from the `from` coordinate to the first transit stop.
            If empty (the default), all providers are allowed.
          schema:
            type: array
            items:
              type: string

        - name: postTransitRentalProviders
          in: query
          required: false
          description: |
            Experimental. Expect unannounced breaking changes (without version bumps).
            
            Optional. Only applies if the `to` place is a coordinate (not a transit stop). Does not apply to direct connections (see `directRentalProviders`).
            
            A list of rental providers that are allowed to be used from the last transit stop to the `to` coordinate.
            If empty (the default), all providers are allowed.
          schema:
            type: array
            items:
              type: string

        - 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: true

        - 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: requireBikeTransport
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: |
            Optional. Default is `false`.
            
            If set to `true`, all used transit trips are required to allow bike carriage.

        - 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

        - name: maxDirectTime
          in: query
          required: false
          description: |
            Optional. Default is 30min which is `1800`.
            Maximum time in seconds for direct connections.
          schema:
            type: integer
            default: 1800
            minimum: 0

        - name: timeout
          in: query
          required: false
          description: Optional. Query timeout in seconds.
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: routing result
          content:
            application/json:
              schema:
                type: object
                required:
                  - requestParameters
                  - debugOutput
                  - date
                  - from
                  - to
                  - direct
                  - itineraries
                  - previousPageCursor
                  - nextPageCursor
                properties:
                  requestParameters:
                    description: "the routing query"
                    type: object
                    additionalProperties:
                      type: string
                  debugOutput:
                    description: "debug statistics"
                    type: object
                    additionalProperties:
                      type: integer
                  from:
                    $ref: '#/components/schemas/Place'
                  to:
                    $ref: '#/components/schemas/Place'
                  direct:
                    description: |
                      Direct trips by `WALK`, `BIKE`, `CAR`, etc. without time-dependency.
                      The starting time (`arriveBy=false`) / arrival time (`arriveBy=true`) is always the queried `time` parameter (set to \"now\" if not set).
                      But all `direct` connections are meant to be independent of absolute times.
                    type: array
                    items:
                      $ref: '#/components/schemas/Itinerary'
                  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

  /api/v1/map/trips:
    get:
      tags:
        - map
      operationId: trips
      summary: |
        Given a area frame (box defined by top right and bottom left corner) and a time frame,
        it returns all trips and their respective shapes that operate in this area + time frame.
        Trips are filtered by zoom level. On low zoom levels, only long distance trains will be shown
        while on high zoom levels, also metros, buses and trams will be returned.
      parameters:
        - name: zoom
          in: query
          required: true
          description: current zoom level
          schema:
            type: number
        - name: min
          in: query
          required: true
          description: latitude,longitude pair of the lower right coordinate
          schema:
            type: string
        - name: max
          in: query
          required: true
          description: latitude,longitude pair of the upper left coordinate
          schema:
            type: string
        - name: startTime
          in: query
          required: true
          description: start of the time window
          schema:
            type: string
            format: date-time
        - name: endTime
          in: query
          required: true
          description: end if the time window
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: a list of trips
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TripSegment'

  /api/v1/map/initial:
    get:
      tags:
        - map
      operationId: initial
      summary: initial location to view the map at after loading based on where public transport should be visible
      responses:
        '200':
          description: latitude, longitude and zoom level to set the map to
          content:
            application/json:
              schema:
                type: object
                required:
                  - lat
                  - lon
                  - zoom
                properties:
                  lat:
                    description: latitude
                    type: number
                  lon:
                    description: longitude
                    type: number
                  zoom:
                    description: zoom level
                    type: number

  /api/v1/map/stops:
    get:
      tags:
        - map
      summary: Get all stops for a map section
      operationId: stops
      parameters:
        - name: min
          in: query
          required: true
          description: latitude,longitude pair of the lower right coordinate
          schema:
            type: string
        - name: max
          in: query
          required: true
          description: latitude,longitude pair of the upper left coordinate
          schema:
            type: string
      responses:
        '200':
          description: array of stop places in the selected map section
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Place'

  /api/v1/map/levels:
    get:
      tags:
        - map
      summary: Get all available levels for a map section
      operationId: levels
      parameters:
        - name: min
          in: query
          required: true
          description: latitude,longitude pair of the lower right coordinate
          schema:
            type: string
        - name: max
          in: query
          required: true
          description: latitude,longitude pair of the upper left coordinate
          schema:
            type: string
      responses:
        '200':
          description: array of available levels
          content:
            application/json:
              schema:
                type: array
                items:
                  type: number

  /api/debug/footpaths:
    get:
      tags:
        - debug
      summary: Prints all footpaths of a timetable location (track, bus stop, etc.)
      operationId: footpaths
      parameters:
        - name: id
          in: query
          required: true
          description: location id
          schema:
            type: string
      responses:
        '200':
          description: list of outgoing footpaths of this location
          content:
            application/json:
              schema:
                type: object
                required:
                  - place
                  - footpaths
                properties:
                  place:
                    $ref: '#/components/schemas/Place'
                  footpaths:
                    description: all outgoing footpaths of this location
                    type: array
                    items:
                      $ref: '#/components/schemas/Footpath'

components:
  schemas:
    Duration:
      description: Object containing duration if a path was found or none if no path was found
      type: object
      required: [ ]
      properties:
        duration:
          type: number
          description: duration in seconds if a path was found, otherwise missing

    Area:
      description: Administrative area
      type: object
      required:
        - name
        - adminLevel
        - matched
      properties:
        name:
          type: string
          description: Name of the area
        adminLevel:
          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
        level:
          description: |
            level according to OpenStreetMap
            (at the moment only for public transport)
          type: number
        street:
          description: street name
          type: string
        houseNumber:
          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

    PedestrianProfile:
      description: Different accessibility profiles for pedestrians.
      type: string
      enum:
        - FOOT
        - WHEELCHAIR

    Mode:
      description: |
        # Street modes
        
          - `WALK`
          - `BIKE`
          - `RENTAL` Experimental. Expect unannounced breaking changes (without version bumps).
          - `CAR`
          - `CAR_PARKING`

        # 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
          - `REGIONAL_FAST_RAIL`: regional express routes that skip low traffic stops to be faster
          - `REGIONAL_RAIL`: regional train
      type: string
      enum:
        # === Street ===
        - WALK
        - BIKE
        - RENTAL
        - CAR
        - CAR_PARKING
        # === 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
        - `TRANSIT` - transit stop
      enum:
        - NORMAL
        - BIKESHARE
        - TRANSIT

    Place:
      type: object
      required:
        - name
        - lat
        - lon
        - level
      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
        level:
          description: level according to OpenStreetMap
          type: number
        arrival:
          description: arrival time
          type: string
          format: date-time
        departure:
          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
        track:
          description: |
            The current track/platform information, updated with real-time updates if available. 
            Can be missing if neither real-time updates nor the schedule timetable contains track information.
          type: string
        vertexType:
          $ref: '#/components/schemas/VertexType'

    StopTime:
      description: departure or arrival event at a stop
      type: object
      required:
        - place
        - mode
        - realTime
        - headsign
        - agencyId
        - agencyName
        - agencyUrl
        - tripId
        - routeShortName
        - source
      properties:
        place:
          $ref: '#/components/schemas/Place'
          description: information about the stop place and time
        mode:
          $ref: '#/components/schemas/Mode'
          description: Transport mode for this leg
        realTime:
          description: Whether there is real-time data about this leg
          type: boolean
        headsign:
          description: |
            For transit legs, the headsign of the bus or train being used.
            For non-transit legs, null
          type: string
        agencyId:
          type: string
        agencyName:
          type: string
        agencyUrl:
          type: string
        routeColor:
          type: string
        routeTextColor:
          type: string
        tripId:
          type: string
        routeShortName:
          type: string
        source:
          description: Filename and line number where this trip is from
          type: string

    TripInfo:
      description: trip id and name
      type: object
      required:
        - tripId
        - routeShortName
      properties:
        tripId:
          description: trip ID (dataset trip id prefixed with the dataset tag)
          type: string
        routeShortName:
          description: trip display name
          type: string

    TripSegment:
      description: trip segment between two stops to show a trip on a map
      type: object
      required:
        - trips
        - mode
        - distance
        - from
        - to
        - departure
        - arrival
        - scheduledArrival
        - scheduledDeparture
        - realTime
        - polyline
      properties:
        trips:
          type: array
          items:
            $ref: '#/components/schemas/TripInfo'
        routeColor:
          type: string
        mode:
          $ref: '#/components/schemas/Mode'
          description: Transport mode for this leg
        distance:
          type: number
          description: distance in meters
        from:
          $ref: '#/components/schemas/Place'
        to:
          $ref: '#/components/schemas/Place'
        departure:
          description: departure time
          type: string
          format: date-time
        arrival:
          description: arrival time
          type: string
          format: date-time
        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
        polyline:
          description: Google polyline encoded coordinate sequence (with precision 7) where the trip travels on this segment.
          type: string

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

    EncodedPolyline:
      type: object
      required:
        - points
        - length
      properties:
        points:
          description: The encoded points of the polyline using the Google polyline encoding with precision 7.
          type: string
        length:
          description: The number of points in the string
          type: integer

    StepInstruction:
      type: object
      required:
        - fromLevel
        - toLevel
        - polyline
        - relativeDirection
        - distance
        - streetName
        - exit
        - stayOn
        - area
      properties:
        relativeDirection:
          $ref: '#/components/schemas/Direction'
        distance:
          description: The distance in meters that this step takes.
          type: number
        fromLevel:
          description: level where this segment starts, based on OpenStreetMap data
          type: number
        toLevel:
          description: level where this segment starts, based on OpenStreetMap data
          type: number
        osmWay:
          description: OpenStreetMap way index
          type: integer
        polyline:
          $ref: '#/components/schemas/EncodedPolyline'
        streetName:
          description: The name of the street.
          type: string
        exit:
          description: |
            Not implemented!
            When exiting a highway or traffic circle, the exit name/number.
          type: string
        stayOn:
          description: |
            Not implemented!
            Indicates whether or not a street changes direction at an intersection.
          type: boolean
        area:
          description: |
            Not implemented!
            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

    RentalFormFactor:
      type: string
      enum:
        - BICYCLE
        - CARGO_BICYCLE
        - CAR
        - MOPED
        - SCOOTER_STANDING
        - SCOOTER_SEATED
        - OTHER

    RentalPropulsionType:
      type: string
      enum:
        - HUMAN
        - ELECTRIC_ASSIST
        - ELECTRIC
        - COMBUSTION
        - COMBUSTION_DIESEL
        - HYBRID
        - PLUG_IN_HYBRID
        - HYDROGEN_FUEL_CELL

    RentalReturnConstraint:
      type: string
      enum:
        - NONE
        - ANY_STATION
        - ROUNDTRIP_STATION

    Rental:
      description: Vehicle rental
      type: object
      required:
        - systemId
      properties:
        systemId:
          type: string
          description: Vehicle share system ID
        systemName:
          type: string
          description: Vehicle share system name
        url:
          type: string
          description: URL of the vehicle share system
        stationName:
          type: string
          description: Name of the station
        rentalUriAndroid:
          type: string
          description: Rental URI for Android (deep link to the specific station or vehicle)
        rentalUriIOS:
          type: string
          description: Rental URI for iOS (deep link to the specific station or vehicle)
        rentalUriWeb:
          type: string
          description: Rental URI for web (deep link to the specific station or vehicle)
        formFactor:
          $ref: '#/components/schemas/RentalFormFactor'
        propulsionType:
          $ref: '#/components/schemas/RentalPropulsionType'
        returnConstraint:
          $ref: '#/components/schemas/RentalReturnConstraint'

    Leg:
      type: object
      required:
        - mode
        - startTime
        - endTime
        - scheduledStartTime
        - scheduledEndTime
        - realTime
        - 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

            If leg is footpath:
              The footpath duration is derived from the default footpath
              duration using the query parameters `transferTimeFactor` and
              `additionalTransferTime` as follows:
              `leg.duration = defaultDuration * transferTimeFactor + additionalTransferTime.`
              In case the defaultDuration is needed, it can be calculated by
              `defaultDuration = (leg.duration - additionalTransferTime) / transferTimeFactor`.
              Note that the default values are `transferTimeFactor = 1` and
              `additionalTransferTime = 0` in case they are not explicitly
              provided in the query.
          type: integer
        startTime:
          type: string
          format: date-time
          description: leg departure time
        endTime:
          type: string
          format: date-time
          description: leg arrival time
        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: 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
        headsign:
          description: |
            For transit legs, the headsign of the bus or train being used.
            For non-transit legs, null
          type: string
        routeColor:
          type: string
        routeTextColor:
          type: string
        routeType:
          type: string
        agencyName:
          type: string
        agencyUrl:
          type: string
        agencyId:
          type: string
        tripId:
          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'
        steps:
          description: |
            A series of turn by turn instructions
            used for walking, biking and driving.
          type: array
          items:
            $ref: '#/components/schemas/StepInstruction'
        rental:
          $ref: '#/components/schemas/Rental'

    Itinerary:
      type: object
      required:
        - duration
        - startTime
        - endTime
        - transfers
        - legs
      properties:
        duration:
          description: journey duration in seconds
          type: integer
        startTime:
          type: string
          format: date-time
          description: journey departure time
        endTime:
          type: string
          format: date-time
          description: journey arrival time
        transfers:
          type: integer
          description: The number of transfers this trip has.
        legs:
          description: Journey legs
          type: array
          items:
            $ref: '#/components/schemas/Leg'

    Footpath:
      description: footpath from one location to another
      type: object
      required:
        - to
      properties:
        to:
          $ref: '#/components/schemas/Place'
        default:
          type: number
          description: |
            optional; missing if the GTFS did not contain a footpath
            footpath duration in minutes according to GTFS (+heuristics)
        foot:
          type: number
          description: |
            optional; missing if no path was found (timetable / osr)
            footpath duration in minutes for the foot profile
        footRouted:
          type: number
          description: |
            optional; missing if no path was found with foot routing
            footpath duration in minutes for the foot profile
        wheelchair:
          type: number
          description: |
            optional; missing if no path was found with the wheelchair profile 
            footpath duration in minutes for the wheelchair profile
        wheelchairUsesElevator:
          type: boolean
          description: |
            optional; missing if no path was found with the wheelchair profile
            true if the wheelchair path uses an elevator