openapi: 3.0.1
info:
  title: umd.io bus API
  description: 'Welcome to umd.io, the open-source API for University of Maryland data. If you are building a University data-focused app, hack, or project, you’re in the right place. This site will walk you through basic API use and document all supported API calls.


    umd.io is a GETful API. It follows RESTful conventions, but for now, you can only get data – you can’t create, update, or destroy.


    We''re now in version 1! We might add new endpoints or more data to existing responses, but we won''t remove anything without a major version change.


    If you''re looking for the v0 docs, you can find them at https://docs.umd.io/. Please note that v0 is deprecated. It will continue to be supported until at least 2021, but will get no further feature updates, and will eventually be discontinued.


    We are actively looking for contributors! Tweet, email, or otherwise get in touch with us.'
  contact:
    email: hi@umd.io
  license:
    name: MIT
    url: https://github.com/umdio/umdio/blob/master/LICENSE
  version: 1.0.0 Beta
servers:
- url: https://api.umd.io/v1
tags:
- name: bus
  description: This endpoint lets you get data about bus routes, schedules, stops, locations, and predicted arrival times. The data is provided by NextBus, which monitors buses and gives the data to us via their API. We think our API is easier to use, but our data might be behind NextBus by a few seconds. If your app requires to-the-second bus location info, you can go right to the source. All bus data is copyright University of Maryland
paths:
  /bus/routes:
    get:
      tags:
      - bus
      summary: List routes
      description: Get a list of the available routes.
      operationId: getRoutes
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    route_id:
                      type: string
                    title:
                      type: string
  /bus/routes/{route_ids}:
    get:
      tags:
      - bus
      summary: View specific routes
      description: Get route data for one or more routes
      operationId: getRoutesById
      parameters:
      - in: path
        name: route_ids
        required: true
        schema:
          type: array
          items:
            type: string
        description: Route ids
        explode: true
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Route'
                  count:
                    type: number
                    description: Number of routes returned
                    example: 1
        '400':
          description: Malformed route code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown route code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /bus/stops:
    get:
      tags:
      - bus
      summary: List stops
      description: Get a list of the available stops.
      operationId: getStops
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    stop_id:
                      type: string
                    title:
                      type: string
  /bus/stops/{stop_ids}:
    get:
      tags:
      - bus
      summary: Get specific stops
      description: Get data for one or more stops
      operationId: getStopsById
      parameters:
      - in: path
        name: stop_ids
        required: true
        schema:
          type: array
          items:
            type: string
        description: Stop ids
        explode: true
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Stop'
                  count:
                    type: number
                    description: Number of routes returned
                    example: 1
        '400':
          description: Malformed route code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown route code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /bus/routes/{route_id}/locations:
    get:
      tags:
      - bus
      summary: Current bus locations by route
      description: Get bus locations for a route
      operationId: getLocations
      parameters:
      - in: path
        name: route_id
        required: true
        schema:
          type: string
        description: Route id
        explode: true
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                description: Bus location object
                properties:
                  lastTime:
                    type: object
                    properties:
                      time:
                        type: string
                        description: A unix timestamp
                        example: '1624045272049'
                  copyright:
                    type: string
        '400':
          description: Malformed route code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown route code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /bus/routes/{route_id}/schedules:
    get:
      tags:
      - bus
      summary: Bus schedules
      description: Get bus schedules for a route
      operationId: getSchedules
      parameters:
      - in: path
        name: route_id
        required: true
        schema:
          type: string
        description: Route id
        explode: true
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BusSchedule'
        '400':
          description: Malformed route code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown route code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /bus/routes/{route_id}/arrivals/{stop_id}:
    get:
      tags:
      - bus
      summary: Get arrivals for a stop for a route
      description: Get arrivals for a stop for a route
      operationId: getArrival
      parameters:
      - in: path
        name: route_id
        required: true
        schema:
          type: string
        description: Route id
        explode: true
      - in: path
        name: stop_id
        required: true
        schema:
          type: string
        description: Stop id
        explode: true
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  copyright:
                    type: string
                    example: All data copyright University of Maryland 2021.
                  predictions:
                    type: object
                    properties:
                      routeTag:
                        type: string
                        example: '104'
                      stopTag:
                        type: string
                        example: regdrgar_d
                      routeTitle:
                        type: string
                        example: 104 College Park Metro
                      agencyTitle:
                        type: string
                        example: University of Maryland
                      dirTitleBecauseNoPredictions:
                        type: string
                        example: College Park Metro
                      message:
                        type: array
                        items:
                          type: object
                          properties:
                            text:
                              type: string
                            priority:
                              type: string
                              example: Normal
        '400':
          description: Malformed route id or stop id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown route id or stop id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Route:
      type: object
      description: Bus route
      properties:
        route_id:
          type: string
          description: A unique three digit route number
          example: '701'
        title:
          type: string
          description: String name of the route
          example: 701 UMB BioPark
        stops:
          type: array
          description: Array of stops on the route
          items:
            $ref: '#/components/schemas/Stop'
        directions:
          type: array
          description: Array of directions the bus travels
          items:
            description: A direction for a bus route. Many buses only have one direction, ‘loop’ , which has all stops on the route. Otherwise, there are usually two directions, mostly named for the final stop in that direction.
            type: object
            properties:
              direction_id:
                type: string
                description: Unique (relative to the route) string titling the direction
                example: ramsapts
              title:
                type: string
                description: String name of the direction
                example: Ramsay St Apts
              stops:
                type: array
                description: Names of stops along the route
                items:
                  type: string
        paths:
          description: Lat/Long points to draw the route on a map
          type: array
          items:
            type: array
            items:
              type: object
              properties:
                lat:
                  type: number
                  format: float
                long:
                  type: number
                  format: float
        lat_max:
          type: number
          format: float
          example: 39.2995236
        lat_min:
          type: number
          format: float
          example: 39.28301
        long_max:
          type: number
          format: float
          example: -76.620848
        long_min:
          type: number
          format: float
          example: -76.6320545
    Stop:
      type: object
      description: Bus stop
      properties:
        stop_id:
          type: string
          description: Unique string identifier for a stop, should be mostly human-readable
          example: laplat
        title:
          type: string
          description: Full name of the stop
          example: La Plata Hall
        lat:
          type: number
          format: float
          description: Latitude
          example: -76.94563
        long:
          type: number
          format: float
          description: Longitude
          example: 38.9922185
    Error:
      type: object
      description: Represents an HTTP error
      properties:
        error_code:
          type: number
        message:
          type: string
        docs:
          type: string
    BusSchedule:
      type: object
      description: Each route has multiple schedules, because buses run differently on different days of the week
      properties:
        days:
          type: string
          description: The days the schedule runs
          example: f
        direction:
          type: string
          description: Direction id for the route. See Route object.
        route:
          type: string
          description: Route id
        stops:
          description: Scheduled stops on the route.
          type: array
          items:
            type: object
            properties:
              stop_id:
                type: string
                description: Stop id
                example: laplat
              name:
                type: string
                description: Full stop name
                example: La Plata Hall
        trips:
          description: Scheduled stops for the route, and when busses should be stopping there.
          type: array
          items:
            type: array
            items:
              type: object
              properties:
                stop_id:
                  type: string
                  description: Stop id. See Stop object
                arrival_time:
                  type: string
                  description: Arrival time, localized to hh:mm:ss in EST/EDT
                arrival_time_secs:
                  type: string
                  description: Time in ms from start of the day
externalDocs:
  description: Github
  url: https://github.com/umdio/umdio