Permalink
Browse files

update the README

  • Loading branch information...
JoshData committed Apr 8, 2013
1 parent f619d59 commit 8a49cf29572c5b5c81b34e9b47ededc8e42f3519
Showing with 66 additions and 45 deletions.
  1. +66 −45 README.md
View
111 README.md
@@ -42,65 +42,56 @@ Each legislator record is grouped into four guaranteed parts: id's which relate
bioguide: R000570
thomas: '01560'
govtrack: 400351
+ opensecrets: N00004357
name:
first: Paul
middle: D.
last: Ryan
bio:
+ birthday: '1970-01-29'
gender: M
terms:
+ ...
- type: rep
- start: '2011-01-05'
+ start: '2011-01-03'
end: '2013-01-03'
- state: WI
- district: 1
- party: Republican
- url: http://www.house.gov/ryan
- address: 1233 Longworth House Office Building; 20515-4901
+ ...
- type: rep
- start: '2009-01-06'
- end: '2010-12-22'
+ start: '2013-01-03'
+ end: '2015-01-03'
state: WI
- ...
-
-An optional fifth part, other_names, will list other names the legislator has gone by officially. This is helpful in cases where a Legislator's legal name has changed. These listings will only include the name attributes which differ from the current name, and a start or end date where applicable. An excerpted example:
-
- - id:
- bioguide: B001228
- thomas: '01465'
- govtrack: 400039
- opensecrets: N00007068
- votesmart: 1434
- name:
- first: Mary
- middle: Whitaker
- last: Bono Mack
- other_names:
- - last: Bono
- end: '2007-12-17'
- ...
-
-Where multiple names exist, other names are listed chronologically by end date.
-
+ party: Republican
+ district: 1
+ url: http://paulryan.house.gov
+ address: 1233 Longworth HOB; Washington DC 20515-4901
+ phone: 202-225-3031
+ fax: 202-225-3393
+ contact_form: http://www.house.gov/ryan/email.htm
+ office: 1233 Longworth House Office Building
+
+Terms correspond to elections and are listed in chronological order. If a legislator is currently serving, the current term information will always be the last one. To check if a legislator is currently serving, check that the end date on the last term is in the future.
+
The split between legislators-current.yaml and legislators-historical.yaml is somewhat arbitrary because these files may not be updated immediately when a legislator leaves office. If it matters to you, just load both files.
A separate file legislators-social-media.yaml stores social media account information. Its structure is similar but includes different fields.
Legislators Data Dictionary
---------------------------
-legislators-current.yaml and legislators-historical.yaml
+The following fields are available in legislators-current.yaml and legislators-historical.yaml:
* id
* bioguide: The alphanumeric ID for this legislator in http://bioguide.congress.gov. Note that at one time some legislators (women who had changed their name when they got married) had two entries on the bioguide website. Only one bioguide ID is included here.
* thomas: The numeric ID for this legislator on http://thomas.gov and http://beta.congress.gov. The ID is stored as a string with leading zeros preserved.
* lis: The alphanumeric ID for this legislator found in Senate roll call votes (http://www.senate.gov/pagelayout/legislative/a_three_sections_with_teasers/votes.htm).
- * govtrack: The numeric ID for this legislator on GovTrack.us.
+ * fec: A *list* of IDs for this legislator in Federal Election Commission data.
+ * govtrack: The numeric ID for this legislator on GovTrack.us (stored as an integer).
* opensecrets: The alphanumeric ID for this legislator on OpenSecrets.org.
- * votesmart: The numeric ID for this legislator on VoteSmart.org.
- * icpsr: The numeric ID for this legislator in Interuniversity Consortium for Political and Social Research databases.
- * cspan: The numeric ID for this legislator on C-SPAN's video website, e.g. http://www.c-spanvideo.org/person/1745.
+ * votesmart: The numeric ID for this legislator on VoteSmart.org (stored as an integer).
+ * icpsr: The numeric ID for this legislator in Keith Poole's VoteView.com website, originally based on an ID system by the Interuniversity Consortium for Political and Social Research (stored as an integer).
+ * cspan: The numeric ID for this legislator on C-SPAN's video website, e.g. http://www.c-spanvideo.org/person/1745 (stored as an integer).
* wikipedia: The Wikipedia page name for the person (spaces are given as spaces, not underscores).
+ * bioguide_previous: When bioguide.congress.gov mistakenly listed a legislator under multiple IDs, this field is a *list* of alternative IDs. (This often ocurred for women who changed their name.) The IDs in this list probably were removed from bioguide.congress.gov but might still be in use in the wild.
* name
* first: The legislator's first name. Sometimes a first initial and period (e.g. in W. Todd Akin), in which case it is suggested to not use the first name for display purposes.
@@ -110,25 +101,42 @@ legislators-current.yaml and legislators-historical.yaml
* nickname: The legislator's nick name when used as a common alternative to his first name.
* official_full: The full name of the legislator according to the House or Senate (usually first, middle initial, nickname, last, and suffix). Present for those serving on 2012-10-30 and later.
+* other_names, when present, lists other names the legislator has gone by officially. This is helpful in cases where a legislator's legal name has changed. These listings will only include the name attributes which differ from the current name, and a start or end date where applicable. Where multiple names exist, other names are listed chronologically by end date. An excerpted example:
+
+ - id:
+ bioguide: B001228
+ thomas: '01465'
+ govtrack: 400039
+ opensecrets: N00007068
+ name:
+ first: Mary
+ middle: Whitaker
+ last: Bono Mack
+ other_names:
+ - last: Bono
+ end: '2007-12-17'
+ ...
+
* bio
* birthday: The legislator's birthday, in YYYY-MM-DD format.
* gender: The legislator's gender, either "M" or "F".
* religion: The legislator's religion.
* terms (one entry for each election)
- * type: The type of the term. Either "sen" for senators or "rep" for representatives.
+ * type: The type of the term. Either "sen" for senators or "rep" for representatives and delegates to the House.
* start: The date the term began (i.e. typically a swearing in), in YYYY-MM-DD format. In contemporary data (>1940), it may be Jan. 3 on odd-numbered years or later if Congress does not meet immediately.
* end: The date the term ended (because the Congress ended, the legislator died or resigned, etc.). For Members of Congress that served their whole term, starting with the 112th Congress end dates follow the Constitutional end of a Congress, Jan. 3 on odd-numbered years (which is unfortunately the same date the next Congress begins), but prior to the 112th Congress end dates were set to the last date of adjournment of Congress. The end date is the last date on which the legislator served this term.
* state: The two-letter, uppercase USPS abbreviation for the state that the legislator is serving from. See below.
* district: For representatives, the district number they are serving from. At-large districts are district 0. In historical data, unknown district numbers are recorded as -1.
* class: For senators, their election class (1, 2, or 3). Note that this is unrelated to seniority.
- * party: The political party of the legislator. If the legislator changed parties, it is typically the most recent party held during the term.
+ * state_rank: For senators, whether they are the "junior" or "senior" senator (only valid if the term is current, otherwise the senator's rank at the time the term ended).
+ * party: The political party of the legislator. If the legislator changed parties, it is typically the most recent party held during the term. This is typically "Democrat", "Independent", or "Republican". The party reflects the partisan caucuses in Congress, and it may differ from the party listed on the ballot during the legislator's election.
* url: The official website URL of the legislator (only valid if the term is current).
- * address: The mailing address of the legislator's Washington, D.C. office (only valid if the term is current).
- * phone: The phone number of the legislator's Washington, D.C. office (only valid if the term is current).
- * fax: The fax number of the legislator's Washington, D.C. office (only valid if the term is current).
- * contact_form: The website URL of the contact page on the legislator's official website (only valid if the term is current).
- * office: Similar to the address field, this is just the room and building number, suitable for display (only valid if the term is current).
+ * address: The mailing address of the legislator's Washington, D.C. office (only valid if the term is current, otherwise the last known address).
+ * phone: The phone number of the legislator's Washington, D.C. office (only valid if the term is current, otherwise the last known number).
+ * fax: The fax number of the legislator's Washington, D.C. office (only valid if the term is current, otherwise the last known number).
+ * contact_form: The website URL of the contact page on the legislator's official website (only valid if the term is current, otherwise the last known URL).
+ * office: Similar to the address field, this is just the room and building number, suitable for display (only valid if the term is current, otherwise the last known office).
Except where noted, fields are omitted when their value is empty or unknown. Any field may be unknown.
@@ -157,9 +165,7 @@ All values can be turned into URLs by preceding them with the domain name of the
* `http://youtube.com/[username or channel value]`
* `http://facebook.com/[username or ID]`
-When a legislator leaves office, their social media account information is left in this file for historical preservation.
-
-The file is in lexical order by bioguide ID for convenience. Legislators are only present when they have one or more social media accounts known. Fields are omitted when the account is unknown.
+Legislators are only present when they have one or more social media accounts known. Fields are omitted when the account is unknown.
Committees Data Dictionary
--------------------------
@@ -234,7 +240,22 @@ Each committee/subcommittee entry is a list containing the members of the commit
* party: Either "majority" or "minority." Committee work is divided strictly by party.
* rank: The apparent rank of the member on the committee, within his or her party. This is based on the order of names on the House/Senate committee membership pages. Rank 1 is always for the committee chair or ranking member (the most senior minority party member). The rank is essentially approximate, because the House/Senate pages don't necessarily make a committment that the order on the page precisely indicates actual rank (if such a concept even applies). But if you want to preserve the order as displayed by the House and Senate, you can use this attribute.
* title: The title of the member on the committee, e.g. Chair, Ranking Member, or Ex Officio. This field is not normalized, however, so be prepared to accept any string.
-
+
+The Executive Branch
+--------------------
+
+Because of their role in the legislative process, we also include a file executive.yaml which contains terms served by U.S. presidents (who signed legislation) and U.S. vice presidents (who are nominally the president of the Senate and occassionally cast tie-breaking votes there).
+
+This file has a similar structure as the legislator files. The file contains a list, where each entry is a person. Each entry is a dict with id, name, bio, and terms fields. The id, bio, and name fields are the same as those listed above. Each term has the following fields:
+
+* type: either "prez" (a presidential term) or "viceprez" (a vice presidential term).
+* start: The start date of the term. In modern times, typically January 20 following an election year.
+* end: The end date of the term. In modern times, typically January 20 following an election year.
+* party: The political party from which the person was elected.
+* how: How the term came to be, either "election" (the normal case), "succession" (presidential succession), or "appointment" (the appointment by the president of a new vice president).
+
+Presidents and vice presidents that previously served in Congress will also be listed in one of the legislator files, but their Congressional terms will only appear in the legislator files and their executive-branch terms will only appear in executive.yaml.
+
State Abbreviations
-------------------

0 comments on commit 8a49cf2

Please sign in to comment.