The Associated Press client

Retrieving data

The AP client is public class you can use to connect to the AP’s data feed.

client.get_state(state_postal_code)

Takes a single state postal code, returns that state’s results.

>>> from elections import AP
>>> client = AP(USERNAME, PASSWORD)
>>> client.get_state('IA')
<State: IA>
client.get_states(*state_postal_codes)

Takes one to many state postal codes as arguments, returns a list of results for the requested states.

>>> from elections import AP
>>> client = AP(USERNAME, PASSWORD)
>>> client.get_states('IA', 'NH')
[<State: IA>, <State: NH>]
client.get_topofticket(election_date)

Top of the ticket is an AP data service that provides limited results on the top races for all 50 states (i.e. President, Governor, US Senate, and US House). It requires a date in any common format, YYYY-MM-DD is preferred, and returns all results for that date.

If you do not provide a date, it defaults to the next major election. Today that is the Nov. 6, 2012 general election.

>>> from elections import AP
>>> client = AP(USERNAME, PASSWORD)
>>> client.get_topofticket('2012-02-07')
<TopOfTicket: 20120207>
client.get_presidential_summary(districts=False)

Returns a summary of presidential election results at three levels: nationwide popular vote and electoral vote; state-level popular vote and electoral vote; county-level popular vote.

If districts is provided and set to True the results will include Congressional district-level results in the two states that break out their presidential electors: Maine and Nebraska. This feature only works if the AP has given your account access to the ME and NE data folders. By default, districts is set to False.

>>> from elections import AP
>>> client = AP(USERNAME, PASSWORD)
>>> client.get_presidential_summary()
<PresidentialSummary: None>
client.get_delegate_summary()

Return a nationwide summary and state-level totals contain delegate counts for all the candidates in the presidential nomination contest held by the two major parties.

Warning: This method does not currently work because the 2012 primaries are over and the AP has removed the folders it depends on.

>>> from elections import AP
>>> client = AP(USERNAME, PASSWORD)
>>> client.documents.get_delegate_summary()
[<Nomination: Dem>, <Nomination: GOP>]

Election result collections

Depending on which client method you use to harvest data, results may be returned as State or TopOfTicket objects. Don’t worry about the distinction, because they act pretty much the same. They share the following attributes for you to use.

obj.counties

Returns a list of all the counties from the pool of reporting units.

>>> obj = client.get_state('IA')
>>> obj.counties
[<ReportingUnit: Guthrie>, <ReportingUnit: Union>, <ReportingUnit: Crawford>, <ReportingUnit: Wright>, <ReportingUnit: Tama>, <ReportingUnit: Hamilton>, <ReportingUnit: Worth>, <ReportingUnit: Hancock>, <ReportingUnit: Cherokee>, <ReportingUnit: Carroll>, <ReportingUnit: Webster>, <ReportingUnit: Clarke>, ...]
obj.filter_races(**kwargs)

Takes a series of keyword arguments and returns any races that match.

>>> obj = client.get_state('IA')
>>> obj.filter_races(office_name='President', party='GOP')
[<Race: GOP Caucus - President>]
obj.races

Returns a list of all the races reporting results.

>>> obj = client.get_state('IA')
>>> obj.races
[<Race: GOP Caucus - President>]
obj.reporting_units

Returns a list of all reporting units in the result collection.

>>> obj = client.get_state("IA")
>>> obj.reporting_units
[<ReportingUnit: Guthrie>, <ReportingUnit: Union>, <ReportingUnit: Crawford>, <ReportingUnit: Wright>, <ReportingUnit: Tama>, <ReportingUnit: Hamilton>, <ReportingUnit: Worth>, <ReportingUnit: Hancock>, <ReportingUnit: Cherokee>, <ReportingUnit: Carroll>, <ReportingUnit: Webster>, <ReportingUnit: Clarke>, ...]
obj.states

Returns a list of all the states from the pool of reporting units. Only available on TopOfTicket result collections.

>>> obj = client.get_topofticket('2012-02-07')
>>> obj.states
[<ReportingUnit: Missouri (state)>, <ReportingUnit: Minnesota (state)>, <ReportingUnit: Colorado (state)>]

Races

A contest being decided by voters choosing between candidates. This object is the key to everything about it. It is often found in the races attribute of a result collection.

obj.ap_race_number

AP-assigned race number. Race numbers are guaranteed to be unique only within a state.

>>> obj.ap_race_number
'16957'
obj.candidates

The list of candidates participating in the race.

>>> obj.candidates
[<Candidate: Michele Bachmann>, <Candidate: Herman Cain>, <Candidate: Newt Gingrich>, <Candidate: Jon Huntsman>, <Candidate: No Preference>, <Candidate: Other>, <Candidate: Ron Paul>, <Candidate: Rick Perry>, <Candidate: Buddy Roemer>, <Candidate: Mitt Romney>, <Candidate: Rick Santorum>]
obj.counties

Returns all the counties that report results for this race as a list.

>>> obj.counties
[<ReportingUnit: Adair>, <ReportingUnit: Adams>, <ReportingUnit: Allamakee>, <ReportingUnit: Appanoose>, <ReportingUnit: Audubon>, <ReportingUnit: Benton>, <ReportingUnit: Black Hawk>, <ReportingUnit: Boone>, <ReportingUnit: Bremer>, <ReportingUnit: Buchanan>, ...
obj.date

The date of the election in Python’s datetime format.

>>> obj.date
datetime.date(2012, 1, 3)
obj.is_primary

Returns True if the race is a primary.

obj.is_caucus

Returns True if the race is a caucus.

obj.is_general

Returns True if the race is part of a general election.

obj.name

The name of the race.

>>> obj.name
'GOP Caucus - President'
obj.num_winners

Integer giving the maximum number of winners.

>>> obj.num_winners
1
obj.office_name

Character string for office name (e.g., U.S. House, Governor, etc.)

>>> obj.office_name
'President'
obj.office_description

Character string further describing the office type. May be empty.

obj.office_id

Single character Office Type ID. Only top-of-the-ticket races (President, Governor, US Senate, and US House) are guaranteed to be unique on a national level. All other office types are guaranteed to be unique only within a state. A full list of the office identifiers can be found in AP’s documentation.

obj.party

Name of party to which race applies, i.e., GOP if a Republican Primary.

obj.race_type_name

Returns a descriptive name for the race_type.

>>> obj.race_type_name
'GOP Caucus'
obj.reporting_units

Returns all reporting units that belong to this race as a list.

>>> obj.reporting_units
[<ReportingUnit: Guthrie>, <ReportingUnit: Union>, <ReportingUnit: Crawford>, <ReportingUnit: Wright>, <ReportingUnit: Tama>, <ReportingUnit: Hamilton>, <ReportingUnit: Worth>, <ReportingUnit: Hancock>, <ReportingUnit: Cherokee>, <ReportingUnit: Carroll>, ...
obj.scope

Office scope – whether the race is a Local (L) or Statewide (S) race

>>> obj.scope
'S'
obj.state

Returns the state-level results for this race as a ReportingUnit object.

>>> obj.state
<ReportingUnit: Iowa (state)>
obj.seat_name

Character string giving the district or initiative name (e.g., District 46, 1A-Gay Marriage, etc.) This may be empty for a statewide race (e.g., a Governor race).

obj.seat_number

Integer indicating district number or an initiative number. This may be zero (0) for a statewide race.

obj.state_postal

Two character state postal string (e.g., IA, LA, etc.).

self.uncontested

Returns True is the race is uncontested.

self.is_referendum

Returns True if this is a race where the people vote to decide about a law, measure, proposition, amendment, etc.

Reporting units

An area or unit that groups votes into a total. For instance, a state, a congressional district, a county.

obj.abbrev

Short Name of reporting unit

>>> obj.abbrev
'Poweshiek'
obj.ap_number

Unique ID within a state for reporting unit.

>>> obj.ap_number
'16079'
obj.name

The full name of the reporting unit

>>> obj.name
'Poweshiek'
obj.fips

The unique FIPS code for this reporting unit, assigned by the U.S. government.

>>> obj.fips
'19157'
obj.num_reg_voters

The number of registered votes who live in this reporting unit.

>>> obj.num_reg_voters
3897
obj.votes_cast

The number of votes cast in this reporting unit.

>>> obj.votes_cast
709
obj.precincts_total

The number of voting precincts in this reporting unit.

>>> obj.precincts_total
10
obj.precincts_reporting

The number of precincts that have already provided results.

>>> obj.precincts_reporting
10
obj.precincts_reporting_percent

The percentage of precincts that have already provided results.

>>> obj.precincts_reporting_percent
100.0
obj.results

Returns a list of result objects sorted by total votes (highest first). If no votes are in, it returns the candidates in alphabetical order.

>>> obj.results
[<Result: Rick Santorum, Iowa (state), 29839>, <Result: Mitt Romney, Iowa (state), 29805>, <Result: Ron Paul, Iowa (state), 26036>, <Result: Newt Gingrich, Iowa (state), 16163>, <Result: Rick Perry, Iowa (state), 12557>, <Result: Michele Bachmann, Iowa (state), 6046>, <Result: Jon Huntsman, Iowa (state), 739>, <Result: No Preference, Iowa (state), 147>, <Result: Other, Iowa (state), 107>, <Result: Herman Cain, Iowa (state), 45>, <Result: Buddy Roemer, Iowa (state), 17>]
obj.is_state

Returns True if the reporting unit is a state, rather than some other unit like a county.

obj.electoral_votes_total

Returns the number of presidential electors this area controls. Typically only found on states.

Candidates

A choice for voters in a race. In the presidential race, a person, like Barack Obama. In a ballot measure, a direction, like Yes or No.

obj.abbrev_name

Candidate’s abbreviated name, usually last name with some vowels removed if too long.

>>> obj.abbrev_name
'Bchmnn'
obj.ap_natl_number

Unique ID to identify this politician across states and races.

>>> obj.ap_natl_number
'302'
obj.ap_pol_number

Unique ID within a state for this candidate.

>>> obj.ap_pol_number
'18538'
obj.ap_polra_number

Unique ID within a state for this candidate for this race for their party.

>>> obj.ap_polra_number
'21304'
obj.ap_race_number

Unique ID within a state for the race object this candidate object is linked to.

>>> obj.ap_race_number
'16957'
obj.delegates

The number of delegates the candidate has won in this state, according to AP’s estimates. Warning: AP has told The Times that it stops updating these totals after they decide a race has “closed” following the election. That means that if you want to track changes to these totals between the vote and the eventual nomination, you should use the nationwide delegate methods detailed below.

>>> obj.delegates
0
obj.first_name

The first name of the candidate.

>>> obj.first_name
'Michele'
obj.is_incumbent

Returns True if the candidate is the current officeholder.

obj.is_winner

Returns True if the candidate has won the race.

obj.is_runoff

Returns True is the candidate is advancing to a runoff.

obj.last_name

The last name of the candidate.

>>> obj.last_name
'Bachmann'
obj.middle_name

The middle name of the candidate. Might not always exist.

>>> obj.middle_name
'J.'
obj.name

The full name of candidate.

>>> obj.name
u'Michele Bachmann'
obj.party

Candidate’s party abbreviation.

>>> obj.party
'GOP'
obj.suffix

The suffix to the candidate’s name. Might not exist.

>>> obj.suffix
'Jr.'
obj.use_suffix

Returns True if you should use the suffix with the name.

Result

The vote count for a candidate in a race in a particular reporting unit.

obj.candidate

The candidate this result is for.

>>> obj.candidate
<Candidate: Rick Santorum>
obj.reporting_unit

The reporting unit this result is for.

>>> obj.reporting_unit
<ReportingUnit: Iowa (state)>
obj.vote_total

The number of votes the candidate has collected in this reporting unit.

>>> obj.vote_total
29839
obj.vote_total_percent

The percentage of the tpta; votes the candidate has collected in this reporting unit.

>>> obj.vote_total_percent
24.558645607855077
obj.electoral_votes_total

Returns the number of presidential electors awarded by this result.

Presidential summary collections

Calling presidential methods, like get_presidential_summary will return a slightly different, and simpler, result collection.

obj.nationwide

Returns only the nationwide reporting unit.

>>> obj.nationwide
<ReportingUnit: US>
obj.states

Returns only the state-level reporting units

>>> obj.states
[<ReportingUnit: South Carolina (state)>, <ReportingUnit: North Carolina (state)>, <ReportingUnit: Delaware (state)>, <ReportingUnit: Florida (state)>, <ReportingUnit: District of Columbia (state)>, <ReportingUnit: Indiana (state)>, <ReportingUnit: New Mexico (state)>, <ReportingUnit: Washington (state)>, <ReportingUnit: Oregon (state)>, <ReportingUnit: New Hampshire (state)>, <ReportingUnit: Nebraska (state)>, <ReportingUnit: North Dakota (state)>, ...]
obj.counties

Returns only the county-level reporting units

>>> obj.counties
[<ReportingUnit: Abbeville>, <ReportingUnit: Aiken>, <ReportingUnit: Allendale>, <ReportingUnit: Anderson>, <ReportingUnit: Bamberg>, <ReportingUnit: Barnwell>, <ReportingUnit: Beaufort>, <ReportingUnit: Berkeley>, <ReportingUnit: Calhoun>, <ReportingUnit: Charleston>, <ReportingUnit: Cherokee>, <ReportingUnit: Chester>, <ReportingUnit: Chesterfield>, <ReportingUnit: Clarendon>, <ReportingUnit: Colleton>, <ReportingUnit: Darlington>, <ReportingUnit: Dillon>, <ReportingUnit: Dorchester>, <ReportingUnit: Edgefield>, <ReportingUnit: Fairfield>...]
obj.districts

Returns only Congressional district-level results in the two states that break out their presidential electors: Maine and Nebraska. This feature only works if districts is set to True and passed into the get_presidential_summary model.

>>> prez = client.get_presidential_summary(districts=True)
>>> prez.districts
[<ReportingUnit: ME District 2>, <ReportingUnit: ME District 1>, <ReportingUnit: NE District 2>, <ReportingUnit: NE District 3>, <ReportingUnit: NE District 1>]

Delegate summary collections

Calling delegate related methods, like get_delegate_summary will return a slightly different, and simpler, result collection. To start, you should receive a list containing two Nomination objects.

Nominations

A contest to be the presidential nominee of one of the two major parties.

obj.candidates

The list of candidates participating in the race.

>>> obj.candidates
[<Candidate: Michele Bachmann>, <Candidate: Herman Cain>, <Candidate: Newt Gingrich>, <Candidate: Jon Huntsman>, <Candidate: No Preference>, <Candidate: Other>, <Candidate: Ron Paul>, <Candidate: Rick Perry>, <Candidate: Buddy Roemer>, <Candidate: Mitt Romney>, <Candidate: Rick Santorum>]
obj.delegates_needed

The number of delegates needed to capture the nomination.

obj.delegates_total

The total number of delegates available.

obj.delegates_chosen

The total number of delegates that have been awarded.

obj.delegates_chosen_percent

The percentage of the total delegates that have been awarded.

obj.party

Candidate’s party abbreviation.

>>> obj.party
'GOP'
obj.states

Returns a list of all the state delegates we have counts for.

>>> obj.states
[<StateDelegation: AK>, <StateDelegation: AL>, <StateDelegation: AR>, <StateDelegation: AS>, <StateDelegation: AZ>, <StateDelegation: CA>, <StateDelegation: CO>, <StateDelegation: CT>, <StateDelegation: DC>, <StateDelegation: DE>, <StateDelegation: FL>, <StateDelegation: GA>, <StateDelegation: GU>, <StateDelegation: HI>, <StateDelegation: IA>, <StateDelegation: ID>, <StateDelegation: IL>, <StateDelegation: IN>, ...]

State delegations

A state’s delegation and who they choose to be a party’s presidential nominee.

obj.candidates

The list of candidates participating in the race.

>>> obj.candidates
[<Candidate: Michele Bachmann>, <Candidate: Herman Cain>, <Candidate: Newt Gingrich>, <Candidate: Jon Huntsman>, <Candidate: No Preference>, <Candidate: Other>, <Candidate: Ron Paul>, <Candidate: Rick Perry>, <Candidate: Buddy Roemer>, <Candidate: Mitt Romney>, <Candidate: Rick Santorum>]
obj.name

The name of the state. The AP only provides the postal code.

>>> obj.name
'IA'