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:

All API calls should be made with HTTP GET
All API responses are in JSON format by default
Some API endpoints (noted below) can also return a comma-separated value file (CSV)
All methods are accessed via: http://illinoissunshine.org/api/SOME-ENDPOINT
You must follow our terms of use and attribution guidelines

API endpoints

GET /api/advanced-search/

search data for a term

Searches selected tables for a given term. Results are ordered in reverse order by date.

Query Parameters

All query parameters are optional except for term

Parameter	Default value	Possible values	Description
`term`	none	Any string	The term to search for across selected tables. Must be at least three characters long.
`limit`	50	Any positive integer	The number of results to return. Use this in combination with `offset` to paginate results.
`offset`	0	Any positive integer	Skip this number of results from the beginning of the response. Use this in combination with `limit` to paginate results.
`datatype`	json	`csv` or `json`	Format to return the data in. `csv` returns a zip file containing CSV files with the results from each of the selected tables.
`table_name`	`committees` `candidates` `receipts` `expenditures` `officers`	`committees` `candidates` `receipts` `expenditures` `officers` `investments`	The name of the table to search within. Multiple `table_name` allow you to search within multiple tables. So, to search within the `receipts` and `expenditures` tables, add this to your querystring: `&table_name=receipts&table_name=expenditures`

Response

Parameter	Description
`objects`	A JSON object containing arrays of results from each of the selected tables. The fields returned depend on the table. See data description above for details above for descriptions of each data table.

Example

http://illinoissunshine.org/api/advanced-search/?term=cullerton
Returns all committees, candidates, receipts, officers and expenditures containing the word 'cullerton'

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:

ensure that the fundamental meaning of the API content is not changed or distorted;
ensure that the use or display of API content does not suggest that Reform for Illinois promotes or endorses you or any third party or the causes, ideas, Web sites, political candidates or parties, products or services of you or any third party. RFI is a nonpartisan, nonprofit 501(c)3 organization, and cannot endorse or support any political party, candidate for elected office, or partisan politics;
not display the name, logo, trademark or other identifier of another person (except for RFI or you) on your Site in such a manner as to give the viewer the impression that such other person is a publisher or distributor of the API content on the Site

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