mattcone/bus-o-matic

A simple Ruby wrapper for the Pittsburgh Port Authority API

Bus-o-matic

Bus-o-matic is a simple Ruby wrapper for the Pittsburgh Port Authority API. It allows you to retrieve real-time information about vehicles, routes, stops, and predicted arrival times for buses in Pittsburgh, Pennsylvania. This gem borrows heavily from cta-api by Frank Bonetti.

Installation

Add this line to your application's Gemfile:

gem 'bus-o-matic'

Setup

Before using Bus-o-matic, you'll need to request an API key from the Port Authority. Require the gem and add your Port Authority API key. This can be put in an initializer.

require 'bus-o-matic'

key = "xxxxxxxxxxxxxxxxxxxx"
PIT::Busomatic.key = key

Usage

The following examples illustrate how you can use Bus-o-matic.

Routes and Stops

Bus-o-matic can list all of the routes available. You can also get the directions for a particular route, and a list of all the stops on a route.

# Retrieve a list of all available routes
PIT::Busomatic.routes

# Retrieve the available directions for the specified route (INBOUND, OUTBOUND, etc.)
PIT::Busomatic.directions :rt => 16

# Retrieve the stops for Route 16 heading Inbound
PIT::Busomatic.stops :rt => 16, :dir => :INBOUND

Note that the available directions (INBOUND, etc.) appear to be case sensitive.

Patterns

Bus-o-matic can retrieve a set of geo-positional points for a route, something known as a "pattern." Patterns can be used to outline routes on maps.

# Retrieve the pattern for Route 16
PIT::Busomatic.patterns :rt => 16

Vehicles

Bus-o-matic can find all of the vehicles that are currently active on a route, or retrieve information about a specific vehicle. The first step is finding the active vehicles on a route.

# Returns an array of vehicles that are active on Route 16.
PIT::Busomatic.vehicles :rt => 16

You can retrieve information for vehicles on more than one route. Up to 10 routes can be specified at once.

# Returns an array of vehicles that are active on Routes 13, 16, and 17.
PIT::Busomatic.vehicles :rt => ["16","17","13"]

You can also find information about one or more vehicles that are currently active. Up to 10 vehicle IDs can be specified at once.

# Returns information about a specific vehicle.
PIT::Busomatic.vehicles :vid => 6013

# Returns information about multiple vehicles.
PIT::Busomatic.vehicles :vid => ["6013","6001"]

Note that you cannot combine both the rt and vid parameters in a single request.

Predicted Arrival Times

Bus-o-matic can return predicted arrival times for one or more buses. Up to 10 vehicle IDs can be specified at once. Note that you cannot combine both vid and stpid parameters in a single request.

# Returns predictions for a single vehicle.
PIT::Busomatic.predictions :vid => 5629

# Returns predictions for multiple vehicles. 
PIT::Busomatic.predictions :vid => ["5629","5604"]

You can also retrieve predictions for one or more stops. Up to 10 stop IDs can be specified at once. You can combine the stpid and rt parameters, as shown below.

# Returns predictions for all buses on all applicable routes for single stop.
PIT::Busomatic.predictions :stpid => 1326

# Returns predictions for multiple stops.
PIT::Busomatic.predictions :stpid => ["1326","18320","18563"]

# Returns predictions for all buses on Route 16 for a single stop 
PIT::Busomatic.predictions :stpid => 1326, :rt => 16

# Returns predictions for buses on Routes 13, 16, and 17 for Stop 1326.
PIT::Busomatic.predictions :stpid => 1326, :rt => ["13","16","17"]

System Time

Returns the official Port Authority API system time.

PIT::Busomatic.time

Contributing

I'd appreciate you reporting issues or creating pull requests.

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

License

The MIT License (MIT). See the LICENSE.txt file for details.