TransCAPI Bus API

openapi: 3.2.0
info:
  contact:
    url: https://www.transcapi.com
  description: 'Public transport data for Great Britain (England, Scotland and Wales): stops and places, bus and rail departures and arrivals with live running, routes and services, live bus positions, disruptions and journey planning. Every departure says in `source` whether its time is live or timetabled. Data is official open data; attribution requirements are at https://www.transcapi.com/docs/data-sources.'
  termsOfService: https://www.transcapi.com/terms
  title: TransC Bus API
  version: 1.0.0
servers:
- description: Production
  url: https://api.transcapi.com
security:
- ApiKeyHeader: []
- ApiKeyQuery: []
tags:
- name: Bus
paths:
  /v1/bus/activity.json:
    get:
      description: 'Over the last `days` complete days (default 7, 1-28), from the stops each tracked bus was seen passing: trips run, distance driven, buses used, stops served, the places passed and how often, trips by hour, and for each bus its trips, distance and lines. Give operator + line, or operator + vehicle (a fleet number such as 35682, or a vehicle_id from /v1/bus/vehicles.json). Built for bus and roadside advertising: where a line or an advertised bus went and how often. It counts buses, not passengers. Distance is each trip''s route length where known, otherwise straight-line between stops plus a quarter.'
      parameters:
      - description: National Operator Code
        e.g. GNEL: null
        in: query
        name: operator
        required: true
        schema:
          type: string
      - description: Line name as on the bus
        e.g. 21: null
        in: query
        name: line
        schema:
          type: string
      - description: Fleet number or vehicle_id
        in: query
        name: vehicle
        schema:
          type: string
      - in: query
        name: days
        schema:
          default: 7
          type: integer
      responses:
        '200':
          description: Activity summary
        '404':
          description: Nothing tracked for that line or bus in the period
      summary: Bus activity by line or vehicle
      tags:
      - Bus
      operationId: getV1BusActivityJson
      x-operation-id-source: derived
  /v1/bus/reliability.json:
    get:
      description: 'Observed punctuality over the last `days` complete days (default 28, 7-56): the share of stop calls on time, early, late and very late, mean delay and its spread, on-time rates at timing points, first and last stops, and an hour-by-hour breakdown. Give a route_id (from /v1/bus/routes.json), or operator + line. operator alone lists that operator''s lines. Measured where TransCAPI tracks buses: northern England and West Sussex.'
      parameters:
      - in: query
        name: route_id
        schema:
          type: string
      - description: National Operator Code
        e.g. FSYO: null
        in: query
        name: operator
        schema:
          type: string
      - description: Line name as on the bus
        e.g. 51: null
        in: query
        name: line
        schema:
          type: string
      - in: query
        name: days
        schema:
          default: 28
          type: integer
      responses:
        '200':
          description: Punctuality summary
        '404':
          description: No observations for that route or line
      summary: Bus punctuality by route or line
      tags:
      - Bus
      operationId: getV1BusReliabilityJson
      x-operation-id-source: derived
  /v1/bus/routes.json:
    get:
      parameters:
      - description: Line number or name, e.g. "36" or "X1"
        in: query
        name: q
        schema:
          type: string
      - description: Operator name or agency id
        in: query
        name: operator
        schema:
          type: string
      - description: Only routes calling at this stop
        in: query
        name: atcocode
        schema:
          type: string
      - in: query
        name: limit
        schema:
          default: 20
          type: integer
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      responses:
        '200':
          description: List of routes
        '400':
          description: No search criterion given
      summary: Find bus routes by line number, operator, or a stop they serve
      tags:
      - Bus
      operationId: getV1BusRoutesJson
      x-operation-id-source: derived
  /v1/bus/routes/{route_id}.json:
    get:
      description: 'A route id covers every journey run under one line number by one operator, including short workings and school journeys, so `representative_stops` is the longest single journey found rather than a union of them. `timetable` lists that day''s journeys in departure order; each carries a `trip_id` to look up with /v1/bus/services/{trip_id}.json.


        Each entry in `directions` carries a `shape`: the path those journeys actually take, as an encoded polyline (Google algorithm, precision 5) with its point count and length in metres. It is null where the operator publishes no geometry. Do not substitute a line drawn through `representative_stops` for it -- that cuts through buildings and down roads no bus can use.'
      parameters:
      - in: path
        name: route_id
        required: true
        schema:
          type: string
      - description: Service date (default today, UK local)
        in: query
        name: date
        schema:
          format: date
          type: string
      - in: query
        name: direction
        schema:
          enum:
          - 0
          - 1
          type: integer
      - description: Journeys per page of the timetable
        in: query
        name: limit
        schema:
          default: 50
          type: integer
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      responses:
        '200':
          description: Route detail
        '404':
          description: Route not found
      summary: A bus route's directions, stops and timetable for a day
      tags:
      - Bus
      operationId: getV1BusRoutes{routeId}Json
      x-operation-id-source: derived
  /v1/bus/services/{trip_id}.json:
    get:
      description: Answers "where does the 09:42 stop, and where has it got to?" for a single journey. `trip_id` is the value returned as `trip_id` (or `dated_vehicle_journey_ref`) on a stop timetable, or in a route's timetable. `live_vehicle` carries the tracked position and `current_stop_sequence` when a vehicle is working the journey right now, and is null otherwise - including for a journey later today, which has not set off and so has nothing to report.
      parameters:
      - in: path
        name: trip_id
        required: true
        schema:
          type: string
      - description: Service date the times are for (default today, UK local)
        in: query
        name: date
        schema:
          format: date
          type: string
      - description: Look up the live vehicle position for this journey
        in: query
        name: live
        schema:
          default: true
          type: boolean
      responses:
        '200':
          description: Service detail
        '404':
          description: Service not found
      summary: One scheduled journey - every stop it calls at, and where it is now
      tags:
      - Bus
      operationId: getV1BusServices{tripId}Json
      x-operation-id-source: derived
  /v1/bus/stop_reliability/{atcocode}.json:
    get:
      description: 'For each line calling at the stop, over the last `days` complete days (default 28, 7-35): observations, the share on time, early, late and very late, and the median and 90th-percentile delay. Measured where TransCAPI tracks buses: northern England and West Sussex since 4 August 2026, the rest of Great Britain since 30 September 2026.'
      parameters:
      - in: path
        name: atcocode
        required: true
        schema:
          type: string
      - in: query
        name: days
        schema:
          default: 28
          type: integer
      responses:
        '200':
          busiest first; empty if the stop has no observations: null
          description: One entry per line
      summary: Bus punctuality at a stop
      tags:
      - Bus
      operationId: getV1BusStopReliability{atcocode}Json
      x-operation-id-source: derived
  /v1/bus/stop_timetables/{atcocode}.json:
    get:
      parameters:
      - in: path
        name: atcocode
        required: true
        schema:
          type: string
      - description: ISO 8601 datetime to plan around (default now)
        in: query
        name: datetime
        schema:
          format: date-time
          type: string
      - description: Minutes from `datetime` to start the departure window
        in: query
        name: from_offset
        schema:
          default: 0
          type: integer
      - description: Minutes from `datetime` to end the departure window
        in: query
        name: to_offset
        schema:
          default: 60
          type: integer
      - in: query
        name: limit
        schema:
          default: 20
          type: integer
      - description: 'Also fetch live BODS SIRI-VM vehicle positions and match them to departures. Applies to departures only - the feed carries an origin departure time to match on, not an arrival time at this stop.

          '
        in: query
        name: live
        schema:
          default: false
          type: boolean
      - description: 'Which board to return. `arrivals` lists services terminating or calling here by the time they arrive, including those that terminate at this stop and so never appear as a departure.

          '
        in: query
        name: type
        schema:
          default: departures
          enum:
          - departures
          - arrivals
          - both
          type: string
      responses:
        '200':
          description: Stop timetable
        '404':
          description: Stop not found
      summary: Departures and arrivals for a bus stop, with expected times for tracked buses…
      tags:
      - Bus
      operationId: getV1BusStopTimetables{atcocode}Json
      x-operation-id-source: derived
  /v1/bus/stops.json:
    get:
      description: 'Roughly a third of stop names are shared by more than one stop, because a name describes a place and the two poles either side of a road are both at it. Three fields tell them apart. `towards` is the commonest destination of journeys calling there, derived from the timetable, and is the one a passenger can act on. `towards_next` is the first differently-named stop the bus calls at next, which separates the pairs that share a destination -- any circular route does. `bearing` is NaPTAN''s own compass direction and is the weakest of the three: opposite poles on one road are frequently given the same one.'
      parameters:
      - in: query
        name: lat
        schema:
          type: number
      - in: query
        name: lon
        schema:
          type: number
      - description: Search radius in metres (used with lat/lon)
        in: query
        name: radius
        schema:
          default: 400
          type: integer
      - in: query
        name: min_lat
        schema:
          type: number
      - in: query
        name: min_lon
        schema:
          type: number
      - in: query
        name: max_lat
        schema:
          type: number
      - in: query
        name: max_lon
        schema:
          type: number
      - in: query
        name: limit
        schema:
          default: 20
          type: integer
      - in: query
        name: page
        schema:
          default: 1
          type: integer
      - in: query
        name: type
        schema:
          items:
            enum:
            - bus_stop
            - train_station
            - tram_stop
            type: string
          type: array
      responses:
        '200':
          description: List of stops
      summary: Find bus/tram/rail stops near a location or within a bounding box
      tags:
      - Bus
      operationId: getV1BusStopsJson
      x-operation-id-source: derived
  /v1/bus/vehicles.json:
    get:
      description: Every bus reporting its position to BODS in the area, linked to its timetabled trip where the timetable holds it, so `trip_id` can be passed to /v1/bus/services/{trip_id}.json. `delay_seconds` is given where TransCAPI tracks the bus against its timetable (currently wherever the operator reports positions to BODS) and null elsewhere. Positions older than five minutes are left out.
      parameters:
      - in: query
        name: lat
        schema:
          type: number
      - in: query
        name: lon
        schema:
          type: number
      - description: Metres from lat/lon, up to 10000
        in: query
        name: radius
        schema:
          default: 1000
          type: integer
      - in: query
        name: min_lat
        schema:
          type: number
      - in: query
        name: min_lon
        schema:
          type: number
      - in: query
        name: max_lat
        schema:
          type: number
      - in: query
        name: max_lon
        schema:
          type: number
      - description: Line name, e.g. 52a (case-insensitive)
        in: query
        name: line
        schema:
          type: string
      - description: Operator code (NOC) or exact name
        in: query
        name: operator
        schema:
          type: string
      - in: query
        name: limit
        schema:
          default: 100
          type: integer
      responses:
        '200':
          description: Live vehicles
      summary: Live bus positions near a point or in a bounding box
      tags:
      - Bus
      operationId: getV1BusVehiclesJson
      x-operation-id-source: derived
components:
  securitySchemes:
    ApiKeyHeader:
      in: header
      name: X-Api-Key
      type: apiKey
    ApiKeyQuery:
      in: query
      name: api_key
      type: apiKey