OneBusAway Where API

openapi: 3.2.0
info:
  title: OneBusAway default Where API
  description: The OneBusAway REST API. For use with servers like https://api.pugetsound.onebusaway.org
  version: 0.0.2
servers:
- url: https://api.pugetsound.onebusaway.org
security:
- ApiKeyAuth: []
tags:
- name: Where
paths:
  /api/where/agency/{agencyID}.json:
    get:
      summary: Retrieve info for a specific transit agency identified by ID
      description: Retrieve information for a specific transit agency identified by its unique ID.
      parameters:
      - name: agencyID
        in: path
        required: true
        description: The ID of the transit agency.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ResponseWrapper'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/AgencyResponse'
                  required:
                  - data
      tags:
      - Where
  /api/where/route/{routeID}.json:
    get:
      summary: Retrieve info for a specific route identified by ID
      description: Retrieve information for a specific route identified by its unique ID.
      parameters:
      - name: routeID
        in: path
        required: true
        description: The ID of the route.
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                allOf:
                - $ref: '#/components/schemas/ResponseWrapper'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/RouteResponse'
                  required:
                  - data
      tags:
      - Where
  /api/where/route-ids-for-agency/{agencyID}.json:
    parameters:
    - name: agencyID
      in: path
      required: true
      schema:
        type: string
      description: ID of the agency
    get:
      summary: Get route IDs for a specific agency
      responses:
        '200':
          description: List of routeIDs for the agency
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ResponseWrapper'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/RouteIDsForAgencyResponse'
                  required:
                  - data
      tags:
      - Where
  /api/where/vehicles-for-agency/{agencyID}.json:
    parameters:
    - name: agencyID
      in: path
      required: true
      schema:
        type: string
      description: ID of the agency
    - name: time
      in: query
      required: false
      schema:
        type: string
        description: Specific time for querying the status (timestamp format)
    get:
      summary: Get vehicles for a specific agency
      responses:
        '200':
          description: List of vehicles for the agency
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ResponseWrapper'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/VehiclesForAgencyResponse'
                  required:
                  - data
      tags:
      - Where
  /api/where/trip/{tripID}.json:
    parameters:
    - name: tripID
      in: path
      required: true
      schema:
        type: string
      description: ID of the trip
    get:
      summary: Get details of a specific trip
      responses:
        '200':
          description: Details of the trip
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ResponseWrapper'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/TripResponse'
                  required:
                  - data
      tags:
      - Where
  /api/where/trips-for-location.json:
    get:
      summary: Retrieve trips for a given location
      parameters:
      - name: lat
        in: query
        required: true
        schema:
          type: number
          format: float
        description: The latitude coordinate of the search center
      - name: lon
        in: query
        required: true
        schema:
          type: number
          format: float
        description: The longitude coordinate of the search center
      - name: latSpan
        in: query
        required: true
        schema:
          type: number
          format: float
        description: Latitude span of the search bounding box
      - name: lonSpan
        in: query
        required: true
        schema:
          type: number
          format: float
        description: Longitude span of the search bounding box
      - name: includeTrip
        in: query
        required: false
        schema:
          type: boolean
        description: Whether to include full trip elements in the references section. Defaults to false.
      - name: includeSchedule
        in: query
        required: false
        schema:
          type: boolean
        description: Whether to include full schedule elements in the tripDetails section. Defaults to false.
      - name: time
        in: query
        required: false
        schema:
          type: integer
          format: int64
        description: Specific time for the query. Defaults to the current time.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ResponseWrapper'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/TripsForLocationResponse'
                  required:
                  - data
      tags:
      - Where
  /api/where/stops-for-route/{routeID}.json:
    parameters:
    - name: routeID
      in: path
      required: true
      schema:
        type: string
      description: ID of the route
    - name: includePolylines
      in: query
      required: false
      schema:
        type: boolean
      description: Include polyline elements in the response (default true)
    - name: time
      required: false
      in: query
      schema:
        type: string
      description: Specify service date (YYYY-MM-DD or epoch) (default today)
    get:
      summary: Get stops for a specific route
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ResponseWrapper'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/StopsForRouteResponse'
                  required:
                  - data
      tags:
      - Where
  /api/where/stops-for-agency/{agencyID}.json:
    parameters:
    - name: agencyID
      in: path
      required: true
      schema:
        type: string
      description: ID of the agency
    get:
      summary: Get stops for a specific agency
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ResponseWrapper'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/StopsForAgencyResponse'
                  required:
                  - data
      tags:
      - Where
  /api/where/stop/{stopID}.json:
    parameters:
    - name: stopID
      in: path
      required: true
      schema:
        type: string
      description: ID of the stop
    get:
      summary: Get details of a specific stop
      responses:
        '200':
          description: Details of the stop
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ResponseWrapper'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/StopResponse'
                  required:
                  - data
      tags:
      - Where
  /api/where/schedule-for-stop/{stopID}.json:
    get:
      summary: Get schedule for a specific stop
      parameters:
      - name: stopID
        in: path
        required: true
        schema:
          type: string
        description: The stop id to request the schedule for, encoded directly in the URL
      - name: date
        in: query
        required: false
        schema:
          type: string
          format: date
        description: The date for which you want to request a schedule in the format YYYY-MM-DD (optional, defaults to the current date)
      responses:
        '200':
          description: Schedule information for the stop
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ResponseWrapper'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/ScheduleForStopResponse'
                  required:
                  - data
      tags:
      - Where
  /api/where/stop-ids-for-agency/{agencyID}.json:
    parameters:
    - name: agencyID
      in: path
      required: true
      schema:
        type: string
      description: ID of the agency
    get:
      summary: Get stop IDs for a specific agency
      responses:
        '200':
          description: List of stop IDs for the agency
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ResponseWrapper'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/StopIDsForAgencyResponse'
                  required:
                  - data
      tags:
      - Where
  /api/where/report-problem-with-stop/{stopID}.json:
    get:
      summary: Submit a user-generated problem report for a stop
      operationId: reportProblemWithStop
      parameters:
      - name: stopID
        in: path
        required: true
        description: The ID of the stop
        schema:
          type: string
      - name: code
        in: query
        required: false
        description: A string code identifying the nature of the problem
        schema:
          type: string
          enum:
          - stop_name_wrong
          - stop_number_wrong
          - stop_location_wrong
          - route_or_trip_missing
          - other
      - name: userComment
        in: query
        required: false
        description: Additional comment text supplied by the user describing the problem
        schema:
          type: string
      - name: userLat
        in: query
        required: false
        description: The reporting user’s current latitude
        schema:
          type: number
          format: float
      - name: userLon
        in: query
        required: false
        description: The reporting user’s current longitude
        schema:
          type: number
          format: float
      - name: userLocationAccuracy
        in: query
        required: false
        description: The reporting user’s location accuracy, in meters
        schema:
          type: number
          format: float
      responses:
        '200':
          description: Problem report successfully submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseWrapper'
      tags:
      - Where
  /api/where/report-problem-with-trip/{tripID}.json:
    get:
      summary: Submit a user-generated problem report for a particular trip.
      operationId: reportProblemWithTrip
      parameters:
      - name: tripID
        in: path
        required: true
        description: The ID of the trip
        schema:
          type: string
      - name: serviceDate
        in: query
        required: false
        description: The service date of the trip
        schema:
          type: integer
          format: int64
      - name: vehicleID
        in: query
        required: false
        description: The vehicle actively serving the trip
        schema:
          type: string
      - name: stopID
        in: query
        required: false
        description: A stop ID indicating where the user is experiencing the problem
        schema:
          type: string
      - name: code
        in: query
        required: false
        description: A string code identifying the nature of the problem
        schema:
          type: string
          enum:
          - vehicle_never_came
          - vehicle_came_early
          - vehicle_came_late
          - wrong_headsign
          - vehicle_does_not_stop_here
          - other
      - name: userComment
        in: query
        required: false
        description: Additional comment text supplied by the user describing the problem
        schema:
          type: string
      - name: userOnVehicle
        in: query
        required: false
        description: Indicator if the user is on the transit vehicle experiencing the problem
        schema:
          type: boolean
      - name: userVehicleNumber
        in: query
        required: false
        description: The vehicle number, as reported by the user
        schema:
          type: string
      - name: userLat
        in: query
        required: false
        description: The reporting user’s current latitude
        schema:
          type: number
          format: float
      - name: userLon
        in: query
        required: false
        description: The reporting user’s current longitude
        schema:
          type: number
          format: float
      - name: userLocationAccuracy
        in: query
        required: false
        description: The reporting user’s location accuracy, in meters
        schema:
          type: number
          format: float
      responses:
        '200':
          description: Problem report successfully submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseWrapper'
      tags:
      - Where
  /api/where/search/stop.json:
    get:
      summary: Search for a stop based on its name.
      operationId: searchStop
      parameters:
      - name: input
        in: query
        description: The string to search for.
        required: true
        schema:
          type: string
      - name: maxCount
        in: query
        description: The max number of results to return. Defaults to 20.
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Successful stop search.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ResponseWrapper'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/SearchStopResponse'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
      - Where
  /api/where/search/route.json:
    get:
      summary: Search for a route based on its name.
      operationId: searchRoute
      parameters:
      - name: input
        in: query
        description: The string to search for.
        required: true
        schema:
          type: string
      - name: maxCount
        in: query
        description: The max number of results to return. Defaults to 20.
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Successful route search.
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ResponseWrapper'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/SearchRouteResponse'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
      - Where
  /api/where/block/{blockID}.json:
    parameters:
    - name: blockID
      in: path
      required: true
      schema:
        type: string
      description: ID of the block
    get:
      summary: Get details of a specific block by ID
      responses:
        '200':
          description: Details of the block
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ResponseWrapper'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/BlockResponse'
                  required:
                  - data
      tags:
      - Where
  /api/where/shape/{shapeID}.json:
    get:
      summary: Retrieve a shape by ID
      description: Retrieve a shape (the path traveled by a transit vehicle) by ID.
      parameters:
      - name: shapeID
        in: path
        required: true
        description: The shape ID, encoded directly in the URL
        schema:
          type: string
      responses:
        '200':
          description: The shape of the path traveled by the transit vehicle
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ResponseWrapper'
                - type: object
                  properties:
                    data:
                      $ref: '#/components/schemas/ShapeResponse'
                  required:
                  - data
      tags:
      - Where
components:
  schemas:
    StopGrouping:
      type: object
      properties:
        id:
          type: string
        name:
          type: object
          properties:
            name:
              type: string
            names:
              type: array
              items:
                type: string
            type:
              type: string
        polylines:
          type: array
          items:
            $ref: '#/components/schemas/Polylines'
        stopIds:
          type: array
          items:
            type: string
    RouteIDsForAgencyResponse:
      type: object
      properties:
        limitExceeded:
          type: boolean
        list:
          type: array
          items:
            type: string
        references:
          $ref: '#/components/schemas/Reference'
      required:
      - list
      - references
    BlockTrip:
      type: object
      properties:
        tripId:
          type: string
        distanceAlongBlock:
          type: number
          format: float
        accumulatedSlackTime:
          type: number
          format: float
        blockStopTimes:
          type: array
          items:
            $ref: '#/components/schemas/BlockStopTime'
      required:
      - tripId
      - blockStopTimes
      - distanceAlongBlock
      - accumulatedSlackTime
    BlockStopTime:
      type: object
      properties:
        blockSequence:
          type: integer
        distanceAlongBlock:
          type: number
          format: float
        accumulatedSlackTime:
          type: number
          format: float
        stopTime:
          type: object
          properties:
            stopId:
              type: string
            arrivalTime:
              type: integer
            departureTime:
              type: integer
            pickupType:
              type: integer
            dropOffType:
              type: integer
          required:
          - stopId
          - arrivalTime
          - departureTime
      required:
      - blockSequence
      - stopTime
      - distanceAlongBlock
      - accumulatedSlackTime
    VehiclesForAgencyResponse:
      type: object
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/VehicleStatus'
        limitExceeded:
          type: boolean
        references:
          $ref: '#/components/schemas/Reference'
      required:
      - list
      - references
    ScheduleForStopEntry:
      type: object
      properties:
        date:
          type: integer
          format: int64
        stopId:
          type: string
        stopRouteSchedules:
          type: array
          items:
            $ref: '#/components/schemas/StopRouteSchedule'
      required:
      - date
      - stopId
      - stopRouteSchedules
    ShapeResponse:
      type: object
      properties:
        entry:
          type: object
          properties:
            length:
              type: integer
            levels:
              type: string
            points:
              type: string
              description: Encoded polyline format representing the shape of the path
          required:
          - length
          - points
        references:
          $ref: '#/components/schemas/Reference'
      required:
      - entry
      - references
    TripResponse:
      type: object
      properties:
        entry:
          $ref: '#/components/schemas/Trip'
        references:
          $ref: '#/components/schemas/Reference'
      required:
      - entry
      - references
    VehicleStatus:
      type: object
      properties:
        vehicleId:
          type: string
        lastUpdateTime:
          type: integer
          format: int64
        lastLocationUpdateTime:
          type: integer
          format: int64
        location:
          $ref: '#/components/schemas/Location'
        tripId:
          type: string
        tripStatus:
          $ref: '#/components/schemas/TripStatus'
        occupancyCapacity:
          type: integer
        occupancyCount:
          type: integer
        occupancyStatus:
          type: string
        phase:
          type: string
        status:
          type: string
      required:
      - vehicleId
      - lastUpdateTime
      - lastLocationUpdateTime
    TripStatus:
      type: object
      description: Trip-specific status for the arriving transit vehicle.
      properties:
        activeTripId:
          type: string
          description: Trip ID of the trip the vehicle is actively serving.
        blockTripSequence:
          type: integer
          description: Index of the active trip into the sequence of trips for the active block.
        closestStop:
          type: string
          description: ID of the closest stop to the current location of the transit vehicle.
        closestStopTimeOffset:
          type: integer
          description: Time offset from the closest stop to the current position of the transit vehicle (in seconds).
        distanceAlongTrip:
          type: number
          description: Distance, in meters, the transit vehicle has progressed along the active trip.
        frequency:
          type:
          - string
          - 'null'
          description: Information about frequency-based scheduling, if applicable to the trip.
        lastKnownDistanceAlongTrip:
          type: number
          description: Last known distance along the trip received in real-time from the transit vehicle.
        lastKnownLocation:
          type:
          - object
          - 'null'
          properties:
            lat:
              type: number
              description: Latitude of the last known location of the transit vehicle.
            lon:
              type: number
              description: Longitude of the last known location of the transit vehicle.
          description: Last known location of the transit vehicle (optional).
        lastKnownOrientation:
          type: number
          description: Last known orientation value received in real-time from the transit vehicle.
        lastLocationUpdateTime:
          type: integer
          description: Timestamp of the last known real-time location update from the transit vehicle.
        lastUpdateTime:
          type: integer
          description: Timestamp of the last known real-time update from the transit vehicle.
        nextStop:
          type: string
          description: ID of the next stop the transit vehicle is scheduled to arrive at.
        nextStopTimeOffset:
          type: integer
          description: Time offset from the next stop to the current position of the transit vehicle (in seconds).
        occupancyCapacity:
          type: integer
          description: Capacity of the transit vehicle in terms of occupancy.
        occupancyCount:
          type: integer
          description: Current count of occupants in the transit vehicle.
        occupancyStatus:
          type: string
          description: Current occupancy status of the transit vehicle.
        orientation:
          type: number
          description: Orientation of the transit vehicle, represented as an angle in degrees.
        phase:
          type: string
          description: Current journey phase of the trip.
        position:
          type: object
          properties:
            lat:
              type: number
              description: Latitude of the current position of the transit vehicle.
            lon:
              type: number
              description: Longitude of the current position of the transit vehicle.
          description: Current position of the transit vehicle.
        predicted:
          type: boolean
          description: Indicates if real-time arrival info is available for this trip.
        scheduleDeviation:
          type: integer
          description: Deviation from the schedule in seconds (positive for late, negative for early).
        scheduledDistanceAlongTrip:
          type: number
          description: Distance, in meters, the transit vehicle is scheduled to have progressed along the active trip.
        serviceDate:
          type: integer
          description: Time, in milliseconds since the Unix epoch, of midnight for the start of the service date for the trip.
        situationIds:
          type: array
          items:
            type: string
          description: References to situation elements (if any) applicable to this trip.
        status:
          type: string
          description: Current status modifiers for the trip.
        totalDistanceAlongTrip:
          type: number
          description: Total length of the trip, in meters.
        vehicleId:
          type: string
          description: ID of the transit vehicle currently serving the trip.
      required:
      - activeTripId
      - blockTripSequence
      - closestStop
      - distanceAlongTrip
      - lastKnownDistanceAlongTrip
      - lastLocationUpdateTime
      - lastUpdateTime
      - occupancyCapacity
      - occupancyCount
      - occupancyStatus
      - phase
      - predicted
      - scheduleDeviation
      - serviceDate
      - status
      - totalDistanceAlongTrip
    ResponseWrapper:
      type: object
      properties:
        code:
          type: integer
        currentTime:
          type: integer
        text:
          type: string
        version:
          type: integer
      required:
      - code
      - currentTime
      - text
      - version
    StopTime:
      type: object
      properties:
        arrivalTime:
          type: integer
        departureTime:
          type: integer
        distanceAlongTrip:
          type: number
        historicalOccupancy:
          type: string
        stopHeadsign:
          type: string
        stopId:
          type: string
    SearchRouteResponse:
      type: object
      properties:
        limitExceeded:
          type: boolean
        list:
          type: array
          items:
            $ref: '#/components/schemas/Route'
        outOfRange:
          type: boolean
        references:
          $ref: '#/components/schemas/Reference'
      required:
      - list
      - outOfRange
      - references
    AgencyResponse:
      type: object
      properties:
        entry:
          $ref: '#/components/schemas/Agency'
        references:
          $ref: '#/components/schemas/Reference'
      required:
      - entry
      - references
    TimeWindow:
      type: object
      properties:
        from:
          type: integer
          format: int64
          description: Start time of the time window as a Unix timestamp.
        to:
          type: integer
          format: int64
          description: End time of the time window as a Unix timestamp.
      required:
      - from
      - to
    TripSchedule:
      type:
      - object
      - 'null'
      properties:
        frequency:
          type:
          - string
          - 'null'
        nextTripId:
          type: string
        previousTripId:
          type: string
        stopTimes:
          type: array
          items:
            $ref: '#/components/schemas/StopTime'
        timeZone:
          type: string
      required:
      - stopTimes
      - timeZone
      - nextTripId
      - previousTripId
    StopRouteDirectionSchedule:
      type: object
      properties:
        scheduleFrequencies:
          type: array
          items:
            $ref: '#/components/schemas/ScheduleFrequency'
        scheduleStopTimes:
          type: array
          items:
            $ref: '#/components/schemas/ScheduleStopTime'
        tripHeadsign:
          type: string
      required:
      - scheduleStopTimes
      - tripHeadsign
    Reference:
      type: object
      properties:
        agencies:
          type: array
          items:
            $ref: '#/components/schemas/Agency'
        routes:
          type: array
          items:
            $ref: '#/components/schemas/Route'
        situations:
          type: array
          items:
            $ref: '#/components/schemas/Situation'
        stopTimes:
          type: array
          items:
            $ref: '#/components/schemas/StopTime'
        stops:
          type: array
          items:
            $ref: '#/components/schemas/Stop'
        trips:
          type: array
          items:
            $ref: '#/components/schemas/Trip'
      required:
      - agencies
      - routes
      - situations
      - stopTimes
      - stops
      - trips
    ScheduleStopTime:
      type: object
      properties:
        arrivalEnabled:
          type: boolean
        arrivalTime:
          type: integer
          format: int64
        departureEnabled:
          type: boolean
        departureTime:
          type: integer
          format: int64
        serviceId:
          type: string
        stopHeadsign:
          type: string
        tripId:
          type: string
      required:
      - arrivalEnabled
      - arrivalTime
      - departureEnabled
      - departureTime
      - serviceId
      - tripId
    RouteResponse:
      type: object
      properties:
        entry:
          $ref: '#/components/schemas/Route'
        references:
          $ref: '#/components/schemas/Reference'
      required:
      - entry
      - references
    Situation:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the situation.
        creationTime:
          type: integer
          format: int64
          description: Unix timestamp of when this situation was created.
        reason:
          type: string
          description: Reason for the service alert, taken from TPEG codes.
        summary:
          type: object
          properties:
            lang:
              type: string
              description: Language of the summary.
            value:
              type: string
              description: Short summary of the situation.
        description:
          type: object
          properties:
            lang:
              type: string
              description: Language of the description.
            value:
              type: string
              description: Longer description of the situation.
        url:
          type: object
          properties:
            lang:
              type: string
    

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