Skip to main content

GET /positions

tip

Check out our GraphQL API for a more flexible approach to incorporate BallotReady data in your projects.

Parameters

Note that either address OR lat/lon is required.

  • address (optional): primary search criteria
  • county (optional): the county the position is held in
  • election_date (optional): set an election_date to return only candidates who are up for election on that date in YYYY-MM-DD format
  • election_id (optional): if you include candidates, you can filter by one or more election_ids, separated by commas (e.g. election_id=840,852).
  • exclude_statewide (optional): option to exclude statewide positions
  • include_candidates (optional): choose to include candidates in API response by passing include_candidates=1
  • include_endorsements (optional): choose to include endorsements in API response or not
  • include_office_holders (optional): choose to include office holders in API response or not
  • include_uncertified_candidates (optional): choose to include uncertified candidates in API response or not
  • include_volunteer_urls (optional): choose to include volunteer urls in API response or not
  • lat (optional): instead of using address, pass lat/lon and bypass geocoding
  • level (optional): return only positions at a single level. Possible values: federal/state/county/city/local/party, see notes below for further documentation
  • lon (optional): instead of using address, pass lat/lon and bypass geocoding
  • search_radius (optional): return positions within X miles of address (up to 30)
  • state (optional): the state the position is held in
  • tier (optional): civicengine position tier
  • year (optional): limits results to a specific year. If no year is specified, the results will be limited to the current year.
  • starting_after (optional): A cursor for use in pagination. starting_after is a position's id that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list. In order to get the first page set starting_after=0. Without this parameter, there will be no pagination.

Request

To query candidate positions based on address:

curl -H 'x-api-key: APIKEY' "https://api.civicengine.com/positions?address=350%2B5th%2BNew%2BYork%2BNY%2B10118"

To query the API and limit the result by multiple Election IDs:

curl -H 'x-api-key: APIKEY' "https://api.civicengine.com/positions?lat=33.9339542&lon=-118.0946877&election_id=64,122"

Response

{
"timestamp": "2020-04-16T17:48:05.972991",
"positions": [
{
"position_id": 36,
"paperwork_instructions": null,
"general_date": "2020-11-03",
"sub_area_value": null,
"normalized_position": {
"id": 10,
"mtfcc": null,
"description": null,
"name": "President of the United States of America",
"level": "federal"
},
"sub_area_name": null,
"retention": false,
"unexpired_term": false,
"employment_type": "full time",
"primary_date": "2020-06-23",
"state": "NY",
"candidates": [],
"selections_allowed": 1,
"general_filing_end": "2020-05-26",
"description": "The President is the chief executive of the county, possessing many powers including signing bills into law, vetoing legislation, appointing federal judges and executive department heads, issue executive orders, and conducting foreign policy.",
"eligibility_requirements": null,
"filing_requirements": null,
"updated_at": "2019-10-07T20:55:30.986351",
"has_unknown_boundaries": false,
"tier": 1,
"slug": null,
"la_style": false,
"salary": "$400,000 + $50,000 expense account per year",
"number_of_seats": 1,
"name": "President of the United States",
"level": "FEDERAL",
"position_type": null,
"runoff_date": null,
"judicial": false,
"primary_filing_end": "2020-01-07"
},
{
"position_id": 1,
"paperwork_instructions": null,
"general_date": "2020-11-03",
"sub_area_value": null,
"normalized_position": {
"id": 10,
"mtfcc": null,
"description": null,
"name": "President of the United States of America",
"level": "federal"
},
"sub_area_name": null,
"retention": false,
"unexpired_term": false,
"employment_type": "full time",
"primary_date": "",
"state": "US",
"candidates": [],
"selections_allowed": 1,
"general_filing_end": "",
"description": "The President is the chief executive of the county, possessing many powers including signing bills into law, vetoing legislation, appointing federal judges and executive department heads, issue executive orders, and conducting foreign policy.",
"eligibility_requirements": null,
"filing_requirements": null,
"updated_at": "2019-10-07T20:55:30.986351",
"has_unknown_boundaries": false,
"tier": 1,
"slug": null,
"la_style": false,
"salary": "$400,000 + $50,000 expense account per year",
"number_of_seats": 1,
"name": "President of the United States",
"level": "FEDERAL",
"position_type": null,
"runoff_date": null,
"judicial": false,
"primary_filing_end": "n/a"
},
{
"position_id": 46507,
"paperwork_instructions": "Submit paperwork to the New York City Board of Elections office.",
"general_date": "2020-11-03",
"sub_area_value": "12",
"normalized_position": {
"id": 40,
"mtfcc": null,
"description": null,
"name": "U.S. House",
"level": "federal"
},
"sub_area_name": "Congressional District",
"retention": false,
"unexpired_term": false,
"employment_type": "Full Time",
"primary_date": "2020-06-23",
"state": "NY",
"candidates": [],
"selections_allowed": 1,
"general_filing_end": "2020-05-26",
"description": "US House of Representatives is one of two chambers for the federal legislature. Representatives begin the legislation process, offer amendments, and serve on committees",
"eligibility_requirements": "Representative must be at least twenty-five years old, have been a citizen of the United States for the past seven years, and be an inhabitant of the state they seek to represent.",
"filing_requirements": "No filing fee. Petition signature requirements: For candidates running for party nomination: 5% of enrolled voters of the party in the district or 1,250, whichever is less; for independent candidates: 5% of the total number of votes cast for governor at the last gubernatorial election in the district or 3,500, whichever is less",
"updated_at": "2019-07-11T22:28:48.647845",
"has_unknown_boundaries": false,
"tier": 1,
"slug": "new-york-u-s-house-of-representatives-new-york-12th-congressional-district",
"la_style": false,
"salary": "$174,000/year",
"number_of_seats": 1,
"name": "U.S. House of Representatives - New York 12th Congressional District",
"level": "FEDERAL",
"position_type": "U.S. House of Representatives",
"runoff_date": null,
"judicial": false,
"primary_filing_end": "2020-04-02"
},
{
"position_id": 47467,
"paperwork_instructions": "Submit paperwork to the New York City Board of Elections office.",
"general_date": "2020-11-03",
"sub_area_value": "27",
"normalized_position": {
"id": 600,
"mtfcc": null,
"description": null,
"name": "State Senate",
"level": "state"
},
"sub_area_name": "District",
"retention": false,
"unexpired_term": false,
"employment_type": "Full Time",
"primary_date": "2020-06-23",
"state": "NY",
"candidates": [],
"selections_allowed": 1,
"general_filing_end": "2020-05-26",
"description": "Legislative authority and responsibilities include passing bills on public policy matters, setting levels for state spending, raising and lowering taxes, and voting to uphold or override gubernatorial vetoes.",
"eligibility_requirements": "A candidate must be at least 18 years old, a citizen of the state, a resident of state for 5 years, and a resident of district for 12 months immediately preceding election",
"filing_requirements": "No filing fee. Petition signature requirements: For candidates running for party nomination: 5% of enrolled voters of the party in the district or 1,000, whichever is less; for independent candidates: 5% of the total number of votes cast for governor at the last gubernatorial election in the district or 3,000, whichever is less",
"updated_at": "2019-07-11T22:28:48.647845",
"has_unknown_boundaries": false,
"tier": 2,
"slug": "new-york-new-york-state-senate-district-27",
"la_style": false,
"salary": "$110,000/year (+ per diem)",
"number_of_seats": 1,
"name": "New York State Senate - District 27",
"level": "STATE",
"position_type": "State Legislative District (Upper Chamber)",
"runoff_date": null,
"judicial": false,
"primary_filing_end": "2020-04-02"
},
{
"position_id": 51568,
"paperwork_instructions": "Submit paperwork to the New York City Board of Elections office.",
"general_date": "2020-11-03",
"sub_area_value": "75",
"normalized_position": {
"id": 610,
"mtfcc": null,
"description": null,
"name": "State House of Representatives",
"level": "state"
},
"sub_area_name": "District",
"retention": false,
"unexpired_term": false,
"employment_type": "Full Time",
"primary_date": "2020-06-23",
"state": "NY",
"candidates": [],
"selections_allowed": 1,
"general_filing_end": "2020-05-26",
"description": "Legislative authority and responsibilities include passing bills on public policy matters, setting levels for state spending, raising and lowering taxes, and voting to uphold or override gubernatorial vetoes.",
"eligibility_requirements": "A candidate must be at least 18 years old, a citizen of the state, a resident of state for 5 years, and a resident of district for 12 months immediately preceding election",
"filing_requirements": "No filing fee. Petition signature requirements: For candidates running for party nomination: 5% of enrolled voters of the party in the district or 500, whichever is less; for independent candidates: 5% of the total number of votes cast for governor at the last gubernatorial election in the district or 1,500, whichever is less",
"updated_at": "2019-07-11T22:28:48.647845",
"has_unknown_boundaries": false,
"tier": 2,
"slug": "new-york-new-york-state-assembly-district-75",
"la_style": false,
"salary": "$110,000/year (+ per diem)",
"number_of_seats": 1,
"name": "New York State Assembly - District 75",
"level": "STATE",
"position_type": "State Legislative District (Lower Chamber)",
"runoff_date": null,
"judicial": false,
"primary_filing_end": "2020-04-02"
},
{
"position_id": 287717,
"paperwork_instructions": "Submit paperwork to the New York City Board of Elections office.",
"general_date": "2020-11-03",
"sub_area_value": "1",
"normalized_position": {
"id": 4027,
"mtfcc": null,
"description": null,
"name": "Judicial Trial Court - General",
"level": "state"
},
"sub_area_name": null,
"retention": false,
"unexpired_term": false,
"employment_type": "Full Time",
"primary_date": "",
"state": "NY",
"candidates": [],
"selections_allowed": 2,
"general_filing_end": "2020-05-26",
"description": "District or Circuit court Judges are responsible for adjudicating cases in Civil and Criminal Courts at the trial-level.",
"eligibility_requirements": "Must be under the age of 70 years old. Must have been admitted to practice as an attorney in the State of New York for at least ten years.",
"filing_requirements": "No filing fee. Petition signature requirements: For candidates running for party nomination: 5% of enrolled voters of the party in the district or 500, whichever is less; for independent candidates: 5% of the total number of votes cast for governor at the last gubernatorial election in the district or 1,500, whichever is less",
"updated_at": "2019-07-11T22:28:48.647845",
"has_unknown_boundaries": false,
"tier": 2,
"slug": null,
"la_style": false,
"salary": "$208,000 / year",
"number_of_seats": 2,
"name": "New York Supreme Court Justice - District 1",
"level": "STATE",
"position_type": null,
"runoff_date": null,
"judicial": true,
"primary_filing_end": "n/a"
},
{
"position_id": 288227,
"paperwork_instructions": "Submit paperwork to the New York City Board of Elections office.",
"general_date": "2020-11-03",
"sub_area_value": null,
"normalized_position": {
"id": 4478,
"mtfcc": null,
"description": null,
"name": "Judicial County Court - Civil",
"level": "county"
},
"sub_area_name": null,
"retention": false,
"unexpired_term": false,
"employment_type": "Full Time",
"primary_date": "2020-06-23",
"state": "NY",
"candidates": [],
"selections_allowed": 3,
"general_filing_end": "2020-05-26",
"description": "County court judges responsible for adjudicating cases in Civil Courts at the trial-level, typically limited to a certain dollar amount.",
"eligibility_requirements": "Must be under the age of 70 years old. Must have been admitted to practice as an attorney in the State of New York for at least five years.",
"filing_requirements": "No filing fee. Petition signature requirement: For candidates running for party nomination: 5% of enrolled voters of the party in the borough or 1500, whichever is less; for independent candidates: 4000",
"updated_at": "2019-07-11T22:28:48.647845",
"has_unknown_boundaries": false,
"tier": 3,
"slug": null,
"la_style": false,
"salary": "$193,500 / year",
"number_of_seats": 3,
"name": "New York County Civil Court Judge - At Large",
"level": "COUNTY",
"position_type": null,
"runoff_date": null,
"judicial": true,
"primary_filing_end": "2020-04-02"
},
{
"position_id": 288230,
"paperwork_instructions": "Submit paperwork to the New York City Board of Elections office.",
"general_date": "2020-11-03",
"sub_area_value": "9",
"normalized_position": {
"id": 4478,
"mtfcc": null,
"description": null,
"name": "Judicial County Court - Civil",
"level": "county"
},
"sub_area_name": null,
"retention": false,
"unexpired_term": false,
"employment_type": "Full Time",
"primary_date": "2020-06-23",
"state": "NY",
"candidates": [],
"selections_allowed": 1,
"general_filing_end": "2020-05-26",
"description": "County court judges responsible for adjudicating cases in Civil Courts at the trial-level, typically limited to a certain dollar amount.",
"eligibility_requirements": "Must be under the age of 70 years old. Must have been admitted to practice as an attorney in the State of New York for at least five years.",
"filing_requirements": "No filing fee. Petition signature requirement: For candidates running for party nomination: 5% of enrolled voters of the party in the borough or 1500, whichever is less; for independent candidates: 4000",
"updated_at": "2019-07-11T22:28:48.647845",
"has_unknown_boundaries": true,
"tier": 3,
"slug": null,
"la_style": false,
"salary": "$193,500 / year",
"number_of_seats": 1,
"name": "New York County Civil Court Judge - District 9",
"level": "COUNTY",
"position_type": null,
"runoff_date": null,
"judicial": true,
"primary_filing_end": "2020-04-02"
}
],
"address": "350+5th+New+York+NY+10118",
"coords": {
"latitude": 40.7482436,
"longitude": -73.9851073
},
"page_size": 1000,
"result_count": 8
}

Notes on Levels

We have six primary "levels" for a position

  • federal - Federal positions (President, Vice President, US House, US Senate)
  • state - State level positions, executive and legislative
  • county - County level positions such as commissioners
  • city (introduced 2020) - Incorporated municipalities and places
  • local - Townships + Un-incorproated local positions
  • party - Intra-party positions

Notes on election results

In the case of a PAST election, the election result will be in the candidate object returned above as the election_result object. It can take one of three values (LOSE, WIN, RUNOFF, PRIMARY WIN). Below is an example of a snippet of the candidate response with an election result in it.

"first_name": "Clare",
"last_name": "Quish",
"election_result": "WON",
"suffix": "",
"incumbent": false,
"position_id": 78977,
"election_id": 5,
"election_day": "2018-03-20",

The best way to make sure you get only the values for the election you want is to query on the election_date parameter. Once the election passes, we'll being updating the election_result flags.

Election results can mean different things for different types of primary election races. If the position is Louisiana style (la_style: true), then the position can be won outright in the primary. In a normal primary election (la_style: false), this is not the case.

In a normal (la_style: false) primary election:

RUNOFF means the candidate is advancing to a primary runoff. PRIMARY WIN means the candidate won the primary and is moving on to the general election.

In a Louisiana Style (la_style: true) primary election:

WON means the candidate won outright. RUNOFF means the candidate is advancing to the runoff/general election.