Omnibus

Omnibus is a hybrid web service/node module that provides a clean API for accessing data on activities of the US Congress.

• Using Omnibus
  • Deploying as a web service
  • Using as an Express router
  • Requiring as a Node module
• API
  • Bills API
  • Congress API
  • Votes API
• Configuration

Using Omnibus

Omnibus is extremely versatile. It can be run as a standalone web service, incorporated as router into another Express app, or required as a node module and used through it's API directly. It can even run in the browser. Omnibus is in active development. If you'd like to see a specific endpoint added, open an issue, or better yet, a pull request.

Deploying as a web service

Omnibus includes a deployable Express application. The app exposes an HTTP interface that mirrors the JavaScript API. You can deploy the full application with a single line of JS (as long as you have a couple environment variables set up, as detailed below in configuration).

require( 'omnibus/app' ).launch();

Alternately, you can clone the repo and start it from the command line.

git clone https://github.com/omnibus-app/omnibus-backend
cd omnibus && npm start
curl -X GET localhost:3000/api/bills/113-hr2397

The web service includes optional support for a Redis cache that can be used to dramatically speed up the response time of repeated requests.

Using as an Express router

Omnibus provides direct access to its application router. This allows an existing Express application to incorporate the HTTP interface.

app.use( '/omnibus/', require( 'omnibus/router' ) );

Requiring as a Node module

Omnibus exposes a JavaScript API; simply require() the module.

var omnibus = require( 'omnibus' );
omnibus.bills( '113-HR2397' ).versions().then( /* etc */ );

It also works in the browser with Browserify. Yep, it's both a deployable web service and a client-side library.

API

Omnibus was initially developed as a RESTful web service. A typical URL might look like this

/bills/:id/version

In exposing the underlying JavaScript API, we sought to provide an interface similar to the REST routes.

// REST endpoint
bills/:id/version

// JS
omnibus.bills(id).version();

// REST endpoint
bills/search?q=searchString

// jS
omnibus.bills().search({q: 'searchString'});

All JS examples assume that Omnibus is available as var omnibus = require( 'omnibus' ). All methods return promises - Omnibus uses Bluebird interally. The REST endpoints assume that the router is serving at /api.

Configuration

Omnibus uses the New York Times Congress API and the Sunlight Congress API, which require API keys. You'll need to get keys and configure Omnibus with them before use.

When deploying as a web service you should make them available under process.env.NYT_CONGRESS_KEY and process.env.SUNLIGHT_CONGRESS_KEY respectively. When using the JavaScript API directly, you can set configuration parameters like so:

omnibus.config.set({
  'NYT_CONGRESS_KEY': 'your_nyt_key',
  'SUNLIGHT_CONGRESS_KEY': 'your_sunlight_key'
})

Bills API

The bills API supports methods/endpoints for amendments, general info, text search, subjects, versions, and votes.

Amendments

JavaScript

omnibus.bills(billId).amendments()

HTTP

/api/bills/:id/amendments

Details

JavaScript

omnibus.bills(billId).details()

HTTP

/api/bills/:id

Search

JavaScript

omnibus.bills().search({q: 'obamacare'});

HTTP

/api/bills?q=obamacare

Subjects

JavaScript

omnibus.bills(billId).subjects()

HTTP

/api/bills/:id/subjects

Versions

JavaScript

omnibus.bills(billId).versions()

HTTP

/api/bills/:id/versions

Votes

JavaScript

omnibus.bills(billId).votes()

HTTP

/api/bills/:id/votes

Congress API

The "id" associated with a given Congress is it's number. The current Congress is 113.

Enacted

JavaScript

omnibus.congress(id).enacted()

HTTP

/api/congress/:id/enacted

Votes API

By Month

The "id" associated with a given month is the month in YYYY-MM format.

JavaScript

omnibus.votes(id).month()

HTTP

/api/votes/:id