OneBusAway Where API

openapi: 3.0.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:
    BlockResponse:
      type: object
      properties:
        entry:
          $ref: '#/components/schemas/BlockEntry'
        references:
          $ref: '#/components/schemas/Reference'
      required:
      - entry
      - 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
    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
    StopsForRouteResponse:
      type: object
      properties:
        entry:
          type: object
          properties:
            polylines:
              type: array
              items:
                $ref: '#/components/schemas/Polylines'
            routeId:
              type: string
              example: '1_100224'
            stopGroupings:
              type: array
              items:
                $ref: '#/components/schemas/StopGrouping'
            stopIds:
              type: array
              items:
                type: string
                example: '1_10911'
        references:
          $ref: '#/components/schemas/Reference'
      required:
      - entry
      - references
    TripsForLocationResponse:
      type: object
      properties:
        limitExceeded:
          type: boolean
          description: Indicates if the limit of trips has been exceeded
        list:
          type: array
          items:
            $ref: '#/components/schemas/TripDetails'
        outOfRange:
          type: boolean
          description: Indicates if the search location is out of range
        references:
          $ref: '#/components/schemas/Reference'
      required:
      - list
      - references
    BlockEntry:
      type: object
      properties:
        id:
          type: string
        configurations:
          type: array
          items:
            $ref: '#/components/schemas/BlockConfiguration'
      required:
      - id
      - configurations
    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
    StopTime:
      type: object
      properties:
        arrivalTime:
          type: integer
        departureTime:
          type: integer
        distanceAlongTrip:
          type: number
        historicalOccupancy:
          type: string
        stopHeadsign:
          type: string
        stopId:
          type: string
    SearchStopResponse:
      type: object
      properties:
        limitExceeded:
          type: boolean
        list:
          type: array
          items:
            $ref: '#/components/schemas/Stop'
        outOfRange:
          type: boolean
        references:
          $ref: '#/components/schemas/Reference'
      required:
      - list
      - outOfRange
      - references
    ResponseWrapper:
      type: object
      properties:
        code:
          type: integer
        currentTime:
          type: integer
        text:
          type: string
        version:
          type: integer
      required:
      - code
      - currentTime
      - text
      - version
    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
    StopsForAgencyResponse:
      type: object
      properties:
        limitExceeded:
          type: boolean
        outOfRange:
          type: boolean
        list:
          type: array
          items:
            $ref: '#/components/schemas/Stop'
        references:
          $ref: '#/components/schemas/Reference'
      required:
      - list
      - references
    BlockConfiguration:
      type: object
      properties:
        activeServiceIds:
          type: array
          items:
            type: string
        inactiveServiceIds:
          type: array
          items:
            type: string
        trips:
          type: array
          items:
            $ref: '#/components/schemas/BlockTrip'
      required:
      - activeServiceIds
      - trips
    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
    StopRouteSchedule:
      type: object
      properties:
        routeId:
          type: string
        stopRouteDirectionSchedules:
          type: array
          items:
            $ref: '#/components/schemas/StopRouteDirectionSchedule'
      required:
      - routeId
      - stopRouteDirectionSchedules
    Location:
      type: object
      properties:
        lat:
          type: number
        lon:
          type: number
    StopIDsForAgencyResponse:
      type: object
      properties:
        limitExceeded:
          type: boolean
        list:
          type: array
          items:
            type: string
        references:
          $ref: '#/components/schemas/Reference'
      required:
      - list
      - references
    RouteResponse:
      type: object
      properties:
        entry:
          $ref: '#/components/schemas/Route'
        references:
          $ref: '#/components/schemas/Reference'
      required:
      - entry
      - references
    ScheduleFrequency:
      type: object
      properties:
        serviceDate:
          type: integer
          format: int64
        startTime:
          type: integer
          format: int64
        endTime:
          type: integer
          format: int64
        headway:
          type: integer
          format: int32
        serviceId:
          type: string
        tripId:
          type: string
      required:
      - serviceDate
      - startTime
      - endTime
      - headway
      - serviceId
      - tripId
    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
              description: Language of the URL.
            value:
              type: string
              description: URL for more information about the situation.
        activeWindows:
          type: array
          items:
            type: object
            properties:
              from:
                type: integer
                format: int64
                description: Start time of the active window as a Unix timestamp.
              to:
                type: integer
                format: int64
                description: End time of the active window as a Unix timestamp.
        allAffects:
          type: array
          items:
            type: object
            properties:
              agencyId:
                type: string
                description: Identifier for the agency.
              applicationId:
                type: string
                description: Identifier for the application.
              directionId:
                type: string
                description: Identifier for the direction.
              routeId:
                type: string
                description: Identifier for the route.
              stopId:
                type: string
                description: Identifier for the stop.
              tripId:
                type: string
                description: Identifier for the trip.
        consequences:
          type: array
          items:
            type: object
            properties:
              condition:
                type: string
                description: Condition of the consequence.
              conditionDetails:
                type: object
                properties:
                  diversionPath:
                    type: object
                    properties:
                      length:
                        type: integer
                        description: Length of the diversion path.
                      levels:
                        type: string
                        description: Levels of the diversion path.
                      points:
                        type: string
                        description: Points of the diversion path.
                  diversionStopIds:
                    type: array
                    items:
                      type: string
                      description: List of stop IDs affected by the diversion.
        publicationWindows:
          type: array
          items:
            $ref: '#/components/schemas/TimeWindow'
        severity:
          type: string
          description: Severity of the situation.
        consequenceMessage:
          type: string
          description: Message regarding the consequence of the situation.
      required:
      - id
      - creationTime
    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
    Agency:
      type: object
      properties:
        disclaimer:
          type: string
        email:
          type: string
        fareUrl:
          type: string
        id:
          type: string
        lang:
          type: string
        name:
          type: string
        phone:
          type: string
        privateService:
          type: boolean
        timezone:
          type: string
        url:
          type: string
      required:
      - id
      - name
      - timezone
      - url
    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
    StopResponse:
      type: object
      properties:
        entry:
          $ref: '#/components/schemas/Stop'
        references:
          $ref: '#/components/schemas/Reference'
      required:
      - entry
      - references
    VehiclesForAgencyResponse:
      type: object
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/VehicleStatus'
        limitExceeded:
          type: boolean
        references:
          $ref: '#/components/schemas/Reference'
      required:
      - list
      - references
    TripDetails:
      type: object
      properties:
        frequency:
          type: string
          nullable: true
        serviceDate:
          type: integer
          format: int64
        situationIds:
          type: array
          items:
            type: string
        tripId:
          type: string
        schedule:
          $ref: '#/components/schemas/TripSchedule'
        status:
          $ref: '#/components/schemas/TripStatus'
      required:
      - tripId
      - schedule
      - status
    ScheduleForStopResponse:
      type: object
      properties:
        entry:
          $ref: '#/components/schemas/ScheduleForStopEntry'
        references:
          $ref: '#/components/schemas/Reference'
      required:
      - entry
      - references
    BlockStopTime:
      type: object
      properties:


# --- 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