Transit API

openapi: 3.1.0
info:
  title: Transit API (Stable)
  version: 4.0.0
  x-logo:
    url: transit-logotype_iOS-dark.png
  contact: {}
  description: "**\U0001F4CC You are viewing v4 (Stable). View the legacy [v3 API here](v3.html).**\n\nAPI provided by data\
    \ from [transit.app](https://transit.app). Request an API key [here](https://https://transitapp.com/partners/apis).\n"
paths:
  /v4/public/nearby_routes:
    get:
      operationId: /v4/public/nearby_routes
      description: Returns routes around a location
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - in: query
        name: max_distance
        description: Maximum radius of search from the request location (in meters)
        schema:
          type: integer
          example: 1500
          default: 150
          maximum: 1500
      - $ref: '#/components/parameters/Locale'
      - $ref: '#/components/parameters/Accept-Language'
      - schema:
          type: boolean
          default: true
        in: query
        name: should_update_realtime
        description: 'Boolean telling the system if it should update real time or just return schedule information. '
      - in: query
        name: max_num_departures
        description: Number of departures to return per merged itinerary
        schema:
          type: integer
          default: 3
          minimum: 1
          maximum: 10
      - in: query
        name: time
        description: Optional epoch timestamp for getting routes at a specific time. If not provided, current time is used.
        schema:
          type: integer
          example: 1641024000
      - in: query
        name: include_stops_and_shapes
        description: Boolean to control whether stops and shapes are included in itineraries. When false, only itinerary metadata
          is returned without stops and shape polylines, reducing response size.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: List of nearby routes
          content:
            application/json:
              schema:
                type: object
                properties:
                  nearby_routes:
                    type: array
                    items:
                      type: object
                      properties:
                        alerts:
                          type: array
                          description: Service alerts that affect this route
                          items:
                            $ref: '#/components/schemas/ServiceAlert'
                        global_route_id:
                          $ref: '#/components/schemas/GlobalRouteId'
                        route_long_name:
                          type: string
                          description: Route long name from GTFS
                        route_short_name:
                          type: string
                          description: Route short name from GTFS
                        route_timezone:
                          type: string
                          description: The timezone of the route
                        route_display_short_name:
                          $ref: '#/components/schemas/DisplayShortName'
                        compact_display_short_name:
                          $ref: '#/components/schemas/DisplayShortName'
                        fares:
                          type: array
                          items:
                            $ref: '#/components/schemas/Fare'
                        route_type:
                          type: integer
                          description: Route type as defined in GTFS
                        route_color:
                          type: string
                          description: Route color as defined in GTFS
                        route_text_color:
                          type: string
                          description: Route text color as defined in GTFS
                        route_network_name:
                          type: string
                          description: The network name associated with that route
                        route_network_id:
                          type: string
                          description: A global unique identifier for the network
                        tts_long_name:
                          type: string
                          description: Long name for TTS
                        tts_short_name:
                          type: string
                          description: Short name for TTS
                        sorting_key:
                          type: string
                          description: Key for sorting routes
                        mode_name:
                          type: string
                          description: Mode name for the given route
                        real_time_route_id:
                          type: string
                          description: Route id used for real time
                        vehicle:
                          $ref: '#/components/schemas/Vehicle'
                        merged_itineraries:
                          type: array
                          description: Array of merged itineraries, each containing individual itineraries and schedule items
                          items:
                            type: object
                            properties:
                              direction_id:
                                type: integer
                                description: Direction ID
                              closest_stop:
                                $ref: '#/components/schemas/Stop'
                                description: The closest stop for this merged itinerary
                              itineraries:
                                type: array
                                description: Individual itineraries within this merged itinerary
                                items:
                                  $ref: '#/components/schemas/ItineraryWithInternalId'
                              schedule_items:
                                type: array
                                description: Schedule items for this merged itinerary, each referencing an individual itinerary
                                items:
                                  $ref: '#/components/schemas/ScheduleItemWithInternalId'
                      required:
                      - global_route_id
                      - route_long_name
                      - route_short_name
                      - merged_itineraries
        '400':
          description: Latitude or longitude is invalid or missing
        '500':
          description: Internal server error causing no result
      requestBody:
        content: {}
    parameters: []
  /v4/public/nearby_stops:
    get:
      operationId: /v4/public/nearby_stops
      description: Returns stops around a location
      parameters:
      - $ref: '#/components/parameters/Latitude'
      - $ref: '#/components/parameters/Longitude'
      - in: query
        name: max_distance
        description: Maximum radius of search from the request location (in meters)
        schema:
          type: integer
          example: 1500
          default: 150
          maximum: 1500
      - in: query
        name: stop_filter
        description: 'Determines which location types from the [GTFS](https://developers.google.com/transit/gtfs/reference#stopstxt)
          are included in the response.

          * Routable (GTFS `location_type` 0): Stops which are served by routes

          * EntrancesAndStopsOutsideStations: Entrances to transit stations and freestanding outdoor stops

          * Entrances (GTFS `location_type` 2): Entrances to stations

          * Any: All stops

          '
        schema:
          type: string
          enum:
          - Routable
          - EntrancesAndStopsOutsideStations
          - Entrances
          - Any
          example: Routable
          default: Routable
      - $ref: '#/components/parameters/PickupDropoffFilter'
      - $ref: '#/components/parameters/Locale'
      - $ref: '#/components/parameters/Accept-Language'
      responses:
        '200':
          description: List of nearby stops
          content:
            application/json:
              schema:
                type: object
                properties:
                  stops:
                    type: array
                    items:
                      $ref: '#/components/schemas/Stop'
        '400':
          description: Latitude or longitude is invalid or missing
        '500':
          description: Internal server error causing no result
    parameters: []
  /v4/public/stop_departures:
    get:
      operationId: /v4/public/stop_departures
      description: Get upcoming departures for all routes serving one or more stops, with optional real time information
      parameters:
      - in: query
        name: global_stop_ids
        required: true
        description: Comma-separated list of global stop IDs to get departures for multiple stops at once. Must contain at
          most 100 valid stop IDs. Either this parameter or global_stop_id must be provided.
        schema:
          example: 1:82774,2:54321,1:99999
          type: string
      - in: query
        name: time
        description: UNIX timestamp representing the time for which departures should be determined
        schema:
          type: number
          format: int
          default: The current time when the request was issued
      - in: query
        name: remove_cancelled
        description: Remove cancelled schedule items from the results
        schema:
          type: boolean
          default: false
      - $ref: '#/components/parameters/Locale'
      - $ref: '#/components/parameters/Accept-Language'
      - schema:
          type: boolean
          default: true
        in: query
        name: should_update_realtime
        description: 'Boolean telling the system if it should update real time or just return schedule information. '
      - in: query
        name: max_num_departures
        description: Number of departures to return per merged itinerary
        schema:
          type: integer
          default: 3
          minimum: 1
          maximum: 10
      - in: query
        name: include_stops_and_shapes
        description: Boolean to control whether stops and shapes are included in itineraries. When false, only itinerary metadata
          is returned without stops and shape polylines, reducing response size.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: List of upcoming departures at stop, grouped by route, then by merged itinerary
          content:
            application/json:
              schema:
                type: object
                properties:
                  route_departures:
                    type: array
                    items:
                      type: object
                      properties:
                        alerts:
                          type: array
                          description: Service alerts that affect this route
                          items:
                            $ref: '#/components/schemas/ServiceAlert'
                        global_route_id:
                          $ref: '#/components/schemas/GlobalRouteId'
                        route_long_name:
                          type: string
                          description: Route long name from GTFS
                        route_short_name:
                          type: string
                          description: Route short name from GTFS
                        route_timezone:
                          type: string
                          description: The timezone of the route
                        route_display_short_name:
                          $ref: '#/components/schemas/DisplayShortName'
                        compact_display_short_name:
                          $ref: '#/components/schemas/DisplayShortName'
                        fares:
                          type: array
                          items:
                            $ref: '#/components/schemas/Fare'
                        route_type:
                          type: integer
                          description: Route type as defined in GTFS
                        route_color:
                          type: string
                          description: Route color as defined in GTFS
                        route_text_color:
                          type: string
                          description: Route text color as defined in GTFS
                        route_network_name:
                          type: string
                          description: The network name associated with that route
                        route_network_id:
                          type: string
                          description: A global unique identifier for the network
                        tts_long_name:
                          type: string
                          description: Long name for TTS
                        tts_short_name:
                          type: string
                          description: Short name for TTS
                        sorting_key:
                          type: string
                          description: Key for sorting routes
                        mode_name:
                          type: string
                          description: Mode name for the given route
                        real_time_route_id:
                          type: string
                          description: Route id used for real time
                        vehicle:
                          $ref: '#/components/schemas/Vehicle'
                        merged_itineraries:
                          type: array
                          description: Array of merged itineraries, each containing individual itineraries and schedule items
                          items:
                            type: object
                            properties:
                              direction_id:
                                type: integer
                                description: Direction ID (0 or 1)
                              closest_stop:
                                $ref: '#/components/schemas/Stop'
                                description: The closest stop for this merged itinerary
                              itineraries:
                                type: array
                                description: Individual itineraries within this merged itinerary
                                items:
                                  $ref: '#/components/schemas/ItineraryWithInternalId'
                              schedule_items:
                                type: array
                                description: Schedule items for this merged itinerary, each referencing an individual itinerary
                                items:
                                  $ref: '#/components/schemas/ScheduleItemWithInternalId'
                        global_stop_id:
                          type: string
                          description: The global stop ID associated with this route departure
                          example: STM:88368
                      required:
                      - global_route_id
                      - route_long_name
                      - route_short_name
                      - merged_itineraries
                      - global_stop_id
        '400':
          description: Invalid global stop ID, missing required parameters, or no result could be found
    parameters: []
  /v4/public/estimate_plan_duration:
    get:
      operationId: /v4/public/estimate_plan_duration
      summary: /v4/public/estimate_plan_duration
      description: "This endpoint returns an estimated duration for a trip plan based on the provided origin and destination.\
        \ \n\nThe query params used in this endpoint are the same as /public/plan, except for the more limited mode selection,\
        \ real time not available and multiple results aren't provided. "
      parameters:
      - in: query
        schema:
          type: number
        name: from_lat
        description: Latitude of the starting location for the trip. Required unless from_global_stop_id is provided.
      - in: query
        schema:
          type: number
        name: from_lon
        description: Longitude of the starting location for the trip. Required unless from_global_stop_id is provided.
      - in: query
        schema:
          type: string
        name: from_global_stop_id
        description: Global stop ID for the starting location. Alternative to from_lat/from_lon parameters.
      - in: query
        schema:
          type: number
        name: to_lat
        description: Latitude of the destination location for the trip. Required unless to_global_stop_id is provided.
      - in: query
        schema:
          type: number
        name: to_lon
        description: Longitude of the destination location for the trip. Required unless to_global_stop_id is provided.
      - in: query
        schema:
          type: string
        name: to_global_stop_id
        description: Global stop ID for the destination location. Alternative to to_lat/to_lon parameters.
      - in: query
        name: mode
        description: The primary mode of transportation for the trip
        schema:
          default: transit
          type: string
          enum:
          - transit
          - microtransit
      - in: query
        name: secondary_mode
        description: The secondary mode of transportation for the trip, if applicable
        schema:
          type: string
          enum:
          - microtransit
      - in: query
        name: leave_time
        description: UNIX timestamp representing the desired departure time for the trip
        schema:
          type: number
      - in: query
        name: arrival_time
        description: UNIX timestamp representing the desired arrival time for the trip
        schema:
          type: number
      - in: query
        name: accessibility_need
        description: "This parameter specifies accessibility requirements for the trip. The following values are available:\n\
          \  - `none`: No specific accessibility needs are required; any valid trip may be returned.\n  - `strict`: Returns\
          \ only strictly accessible trips. Specifically, this includes only trips using accessible stops and accessible routes/vehicles.\n\
          \  - `prioritize_step_free`: Prioritizes strictly accessible results but also includes less accessible alternatives\
          \ (those with unknown or non-step-free accessibility).\n"
        schema:
          type: string
          enum:
          - none
          - strict
          - prioritize_step_free
          default: none
      - in: query
        name: walk_reluctance
        description: 'A factor that determines how much walking costly compared to riding in a transit vehicle in the trip
          plan. Values lower than 1.0 will be ignored. Transit uses the value of 1.1 by default and 2.1 when in the "Minimize
          Walking" mode. '
        schema:
          type: number
      - in: query
        name: max_distance_between_location_and_stop
        description: The maximum distance allowed between the starting or destination locations and a transit stop. This value
          can be adjusted to optimize performance by limiting the search radius. This value can only be customized if `mode=transit`,
          and the default is 1500m.
        schema:
          type: number
      responses:
        '200':
          description: This endpoint provides an estimated trip duration in seconds
          content:
            application/json:
              schema:
                type: object
                properties:
                  duration:
                    type: number
                    description: Estimated duration of the trip in seconds
                  type:
                    type: string
                    description: Type of trip plan (Transit, Walk, Bike, Car_Microtransit)
  /v4/public/plan:
    get:
      operationId: /v4/public/plan
      summary: /v4/public/plan
      description: "This endpoint returns a plan from the origin to the destination in different modes, including multimodal\
        \ trips. \n\nThis endpoint will eventually replace the /otp/plan. The OTP endpoint is deprecated as the OpenTripPlanner\
        \ endpoint it's based on is also [deprecated](https://docs.opentripplanner.org/en/latest/Changelog/#250-2024-03-13). "
      parameters:
      - in: query
        schema:
          type: number
          format: double
        name: from_lat
        description: Latitude of the starting location for the trip. Required unless from_global_stop_id or from_global_stop_ids
          is provided.
      - in: query
        schema:
          type: number
          format: double
        name: from_lon
        description: Longitude of the starting location for the trip. Required unless from_global_stop_id or from_global_stop_ids
          is provided.
      - in: query
        schema:
          type: string
        name: from_global_stop_id
        description: Single global stop ID for the starting location. Kept for backward compatibility; prefer from_global_stop_ids
          (plural) to describe a correspondence zone.
      - in: query
        schema:
          type: string
        name: from_global_stop_ids
        description: 'Comma-separated list of global stop IDs describing the origin correspondence zone (e.g. all platforms
          of a hub across different networks/parent stations). Each entry may be a platform stop id or a station stop id;
          stations are automatically expanded to their child platform stops when deciding whether to strip the initial walk
          leg.

          Routing origin: if from_lat and from_lon are provided, the coordinates are used to plan the trip. Otherwise the
          first valid stop''s location from the list is used as a fallback.

          Walk-leg filtering: the initial walk leg is removed from a plan only when the itinerary actually boards at one of
          the provided stops (or at their parent station). Plans that board at an unrelated nearby stop keep their walk leg
          so the client can still present directions to the stop.'
      - in: query
        schema:
          type: number
          format: double
        name: to_lat
        description: Latitude of the destination location for the trip. Required unless to_global_stop_id or to_global_stop_ids
          is provided.
      - in: query
        schema:
          type: number
          format: double
        name: to_lon
        description: Longitude of the destination location for the trip. Required unless to_global_stop_id or to_global_stop_ids
          is provided.
      - in: query
        schema:
          type: string
        name: to_global_stop_id
        description: Single global stop ID for the destination location. Kept for backward compatibility; prefer to_global_stop_ids
          (plural) to describe a correspondence zone.
      - in: query
        schema:
          type: string
        name: to_global_stop_ids
        description: 'Comma-separated list of global stop IDs describing the destination correspondence zone. Behaves symmetrically
          to from_global_stop_ids: coordinates win for routing when provided, otherwise the first valid stop''s location is
          used; the final walk leg is stripped only when the itinerary actually alights at one of the provided stops.'
      - in: query
        name: mode
        description: The primary mode of transportation for the trip
        schema:
          default: transit
          type: string
          enum:
          - transit
          - microtransit
          - personal_bike
          - walk
          - shared_mobility
      - in: query
        name: secondary_mode
        description: 'This specifies the secondary mode of transportation for the trip, if applicable.


          This value allows for creating multimodal trips mixing transit and another mode. If a value other than walk is specified
          here, primary_mode must be set to transit.


          When this value is set, the planner attempts to replace the first and last legs of the trip with the specified mode
          if advantageous to do so. If it is not advantageous, a walk leg might be used instead.


          Note that the results generated are optimal given the specified modes, but they might not represent the absolute
          optimal trip overall. Depending on the context, it may be advantageous to compare the result of the multimodal plan
          against a direct plan (using only the primary mode) to ensure true optimality (i.e., a transit + microtransit result
          should likely be disregarded if the transit-only plan is faster).'
        schema:
          type: string
          enum:
          - microtransit
          - personal_bike
          - walk
          - shared_mobility
      - in: query
        name: sharing_system_type
        description: 'Specifies the type of shared mobility system when mode is set to shared_mobility.


          - docked_bikeshare: Traditional docked bikeshare systems

          - dockless_bikeshare: Dockless bikes

          - scooters: Electric scooters


          If not specified, defaults to docked_bikeshare only.'
        schema:
          type: string
          enum:
          - docked_bikeshare
          - dockless_bikeshare
          - scooters
          default: docked_bikeshare
      - in: query
        name: leave_time
        description: 'UNIX timestamp representing the desired departure time for the trip. If both `arrival_time` and `leave_time`
          are provided, only `leave_time` is taken into account. By default, the current time is used. '
        schema:
          type: number
      - in: query
        name: arrival_time
        description: UNIX timestamp representing the desired arrival time for the trip. If both `arrival_time` and `leave_time`
          are provided, only `leave_time` is taken into account.
        schema:
          type: number
      - in: query
        name: accessibility_need
        description: "This parameter specifies accessibility requirements for the trip. The following values are available:\n\
          \  - `none`: No specific accessibility needs are required; any valid trip may be returned.\n  - `strict`: Returns\
          \ only strictly accessible trips. Specifically, this includes only trips using accessible stops and accessible routes/vehicles.\n\
          \  - `prioritize_step_free`: Prioritizes strictly accessible results but also includes less accessible alternatives\
          \ (those with unknown or non-step-free accessibility).\n"
        schema:
          default: none
          type: string
          enum:
          - none
          - strict
          - prioritize_step_free
      - in: query
        name: walk_reluctance
        description: This factor determines how costly walking is compared to riding in a transit vehicle within the trip
          plan. Values lower than 1.0 will be ignored. Transit, the app, uses a default value of 1.1, and 2.1 when the "Minimize
          Walking" mode is active.
        schema:
          type: number
      - in: query
        name: walk_speed
        description: The walking speed in meters per second for trip planning calculations. Must be between 0.5 and 5.0 m/s.
        schema:
          type: number
          minimum: 0.5
          maximum: 5
      - in: query
        name: should_include_directions
        description: Set to true to get step-by-step directions in the plan results.
        schema:
          type: boolean
          default: false
      - in: query
        name: should_include_pathways
        description: Set to true to expand GTFS Pathways steps in direction items when entering or exiting a transit station.
          Requires should_include_directions to also be set to true.
        schema:
          type: boolean
          default: false
      - in: query
        name: max_distance_between_location_and_stop
        description: This is the maximum distance allowed between the starting or destination locations and a transit stop.
          This value can be adjusted to optimize performance by limiting the search radius. By default, the value depends
          on the selected mode; for example, it is 1500 m for a standard `mode=transit` plan.
        schema:
          type: number
      - schema:
          type: boolean
          default: false
        in: query
        name: should_update_realtime
        description: If true, the server will update the trip times in the response using real-time data, enhancing the schedule
          items with real time information. This happens after the initial route planning, which is still based on static
          schedule data.
      - schema:
          type: boolean
          default: false
        in: query
        name: consider_downtimes
        description: If true, the planning will avoid any known downtimes identified in the service alerts. For example, if
          a subway is currently not working and has a severe service alert, the planner will offer results that work around
          that disruption. This parameter is ignored if the `mode` is set to anything other than `transit`.
      - schema:
          type: string
        in: query
        name: avoid_routes
        description: Comma-separated list of route identifiers to avoid in public transit routing. Each route identifier is
          a colon-separated pair of `<feed_code>:<global_route_id>`. This parameter is ignored if the `mode` is set to anything
          other than `transit`.
      - schema:
          type: string
        in: query
        name: avoid_stops
        description: Comma-separated list of stop identifiers to avoid in public transit routing. Each stop identifier is
          a colon-separated pair of `<feed_code>:<stable_stop_id>`. This parameter is ignored if the `mode` is set to anything
          other than `transit`.
      - schema:
          type: string
        in: query
        name: allowed_modes
        description: Comma-separated list of mode names to allow in public transit routing (e.g., "Bus,Metro,Train"). If specified,
          only routes with matching mode names will be considered for trip planning. Mode names should match the `mode_name`
          field returned in the route object. This parameter is ignored if the `mode` is set to anything other than `transit`.
      - schema:
          type: string
        in: query
        name: excluded_modes
        description: Comma-separated list of mode names to exclude from public transit routing (e.g., "Bus,Ferry"). If specified,
          routes with matching mode names will be excluded from trip planning. Mode names should match the `mode_name` field
          returned in the route object. This parameter is ignored if the `mode` is set to anything other than `transit`.
      - schema:
          type: string
        in: query
        name: allowed_networks
        description: 'If set, only the specified networks will be used to plan trips. A list of available networks can be
          obtained from [`/public/available_networks`](#operation/get-v4-public-available_networks).


          This parameter will accept a comma-separated list containing network IDs, network locations or a combination of
          both. This parameter is ignored if the `mode` is set to anything other than `transit`.

          '
      - schema:
          type: boolean
          default: false
        in: query
        name: enable_network_previews
        description: 'If set to `true`, includes network previews in trip planning. By default, network previews are excluded
          from route planning results. This parameter is ignored if the `mode` is set to anything other than `transit`.

          '
      - schema:
          type: number
          default: 3
        in: query
        name: num_result
        description: Number of results to return. This parameter is only considered for public transit only plans (mode=transit).
          Default is 3 for public transit only and bike plans, and 1 for walk plans.
      - schema:
          type: bool

# --- truncated at 32 KB (156 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/transit-app/refs/heads/main/openapi/transit-openapi.yml