Command line interface

Commands and flags

commands:

  ballot-measures
    Get ballot measures

  candidate-reporting-units
    Get candidate reporting units (without results)

  candidates
    Get candidates

  clear-cache
    Clear the elex response cache

  delegates
    Get all delegate reports

  elections
    Get list of available elections

  next-election
    Get the next election (if date is specified, will be relative to that date, otherwise will use today's date)

  races
    Get races

  reporting-units
    Get reporting units

  results
    Get results

positional arguments:
  date                  Election date (e.g. "2015-11-03"; most common date
                        formats accepted).

optional arguments:
  -h, --help            show this help message and exit
  --debug               toggle debug output
  --quiet               suppress all output
  -o {json,csv}         output format (default: csv)
  -t, --test            Use testing API calls
  -n, --not-live        Do not use live data API calls
  -d DATA_FILE, --data-file DATA_FILE
                        Specify data file instead of making HTTP request when
                        using election commands like `elex results` and `elex
                        races`.
  --delegate-sum-file DELEGATE_SUM_FILE
                        Specify delegate sum report file instead of making
                        HTTP request when using `elex delegates`
  --delegate-super-file DELEGATE_SUPER_FILE
                        Specify delegate super report file instead of making
                        HTTP request when using `elex delegates`
  --format-json         Pretty print JSON when using `-o json`.
  -v, --version         show program's version number and exit
  --results-level RESULTS_LEVEL
                        Specify reporting level for results
  --raceids RACEIDS     Specify raceids to parse
  --set-zero-counts     Override results with zeros; omits the winner
                        indicator.Sets the vote, delegate, and reporting
                        precinct counts to zero.
  --national-only       Limit results to national-level results only.
  --local-only          Limit results to local-level results only.
  --with-timestamp      Append a `timestamp` column to each row of data output
                        with current system timestamp.
  --batch-name BATCH_NAME
                        Specify a value for a `batchname` column to append to
                        each row.

Command reference

class elex.cli.app.ElexBaseController(*args, **kw)
ballot_measures()

elex ballot-measures <electiondate>

Returns ballot measure data for a given election date.

Command:

elex ballot-measures 2016-03-15

Example output:

id candidateid ballotorder description electiondate last polid polnum seatname
2016-03-15-43697 43697 1   2016-03-15 For   37229 Public Improvement Bonds
2016-03-15-43698 43698 2   2016-03-15 Against   37230 Public Improvement Bonds
...                
candidate_reporting_units()

elex candidate-reporting-units <electiondate>

Returns candidate reporting unit data for a given election date.

A candidate reporting unit is a container for the results of a voting in a specific reporting unit. This command is a close cousin of elex results <electiondate>.

This command does not return results.

Command:

elex candidate-reporting-units 2016-03-26

Example output:

id raceid racetype racetypeid ballotorder candidateid description delegatecount electiondate fipscode first incumbent initialization_data is_ballot_measure last lastupdated level national officeid officename party polid polnum precinctsreporting precinctsreportingpct precinctstotal reportingunitid reportingunitname runoff seatname seatnum statename statepostal test uncontested votecount votepct winner
2919-polid-1445-None 2919 Caucus E 2 6527   0 2016-03-26   Bernie False True False Sanders 2016-03-27T03:03:54Z   True P President Dem 1445 4262 0 0.0 0     False     Alaska AK False False 0 0.0 False
2919-polid-1746-None 2919 Caucus E 1 6526   0 2016-03-26   Hillary False True False Clinton 2016-03-27T03:03:54Z   True P President Dem 1746 4261 0 0.0 0     False     Alaska AK False False 0 0.0 False

Notes:

This command can be used to quickly create schemas.

pip install csvkit
elex candidate-reporting-units 03-26-16 | csvsql -i mysql

Will output:

CREATE TABLE stdin (
    id VARCHAR(23) NOT NULL,
    raceid INTEGER NOT NULL,
    racetype VARCHAR(6) NOT NULL,
    racetypeid VARCHAR(1) NOT NULL,
    ...
);
candidates()

elex candidates <electiondate>

Returns candidate data for a given election date.

Command:

elex candidates 2016-03-26

Example output:

id candidateid ballotorder first last party polid polnum
polid-1445 6527 2 Bernie Sanders Dem 1445 4262
polid-1746 6526 1 Hillary Clinton Dem 1746 4261
...              
clear_cache()

elex clear-cache

Returns data about the next election with an optional date to start searching.

Command:

elex clear-cache

Example output:

2016-09-30 00:22:56,992 (INFO) cement:app:elex : Clearing cache (/var/folders/z2/plxshs7c43lm_bctxn/Y/elex-cache)
2016-09-30 00:22:56,993 (INFO) cement:app:elex : Cache cleared.
delegates()

elex delegates

Returns delegate report data.

Command:

elex delegates

Example output:

level party_total superdelegates_count last state candidateid party_need party delegates_count id d1 d7 d30
state 2472 0 Bush MN 1239 1237 GOP 0 MN-1239 0 0 0
state 2472 0 Bush OR 1239 1237 GOP 0 OR-1239 0 0 0
elections()

elex elections

Returns all elections known to the API.

Command:

elex elections

Example output:

2016-02-09 2016-02-09 True False
2016-02-16 2016-02-16 True False
...      
next_election()

elex next-election <date-after>

Returns data about the next election with an optional date to start searching.

Command:

elex next-election

Example output:

id electiondate liveresults testresults
2016-04-19 2016-04-19 False True

You can also specify the date to find the next election after, e.g.:

elex next-election 2016-04-15

This will find the first election after April 15, 2016.

races()

elex races <electiondate>

Returns race data for a given election date.

Command:

elex races 2016-03-26

Example output:

id raceid racetype racetypeid description electiondate initialization_data is_ballot_measure lastupdated national officeid officename party seatname seatnum statename statepostal test uncontested
2919 2919 Caucus E   2016-03-26 True False 2016-03-27T03:03:54Z True P President Dem       AK False False
12975 12975 Caucus E   2016-03-26 True False 2016-03-29T17:17:41Z True P President Dem       HI False False
...                                    
reporting_units()

elex reporting-units <electiondate>

Returns reporting unit data for a given election date.

Reporting units represent geographic aggregation of voting data at the national, state, county, and district level.

Command:

elex reporting-units 2016-03-26

Example output:

id reportingunitid reportingunitname description electiondate fipscode initialization_data lastupdated level national officeid officename precinctsreporting precinctsreportingpct precinctstotal raceid racetype racetypeid seatname seatnum statename statepostal test uncontested votecount
state-1 state-1     2016-03-26   False 2016-03-27T03:03:54Z state True P President 40 1.0 40 2919 Caucus E     Alaska AK False False 539
county-2003 county-2003 State House District 1   2016-03-26   False 2016-03-27T03:03:54Z county True P President 1 1.0 1 2919 Caucus E       AK False False 12
county-2004 county-2004 State House District 2   2016-03-26   False 2016-03-27T03:03:54Z county True P President 1 1.0 1 2919 Caucus E       AK False False 6
...                                                
results()

elex results <electiondate>

Returns result data.

Each row in the output represents a fully flattened and denormalized version of a result for specific candidate in a specific race.

Command:

elex results 2016-03-01

Example output:

id unique_id raceid racetype racetypeid ballotorder candidateid description delegatecount electiondate fipscode first incumbent initialization_data is_ballot_measure last lastupdated level national officeid officename party polid polnum precinctsreporting precinctsreportingpct precinctstotal reportingunitid reportingunitname runoff seatname seatnum statename statepostal test uncontested votecount votepct winner
3021-polid-61815-state-1 3021 Caucus S 2 6528   0 2016-03-01   Ted False False False Cruz 2016-03-02T17:05:46Z state True P President GOP 61815 4263 72 1.0 72 state-1   False     Alaska AK False False 7973 0.363566 True  
3021-polid-8639-state-1 3021 Caucus S 5 6548   0 2016-03-01   Donald False False False Trump 2016-03-02T17:05:46Z state True P President GOP 8639 4273 72 1.0 72 state-1   False     Alaska AK False False 7346 0.334975 False  
...