OC API Documentation 
OpenCongress API Documentation
Welcome. This API provides programmers with structured access to all the data on OpenCongress, everything from official bill info to news and blog coverage to user-generated votes on bills and much more. As an open-source public resource on Congress, we encourage developers to share and remix any of this info on their own websites to keep their online communities up-to-date with their political interests.
Using the API requires an API KEY, which is automatically assigned to every free "My OpenCongress" account -- simply join or login, it takes less than a minute, and your key will appear here, along with sample links to call. The data below is just a start -- we will continually add more unique info & useful enhancements in order to contribute public knowledge about Congress back to the data commons on the open Web. We're always interested in hearing requests or seeing use cases of how you're using this API -- see the Developer Resources at the bottom of this page.
You are not logged in. The API requires an API KEY, which would be displayed here and in the sample links if you were logged in.
People API
The people API is used to query the system for individuals, or groups of people matching given criteria. The following describes the parameters that can be used.
- First Name (first_name)
-
Specify the first name of the person
http://www.opencongress.org/api/people?first_name=John&key= - Last Name (last_name)
-
Specify the last name of the person
http://www.opencongress.org/api/people?last_name=Kerry&key= - OpenCongress ID (person_id)
-
Specify the id of the person
http://www.opencongress.org/api/people?id=300056&key= - Gender (gender)
-
Specify the gender of the person, either 'M' or 'F'
http://www.opencongress.org/api/people?gender=M&last_name=Kennedy&key= - State (state)
-
Specify the two letter state of the person
http://www.opencongress.org/api/people?first_name=John&state=AZ&key= - District (district)
-
Specify the congressional district of the person
http://www.opencongress.org/api/people?district=1&state=FL&key= - Party (party)
-
Specify the political party of the person, either 'Republican', 'Democrat', or 'Independent'
http://www.opencongress.org/api/people?party=Republican&state=FL&key= - User Approval Range (user_approval_from, user_approval_to)
-
Specify an average OpenCongress user approval rating range (0.0 to 10.0)
http://www.opencongress.org/api/people?user_approval_from=5.0&user_approval_to=10.0&key= - Senators most in the news this week
- http://www.opencongress.org/api/senators_most_in_the_news_this_week?key=
- Representatives most in the news this week
- http://www.opencongress.org/api/representatives_most_in_the_news_this_week?key=
- Most blogged Senators this week
- http://www.opencongress.org/api/most_blogged_senators_this_week?key=
- Most blogged Representatives this week
- http://www.opencongress.org/api/most_blogged_representatives_this_week?key=
- Compare Two People
- Specify the ID's of two people to compare, and receive XML of their roll call vote comparisons.
http://www.opencongress.org/person/compare.xml?person1=300001&person2=300013&key= - People Approved of by Open Congress Users are Also
-
Returns bills, representatives, and senators supported and opposed by users's approving of a given person.
http://www.opencongress.org/api/opencongress_users_supporting_person_are_also/300060?key= - People Disapproved of by Open Congress Users are Also
-
Returns bills, representatives, and senators supported and opposed by users's disapproving of a given person.
http://www.opencongress.org/api/opencongress_users_opposing_person_are_also/300060?key= - Open Congress Users tracking person are also tracking
-
Returns bills, people, and issues commonly tracked by people tracking a given person.
http://www.opencongress.org/api/opencongress_users_tracking_person_are_also_tracking/300060?key=
Bills API
The Bills API is used to query OpenCongress for bills matching given criteria. The following describes the functions and parameters that can be used.
- Bills by session of congress
-
Returns bills matching the given congress.
http://www.opencongress.org/api/bills?congress=111&key= - Bills by type
-
Returns bills matching the given type. Type can be: h (house),
s (senate), hj (house joint resolution), sj (senate joint resolution), hc (house concurrent resolution)
sc (senate concurrent resolution), hr (house resolution), sr (senate resolution)
http://www.opencongress.org/api/bills?type=h&congress=111&key= - Bills by number
-
Returns bills matching the given number.
http://www.opencongress.org/api/bills?number=5749&type=h&congress=111&key= - Bills by ident
-
Returns bills matching the given OpenCongress identification strings.
http://www.opencongress.org/api/bills_by_ident?ident[]=110-s1178&ident[]=110-s239&key= - Bills Introduced Since
-
Returns bills that were introduced since the supplied date (30 at a time).
http://www.opencongress.org/api/bills_introduced_since?date=Jan 30th, 2009&key= - Bills by Query
-
Returns bills matching a text query.
http://www.opencongress.org/api/bills_by_query?key=&q=Global Poverty Act of 2007 - Hot Bills
-
Returns bills that OpenCongress editors feel are "hot".
http://www.opencongress.org/api/hot_bills?key= - Most Blogged Bills this Week
-
Returns the most bills most blogged about this week.
http://www.opencongress.org/api/most_blogged_bills_this_week?key= - Bills Most in the News this Week
-
Returns the most bills most reported on by news agencies this week.
http://www.opencongress.org/api/bills_in_the_news_this_week?key= - Most Tracked Bills this Week
-
Returns the most bills most tracked by OpenCongress Users this week.
http://www.opencongress.org/api/most_tracked_bills_this_week?key= - Most Supported Bills this Week
-
Returns the most bills most supported by OpenCongress Users this week.
http://www.opencongress.org/api/most_supported_bills_this_week?key= - Most Opposed Bills this Week
-
Returns the most bills most opposed by OpenCongress Users this week.
http://www.opencongress.org/api/most_opposed_bills_this_week?key= - Bills Supported by Open Congress Users are Also
-
Returns bills, representatives, and senators supported and opposed by users's supporting a given bill.
http://www.opencongress.org/api/opencongress_users_supporting_bill_are_also/111-s1?key= - Bills Opposed by Open Congress Users are Also
-
Returns bills, representatives, and senators supported and opposed by users's opposing a given bill.
http://www.opencongress.org/api/opencongress_users_opposing_bill_are_also/111-s1?key= - Open Congress Users tracking bill are also tracking
-
Returns bills, people, and issues commonly tracked by people tracking a given bill.
http://www.opencongress.org/api/opencongress_users_tracking_bill_are_also_tracking/111-s1?key=
Roll Calls
- Roll Calls by Bills
-
Returns the roll calls for a given list of bills.
http://www.opencongress.org/api/bill_roll_calls?bill_id[]=51865&bill_id[]=51868&key=
Issues
- Issues by Keyword
-
Specify a Keyword, and receive an array of issue areas that match the keyword.
http://www.opencongress.org/api/issues_by_keyword?keyword=Privacy&key=
Wiki APIs
- OpenCongress Semantic MediaWiki API
-
Here is the API for query strings on wiki data, as well as help with writing query language. We'll be doing more extensive documentation of how to use Semantic MediaWiki and the data available through this API soon.
http://www.opencongress.org/wiki/Special:Ask - Semantic MediaWiki Data
-
Here is the page to retrieve all the data on the OpenCongress Wiki, including a simpler query string format. Further documentation of data offerings to come.
http://www.opencongress.org/wiki/Special:GetData
Battle Royale
The Battle Royale API shows 30 bills, people, or issues based on the query you provide. The easiest way to construct a query is to simply visit the Battle Royale with a browser, browse to the data you'd want to extract, and click the "XML" button. You can also build queries from the following information.
All Battle Royale queries take the following parameters:
| Parameter | Possible Values | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| timeframe |
|
||||||||||
| page |
|
||||||||||
| order |
|
Bill Queries support the following parameters:
| Parameter | Possible Values | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| sort |
|
Senator and Representative Queries support the following parameters:
| Parameter | Possible Values | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| sort |
|
Issue Queries support the following parameters:
| Parameter | Possible Values | ||||||
|---|---|---|---|---|---|---|---|
| sort |
|
Sample Battle Royale Queries:
- Bills, 30 days, sorted by total comments descending
-
Specify a Keyword, and receive an array of issue areas that match the keyword.
http://www.opencongress.org/battle_royale.xml?key=&order=desc&page=1&sort=total_comments&timeframe=30days - Bills, 30 days, sorted by total users tracking descending
-
Specify a Keyword, and receive an array of issue areas that match the keyword.
http://www.opencongress.org/battle_royale.xml?key=&order=desc&page=1&sort=bookmark_count_1&timeframe=30days - Representatives, 5 days, sorted by total users tracking descending
-
Specify a Keyword, and receive an array of issue areas that match the keyword.
http://www.opencongress.org/battle_royale/representatives.xml?key=&order=desc&page=1&sort=bookmark_count_1&timeframe=5days - Senators, 1 year, sorted by average approval rating descending
-
Specify a Keyword, and receive an array of issue areas that match the keyword.
http://www.opencongress.org/battle_royale/senators.xml?key=&order=desc&page=1&sort=p_approval_avg&timeframe=1year - Issues, 30 days, sorted by total users tracking descending
-
Specify a Keyword, and receive an array of issue areas that match the keyword.
http://www.opencongress.org/battle_royale/issues.xml?key=&order=desc&page=1&sort=bookmark_count_1&timeframe=30days
OpenCongress Developer Resources
- To ask questions about the API, suggest enhancements, report bugs, or let us know how you're using data from our API, send us an email:
- To sign up for general site updates over e-mail: OpenCongress mailing list (low-volume, major announcements only).
- To subscribe to updates via RSS: Blog RSS feed.
- To sign up for detailed programming updates over e-mail: Site development list-serv.
- To join an associated Google Group: Sunlight Labs, Sunlight Wiki
- To chat with our open-source development team over IRC: #opencongress on irc.freenode.net.
- To check out our site code: GitHub page
- To file a bug report, interface improvement, data source, or feature suggestion: Trac project homepage.