openapi: 3.0.3
info:
  title: Transit API
  description: >-
    The Transit API provides real-time public transit data including live
    departures, trip planning, wheelchair accessibility information, service
    alerts, and shared mobility availability across 900 cities in 25 countries.
  version: v3.0.0
  contact:
    name: Transit Partnership Team
    email: partners+website@transit.app
    url: https://transitapp.com/apis
  x-logo:
    url: https://transitapp.com/images/transit-logo.png
servers:
  - url: https://api-doc.transitapp.com
    description: Transit API Production Server
security:
  - ApiKeyAuth: []
tags:
  - name: Departures
    description: Real-time and scheduled transit departure information
  - name: Trips
    description: Multimodal trip planning and results
  - name: Networks
    description: Transit network and agency data
  - name: Routes
    description: Route information and schedules
  - name: Stops
    description: Stop and station information
  - name: Mobility
    description: Shared bikes, scooters, and carshares
  - name: Alerts
    description: Service alerts and disruptions
paths:
  /public/stop_departures:
    get:
      operationId: getStopDepartures
      summary: Get Stop Departures
      description: >-
        Returns upcoming departures for all routes serving one or more stops,
        with optional real-time information including vehicle locations and
        predictions.
      tags:
        - Departures
      parameters:
        - name: stop_codes
          in: query
          required: true
          schema:
            type: array
            items:
              type: string
          description: One or more stop codes to get departures for
        - name: max_departures
          in: query
          required: false
          schema:
            type: integer
            default: 5
          description: Maximum number of departures to return per route
        - name: network_id
          in: query
          required: false
          schema:
            type: string
          description: Filter departures to a specific network
      responses:
        '200':
          description: Successful response with departure times
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StopDeparturesResponse'
        '401':
          description: Unauthorized - invalid or missing API key
        '404':
          description: Stop not found
        '429':
          description: Rate limit exceeded
  /public/networks:
    get:
      operationId: listNetworks
      summary: List Transit Networks
      description: >-
        Returns a list of transit networks available in the Transit system.
        Optionally filter by geographic coordinates to get networks near a
        specific location.
      tags:
        - Networks
      parameters:
        - name: lat
          in: query
          required: false
          schema:
            type: number
            format: float
          description: Latitude to filter networks by proximity
        - name: lon
          in: query
          required: false
          schema:
            type: number
            format: float
          description: Longitude to filter networks by proximity
        - name: include_agencies
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Include agency details in response
      responses:
        '200':
          description: Successful response with list of networks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NetworksResponse'
        '401':
          description: Unauthorized - invalid or missing API key
  /public/routes:
    get:
      operationId: listRoutes
      summary: List Routes
      description: >-
        Returns all routes for a list of given transit networks.
      tags:
        - Routes
      parameters:
        - name: network_ids
          in: query
          required: true
          schema:
            type: array
            items:
              type: string
          description: Network IDs to get routes for
      responses:
        '200':
          description: Successful response with route list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutesResponse'
        '401':
          description: Unauthorized - invalid or missing API key
  /public/stops:
    get:
      operationId: listStops
      summary: List Stops
      description: >-
        Returns all stops for a given transit network.
      tags:
        - Stops
      parameters:
        - name: network_id
          in: query
          required: true
          schema:
            type: string
          description: Network ID to get stops for
        - name: lat
          in: query
          required: false
          schema:
            type: number
            format: float
          description: Latitude for proximity filtering
        - name: lon
          in: query
          required: false
          schema:
            type: number
            format: float
          description: Longitude for proximity filtering
        - name: radius
          in: query
          required: false
          schema:
            type: integer
            default: 500
          description: Search radius in meters
      responses:
        '200':
          description: Successful response with stop list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StopsResponse'
        '401':
          description: Unauthorized - invalid or missing API key
  /public/trip:
    get:
      operationId: planTrip
      summary: Plan Trip
      description: >-
        Plans a multimodal trip from origin to destination, combining public
        transit with shared mobility options such as bikes, scooters, and
        carshares.
      tags:
        - Trips
      parameters:
        - name: origin_lat
          in: query
          required: true
          schema:
            type: number
            format: float
          description: Origin latitude
        - name: origin_lon
          in: query
          required: true
          schema:
            type: number
            format: float
          description: Origin longitude
        - name: destination_lat
          in: query
          required: true
          schema:
            type: number
            format: float
          description: Destination latitude
        - name: destination_lon
          in: query
          required: true
          schema:
            type: number
            format: float
          description: Destination longitude
        - name: time
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Departure or arrival time (ISO 8601)
        - name: arrive_by
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Whether time represents arrival time
      responses:
        '200':
          description: Successful response with trip plans
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TripResponse'
        '401':
          description: Unauthorized - invalid or missing API key
  /public/alerts:
    get:
      operationId: getServiceAlerts
      summary: Get Service Alerts
      description: >-
        Returns active service alerts and disruptions for one or more
        transit networks.
      tags:
        - Alerts
      parameters:
        - name: network_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
          description: Network IDs to get alerts for
        - name: route_ids
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
          description: Route IDs to filter alerts
      responses:
        '200':
          description: Successful response with service alerts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlertsResponse'
        '401':
          description: Unauthorized - invalid or missing API key
  /public/nearby_vehicles:
    get:
      operationId: getNearbyVehicles
      summary: Get Nearby Vehicles
      description: >-
        Returns real-time vehicle positions and shared mobility options
        (bikes, scooters, carshares) near a geographic location.
      tags:
        - Mobility
      parameters:
        - name: lat
          in: query
          required: true
          schema:
            type: number
            format: float
          description: Latitude of the location
        - name: lon
          in: query
          required: true
          schema:
            type: number
            format: float
          description: Longitude of the location
        - name: radius
          in: query
          required: false
          schema:
            type: integer
            default: 500
          description: Search radius in meters
      responses:
        '200':
          description: Successful response with nearby vehicles and mobility options
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NearbyVehiclesResponse'
        '401':
          description: Unauthorized - invalid or missing API key
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key provided after partner approval
  schemas:
    StopDeparturesResponse:
      type: object
      properties:
        departures:
          type: array
          items:
            $ref: '#/components/schemas/Departure'
    Departure:
      type: object
      properties:
        route_id:
          type: string
          description: Unique route identifier
        route_name:
          type: string
          description: Human-readable route name
        headsign:
          type: string
          description: Destination display text
        scheduled_time:
          type: string
          format: date-time
          description: Scheduled departure time
        real_time:
          type: string
          format: date-time
          description: Real-time predicted departure time
        wheelchair_accessible:
          type: boolean
          description: Whether vehicle is wheelchair accessible
        vehicle_id:
          type: string
          description: Vehicle identifier for real-time tracking
    NetworksResponse:
      type: object
      properties:
        networks:
          type: array
          items:
            $ref: '#/components/schemas/Network'
    Network:
      type: object
      properties:
        id:
          type: string
          description: Network identifier
        name:
          type: string
          description: Network display name
        agencies:
          type: array
          items:
            $ref: '#/components/schemas/Agency'
        location:
          $ref: '#/components/schemas/Location'
    Agency:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        timezone:
          type: string
    Location:
      type: object
      properties:
        lat:
          type: number
          format: float
        lon:
          type: number
          format: float
        city:
          type: string
        country:
          type: string
    RoutesResponse:
      type: object
      properties:
        routes:
          type: array
          items:
            $ref: '#/components/schemas/Route'
    Route:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
          enum: [bus, rail, metro, tram, ferry, cable_car, gondola, funicular]
        color:
          type: string
        text_color:
          type: string
        network_id:
          type: string
    StopsResponse:
      type: object
      properties:
        stops:
          type: array
          items:
            $ref: '#/components/schemas/Stop'
    Stop:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        lat:
          type: number
          format: float
        lon:
          type: number
          format: float
        wheelchair_accessible:
          type: boolean
        routes:
          type: array
          items:
            type: string
    TripResponse:
      type: object
      properties:
        itineraries:
          type: array
          items:
            $ref: '#/components/schemas/Itinerary'
    Itinerary:
      type: object
      properties:
        duration:
          type: integer
          description: Total trip duration in seconds
        departure_time:
          type: string
          format: date-time
        arrival_time:
          type: string
          format: date-time
        legs:
          type: array
          items:
            $ref: '#/components/schemas/Leg'
    Leg:
      type: object
      properties:
        mode:
          type: string
          enum: [walk, bus, rail, metro, tram, bicycle, scooter, car]
        distance:
          type: number
        duration:
          type: integer
        departure_time:
          type: string
          format: date-time
        arrival_time:
          type: string
          format: date-time
        from_stop:
          $ref: '#/components/schemas/Stop'
        to_stop:
          $ref: '#/components/schemas/Stop'
        route:
          $ref: '#/components/schemas/Route'
    AlertsResponse:
      type: object
      properties:
        alerts:
          type: array
          items:
            $ref: '#/components/schemas/Alert'
    Alert:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        effect:
          type: string
        severity:
          type: string
          enum: [info, warning, severe]
        active_periods:
          type: array
          items:
            type: object
            properties:
              start:
                type: string
                format: date-time
              end:
                type: string
                format: date-time
        affected_routes:
          type: array
          items:
            type: string
        affected_stops:
          type: array
          items:
            type: string
    NearbyVehiclesResponse:
      type: object
      properties:
        vehicles:
          type: array
          items:
            $ref: '#/components/schemas/Vehicle'
        bikes:
          type: array
          items:
            $ref: '#/components/schemas/MobilityVehicle'
        scooters:
          type: array
          items:
            $ref: '#/components/schemas/MobilityVehicle'
    Vehicle:
      type: object
      properties:
        id:
          type: string
        lat:
          type: number
          format: float
        lon:
          type: number
          format: float
        bearing:
          type: number
        route_id:
          type: string
        trip_id:
          type: string
    MobilityVehicle:
      type: object
      properties:
        id:
          type: string
        lat:
          type: number
          format: float
        lon:
          type: number
          format: float
        battery_level:
          type: integer
        provider:
          type: string