Menu BP Logo (small) Ballotpedi API Login

Documentation

NOTICE: This is an older version of Ballotpedia's API. For the latest documentation, see: https://ballotpedia.org/API-documentation

Usage

The API is accessible via the endpoint below:

https://api.ballotpedia.org/v1/api.php

The following two parameters are required:

Additional parameters are allowed, depending on the data set you're querying.

Response

The API responds with JSON encoded objects or arrays. Specific responses depend on the data set you're querying.

Limits

To reduce load on our servers, we place usage restrictions on some keys. Depending on your usage plan, your key(s) will be limited to a certain number of requests per day. To request a higher limit, please contact us.

The number of results the API returns is limited to 100. One element of the JSON response is always NumResults. If this is greater than 100, add &Page=2 (etc.) to your parameters to fetch additional results.

Some features of this API return image URLs. In general, you should cache and create thumbnails for these images on your system, both for the performance of your own application and to ease the load on our servers. Keys that abuse this policy may be blocked.

For some API keys, Ballotpedia may require attribution as part of the API Usage Agreement. In such cases, you must link to Ballotpedia's extended profile page for a person, ballot measure, court, or district whenever you display results from one of these data sets.

Data Sets

This API provides several different data sets, each with its own query parameters and returned data. The specifics of each data set are described below.

Elections

This data set provides data for elections at the Federal, State, and Local levels. You can use the following parameters to query the Elections data set:

The API returns the following data:

And for each matching election:

Filing Deadlines

This data set provides data for filing deadlines prior to elections. You can use the following parameters to query the FilingDeadlines data set:

The API returns the following data:

And for each matching filing deadline:

People

This data set provides data for politicians at all levels of government, including candidates and incumbents, elected and appointed officials, and members of the judicial, legislative, and executive branches, as well as some other notable political influencers.

You can use the following parameters to query the People data set:

The API returns the following data:

And for each matching person:

Districts

This data set provides data for various types of political districts.

You can use the following parameters to query the Districts data set:

The API returns the following data:

and for each District:

BallotMeasures

This data set provides data for state and local ballot measures.

You can use the following parameters to query the BallotMeasures data set:

The API returns the following data:

and for each Ballot Measure:

Examples

Searching for all current U.S. Representatives from Rhode Island:

http://api.ballotpedia.org/api.php
	?Key=...
	&DataSet=People
	&Office.Level=Federal
	&Office.Branch=Legislative
	&Office.Chamber=Lower
	&Office.District.State=RI
	&Office.Status=Incumbent

or

http://api.ballotpedia.org/api.php
	?Key=...
	&DataSet=People
	&Office.District.State=RI
	&Office.District.Type=Congress
	&Office.Chamber=Lower
	&Office.Status=Incumbent

Sample response:

{
	"NumResults": 2,
	"Results": [
		{
			"Name": "David Cicilline",
			"Image": "http://ballotpedia.org/wiki/images/b/bb/David_Cicilline.jpg",
			"PageURL": "http://ballotpedia.org/David_Cicilline",
			"DateBorn": "1961-07-15",
			"IsDeceased": false,
			"PartyAffiliation": "Democratic",
			"Offices": [
				{
					"Name": "Mayor of Providence, Rhode Island",
					"Title": "Mayor",
					"Level": "Local",
					"Branch": "Executive",
					"District": {
						"ID": 5983,
						"Type": "Cities",
						"Name": "City of Providence",
						"State": "RI"
					},
					"Status": "Former",
					"OfficeIsElected": true,
					"Election": {
						"ID": 7136,
						"Date": "2002-11-03"
					},
					"OfficeIsAppointed": false,
					"DateAssumed": "2003",
					"DateExpires": "2011"
				},
				{
					"Name": "Rhode Island House of Representatives",
					"Title": "Representative",
					"Level": "State",
					"Branch": "Legislative",
					"Chamber": "Lower",
					"District": {
						"ID": 5712,
						"Type": "StateLegLower",
						"Name": "Rhode Island House of Representatives District 4",
						"State": "RI"
					},
					"Status": "Former",
					"OfficeIsElected": true,
					"Election": {
						"ID": 8173,
						"Date": "1992"
					},
					"OfficeIsAppointed": false,
					"DateAssumed": "1995",
					"DateExpires": "2003"
				},
				{
					"Name": "U.S. Representative",
					"Title": "Representative",
					"Level": "federal",
					"Branch": "Legislative",
					"Chamber": "Lower",
					"District": {
						"ID": 1746,
						"Type": "Congress",
						"Name": "Rhode Island 1st Congressional District",
						"State": "RI"
					},
					"Status": "Incumbent",
					"OfficeIsElected": true,
					"Election": {
						"ID": 5028,
						"Date": "2010-11-02"
					},
					"OfficeIsAppointed": false,
					"DateAssumed": "2011",
					"DateExpires": "2017-01-03"
				}
			]
		},
		{
			"Name": "Jim Langevin",
			"Image": "http://ballotpedia.org/wiki/images/8/86/James_Langevin.jpg",
			"PageURL": "http://ballotpedia.org/Jim_Langevin",
			"DateBorn": "1964-04-22",
			"IsDeceased": false,
			"PartyAffiliation": "Democratic",
			"Offices": [
				{
					"Name": "Rhode Island House of Representatives",
					"Title": "Representative",
					"Level": "State",
					"Branch": "Legislative",
					"Chamber": "Lower",
					"District": {
						"ID": 2736,
						"Type": "StateLegLower",
						"Name": "Rhode Island House of Representatives District 29",
						"State": "RI"
					},
					"Status": "Former",
					"OfficeIsElected": true,
					"Election": {
						"ID": 3098,
						"Date": "1988"
					},
					"OfficeIsAppointed": false,
					"DateAssumed": "1989",
					"DateExpires": "1995"
				},
				{
					"Name": "Secretary of State of Rhode Island",
					"Title": "Secretary",
					"Level": "State",
					"Branch": "Executive",
					"District": {
						"ID": 2347,
						"Type": "State",
						"Name": "Rhode Island",
						"state": "RI"
					},
					"Status": "Former",
					"OfficeIsElected": true,
					"Election": {
						"ID": 9164,
						"Date": "1994"
					},
					"OfficeIsAppointed": false,
					"DateAssumed": "1995",
					"DateExpires": "2001"
				},
				{
					"Name": "U.S. Representative",
					"Title": "Representative",
					"Level": "Federal",
					"Branch": "Legislative",
					"Chamber": "Lower",
					"District": {
						"ID": 8347,
						"Type": "Congress",
						"Name": "Rhode Island 2nd Congressional District",
						"State": "RI"
					},
					"Status": "Incumbent",
					"OfficeIsElected": true,
					"Election": {
						"ID": 2387,
						"Date": "2000-11-072"
					},
					"OfficeIsAppointed": false,
					"DateAssumed": "2001",
					"DateExpires": "2017-01-03"
				}
			]
		}
	]
}