Bus

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 2015.

Bus Endpoint

https://api.umd.io/v0/bus

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 2015.

Bus Endpoint

https://api.umd.io/v0/bus

List routes

List all the bus routes. Returns the route ids and the names of the routes.


https://api.umd.io/v0/bus/routes

Returns: Array of the bus routes as JSON Objects with ‘route_id’ and ‘title’ fields.

Sample Request

GET https://api.umd.io/v0/bus/routes

Trimmed Response:

[
  {
    "route_id": "109",
    "title": "109 River Road"
  },
  {
    "route_id":"114",
    "title": "University View"
  },
  {
    "route_id":"115",
    "title": "115 Orange"
  }
]

List all the bus routes. Returns the route ids and the names of the routes.


https://api.umd.io/v0/bus/routes

Returns: Array of the bus routes as JSON Objects with ‘route_id’ and ‘title’ fields.

Sample Request

GET https://api.umd.io/v0/bus/routes

Trimmed Response:

[
  {
    "route_id": "109",
    "title": "109 River Road"
  },
  {
    "route_id":"114",
    "title": "University View"
  },
  {
    "route_id":"115",
    "title": "115 Orange"
  }
]

The route object

The route object represents a bus route. The properties of a route are:

route_id – a unique three digit route number. Examples: “115”, “701”.

title – string name of the route. Examples: “115 Orange”, “701 UMB BioPark”

stops – Array of bus stops on a route. Stops have a unique string stop_id, a full title, and lon (longitude) and lat (latitude) coordinates. Routes have a lot of stops, so this might look a little messy.

directions – Array of directions the bus travels. A direction has a unique string direction_id, a title, and an array of stops specifying the stops along the route in that direction. 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.

paths – When you want to draw the route on the map, you use the paths. These are several arrays (an array of arrays) of latitude and longitude coordinates (points). According to NextBus, connect the points in array separately, and you will end up with a nice outline of the route. Don’t try to connect the points between the arrays of points, because they won’t match up. There are a lot of points (a few hundred) for each route.

The next four are useful if you are trying to fit the route in a map window.

lat_max – Maximum latitude of the bus route.

lat_min – Minimum latitude of the bus route.

lon_max – Maximum longitude of the bus route.

lon_min – Minimum longitude of the bus route.

Sample route object (trimmed for space - there are more stops and path data)

  {"route_id":"115",
  "title":"115 Orange",
  "stops":
  [

    {"stop_id":"lot1",
    "title":"Union Dr at Lot 1b",
    "lon":"-76.9481576",
    "lat":"38.9872099"},

    {"stop_id":"cspac",
    "title":"Valley Drive at Stadium Drive Garage",
    "lon":"-76.949374",
    "lat":"38.990882"},
  ],
  "directions":[{
    "direction_id":"loop",
    "title":"Loop",
    "stops":["lot1",
      "cspac",
      "elk",
      "hage",
      "laplat",
      "camb",
      "regegara_d"]
    }],
  "paths":[
  [
    {"lon":"-76.9432099","lat":"38.98756"},
    {"lon":"-76.943614","lat":"38.987555"},
    {"lon":"-76.943945","lat":"38.9876099"}
  ],
  [
    {"lon":"-76.93915","lat":"38.98243"},
    {"lon":"-76.93908","lat":"38.9824"},
    {"lon":"-76.93877","lat":"38.98232"},
    {"lon":"-76.93867","lat":"38.9823"},
    {"lon":"-76.93855","lat":"38.98228"},
    {"lon":"-76.93838","lat":"38.98225"},
    {"lon":"-76.93818","lat":"38.9822"},
    {"lon":"-76.93797","lat":"38.98215"},
    {"lon":"-76.93791","lat":"38.98216"},
    {"lon":"-76.93787","lat":"38.9822"},
    {"lon":"-76.93786","lat":"38.9822599"}]
  ],
  "lat_max":"38.99297",
  "lat_min":"38.9824312",
  "lon_max":"-76.9370967",
  "lon_min":"-76.949374"
  }

The route object represents a bus route. The properties of a route are:

route_id – a unique three digit route number. Examples: “115”, “701”.

title – string name of the route. Examples: “115 Orange”, “701 UMB BioPark”

stops – Array of bus stops on a route. Stops have a unique string stop_id, a full title, and lon (longitude) and lat (latitude) coordinates. Routes have a lot of stops, so this might look a little messy.

directions – Array of directions the bus travels. A direction has a unique string direction_id, a title, and an array of stops specifying the stops along the route in that direction. 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.

paths – When you want to draw the route on the map, you use the paths. These are several arrays (an array of arrays) of latitude and longitude coordinates (points). According to NextBus, connect the points in array separately, and you will end up with a nice outline of the route. Don’t try to connect the points between the arrays of points, because they won’t match up. There are a lot of points (a few hundred) for each route.

The next four are useful if you are trying to fit the route in a map window.

lat_max – Maximum latitude of the bus route.

lat_min – Minimum latitude of the bus route.

lon_max – Maximum longitude of the bus route.

lon_min – Minimum longitude of the bus route.

Sample route object (trimmed for space - there are more stops and path data)

  {"route_id":"115",
  "title":"115 Orange",
  "stops":
  [

    {"stop_id":"lot1",
    "title":"Union Dr at Lot 1b",
    "lon":"-76.9481576",
    "lat":"38.9872099"},

    {"stop_id":"cspac",
    "title":"Valley Drive at Stadium Drive Garage",
    "lon":"-76.949374",
    "lat":"38.990882"},
  ],
  "directions":[{
    "direction_id":"loop",
    "title":"Loop",
    "stops":["lot1",
      "cspac",
      "elk",
      "hage",
      "laplat",
      "camb",
      "regegara_d"]
    }],
  "paths":[
  [
    {"lon":"-76.9432099","lat":"38.98756"},
    {"lon":"-76.943614","lat":"38.987555"},
    {"lon":"-76.943945","lat":"38.9876099"}
  ],
  [
    {"lon":"-76.93915","lat":"38.98243"},
    {"lon":"-76.93908","lat":"38.9824"},
    {"lon":"-76.93877","lat":"38.98232"},
    {"lon":"-76.93867","lat":"38.9823"},
    {"lon":"-76.93855","lat":"38.98228"},
    {"lon":"-76.93838","lat":"38.98225"},
    {"lon":"-76.93818","lat":"38.9822"},
    {"lon":"-76.93797","lat":"38.98215"},
    {"lon":"-76.93791","lat":"38.98216"},
    {"lon":"-76.93787","lat":"38.9822"},
    {"lon":"-76.93786","lat":"38.9822599"}]
  ],
  "lat_max":"38.99297",
  "lat_min":"38.9824312",
  "lon_max":"-76.9370967",
  "lon_min":"-76.949374"
  }

Get routes

Get detailed info about one or more bus routes.


https://api.umd.io/v0/bus/routes/<route_id>

Returns: Specified route object.


https://api.umd.io/v0/bus/routes/<route_ids>

Returns: Specified route objects, where route_ids is a comma-separated list of route_ids, like 115,118,701.

Sample Request

GET https://api.umd.io/v0/bus/routes/115

Trimmed Response:

{
  "route_id": "701",
  "title": "701 UMB BioPark",
  "stops": [],
  "directions": [
    {
      "direction_id": "peargara",
      "title": "Pearl St Garage",
      "stops": []
    },
    {
      "direction_id": "ramsapts",
      "title": "Ramsay St Apts",
      "stops": []
    }
  ],
  "paths": [],
  "lat_max": "39.2995236",
  "lat_min": "39.28301",
  "lon_max": "-76.620848",
  "lon_min": "-76.6320545"
}

Get detailed info about one or more bus routes.


https://api.umd.io/v0/bus/routes/<route_id>

Returns: Specified route object.


https://api.umd.io/v0/bus/routes/<route_ids>

Returns: Specified route objects, where route_ids is a comma-separated list of route_ids, like 115,118,701.

Sample Request

GET https://api.umd.io/v0/bus/routes/115

Trimmed Response:

{
  "route_id": "701",
  "title": "701 UMB BioPark",
  "stops": [],
  "directions": [
    {
      "direction_id": "peargara",
      "title": "Pearl St Garage",
      "stops": []
    },
    {
      "direction_id": "ramsapts",
      "title": "Ramsay St Apts",
      "stops": []
    }
  ],
  "paths": [],
  "lat_max": "39.2995236",
  "lat_min": "39.28301",
  "lon_max": "-76.620848",
  "lon_min": "-76.6320545"
}

Stop object

The stop object represents a bus stop.

It has

stop_id – unique string identifier for a stop, like ‘laplat’. NextBus came up with these names, and most of the time, you can decipher what stop they mean. ‘laplat’ is the Laplata Hall stop. ‘guilrowa_out’ is Guilford Drive and Rowalt Drive (Outbound).

title – the full name of the stop.

lon – longitude of the stop

lat – latitude of the stop

Sample Object

  {
  "stop_id": "laplat",
  "title": "La Plata Hall",
  "lon": "-76.94563",
  "lat": "38.9922185"
}

The stop object represents a bus stop.

It has

stop_id – unique string identifier for a stop, like ‘laplat’. NextBus came up with these names, and most of the time, you can decipher what stop they mean. ‘laplat’ is the Laplata Hall stop. ‘guilrowa_out’ is Guilford Drive and Rowalt Drive (Outbound).

title – the full name of the stop.

lon – longitude of the stop

lat – latitude of the stop

Sample Object

  {
  "stop_id": "laplat",
  "title": "La Plata Hall",
  "lon": "-76.94563",
  "lat": "38.9922185"
}

List stops

Get information about all the stops.

Endpoint: https://api.umd.io/v0/bus/stops

Returns: Array of stops with stop_id and title.

Sample Request

GET https://api.umd.io/v0/bus/stops

Trimmed Response:

  [
{
"stop_id": "laplat",
"title": "La Plata Hall"
},
{
"stop_id": "camb",
"title": "Cambridge Hall"
},
{
"stop_id": "guilrowa_out",
"title": "Guilford Drive and Rowalt Drive (Outbound)"
},
{
"stop_id": "guilhart",
"title": "Guilford Drive and Hartwick Road"
},
{
"stop_id": "mowaprei",
"title": "Mowatt Lane and Preinkert Drive"
},
{
"stop_id": "mowagara",
"title": "Mowatt Lane Garage"
},
{
"stop_id": "vanmunch",
"title": "Van Munching Hall (Outbound)"
}
]

Get information about all the stops.

Endpoint: https://api.umd.io/v0/bus/stops

Returns: Array of stops with stop_id and title.

Sample Request

GET https://api.umd.io/v0/bus/stops

Trimmed Response:

  [
{
"stop_id": "laplat",
"title": "La Plata Hall"
},
{
"stop_id": "camb",
"title": "Cambridge Hall"
},
{
"stop_id": "guilrowa_out",
"title": "Guilford Drive and Rowalt Drive (Outbound)"
},
{
"stop_id": "guilhart",
"title": "Guilford Drive and Hartwick Road"
},
{
"stop_id": "mowaprei",
"title": "Mowatt Lane and Preinkert Drive"
},
{
"stop_id": "mowagara",
"title": "Mowatt Lane Garage"
},
{
"stop_id": "vanmunch",
"title": "Van Munching Hall (Outbound)"
}
]

Get stops

Get full information about a stop.

Endpoint: https://api.umd.io/v0/bus/stops/:stop_id

Returns: Stop object as specified.

Sample Request

GET https://api.umd.io/v0/bus/stops/stamsu_d

Trimmed Response:

 [
{
"stop_id": "laplat",
"title": "La Plata Hall",
"lon": "-76.94563",
"lat": "38.9922185"
}
]

Get full information about a stop.

Endpoint: https://api.umd.io/v0/bus/stops/:stop_id

Returns: Stop object as specified.

Sample Request

GET https://api.umd.io/v0/bus/stops/stamsu_d

Trimmed Response:

 [
{
"stop_id": "laplat",
"title": "La Plata Hall",
"lon": "-76.94563",
"lat": "38.9922185"
}
]

Get bus locations

Get locations of all the umd buses.


https://api.umd.io/v0/bus/locations

Returns: Object with several properties - meta information and the list of locations for vehicles.

Sample Request

GET https://api.umd.io/v0/bus/locations

Trimmed Response:

{
"vehicle": [
{
"id": "66",
"lon": "-76.61603",
"routeTag": "702",
"predictable": "true",
"speedKmHr": "3",
"dirTag": "charpenn",
"heading": "106",
"lat": "39.28906",
"secsSinceReport": "4"
},
{
"id": "76",
"lon": "-76.9323299",
"routeTag": "122",
"predictable": "true",
"speedKmHr": "37",
"dirTag": "leoncomm",
"heading": "319",
"lat": "38.9839399",
"secsSinceReport": "15"
}],
"lastTime": {
"time": "1428715950117"
},
"copyright": "All data copyright University of Maryland 2015.",
"Error": {
"content": "last time \"t\" parameter must be specified in query string",
"shouldRetry": "false"
}
}

Get locations of all the umd buses.


https://api.umd.io/v0/bus/locations

Returns: Object with several properties - meta information and the list of locations for vehicles.

Sample Request

GET https://api.umd.io/v0/bus/locations

Trimmed Response:

{
"vehicle": [
{
"id": "66",
"lon": "-76.61603",
"routeTag": "702",
"predictable": "true",
"speedKmHr": "3",
"dirTag": "charpenn",
"heading": "106",
"lat": "39.28906",
"secsSinceReport": "4"
},
{
"id": "76",
"lon": "-76.9323299",
"routeTag": "122",
"predictable": "true",
"speedKmHr": "37",
"dirTag": "leoncomm",
"heading": "319",
"lat": "38.9839399",
"secsSinceReport": "15"
}],
"lastTime": {
"time": "1428715950117"
},
"copyright": "All data copyright University of Maryland 2015.",
"Error": {
"content": "last time \"t\" parameter must be specified in query string",
"shouldRetry": "false"
}
}

Locate buses on a route

Get the locations of buses along a bus route.

Route Locations endpoint: https://api.umd.io/v0/bus/routes/:route_id/locations

Returns: Predicted arrivals for a stop on the route.

Sample Request

GET https://api.umd.io/v0/bus/routes/115/locations

Trimmed Response:

  {
"vehicle": [
{
"id": "36",
"lon": "-76.94308",
"routeTag": "115",
"predictable": "true",
"speedKmHr": "7",
"dirTag": "loop",
"heading": "268",
"lat": "38.98756",
"secsSinceReport": "18"
},
{
"id": "31",
"lon": "-76.94943",
"routeTag": "115",
"predictable": "true",
"speedKmHr": "22",
"dirTag": "loop",
"heading": "0",
"lat": "38.99115",
"secsSinceReport": "6"
},
{
"id": "33",
"lon": "-76.9401199",
"routeTag": "115",
"predictable": "true",
"speedKmHr": "5",
"dirTag": "loop",
"heading": "177",
"lat": "38.98465",
"secsSinceReport": "2"
}
],
"lastTime": {
"time": "1428718998722"
},
"copyright": "All data copyright University of Maryland 2015.",
"Error": {
"content": "last time \"t\" parameter must be specified in query string",
"shouldRetry": "false"
}
}

Get the locations of buses along a bus route.

Route Locations endpoint: https://api.umd.io/v0/bus/routes/:route_id/locations

Returns: Predicted arrivals for a stop on the route.

Sample Request

GET https://api.umd.io/v0/bus/routes/115/locations

Trimmed Response:

  {
"vehicle": [
{
"id": "36",
"lon": "-76.94308",
"routeTag": "115",
"predictable": "true",
"speedKmHr": "7",
"dirTag": "loop",
"heading": "268",
"lat": "38.98756",
"secsSinceReport": "18"
},
{
"id": "31",
"lon": "-76.94943",
"routeTag": "115",
"predictable": "true",
"speedKmHr": "22",
"dirTag": "loop",
"heading": "0",
"lat": "38.99115",
"secsSinceReport": "6"
},
{
"id": "33",
"lon": "-76.9401199",
"routeTag": "115",
"predictable": "true",
"speedKmHr": "5",
"dirTag": "loop",
"heading": "177",
"lat": "38.98465",
"secsSinceReport": "2"
}
],
"lastTime": {
"time": "1428718998722"
},
"copyright": "All data copyright University of Maryland 2015.",
"Error": {
"content": "last time \"t\" parameter must be specified in query string",
"shouldRetry": "false"
}
}

Get predicted arrivals

Get the predicted arrivals for a particular stop on a route.

Arrivals endpoint: https://api.umd.io/v0/bus/routes/:route_id/arrivals/:stop_id

Returns: Predicted arrivals for a stop on the route.

Sample Request

GET https://api.umd.io/v0/bus/routes/701/arrivals/greefaye

Trimmed Response:

{
  "predictions": {
    "agencyTitle": "University of Maryland",
    "routeTag": "701",
    "routeTitle": "701 UMB BioPark",
    "direction": {
      "title": "Ramsay St Apts",
      "prediction": [
        {
        "isDeparture": "false",
        "minutes": "3",
        "seconds": "194",
        "vehicle": "66",
        "affectedByLayover": "true",
        "block": "7011",
        "dirTag": "ramsapts",
        "epochTime": "1428953061631"
        },
        {
        "isDeparture": "false",
        "minutes": "42",
        "seconds": "2523",
        "vehicle": "66",
        "affectedByLayover": "true",
        "block": "7011",
        "dirTag": "ramsapts",
        "epochTime": "1428955390195"
        },
        {
        "isDeparture": "false",
        "minutes": "82",
        "seconds": "4923",
        "vehicle": "66",
        "affectedByLayover": "true",
        "block": "7011",
        "dirTag": "ramsapts",
        "epochTime": "1428957790195"
        }
      ]
    },
    "stopTitle": "Green St & Fayette St",
    "stopTag": "greefaye"
  },
"copyright": "All data copyright University of Maryland 2015."
}

Get the predicted arrivals for a particular stop on a route.

Arrivals endpoint: https://api.umd.io/v0/bus/routes/:route_id/arrivals/:stop_id

Returns: Predicted arrivals for a stop on the route.

Sample Request

GET https://api.umd.io/v0/bus/routes/701/arrivals/greefaye

Trimmed Response:

{
  "predictions": {
    "agencyTitle": "University of Maryland",
    "routeTag": "701",
    "routeTitle": "701 UMB BioPark",
    "direction": {
      "title": "Ramsay St Apts",
      "prediction": [
        {
        "isDeparture": "false",
        "minutes": "3",
        "seconds": "194",
        "vehicle": "66",
        "affectedByLayover": "true",
        "block": "7011",
        "dirTag": "ramsapts",
        "epochTime": "1428953061631"
        },
        {
        "isDeparture": "false",
        "minutes": "42",
        "seconds": "2523",
        "vehicle": "66",
        "affectedByLayover": "true",
        "block": "7011",
        "dirTag": "ramsapts",
        "epochTime": "1428955390195"
        },
        {
        "isDeparture": "false",
        "minutes": "82",
        "seconds": "4923",
        "vehicle": "66",
        "affectedByLayover": "true",
        "block": "7011",
        "dirTag": "ramsapts",
        "epochTime": "1428957790195"
        }
      ]
    },
    "stopTitle": "Green St & Fayette St",
    "stopTag": "greefaye"
  },
"copyright": "All data copyright University of Maryland 2015."
}

Get route schedules

Get the schedules for a route.

Each route has multiple schedules, because buses run differently on different days of the week. umdio can’t guarantee that the buses will arrive at the scheduled times, but we’ll try to get the schedules to you.


https://api.umd.io/v0/bus/routes/:route_id/schedules

Returns: Array of bus schedules for the specified route.

Each schedule has the days that schedule runs - ‘f’ for friday, ‘th’ for tuesday and thursday. Also, the direction of the route, route number, an array of the stops on the schedule, and an array of trips. The stops on the schedule are not all of the stops on the route, just the ones that are scheduled. The trips are each arrays of stops and the times the bus is scheduled to stop, in two formats: arrival_time, which is the ISO 8601 extended time format - hh:mm:ss - and a count of UNIX seconds since the beginning of the day - a number like 21600000, for 6:00 AM. All times are EST, since that’s local.

Sample Request

GET https://api.umd.io/v0/bus/routes/115/schedules

Trimmed Response:

[{
  "days":"f",
  "direction":"ramsapts",
  "route":"701",
  "stops":[{
    "stop_id":"peargara_d",
    "name":"Pearl St Garage"}],
  "trips":[[{
    "stop_id":"peargara_d",
    "arrival_time":"06:00:00",
    "arrival_time_secs":"21600000"}],
    [{"stop_id":"peargara_d",
    "arrival_time":"06:32:00",
    "arrival_time_secs":"23520000"}],
    [{"stop_id":"peargara_d",
    "arrival_time":"07:04:00",
    "arrival_time_secs":"25440000"}],
    [{"stop_id":"peargara_d",
    "arrival_time":"07:38:00",
    "arrival_time_secs":"27480000"}]]
}]

Get the schedules for a route.

Each route has multiple schedules, because buses run differently on different days of the week. umdio can’t guarantee that the buses will arrive at the scheduled times, but we’ll try to get the schedules to you.


https://api.umd.io/v0/bus/routes/:route_id/schedules

Returns: Array of bus schedules for the specified route.

Each schedule has the days that schedule runs - ‘f’ for friday, ‘th’ for tuesday and thursday. Also, the direction of the route, route number, an array of the stops on the schedule, and an array of trips. The stops on the schedule are not all of the stops on the route, just the ones that are scheduled. The trips are each arrays of stops and the times the bus is scheduled to stop, in two formats: arrival_time, which is the ISO 8601 extended time format - hh:mm:ss - and a count of UNIX seconds since the beginning of the day - a number like 21600000, for 6:00 AM. All times are EST, since that’s local.

Sample Request

GET https://api.umd.io/v0/bus/routes/115/schedules

Trimmed Response:

[{
  "days":"f",
  "direction":"ramsapts",
  "route":"701",
  "stops":[{
    "stop_id":"peargara_d",
    "name":"Pearl St Garage"}],
  "trips":[[{
    "stop_id":"peargara_d",
    "arrival_time":"06:00:00",
    "arrival_time_secs":"21600000"}],
    [{"stop_id":"peargara_d",
    "arrival_time":"06:32:00",
    "arrival_time_secs":"23520000"}],
    [{"stop_id":"peargara_d",
    "arrival_time":"07:04:00",
    "arrival_time_secs":"25440000"}],
    [{"stop_id":"peargara_d",
    "arrival_time":"07:38:00",
    "arrival_time_secs":"27480000"}]]
}]