What is Ballot API?

Ballot API is a database that contains information for what is on voting
ballots for each election. You can query based on location to see the ballot for
that location. Alternatively, you can query based on measure to see the
precincts that contain that measure.

Why make Ballot API?

The purpose of this project is to make it easier to see what will be on your
ballot before you go vote. Most ballot databases are either local to their
particular jurisdiction (e.g. local county registrar of voters) or only contain
higher level measures (e.g. national measures/contests only). This project aims
to be a comprehensive source of ballot information for all levels of government.

How do you use Ballot API?

There are three ways to use the Ballot API. First, you can browse the database
by visiting http://www.ballotapi.com/api/ in a web browser. Second, you can
make API requests to http://www.ballotapi.com/api/ endpoints that are
documented below. Third, you can copy this repository to self-host the database
and make requests via either of the two methods described above to your
self-hosted repo (see "How to self-host" below on how to do this).

Current Status

This project is in active development. Please file issues if you find bugs or want to request changes.

API docs - done

Database schema - done

Test cases

API implementation (json) - in development

API implementation (html)

Demo webapp - in development

Continuous integration

Status reports

Database population

User experience refinement

Authentication

All requests are open to the public and do not need authentication.

Response Formats

If you request an individual object (e.g. /elections/123), you will receive just that object (see Object Formats). If you request a list of objects (e.g. /elections?dates=2014-01-01:2014-12-31), you will recieve a paginated list of objects in the following format:

Any API endpoint that returns a list of objects will accept optional limit=<int> and offset=<int> parameters in the request. See each endpoint for the default values of these parameters.

Object Formats

There are three base object formats: Election, Precinct, and Measure. Inside the
Precinct object, the "geo" field contains a GeoJSON object. Inside the Measure
object, the "choices" field contains a list of Choice objects. The rest of the
fields in all base objects are either integers or strings.

Precinct

Precinct objects contain information for a particular geographical area. They
are the lowest common denominator for ballot measures in a particular election,
so any location with that Precinct will have the same list of ballot measures.
NOTE: Precincts are unique across elections, so you cannot use the same Precinct
id for a different Election (since Precinct boundaries change over time). The
"info" field may be the same, but is not guaranteed to be. Tracking precinct
changes across Elections is outside of the scope of this project.

Measure Type

These are the types of measure (i.e. what kind of question is being asked). They will be one of the following strings:

"election" - voting is to elect a person or party

"measure" - voting is to decide on a specific initiative or policy

Voting Method

These are the voting methods for measures, which are the voting system used
for the choices. The API is agnostic to what kind of entity or contest is
actually being voted on (person, party, bond measure, etc.).

"plurality" - choose one choice

"approval" - choose all choices that you approve

"instant-runoff" - choose first and second choices

"ranked" - sort choices in order of preference (first is most preferred)

Threshold

These are the winning threshold requirements that the measure. The values in
this field are strings because thresholds are often not as simple as a given
number or percentage.

"1/2 + 1" - A majority is required (i.e. more than 50% of votes)

"2/3 + 1" - A two-thirds majority is required (i.e. more than 67% of votes)

"max, >30%" - The most voted for choice, and that choice has to win over 30% of all votes.

Need more. Please pull request!

Choice

Choice objects contain the details for each item in the choices list of the
Measure object. They do not have unique ids because they are always include in
the Measure object.

API Reference

All Ballot API endpoints respond to only GET requests (i.e. read-only). There
are json and html formats for every endpoint. You can specify which format by
appending ".json" or ".html" to the end of the endpoint.

?election_dates=<start_date>[:<end_date>[,...]]

Return only elections within a certain date range. You can omit either the start
or end dates to leave that side open ended. Dates are inclusive, so results
include elections that happen on the start or end dates. You can also specify a
single date, which is the equivalent to specifying that date as both the start
and end date. You can also have multiple date ranges, separated by commas.

?ids=<id>[,<id>,...]

?elections=<id>[,<id>,...]

Return only precincts that are part of these elections. Multiple elections can
be listed as comma separated ids, which will return precincts that contain any
of the listed elections (i.e. treated as OR).

?election_dates=<start_date>[:<end_date>[,...]]

Return only precincts that belong to elections within a certain date range. You
can omit either the start or end dates to leave that side open ended. Dates are
inclusive, so results include elections that happen on the start or end dates.
You can also specify a single date, which is the equivalent to specifying that
date as both the start and end date. You can also have multiple date ranges,
separated by commas.

?coords=<latitude>,<longitude>

?measures=<id>[,<id>,...]

Return only precincts that contain these measures. Multiple measures can be
listed as comma separated ids, which will return precincts that contain any of
the listed measures (i.e. treated as OR). Multiple measures parameters will
intersect the precincts returned by each measures parameter (i.e. treated as
AND).

?ids=<id>[,<id>,...]

?elections=<id>[,<id>,...]

Return only measures that are part of these elections. Multiple elections can
be listed as comma separated ids, which will return measures that contain any
of the listed elections (i.e. treated as OR).

?election_dates=<start_date>[:<end_date>[,...]]

Return only measures that belong to elections within a certain date range. You
can omit either the start or end dates to leave that side open ended. Dates are
inclusive, so results include elections that happen on the start or end dates.
You can also specify a single date, which is the equivalent to specifying that
date as both the start and end date. You can also have multiple date ranges,
separated by commas.

?precincts=<id>[,<id>,...]

Return only measures that are a part of these precincts. Multiple precincts can
be listed as comma separated ids, which will return measures that are a part of
any of the listed precincts (i.e. treated as OR). Multiple precincts parameters
will intersect the measures returned by each precincts parameter (i.e. treated
as AND).

To update to the latest version of the API, simply re-download this repo and
re-import the database.

License

Project License

This entire project (including all source code, documentation, and ballot data)
is released into the public domain.

This is free and unencumbered software released into the public domain.
Anyone is free to copy, modify, publish, use, compile, sell, or distribute this
software, either in source code form or as a compiled binary, for any purpose,
commercial or non-commercial, and by any means.
In jurisdictions that recognize copyright laws, the author or authors of this
software dedicate any and all copyright interest in the software to the public
domain. We make this dedication for the benefit of the public at large and to
the detriment of our heirs and successors. We intend this dedication to be an
overt act of relinquishment in perpetuity of all present and future rights to
this software under copyright law.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
For more information, please refer to http://unlicense.org

Dependency Licenses

While this project is released into the public domain, it does depend on other
open source projects. All dependencies are not included in the project licencse
are released under their respective open source licenses.