Drumbone_API / Bill

Deprecation Notice

This API is deprecated in favor of the Real Time Congress API. It contains most legislative information that Drumbone does. Drumbone may be deactivated in the near future.

Introduction

Bills and resolutions in the United States Congress. There are two methods available:

  • bill - Returns one bill document, referenced by bill ID.
  • bills - Returns multiple bills, paginated, filtered, and ordered by various parameters.

Important: Use of this data is subject to GovTrack's bulk data license, and this data's accuracy and recency is tied to GovTrack's.

You can see exactly where Drumbone's data on H.R. 4872 comes from, for example, by viewing h4872.xml on GovTrack.

Timestamp Issue

The dates for bills in Drumbone, such as the date a bill was introduced at, should really just be dates, with no times associated with them. Most events here are designated in THOMAS as on that day, not to a time in it. Unfortunately, the timestamps in the API include a time. To avoid inaccuracy, these timestamps are set as having happened at noon UTC, so that they happen on the same day throughout the world. A v2 of the Drumbone API will include removing the time portion of these timestamps.

Types of Bills

There are 8 types of bills:

  • hr - House bills ("H.R.")
  • hres - House resolutions ("H.Res")
  • hjres - House joint resolutions ("H.J.Res")
  • hcres - House concurrent resolutions ("H.C.Res")
  • s - Senate bills ("S.")
  • sres - Senate resolutions ("S.Res")
  • sjres - Senate joint resolutions ("S.J.Res")
  • scres - Senate concurrent resolutions ("S.C.Res")

If you're trying to separate bills or laws from resolutions, it should be noted that House and Senate joint resolutions are actually laws, and are signed by the President. The sole exception is constitutional amendments, which are joint resolutions that are not submitted to the President. The Senate glossary does a good job of explaining these, and other, terms.

Note: GovTrack uses different bill type identifiers. In the same order as the list above, GovTrack's types are "h", "hr", "hj", "hc", "s", "sr", "sj", and "sc". Keep this in mind if you're trying to cross reference Drumbone's data with GovTrack's. Drumbone's type identifiers are designed to be easily obtained from the formal prefix to a bill (e.g. "H.J.Res" => "hjres").

Bill ID

The only unique key for a bill is contained in the field "bill_id". Bill IDs are a combination of the type of bill, the bill number, and the session of Congress a bill was introduced in.

They are of the format: [type][number]-[session]

For example, H.R. 4173 from the 111th Congress would be "hr4173-111".

Filtering keys

  • session - Get bills from a particular session of Congress (i.e. "111" for the 111th Congress)
  • chamber - Get bills from a particular chamber of Congress - accepts only "house" or "senate", and is case sensitive)
  • sponsor_id - Provide a legislator's bioguide_id to find bills sponsored by that legislator.
  • cosponsor_ids - Provide a legislator's bioguide_id to find bills cosponsored by that legislator.
  • enacted - true or false - whether the bill has been enacted into law.

You'll probably want to give at least a session parameter as a filter.

Ordering keys

  • introduced_at - When the bill was introduced.
  • enacted_at - When the bill became law. (can be null)
  • last_vote_at - When the bill last was voted upon. (can be null)
  • last_action_at - When the bill last was acted upon. (can be null)

Sections

basic
bill_id
The bill ID as described above.
type
One of the 8 types of bills as described above.
number
Just the "number" part of the bill. So for H.R. 3200, this would be "3200".
session
The session of Congress. For the 111th Congress, this would be "111".
state
The state of the bill, as reported by GovTrack.
short_title
The most recent short title of the bill, if one exists.
official_title
The most recent official title of the bill.
sponsor_id
The bioguide ID of the sponsor of the bill.
cosponsors_count
The number of cosponsors of the bill.
last_action_at
The date of the most recent action in the "actions" section.
votes_count
The number of votes in the "votes" section.
last_vote_at
The date of the most recent vote in the "votes" section.
last_updated
When the bill was last updated.

There are a number of flags and timestamps related to the bill's state and history.

introduced_at
When the bill was introduced.
house_result
"pass", "fail", or null. The result of the most recent passage vote in the House (not including veto overrides).
house_result_at
If house_result is "pass" or "fail", this is the time that it happened.
senate_result
"pass", "fail", or null. The result of the most recent passage vote in the Senate (not including veto overrides).
senate_result_at
If senate_result is "pass" or "fail", this is the time that it happened.
passed
true or false. Whether the House and Senate have both passed the bill. *Note*: this doesn't mean the House and Senate both passed the same _version_ of the bill. It may still need to be worked out in conference before the president signs it.
passed_at
If passed is true, this is the time it became so.
vetoed
true or false. Whether the President has vetoed the bill.
vetoed_at
If vetoed is true, this is the time it became so.
override_house_result
"pass", "fail", or null. The result of the most recent veto override vote in the House.
override_house_result_at
If override_house_result is "pass" or "fail", this is the time that it happened.
override_senate_result
"pass", "fail", or null. The result of the most recent veto override vote in the Senate.
override_senate_result_at
If override_senate_result is "pass" or "fail", this is the time that it happened.
awaiting_signature
true or false. Whether or not the bill has been presented to the President, but neither signed nor vetoed.
awaiting_signature_since
If awaiting_signature is true, this is the time it became so.
enacted
true or false. Whether or not the bill is law.
enacted_at
If enacted is true, this is the time it became so.
votes

An array of information about each passage vote on the bill. Includes both voice and roll call votes.

NOTE: There are limitations to this field, that are very important to understand. The votes in this field correspond to the <vote> elements in GovTrack's XML. These capture both voice votes and roll call votes on passage of legislation, and do not capture procedural votes. However, they do not currently capture certain important votes, where one chamber is agreeing to amendments by another chamber (the so-called "ping pong" process). See the data for H.R. 3590 for an important example of this.

Each vote object has the following fields:

result
"pass" or "fail"
voted_at
The date the vote took place.
text
The text in the official record describing the vote.
how
"roll" for a roll call vote. Anything else ("by voice vote", "unanimous consent", etc.) means a voice vote, for which no roll call was taken.
type
"vote", "vote2", or "vote-aux". "vote2" means it's the second chamber voting on a piece of legislation, and its presence (with a result of "pass") is what dictates the value of whether a bill is considered "passed" in the basic fields. "vote-aux" means it's a vote on a conference report.
chamber
"house" or "senate"
roll_id
If the vote is a roll call, this is the roll_id necessary to look up more information about it in Drumbone.
actions

An array of action objects describing the history of a bill.

text
The text in the official record describing the action.
acted_at
The date this action took place.
type
The type of action this is. There are many, but most actions are simply of type "action".
last_action

A special section with just the most recent action on a bill. The fields are identical to those in the "actions" section.

titles

An array of all short and official titles that have ever been assigned to this bill. Each object has the following fields:

title
The title itself
type
"short", "official", or "popular"
as
Under what conditions this title was assigned. Examples: "introduced", "passed house", "passed senate".
sponsor

A subset of the "basic" fields of the legislator sponsoring the legislation. Includes title, first_name, nickname, last_name, name_suffix, district, state, party, bioguide_id, and govtrack_id.

cosponsors

An array of objects with a subset of basic fields of the legislators cosponsoring the legislation. Each object has the same fields as "sponsor" above.

cosponsor_ids

An array of bioguide_ids for the legislators cosponsoring the legislation, if any exist.

summary

The official CRS summary for a bill, if one exists.

keywords

The official set of keywords for a bill. There are many, and they get specific. Examples include "HIV-AIDS", "Health programs administration and funding", "Income tax rates", etc.

Full Example