API documentation (for the nerds)

Want to use our data? We have an API for you! The Illinois Sunshine API can be used to do powerful searches, get the top donors to a committee, and fetch detailed data about individual donations, expenditures and committees.

If you'd rather just download all of the data, you can do that too.

About the data

The data that powers Illinois Sunshine comes directly from the Illinois State Board of Elections and is a direct reflection of that source. Therefore, under the hood, Illinois Sunshine has data on candidates (and their candidacies), committees, receipts by committees, expenditures made by committees, investments made by committees as well as information about all of the various documents that accompany the financial disclosures.

Largely due to the way this information is reported, the data in these tables is often messy. Below is a description of the tables that house the information exposed in this API. Refer to these tables when interpreting the responses made by the endpoints below.


candidates

Information about candidates

Field Description Contains null values? Sample values
id Unique numerical identifier for candidate created by the Illinois State Board of Elections No 10109
18634
306
894
3410
last_name Candidate last (family) name No Oncken
Ruzzier
Hall, Jr
Wartan
McGruder
first_name Candidate first (given) name No Martin (Marty)
John
Edward J
Joseph P "Joe"
Dick
address_1 Candidate contact address line one Yes 508 N Maple
5315 Fair Elms
2500 S St Louis Ave
Rt 1
460 S Hampshire Ave
address_2 Candidate contact address line two Yes 4625
Apt 506 B
PO Box 1149
Ste 143
353 N Clark St, Ste 3500
city Candidate contact address city Yes Cissna Park
Olney
Caseyville
Colchester
Western Springs
state Candidate contact address state Yes DC
IL
I
IN
Wi
il
ZI
MI
Il
zipcode Candidate contact address ZIP Code Yes 62902-6107
62082
62512
62338
62816
office Elected office sought by candidate Yes Circuit Clerk/McLean County
Twp Highway Commissioner/Hanover Twp
County Board Chairman/DuPage County
Village Trustee/Bethalto
Judge, Appellate Court/5th Dist
district_type Type of district covered by office Yes Vilalge (yes, actually spelled that way)
Representative
Municipal
Trustee
Township
district Name of the district covered by office Yes 303
120
52
50
20
residence_county Candidate residence county Yes Randolph
Jo Davies
Will
Cook
Shelby
party Candidate political party Yes Harold Washington
United
Tinley '97
Continued Progress Party
Community
redaction_requested Boolean indicating whether the candidate requested that their information be redacted No true
false
date_added Date record was added to Illinois Sunshine No
committees

Information about committees

Field Description Null values? Sample values
id Unique numerical identifier for committee created by the Illinois State Board of Elections No 9598
14146
2608
13238
2203
type Committee type Yes Candidate
Ballot Initiative
Political Party
Political Action
Independent Expenditure
state_committee Boolean indicating whether committee reports to state board of elections (deprecated?) No true
false
state_id Unique numeric identifier used by the Illinois State Board of Elections (deprecated?) Yes 5555
9071
9212
497
10003
local_committee Boolean indicating whether committee reports to local authority (deprecated?) No true
false
local_id Unique numeric identifier used by local election authority (deprecated?) Yes 7204
10367
9719
8558
7761
refer_name Abbreviated form of committee name No 97N14.Com
Voss T
Diaz R A
Andolino L
One Cent
name Committee name No Yes For Richland
Citz For Vaughn
Northbrook Village Caucus Committee
Steger Community Party
Citz To Elect Kathleen Longman
address1 Committee address line 1 Yes 807 Brae Burn Ln
320 S Monroe St
c/o Fred Turner
162 Elm Tree Lane
9933 N Lawler St
address2 Committee address line 2 Yes 744 Madelyn Dr
3-b Club Centre
Unit 201
7646 Moore Rd
2317 S Trumbull
address3 Committee address line 3 Yes 5711 N Milwaukee Ave
PO Box 719
Attn Mark Flood
125 S Wacker Dr, Ste 1500
129 W Joliet Hwy
city Committee address city No Crystal Lke
Schiller Park
Wapella
Minier
South Barrington
state Committee address state No NM
IL
KS
MD
WA
zipcode Committee address ZIP Code No 46074-2303
62815
62568-9601
61273
60606-6359
active Boolean indicating whether committee is active No true
false
status_date Date active status was recorded No
creation_date Date committee was formed Yes
creation_amount Funds controlled by committee when created No 290.63
150.25
760000
517.71
637.8
disp_funds_return Unknown (Boolean) No true
false
disp_funds_political_committee Unknown (Boolean) No true
false
disp_funds_charity Unknown (Boolean) No true
false
disp_funds_95 Unknown (Boolean) No true
false
disp_funds_description Unknown (Boolean) No true
false
candidate_position For candidate centric committees, indicates whether the linked candidates are supported or opposed. Often seems unreliable. Yes support
oppose
policy_position For policy centric committees, indicates whether the policy is supported or opposed. Yes support
oppose
party Committee political party Yes Non-Partisan
Republican or Independent
United Party
United Party of Justice
Better Government Party
purpose Committee stated purpose Yes To elect Glen R Kuhlemier Mayor of Rock Falls
To get Michael C Kirchner elected to the office of County Clerk.
To elect Michael Scott Jr. to the office of Alderman
Support Jonathan Baum for the District 65 School Board
Elect Chris Remhof to the Ogle County Board, and support area democrats.
officers

Information about committee officers

Field Description Null values? Sample values
id Unique numerical identifier for committee officer created by the Illinois State Board of Elections No
committee_id Unique numerical identifier for committee (foreign key to committees table) No
last_name Committee officer last (family) name No
first_name Committee officer first (given) name Yes
address1 Committee officer address line 1 Yes
address2 Committee officer address line 2 Yes
city Committee officer address city Yes
state Committee officer address state Yes
zipcode Committee officer address ZIP Code Yes
title Committee officer title No Contact/Person
Asst Treasurer
Asst Chairman
Acting Treas
Vice President
phone Committee officer phone number Yes
resign_date Date officer resigned committee post Yes
redaction_requested Boolean indicating if committee officer requested personal information be redacted No
current Boolean indicating if committee officer is currently serving No
receipts

Information about committee receipts

Field Description Null values?
id Unique numerical identifier for receipt created by the Illinois State Board of Elections No
committee_id Unique numerical identifier for reporting committee (foreign key to committees table) No
filed_doc_id Unique numerical identifier for the filing that this receipt was part of No
etrans_id Unknown Yes
last_name Donor's last (family) or organization name (in the case where the donation was not made by an individual) No
first_name Donor's first (given) name (blank in the case where the donation was made by an organization) Yes
received_date Date the donation was reported as received by the committee No
amount Dollar amount of the donation No
aggregate_amount In the case of multiple donations by the same origanization or individual during a reporting period, the aggregate amount given. If only one donation was given, this will be 0 Yes
loan_amount Amount of the donation loaned to the committee Yes
occupation Donor's occupation Yes
employer Donor's employer Yes
address1 Donor's address line 1 Yes
address2 Donor's address line 2 Yes
city Donor's address city Yes
state Donor's address state Yes
zipcode Donor's address zipcode Yes
d2_part Part of the D2 Report that this donation falls into. No 1A - Itemized individual contribution
2A - Itemized transfer in
3A - Itemized loans received
4A - Itemized "other" receipts (such as refunds, reimbursements, interest accrued, etc)
5A - Itemized in-kind contribution
description Donation description Yes
vendor_last_name Last name of individual or organization name of vendor providing a good or service or loan Yes
vendor_first_name First name of individual vendor providing a good or service or loan Yes
vendor_address1 Address line 1 of vendor providing a good or service or loan Yes
vendor_address2 Address line 2 of vendor providing a good or service or loan Yes
vendor_city Address city of vendor providing a good or service or loan Yes
vendor_state Address state of vendor providing a good or service or loan Yes
vendor_zipcode Address state of vendor providing a good or service or loan Yes
archived Unknown (boolean) No
country Donor country Yes
redaction_requested Boolean indicating if donor requested personal information be redacted No
expenditures

Information about committee expenditures

Field Description Null values?
id Unique numerical identifier for expenditure created by the Illinois State Board of Elections No
committee_id Unique numerical identifier for reporting committee (foreign key to committees table) No
filed_doc_id Unique numerical identifier for the filing that this expenditure was part of No
etrans_id Unknown Yes
last_name Last (family) or name of individual or organization listed as receiving expense No
first_name First (given) name of individual who received expense (blank in the case where the expense was received by an organization) Yes
expended_date Date the expense was reported as being spent by the committee No
amount Dollar amount of the expense No
aggregate_amount In the case of multiple expenses received by the same origanization or individual during a reporting period, the aggregate amount received. If only one expense was received, this will be 0 Yes
address1 Expense address line 1 Yes
address2 Expense address line 2 Yes
city Expense address city Yes
state Expense address state Yes
zipcode Expense address zipcode Yes
d2_part Part of the D2 Report that this expense falls into. No 6B - Itemized transfers out
7B - Itemized loans made
8B - Itemized individual expenditures
9B - Itemized independent expenditures
purpose Expense purpose Yes
candidate_name In the case of expenditures made in support of or in opposition a candidate, the name of the candidate supported or opposed. Yes
office Office sought by candidate supported or opposed. Yes
supporting Boolean indicating whether candidate was supported No
opposed Boolean indicating whether candidate was opposed No
archived Unknown (boolean) No
country Expense country Yes
redaction_requested Boolean indicating if individual or organization listed as receiving expense requested personal information be redacted No

Using the API

A few things to know:

API endpoints

GET /api/top-money/

Find top donors or expenses for a committee

Returns top 25 donors or expenses for a given committee

Query Parameters

All query parameters are required

Parameter Default value Possible values Description
committee_id none Valid unique numeric identifier for a committee
type none receipts
expenditures
Either receipts or expenditures depending on the type of transaction you're interested in

Response

Parameter Description
total Total amount donated or received by individual or organization
first_name First (given) name of individual who either received the total or gave the total, depending on transaction type
last_name Last (family) name of individual or name of organization who either received the total or gave the total, depending on transaction type
total_date Date of most recent transaction

Example

http://illinoissunshine.org/api/top-money/?type=receipts&limit=25&committee_id=1212
Returns the top 25 donors to Taxpayers for Quinn (committee ID 1212)

GET /api/committees/

Query committees table

Filter committee table based upon its attributes

Query Parameters

All query parameters are optional

Parameter Default value Possible values Description
[dataset_field]* none

Any available dataset field. Refer to the committees data description above for what fields are available. Any number of these query parameters can be chained together and are linked together with a SQL AND under the hood.

Query operators
For any given dataset_field, the query can be modified with any of the following operators (where they make sense given the data type of the field)

Operator Description Valid data types
__gt greater than (>) Integers, Floats, Dates, and Datetimes
__ge greater than or equal to (>=) Integers, Floats, Dates, and Datetimes
__lt less than (<) Integers, Floats, Dates, and Datetimes
__le less than or equal to (<=) Integers, Floats, Dates, and Datetimes
__ne not equal (!=) Any
__like like value with % wildcards, case sensitive (LIKE 'State%') Strings
__ilike like value with % wildcards, case insensitive (ILIKE 'state%') Strings
__in within a list of provided values (IN ('list', 'of', 'values')). Values should be supplied as a comma-seperated list Any

Example: name__ilike=%Democratic% translates to "name ILIKE %Democratic%" in SQL

Response

Returns a list of committees (described above) matching query. Within each committees block is a candidates block containing a list of supported candidates (if any)

Example

http://illinoissunshine.org/api/committees/?name__ilike=%democratic%&type=Political Party
Returns committees where the name is like "democratic" and are Political Parties

GET /api/receipts/

Query receipts table

Filter receipts table based upon its attributes

Query Parameters

All query parameters are optional except committee_id

Parameter Default value Possible values Description
committee_id none Any valid numeric identfier for a committee
datatype json csv, json Indicates what data format to respond with
[dataset_field]* none

Any available dataset field. Refer to the receipts data description above for what fields are available. Any number of these query parameters can be chained together and are linked together with a SQL AND under the hood.

Query operators
For any given dataset_field, the query can be modified with any of the following operators (where they make sense given the data type of the field)

Operator Description Valid data types
__gt greater than (>) Integers, Floats, Dates, and Datetimes
__ge greater than or equal to (>=) Integers, Floats, Dates, and Datetimes
__lt less than (<) Integers, Floats, Dates, and Datetimes
__le less than or equal to (<=) Integers, Floats, Dates, and Datetimes
__ne not equal (!=) Any
__like like value with % wildcards, case sensitive (LIKE 'State%') Strings
__ilike like value with % wildcards, case insensitive (ILIKE 'state%') Strings
__in within a list of provided values (IN ('list', 'of', 'values')). Values should be supplied as a comma-seperated list Any

Example: amount__ge=50000 translates to "amount >= 50000" in SQL

Response

Returns a list of receipts (described above) matching query as well as all information about the committee that received them

Example

http://illinoissunshine.org/api/receipts/?committee_id=25185&amount__ge=50000&received_date__ge=2015-01-01
Returns receipts greater than or equal to $50,000 and received after January 1, 2015 by Citizens for Rauner, Inc

GET /api/expenditures/

Query receipts table

Filter expenditures table based upon attributes

Query Parameters

All query parameters are optional except committee_id

Parameter Default value Possible values Description
committee_id none Any valid numeric identfier for a committee
datatype json csv, json Indicates what data format to respond with
[dataset_field]* none

Any available dataset field. Refer to the expenditures data description above for what fields are available. Any number of these query parameters can be chained together and are linked together with a SQL AND under the hood.

Query operators
For any given dataset_field, the query can be modified with any of the following operators (where they make sense given the data type of the field)

Operator Description Valid data types
__gt greater than (>) Integers, Floats, Dates, and Datetimes
__ge greater than or equal to (>=) Integers, Floats, Dates, and Datetimes
__lt less than (<) Integers, Floats, Dates, and Datetimes
__le less than or equal to (<=) Integers, Floats, Dates, and Datetimes
__ne not equal (!=) Any
__like like value with % wildcards, case sensitive (LIKE 'State%') Strings
__ilike like value with % wildcards, case insensitive (ILIKE 'state%') Strings
__in within a list of provided values (IN ('list', 'of', 'values')). Values should be supplied as a comma-seperated list Any

Example: expended_date__ge=2015-01-01 translates to "expended_date >= 2015-01-01" in SQL

Response

Returns a list of expenditures (described above) matching query as well as all information about the committee that made them

Example

http://illinoissunshine.org/api/expenditures/?committee_id=25960&last_name__ilike=Democratic%20Party%25
Returns expenditures made by Chicago Forward to organizations or individuals with a name like "Democratic Party"

Terms of use and attribution guidelines

Use of any Illinois Sunshine API content must appropriately attribute Reform for Illinois (RFI) by name and logo usage whenever possible. You may not display the API content in such a manner that does not allow for successful linking and redirection to, and delivery of, illinoissunshine.org.

Restrictions on Illinois Sunshine data

Unless otherwise consented to or permitted by Reform for Illinois, you will:

Let's work together!

RFI would like to work with you if you plan to use data from Illinois Sunshine. Please contact us at outreach@reformforillinois.org to discuss partnership opportunities.

Reform for Illinois logos