nyt-congress-node

Node wrapper for NYT Congress API. REST API Docs.

Usage

  var Congress = require( 'nyt-congress-node' );
  var client = new Congress( API_KEY );

  client.billDetails({
    billId: 'HR2397',
  }).then( function ( res ) {
    console.log( res );
  });

This package works in the browser. To generate a version that will provide a Congress browser global, go to the project root and run (assuming you have browserify installed globally):

browserify -s Congress ./ > congress-browser.js

Fair warning: the standalone, browserified pacakage is pretty darn big.

nyt-congress-node is a straight-forward wrapper around the New York Times Congress API. The Times' developer site has comprehensive documentation as well as example results for each query.

Internally, nyt-congress-node uses string interpolation on the API endpoints detailed in the API documentation. For example, the bill details endpoint has a url structure as follows

http://api.nytimes.com/svc/politics/{version}/us/legislative/congress/{congress-number}/bills/{bill-id}[.response-format]?api-key={your-API-key}

A valid request needs to fill in this URL with the following parameters: version, congress-number, bill-id, response-format, and an api-key.

Of these, only bill-id is required. The API key must be passed to the constructor and is automatically added to every request. congress-number defaults to 113 (the current congress), and response-format defaults to JSON.

Each method takes a parameters object, which it "dasherizes" (turns the keys from camelCase to dash-case), then interpolates these values into the string.

The example at the top

  var Congress = require( 'nyt-congress-node' );
  var client = new Congress( 'API_KEY' );

  client.billDetails({
    'bill-id': 'HR2397',
  }).then( function ( res ) {
    console.log( res );
  });

will dispatch a request to the following URL:

http://api.nytimes.com/svc/politics/v3/us/legislative/congress/113/bills/HR2397.json?api-key=API_KEY

Every method returns a promise.

API

• Bills

  • billDetails
  • billSubjects
  • billAmendments
  • billRelatedBills
  • billCosponsors

• Members

  • memberLists
  • memberBioAndRoles
  • membersNew
  • membersCurrentByStateOrDistrict
  • membersLeavingOffice
  • memberVotePositions
  • memberVoteComparison
  • memberCosponsoredBills
  • memberSponsorshipComparison
  • memberFloorAppearances

• Nominees

  • nomineeLists
  • nomineeDetails
  • nomineesByState

• Other

  • statePartyCounts
  • committeeList
  • committeeRoster
  • chamberSchedule

• Votes

  • votesRollCall
  • votesByType
  • votesByDate
  • votesNominations

Bills

.billsRecent()

Endpoint documentation: Recent bills

Parameters:

- congressNumber
- chamber
- billType

.billsByMember()

Endpoint documentation: Bills by member

Parameters:

- memberId
- billType

billDetails()

Endpoint documentation: Bill details

Parameters:

- congressNumber
- billId

billSubjects()

Endpoint documentation: Bill subjects, amendments, and related bills with resource set to "subjects"

Parameters:

- congressNumber
- billId

billAmendments()

Endpoint documentation: Bill subjects, amendments, and related bills with resource set to "amendment"

Parameters:

- congressNumber
- billId

billRelatedBills()

Endpoint documentation: Bill subjects, amendments, and related bills with resource set to "related"

Parameters:

- congressNumber
- billId

billCosponsors()

Endpoint documentation: Bill cosponsors

Parameters:

- congressNumber
- billId

Members

memberLists()

Endpoint documentation: Member lists

Parameters:

- congressNumber
- chamber

memberBioAndRoles()

Endpoint documentation: Member bio and roles

Parameters:

- memberId

membersNew()

Endpoint documentation: New members

Parameters:

- _None_

membersCurrentByStateOrDistrict()

Endpoint documentation: Current members by state/district

Parameters:

- chamber
- state
- district

membersLeavingOffice()

Endpoint documentation: Members leaving office

Parameters:

- congressNumber

memberVotePositions()

Endpoint documentation: Member vote positions

Parameters:

- memberId

memberVoteComparison()

Endpoint documentation: Member vote comparison

Parameters:

- memberId1
- memberId2
- congressNumber
- chamber

memberCosponsoredBills()

Endpoint documentation: Bills cosponsored by a member

Parameters:

- memberId
- cosponsorType

memberSponsorshipComparison()

Endpoint documentation: Member cosponsorship comparison

Parameters:

- memberId1
- memberId2
- congressNumber
- chamber

memberFloorAppearances()

Endpoint documentation: Member floor appearances

Parameters:

- memberId

Nominees

nomineeLists()

Endpoint documentation: Nominee lists

Parameters:

- congressNumber
- nominationCategory

nomineeDetails()

Endpoint documentation: Nominee details

Parameters:

- congressNumber
- nomineeId

nomineesByState()

Endpoint documentation: Nominees by state

Parameters:

- congressNumber
- state

Other

statePartyCounts()

Endpoint documentation: State party counts

Parameters:

- _NONE_

committeeList()

Endpoint documentation: Committees and committee members but doesn't accept a committee id

Parameters:

- congressNumber
- chamber

committeeRoster()

Endpoint documentation: Committees and committee members but requires a committee id

Parameters:

- congressNumber
- chamber
- committeeId

chamberSchedule()

Endpoint documentation: Chamber schedule

Parameters:

- chamber

Votes

votesRollCall()

Endpoint documentation: Roll-call votes

Parameters:

- congressNumber
- chamber
- sessionNumber
- rollCallNumber

votesByType()

Endpoint documentation: Votes by type

Parameters:

- congressNumber
- chamber
- voteType

votesByDate()

Endpoint documentation: Votes by date

Parameters:

- chamber
- year
- month

votesNominations()

Endpoint documentation: nominationVotes

Parameters:

- congressNumber

Parameter Validation

nyt-congress-node validates all parameters passed to methods. Generally, parameter strings are checked with contains, alphanumeric, numeric, and date. Contains checks if a value is in a pre-set list. Each parameter will also accept the camelCased version of it's key.

'bill-id': alphanumeric
'bill-type': contains // => ['introduced', 'updated', 'passed', 'major']
'chamber': contains // => ['house', 'senate']
'committee-id': alphanumeric,
'congress-number': contains // => [105, 106, 107, 108, 109, 110, 111, 112, 113]
'cosponsor-type': contains // => ['cosponsored', 'withdrawn']
'district': numeric
'end-date': date
'member-id': alphanumeric
'member-id-2': alphanumeric
'member-id-1': alphanumeric
'nomination-category': contains // => ['received', 'updated', 'confirmed', 'withdrawn']
'nominee-id': alphanumeric
'resource': contains // => ['subjects', 'amendments', 'related'] ),
'response-format': contains // => ['.json', '.xml']
'roll-call-number': numeric
'session-number': numeric
'start-date': date
'state': contains // => ['AL', 'AK', 'AZ', 'AR', 'CA', 'CO', 'CT', 'DE', 'FL', 'GA', 'HI', 'ID', 'IL', 'IN', 'IA', 'KS', 'KY', 'LA', 'ME', 'MD', 'MA', 'MI', 'MN', 'MS', 'MO', 'MT', 'NE', 'NV', 'NH', 'NJ', 'NM', 'NY', 'NC', 'ND', 'OH', 'OK', 'OR', 'PA', 'RI', 'SC', 'SD', 'TN', 'TX', 'UT', 'VT', 'VA', 'WA', 'WV', 'WI', 'WY']
'vote-type': contains // => ['missed_votes', 'party_votes', 'loneno', 'perfect'] ),
'version': // => must be v3
'year': numeric
'month': numeric