openapi: 3.0.0
info:
  title: Sound Transit OneBusAway API
  description: >-
    The Sound Transit OneBusAway API provides access to real-time and scheduled
    transit data for the Puget Sound region including routes, stops, arrivals,
    departures, and vehicle positions. Supports real-time data for the 1 Line,
    2 Line, T Line, and ST Express bus routes.
  version: "2.0"
  contact:
    name: Sound Transit Open Transit Data
    email: open_transit_data@soundtransit.org
    url: https://www.soundtransit.org/help-contacts/business-information/open-transit-data-otd
  license:
    name: Open Data
    url: https://www.soundtransit.org/help-contacts/business-information/open-transit-data-otd/transit-data-terms-use
servers:
  - url: https://api.pugetsound.onebusaway.org/api/where
    description: Puget Sound OneBusAway API
tags:
  - name: Agencies
    description: Transit agency information and coverage
  - name: Routes
    description: Route definitions and schedules
  - name: Stops
    description: Stop locations and schedules
  - name: Arrivals And Departures
    description: Real-time and scheduled arrival/departure information
  - name: Trips
    description: Trip details and active vehicle positions
  - name: Vehicles
    description: Active vehicle locations and assignments
  - name: System
    description: System utilities and configuration
paths:
  /agencies-with-coverage.json:
    get:
      operationId: listAgenciesWithCoverage
      summary: List Agencies With Coverage
      description: List all supported transit agencies along with their geographic coverage areas.
      tags:
        - Agencies
      parameters:
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: List of agencies with coverage areas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgenciesResponse'
        '401':
          description: Unauthorized - invalid API key
  /agency/{id}.json:
    get:
      operationId: getAgency
      summary: Get Agency
      description: Retrieve details for a specific transit agency.
      tags:
        - Agencies
      parameters:
        - name: id
          in: path
          required: true
          description: Unique agency identifier
          schema:
            type: string
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Agency details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgencyResponse'
        '404':
          description: Agency not found
  /route/{id}.json:
    get:
      operationId: getRoute
      summary: Get Route
      description: Retrieve details for a specific transit route.
      tags:
        - Routes
      parameters:
        - name: id
          in: path
          required: true
          description: Unique route identifier
          schema:
            type: string
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Route details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteResponse'
        '404':
          description: Route not found
  /routes-for-agency/{id}.json:
    get:
      operationId: listRoutesForAgency
      summary: List Routes For Agency
      description: List all transit routes for a specific agency.
      tags:
        - Routes
      parameters:
        - name: id
          in: path
          required: true
          description: Agency identifier
          schema:
            type: string
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: List of routes for the agency
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutesResponse'
  /routes-for-location.json:
    get:
      operationId: listRoutesForLocation
      summary: List Routes For Location
      description: Search for transit routes near a geographic location.
      tags:
        - Routes
      parameters:
        - name: lat
          in: query
          required: true
          description: Latitude of the search location
          schema:
            type: number
            format: float
        - name: lon
          in: query
          required: true
          description: Longitude of the search location
          schema:
            type: number
            format: float
        - name: radius
          in: query
          required: false
          description: Search radius in meters
          schema:
            type: integer
        - name: query
          in: query
          required: false
          description: Route name search query
          schema:
            type: string
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: List of routes near the location
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RoutesResponse'
  /stop/{id}.json:
    get:
      operationId: getStop
      summary: Get Stop
      description: Retrieve details for a specific transit stop.
      tags:
        - Stops
      parameters:
        - name: id
          in: path
          required: true
          description: Unique stop identifier
          schema:
            type: string
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Stop details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StopResponse'
        '404':
          description: Stop not found
  /stops-for-location.json:
    get:
      operationId: listStopsForLocation
      summary: List Stops For Location
      description: Search for transit stops near a geographic location.
      tags:
        - Stops
      parameters:
        - name: lat
          in: query
          required: true
          description: Latitude of the search location
          schema:
            type: number
            format: float
        - name: lon
          in: query
          required: true
          description: Longitude of the search location
          schema:
            type: number
            format: float
        - name: radius
          in: query
          required: false
          description: Search radius in meters (default 500)
          schema:
            type: integer
            default: 500
        - name: query
          in: query
          required: false
          description: Stop code or name search query
          schema:
            type: string
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: List of stops near the location
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StopsResponse'
  /stops-for-route/{id}.json:
    get:
      operationId: listStopsForRoute
      summary: List Stops For Route
      description: Get all stops and travel paths for a specific route.
      tags:
        - Stops
      parameters:
        - name: id
          in: path
          required: true
          description: Route identifier
          schema:
            type: string
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Stops and paths for the route
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StopsForRouteResponse'
  /schedule-for-stop/{id}.json:
    get:
      operationId: getScheduleForStop
      summary: Get Schedule For Stop
      description: Get the full schedule for a stop on a particular day.
      tags:
        - Stops
      parameters:
        - name: id
          in: path
          required: true
          description: Stop identifier
          schema:
            type: string
        - name: date
          in: query
          required: false
          description: Service date in YYYY-MM-DD format (default today)
          schema:
            type: string
            format: date
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Full schedule for the stop
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StopScheduleResponse'
  /arrivals-and-departures-for-stop/{id}.json:
    get:
      operationId: getArrivalsAndDeparturesForStop
      summary: Get Arrivals And Departures For Stop
      description: Get current real-time arrivals and departures for a transit stop.
      tags:
        - Arrivals And Departures
      parameters:
        - name: id
          in: path
          required: true
          description: Stop identifier
          schema:
            type: string
        - name: minutesBefore
          in: query
          required: false
          description: How many minutes before now to include arrivals/departures
          schema:
            type: integer
            default: 5
        - name: minutesAfter
          in: query
          required: false
          description: How many minutes after now to include arrivals/departures
          schema:
            type: integer
            default: 35
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Real-time arrivals and departures
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrivalsAndDeparturesResponse'
  /arrival-and-departure-for-stop/{id}.json:
    get:
      operationId: getArrivalAndDepartureForStop
      summary: Get Arrival And Departure For Stop
      description: Get details for a specific arrival or departure at a stop.
      tags:
        - Arrivals And Departures
      parameters:
        - name: id
          in: path
          required: true
          description: Stop identifier
          schema:
            type: string
        - name: tripId
          in: query
          required: true
          description: Trip identifier
          schema:
            type: string
        - name: serviceDate
          in: query
          required: true
          description: Service date in milliseconds since Unix epoch
          schema:
            type: integer
            format: int64
        - name: vehicleId
          in: query
          required: false
          description: Vehicle identifier
          schema:
            type: string
        - name: stopSequence
          in: query
          required: false
          description: Stop sequence number within the trip
          schema:
            type: integer
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Arrival/departure details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArrivalAndDepartureResponse'
  /trip/{id}.json:
    get:
      operationId: getTrip
      summary: Get Trip
      description: Retrieve details for a specific transit trip.
      tags:
        - Trips
      parameters:
        - name: id
          in: path
          required: true
          description: Trip identifier
          schema:
            type: string
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Trip details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TripResponse'
  /trip-details/{id}.json:
    get:
      operationId: getTripDetails
      summary: Get Trip Details
      description: Get extended details for a trip including stop times and schedule deviation.
      tags:
        - Trips
      parameters:
        - name: id
          in: path
          required: true
          description: Trip identifier
          schema:
            type: string
        - name: serviceDate
          in: query
          required: false
          description: Service date in milliseconds since Unix epoch
          schema:
            type: integer
            format: int64
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Extended trip details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TripDetailsResponse'
  /trips-for-route/{id}.json:
    get:
      operationId: listTripsForRoute
      summary: List Trips For Route
      description: Get all currently active trips for a specific route.
      tags:
        - Trips
      parameters:
        - name: id
          in: path
          required: true
          description: Route identifier
          schema:
            type: string
        - name: includeStatus
          in: query
          required: false
          description: Include real-time status information
          schema:
            type: boolean
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Active trips for the route
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TripsResponse'
  /trips-for-location.json:
    get:
      operationId: listTripsForLocation
      summary: List Trips For Location
      description: Get all active trips near a geographic location.
      tags:
        - Trips
      parameters:
        - name: lat
          in: query
          required: true
          schema:
            type: number
            format: float
        - name: lon
          in: query
          required: true
          schema:
            type: number
            format: float
        - name: latSpan
          in: query
          required: true
          description: Latitude span for the bounding box
          schema:
            type: number
            format: float
        - name: lonSpan
          in: query
          required: true
          description: Longitude span for the bounding box
          schema:
            type: number
            format: float
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Active trips near the location
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TripsResponse'
  /trip-for-vehicle/{id}.json:
    get:
      operationId: getTripForVehicle
      summary: Get Trip For Vehicle
      description: Get the current trip details for a specific vehicle.
      tags:
        - Vehicles
      parameters:
        - name: id
          in: path
          required: true
          description: Vehicle identifier
          schema:
            type: string
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Trip details for the vehicle
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TripDetailsResponse'
  /vehicles-for-agency/{id}.json:
    get:
      operationId: listVehiclesForAgency
      summary: List Vehicles For Agency
      description: Get all currently active vehicles for a transit agency.
      tags:
        - Vehicles
      parameters:
        - name: id
          in: path
          required: true
          description: Agency identifier
          schema:
            type: string
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Active vehicles for the agency
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VehiclesResponse'
  /current-time.json:
    get:
      operationId: getCurrentTime
      summary: Get Current Time
      description: Retrieve the current server time.
      tags:
        - System
      parameters:
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Current server time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrentTimeResponse'
  /config.json:
    get:
      operationId: getConfig
      summary: Get Server Configuration
      description: Get server deployment configuration details.
      tags:
        - System
      parameters:
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Server configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfigResponse'
  /shape/{id}.json:
    get:
      operationId: getShape
      summary: Get Shape
      description: Get polyline shape details for a route or trip.
      tags:
        - Routes
      parameters:
        - name: id
          in: path
          required: true
          description: Shape identifier
          schema:
            type: string
        - $ref: '#/components/parameters/ApiKey'
      responses:
        '200':
          description: Shape polyline data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShapeResponse'
components:
  parameters:
    ApiKey:
      name: key
      in: query
      required: true
      description: API key obtained from Sound Transit (contact oba_api_key@soundtransit.org)
      schema:
        type: string
  schemas:
    BaseResponse:
      type: object
      properties:
        code:
          type: integer
          description: HTTP status code
        currentTime:
          type: integer
          format: int64
          description: Current server time in milliseconds
        text:
          type: string
          description: Human-readable status message
        version:
          type: integer
          description: API version
    Agency:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        url:
          type: string
          format: uri
        timezone:
          type: string
        lang:
          type: string
        phone:
          type: string
        fareUrl:
          type: string
          format: uri
    AgencyWithCoverage:
      type: object
      properties:
        agencyId:
          type: string
        lat:
          type: number
          format: float
        lon:
          type: number
          format: float
        latSpan:
          type: number
          format: float
        lonSpan:
          type: number
          format: float
    AgenciesResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                list:
                  type: array
                  items:
                    $ref: '#/components/schemas/AgencyWithCoverage'
                references:
                  type: object
    AgencyResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                entry:
                  $ref: '#/components/schemas/Agency'
    Route:
      type: object
      properties:
        id:
          type: string
        agencyId:
          type: string
        shortName:
          type: string
        longName:
          type: string
        description:
          type: string
        type:
          type: integer
          description: GTFS route type
        url:
          type: string
          format: uri
        color:
          type: string
        textColor:
          type: string
    RouteResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                entry:
                  $ref: '#/components/schemas/Route'
    RoutesResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                list:
                  type: array
                  items:
                    $ref: '#/components/schemas/Route'
    Stop:
      type: object
      properties:
        id:
          type: string
        lat:
          type: number
          format: float
        lon:
          type: number
          format: float
        direction:
          type: string
        name:
          type: string
        code:
          type: string
        locationType:
          type: integer
        routeIds:
          type: array
          items:
            type: string
        wheelchairBoarding:
          type: string
    StopResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                entry:
                  $ref: '#/components/schemas/Stop'
    StopsResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                list:
                  type: array
                  items:
                    $ref: '#/components/schemas/Stop'
    StopsForRouteResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                entry:
                  type: object
                  properties:
                    routeId:
                      type: string
                    stopIds:
                      type: array
                      items:
                        type: string
                    polylines:
                      type: array
                      items:
                        type: object
    StopScheduleResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                entry:
                  type: object
    ArrivalAndDeparture:
      type: object
      properties:
        routeId:
          type: string
        tripId:
          type: string
        serviceDate:
          type: integer
          format: int64
        vehicleId:
          type: string
        stopId:
          type: string
        stopSequence:
          type: integer
        scheduledArrivalTime:
          type: integer
          format: int64
        scheduledDepartureTime:
          type: integer
          format: int64
        predictedArrivalTime:
          type: integer
          format: int64
        predictedDepartureTime:
          type: integer
          format: int64
        predicted:
          type: boolean
        status:
          type: string
        routeShortName:
          type: string
        tripHeadsign:
          type: string
    ArrivalsAndDeparturesResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                entry:
                  type: object
                  properties:
                    arrivalsAndDepartures:
                      type: array
                      items:
                        $ref: '#/components/schemas/ArrivalAndDeparture'
    ArrivalAndDepartureResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                entry:
                  $ref: '#/components/schemas/ArrivalAndDeparture'
    Trip:
      type: object
      properties:
        id:
          type: string
        routeId:
          type: string
        serviceId:
          type: string
        tripHeadsign:
          type: string
        tripShortName:
          type: string
        directionId:
          type: string
        shapeId:
          type: string
        blockId:
          type: string
    TripResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                entry:
                  $ref: '#/components/schemas/Trip'
    TripDetailsResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                entry:
                  type: object
                  properties:
                    tripId:
                      type: string
                    serviceDate:
                      type: integer
                      format: int64
                    status:
                      type: object
                    stopTimes:
                      type: array
                      items:
                        type: object
    TripsResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                list:
                  type: array
                  items:
                    $ref: '#/components/schemas/Trip'
    VehicleStatus:
      type: object
      properties:
        vehicleId:
          type: string
        lastUpdateTime:
          type: integer
          format: int64
        lastLocationUpdateTime:
          type: integer
          format: int64
        location:
          type: object
          properties:
            lat:
              type: number
              format: float
            lon:
              type: number
              format: float
        tripId:
          type: string
        tripStatus:
          type: string
        phase:
          type: string
    VehiclesResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                list:
                  type: array
                  items:
                    $ref: '#/components/schemas/VehicleStatus'
    CurrentTimeResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                entry:
                  type: object
                  properties:
                    time:
                      type: integer
                      format: int64
                    readableTime:
                      type: string
    ConfigResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
    ShapeResponse:
      allOf:
        - $ref: '#/components/schemas/BaseResponse'
        - type: object
          properties:
            data:
              type: object
              properties:
                entry:
                  type: object
                  properties:
                    points:
                      type: string
                      description: Encoded polyline string
                    length:
                      type: integer