What is the Voting Information Project?
The short answer is that the Voting Information Project is all about helping voters find information about their elections. To that end, we have developed an open data format with which state election divisions can publish their voting information. Other organizations or individuals, such as newspapers, search engines, and civic-minded technologists, will parse the data contributed by the states and disseminate the information in the form of easy-to-use websites, maps, and other tools.
We also have a long answer.
Please note that we do not deal with voting machine technology, individually-identifiable information, voter fraud, or any debates related to these topics.
Is there a fee to use data from the Voting Information Project?
I would like to disseminate the information collected in Voting Information Project’s format. How do I get started?
Data can be accessed for free from our feed download page, and the data is usually separated by state. For instance, the voting information for Ohio and Iowa are different files, but they share the same format. Learn about the Voting Information Project format by reading the documentation at the project’s Google code page. You can also join the group for developers and information distributors to learn about what others have done.
I am a part of the election division of a state or locality, or I am an organization that has data that fits your specification. How can I contribute?
See the next section of this FAQ.
I am a voter. Am I at the right place?
Not exactly. The Voting Information Project does not disseminate the information linked from these web pages ourselves. Instead, we rely on partner organizations, such as search engines and newspapers, as well as individual developers to make the data easy for you to access. Shortly, we’ll be providing links to these projects, but for now just keep your eye out for interesting applications that use Voting Information Project data.
Will states pass on individually-identifiable information to the Voting Information Project?
No. States will only provide data linking voting information to addresses, not to specific individuals. Users will be provided with a link to their state’s elections website in order to find out whether they are registered.
How can the Voting Information Project help me implement this spec?
The Voting Information Project team will work closely with your tech team and assist them in implementing the feeds based on published open Voting Information Project specs. There are mainly two components of implementation:
Identifying and mapping correct database elements to EVP XML specifications. This requires a good understanding of your:
- Repositories (databases, flat files, etc)
- Data organization (schema design, etc)
- Data extraction process (SQL, JDBC access, etc)
The Voting Information Project tech team can help you understand the Voting Information Project specification elements as well as suggest various options to extract data from your repositories. We can also assist you in writing some pseudo code or scripts. However, someone from your end should have a solid understanding of the data repositories and how data is organized in those repositories. Both the Voting Information Project team and your team can work together to get this implemented quickly and cost-effectively.
Generation of the XML document based on Voting Information Project XML specifications. The Voting Information Project tech team has provided sample code which can assist you in implementing the XML generator (see zip file on the Google code page). It has detailed instructions identifying the steps to follow to generate your XML feed. If you have any questions or concerns, please feel free to contact us.
Other states who have created feeds have also shared some of there work. Oregon has posted a run-through of their process to create a feed from MS-Access. Maryland has shared an example query to go from SQL to XML.
Producing a Feed File
I have a feed file ready for testing. What should I do with it?
First, download the most recent xsd schema validation file from the Voting Information Project’s Google code page. Check your file against that schema. If your file passes, please send the XML file using this form.
There are several ways to validate your feed file including:
- This website, though there is a file size limit.
- Apache’s XML Validation implementation.
- The UNIX command:
$ xmllint—schema http://election-info-standard.googlecode.com/files/vip_spec_v3.0.xsd your_feed.xml
- The VIP semantic checker checks for semantic correctness and also checks for duplicate identifiers and missing links. This tool works on versions 2.0+ of the VIP specification.
How do I make my feed file available to developers and information distributors?
Feed Location and Fetching:
In order for developers and information distributors to build applications using your state data, your feed must be made available for distributors to access. Through our feeds download page, distributors may download your feed from your server at regular intervals. In practice, the distributors will likely check your server for feed updates at least once a day. The feed retrieval system will only download the files on your server that were added or modified since the previous time that the system checked for feed updates.
Please follow these guidelines for hosting and naming your feed:
- You must host your own XML feed. It must be accessible via HTTP or HTTPS on a production server that can handle traffic generated by developers and information distributors accessing the feed.
- You can supply a single XML file or multiple XML files bundled together in a single zip (*.zip) file.
- The file name is vipFeed-ID where ID is your Voting Information Project-assigned ID number (FIPS5 for states). This ID is consistent with the source object in the feed.
If you supply a single XML file, you can provide either a plain text file or a compressed text file in zip format. The examples below show recommended file naming conventions.
- vipFeed-ID.xml if you provide a plain text file
- vipFeed-ID.xml.zip if you provide a zip file
In order for distributors to access the data, a username and password should not be required to access the feed on your server.
To ensure that a feed retrieval system receives a complete snapshot of your data and does not attempt to download incomplete files, we recommend you use the following process when posting files to your HTTP server. Many content acquisition systems will try to fetch all of the new or modified files in a particular directory (or set of directories). This process ensures that a system will not attempt to download a file until the file is complete.
Create your feed in a directory from which Google does not fetch content.
After your feed is complete and ready, create a symbolic link in a directory that is publicly accessible for fetching of your content. The symbolic link should point to the newly created feed.
Google’s content acquisition system will try to fetch all of the new or modified files in a particular directory (or set of directories). This process ensures that that system will not attempt to download a file until the file is complete.
How often should a state provide/update the feed?
Each state can decide how often they update their XML feed file. Even though voting information changes sporadically (and often in batches), we recommend setting up a nightly, automated job that will extract the requisite information from your voting information database(s). That way, you never have to worry about whether you are providing up-to-date information.
Feed Specification Questions
What data objects are required?
The only top-level objects required for a feed file to comply with the spec are the Source and Election objects. We expect states to include, at a minimum, locality objects and ballot information for statewide races. But we understand that some data are easier to access than others and that some information is simply not available. Priority should be first placed on publishing a valid feed file and then on gathering further information from various databases or from local officials.
Though recommended, IDs need not be stable from one published file to the next.
What is the best way to produce a file with unique IDs for each object?
We recommend that publishers use a prefix-system where each data object type has its own unique prefix. For instance, the IDs for localities would start with 101 and be followed by six digits (i.e., all localities would have IDs between 101,000,000 and 101,999,999). For precincts, you might choose to begin those IDs with the prefix 102 and have those values range between 102,000,000 and 102,999,999). All ID attributes must be unique throughout the entire file. The tag, however, is not subject to this rule as it is assigned by the project and is not an attribute.
What are localities?
Localities are the local jurisdictions that process voting information in your state. In most cases, localities will be counties. In other cases, such as in Connecticut, localities are better specified as towns.
What are tabulation areas and what is their relationship to localities and precincts?
Tabulation areas are districts (i.e., congressional districts, state house districts, fire districts). These districts may comprise multiple localities (e.g., counties) and may even cross the boundaries of these localities. The easiest way to specify the geography of a tabulation area is to list all of the precincts the make up the district. However, any combination of geography elements (state, locality, precinct, and precinct split) can be used to define the tabulation area. A few examples will help:
For a state, the first tabulation area you will want to create is the statewide tabulation area. Use the element to specify your state ID. You will only need one statewide tabulation area because you can link multiple statewide contests to this single statewide tabulation area.
For the next example, let’s imagine that a congressional district comprises six counties. (You should have detailed your county information as objects.) Create a tabulation area with congressional district and include six elements.
Perhaps one of your congressional districts comprises three full counties (of 40 precincts each) and half (e.g., 20 precincts of) a fourth county. In this case, you have two options. Option one is to list the three full counties with three ‘’ elements and the 20 extra precincts with 20 elements. Option two is to list all 140 precincts with 140 ‘’ elements.
The same mixing of geographic types applies to the element.
Some states might not have enough information to fully specify their congressional district tabulation areas (i.e., they do not have a list of precincts and their respective congressional districts). In these cases, we ask that you do not specify incomplete tabulation areas and instead ignore these congressional contests.
What about the Election Markup Language (EML)? Why aren’t you using that?
The Election Markup Language (EML) is a data standard that covers most of what the VIP’s format covers and more. While it’s very flexible, and is global, it has seen little adoption in the United States. To spur state election officials to publish their data in a common format, we designed a more focused format that is easier for states and U.S. organizations to adopt. During this process, we looked to the EML for inspiration and we plan on exporting VIP data into EML in the near future.