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: fastestDirectFactor
in: query
required: false
description: |
Optional. Experimental. Default is `1.0`.
Factor with which the duration of the fastest direct connection is multiplied.
Values > 1.0 allow connections that are slower than the fastest direct connection to be found.
schema:
type: number
default: 1.0
minimum: 0
- name: timeout
in: query
required: false
description: Optional. Query timeout in seconds.
schema:
type: integer
minimum: 0
- name: passengers
in: query
required: false
description: Optional. Experimental. Number of passengers (e.g. for ODM or price calculation)
schema:
type: integer
minimum: 1
- name: luggage
in: query
required: false
description: |
Optional. Experimental. Number of luggage pieces; base unit: airline cabin luggage (e.g. for ODM or price calculation)
schema:
type: integer
minimum: 1
- name: withFares
in: query
required: false
description: Optional. Experimental. If set to true, the response will contain fare information.
schema:
type: boolean
default: false
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
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`
- `ODM`
# 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
- ODM
# === 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
fromStationName:
type: string
description: Name of the station where the vehicle is picked up (empty for free floating vehicles)
toStationName:
type: string
description: Name of the station where the vehicle is returned (empty for free floating vehicles)
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'
fareTransferIndex:
type: integer
description: |
Index into `Itinerary.fareTransfers` array
to identify which fare transfer this leg belongs to
effectiveFareLegIndex:
type: integer
description: |
Index into the `Itinerary.fareTransfers[fareTransferIndex].effectiveFareLegProducts` array
to identify which effective fare leg this itinerary leg belongs to
RiderCategory:
type: object
required:
- riderCategoryName
- isDefaultFareCategory
properties:
riderCategoryName:
description: Rider category name as displayed to the rider.
type: string
isDefaultFareCategory:
description: Specifies if this category should be considered the default (i.e. the main category displayed to riders).
type: boolean
eligibilityUrl:
description: URL to a web page providing detailed information about the rider category and/or its eligibility criteria.
type: string
FareMediaType:
type: string
enum: [ "NONE", "PAPER_TICKET", "TRANSIT_CARD", "CONTACTLESS_EMV", "MOBILE_APP" ]
enumDescriptions:
NONE: No fare media involved (e.g., cash payment)
PAPER_TICKET: Physical paper ticket
TRANSIT_CARD: Physical transit card with stored value
CONTACTLESS_EMV: cEMV (contactless payment)
MOBILE_APP: Mobile app with virtual transit cards/passes
FareMedia:
type: object
required:
- fareMediaType
properties:
fareMediaName:
description: Name of the fare media. Required for transit cards and mobile apps.
type: string
fareMediaType:
description: The type of fare media.
$ref: '#/components/schemas/FareMediaType'
FareProduct:
type: object
required:
- name
- amount
- currency
properties:
name:
description: The name of the fare product as displayed to riders.
type: string
amount:
description: The cost of the fare product. May be negative to represent transfer discounts. May be zero to represent a fare product that is free.
type: number
currency:
description: ISO 4217 currency code. The currency of the cost of the fare product.
type: string
riderCategory:
$ref: '#/components/schemas/RiderCategory'
media:
$ref: '#/components/schemas/FareMedia'
FareTransferRule:
type: string
enum:
- A_AB
- A_AB_B
- AB
FareTransfer:
type: object
description: |
The concept is derived from: https://gtfs.org/documentation/schedule/reference/#fare_transfer_rulestxt
Terminology:
- **Leg**: An itinerary leg as described by the `Leg` type of this API description.
- **Effective Fare Leg**: Itinerary legs can be joined together to form one *effective fare leg*.
- **Fare Transfer**: A fare transfer groups two or more effective fare legs.
- **A** is the first *effective fare leg* of potentially multiple consecutive legs contained in a fare transfer
- **B** is any *effective fare leg* following the first *effective fare leg* in this transfer
- **AB** are all changes between *effective fare legs* contained in this transfer
The fare transfer rule is used to derive the final set of products of the itinerary legs contained in this transfer:
- A_AB means that any product from the first effective fare leg combined with the product attached to the transfer itself (AB) which can be empty (= free). Note that all subsequent effective fare leg products need to be ignored in this case.
- A_AB_B mean that a product for each effective fare leg needs to be purchased in a addition to the product attached to the transfer itself (AB) which can be empty (= free)
- AB only the transfer product itself has to be purchased. Note that all fare products attached to the contained effective fare legs need to be ignored in this case.
An itinerary `Leg` references the index of the fare transfer and the index of the effective fare leg in this transfer it belongs to.
required:
- effectiveFareLegProducts
properties:
rule:
$ref: '#/components/schemas/FareTransferRule'
transferProduct:
$ref: '#/components/schemas/FareProduct'
effectiveFareLegProducts:
description: |
Lists all valid fare products for the effective fare legs.
This is an `array<array<FareProduct>>` where the inner array
lists all possible fare products that would cover this effective fare leg.
Each "effective fare leg" can have multiple options for adult/child/weekly/monthly/day/one-way tickets etc.
You can see the outer array as AND (you need one ticket for each effective fare leg (`A_AB_B`), the first effective fare leg (`A_AB`) or no fare leg at all but only the transfer product (`AB`)
and the inner array as OR (you can choose which ticket to buy)
type: array
items:
type: array
items:
$ref: '#/components/schemas/FareProduct'
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'
fareTransfers:
description: Fare information
type: array
items:
$ref: '#/components/schemas/FareTransfer'
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