VIP Format Specification Version 3.0

General Introduction

Welcome to the Voting Information Project's (VIP) open XML and flat file (CSV) format. This data format provides an easy way to produce data that lets programmers take a voter's address, compare it to street segments, and determine that voter's precinct (or precinct split). Knowing a voter's precinct allows information disseminators (such as Google and Microsoft) provide voters with their official polling locations (and early voting sites), ballots (including both candidates and referenda), local election administrations, and election officials.

General XML Specification

The actual election information specifies collections of elements, some containing links between each other. The entire set of tags must be encapsulated in a root object named vip_object. See the sample xml file and xsd file for more details.

Each top-level tag is a container for other fields, described in their own section. The only required top-level tags are the source object and the election object, each of which must be present exactly once. All other top-level tags can be repeated an unlimited number of times, or not included at all; order of top-level tags does not matter. Each top-level tag is required to have a single attribute, "id", which is required to be: (1) an integer, and (2) unique in a data file. The id attribute for the state object is often the state's FIPS number, but this is not required. The id attributes are not required to remain constant for the same piece of semantic data across multiple productions of the feed. (For example, candidate Michael Smith, running for dogcatcher in Iowa, is not required to have the same candidate id attribute each time the state of Iowa publishes data.)

In general, subtag data can appear a maximum of one time within each top-level tag object and in any order. Exceptions are noted below.

For the data itself, the special characters &, <, and > need to be encoded as &amp;, &lt;, and &gt;, respectively

Naming convention

The file containing the VIP feed should be named vipFeed-[FIPS code for state or county]-[election year]-[election month]-[election day].xml. If the file is zipped, the file extensions of .zip or .xml.zip are also acceptable.

For instance, vipFeed-19-2012-11-06.zip denotes Iowa's (the FIPS code for IA is 19) feed for the Nov 6, 2012 election.

Comma-delimited flat files (CSV)

If your office is producing flat files, they must be comma-delimited .txt files. The CSV column names differ slightly from XML tag names.

Examples of the flat files are below each XML example and include the necessary files to link those elements together as needed. To read more about the flat files, view complete file header templates, and review example files, you can do so in this GitHub repository.

Source items

The Source object represents the organization that is publishing the information. This object is the only required object in the feed file, and only one source object is allowed to be present.
Tag Data type   Description Error handling
name String Required The name field specifies the name of the organization that is providing the information. If the name field is invalid, the implementation is required to ignore the source element containing it.
vip_id Integer Required The vip_id field specifies the ID of the organization as assigned by VIP. This ID is not an attribute so as not to interfere with organizations' own numbering conventions (since id attributes must be unique across the entire file). If the vip_id field is invalid, the implementation is required to ignore the source element containing it.
datetime DateTime Required The datetime field specifies the date and time of the feed production. The date/time is considered to be in the timezone local to the organization. This datetime is required to match the datetime specified in the feed's filename. If the datetime field is not present or invalid, the implementation is required to ignore the source element containing it.
description String Optional The description specifies both the nature of the organization providing the data and what data is in the feed. If the description is invalid, the implementation is required to ignore it.
organization_url String Optional The organization_url field contains a URL to the home page of the organization publishing the data If the organization_url field is invalid, the implementation is required to ignore it.
feed_contact_id Integer Optional The feed_contact_id is a reference to (an election official object) the person who will respond to inquiries about the information contained within the file. If the feed_contact_id field is invalid, the implementation is required to ignore it.
tou_url String Optional The tou_url is the website where the Terms of Use for the information in this file can be found. If the tou_url field is invalid, the implementation is required to ignore it.

Example XML for a source element:


            


            
If your office is producing flat files, the source element is in a comma-delimited .txt file named source.txt. Example file for a source element:

            

          


          

            
Election items


            

              The Election object represents an Election Day, which usually consists of many individual contests and/or referenda. A feed must contain exactly one Election object. All relationships in the feed (e.g., street segment to precinct [split] to polling location) are assumed to relate only to the Election specified by this object. It is permissible, and recommended, to combine unrelated contests (e.g., a special election and a general election) that occur on the same day into one feed with one Election object.
              
		

                  Tag
                  Data type
                   
                  Description
                  Error handling
		

              
              
		

                  date
                  Date
                  Required
                  The date field specifies when the election is being
		    held. The date is considered to be in the timezone local to the state
		    holding the election.
                  If the date is not present or invalid, the
		    implementation is required to ignore the election element
		    containing it.
		

		

                  election_type
                  String
                  Optional
                  The election_type field specifies the highest
		    controlling authority for election (e.g., federal, state, county, city,
		    town, etc.)
                  If the election_type field is invalid, the
		    implementation is required to ignore the election_type field.
		

		

                  state_id
                  Integer
                  Required
                  The state_id specifies a link to the state element
		    where the election is being held.
                  If the state_id is not present or invalid, the
		    implementation is required to ignore the election element
		    containing it.
		

		

                  statewide
                  yesNoEnum
                  Optional
                  The statewide specifies whether the election is
		    statewide. Valid items are "yes" and "no".
                  If the statewide is not present or invalid, the
		    implementation is required to default to "yes".
		

		

                  registration_info
                  String
                  Optional
                  The registration_info specifies information about
		    registration for this election either as text or a URL.
                  If the registration_info field is invalid, the
		    implementation is required to ignore it.
		

		

                  absentee_ballot_info
                  String
                  Optional
                  The absentee_ballot_info specifies information about
		    requesting absentee ballots either as text or a URL
                  If the absentee_ballot_info field isinvalid, the
		    implementation is required to ignore it.
		

		

                  results_url
                  String
                  Optional
                  The results_url field contains a URL where results
		    for the election may be found
                  If the results_url field is invalid, the
		    implementation is required to ignore it.
		

		

                  polling_hours
                  String
                  Optional
                  The polling_hours field contains the hours (in local
		    time) that Election Day polling locations are open. If polling hours
		    differ in specific polling locations, alternative hours may be
		    specified in the Polling Location object.
                  If the polling_hours field is invalid or missing, the
		    implementation is required to ignore it.
		

		

                  election_day_registration
                  yesNoEnum
                  Optional
                  The election_day_registration specifies if a voter can register on the same day of the election (i.e., the last day of the election). Valid items are "yes" and "no".
                  If the election_day_registration field is invalid or missing, the
		    implementation is required to ignore it and not assume one way or the other.
		

		

                  registration_deadline
                  Date
                  Optional
                  The registration_deadline field specifies the last day to register for the election with the possible exception of Election Day registration.
                  If the registration_deadline field is invalid or missing, the
		    implementation is required to ignore it.
		

		

                  absentee_request_deadline
                  Date
                  Optional
                  The absentee_request_deadline field specifies the last day to request an absentee ballot.
                  If the absentee_request_deadline field is invalid or missing, the
		    implementation is required to ignore it.
		

              
            


            
Example XML for an election element:

            


            
If your office is producing flat files, the election element is in a comma-delimited .txt file named election.txt. Example file for an election element:

            

          


          

            
State items


            

              The State object includes state-wide election information. The ID attribute is often the state's FIPS code.  Subtag data must appear in the order below.
              
		

                  Tag
                  Data type
                   
                  Description
                  Error handling
		

              
              
		

                  name
                  String
                  Required
                  The name is the name of a state, such as Alabama
                  If the name field is not present or invalid, the
		    implementation is required to ignore the state element
		    containing it.
		

		

                  election_administration_id
                  Integer
                  Optional
                  The election_administration_id links to the state's election administration object.
                  If the election_administration_id field is invalid the
		    implementation is required to ignore it.
		

		

                  early_vote_site_id
                  Integer
                  Optional;
multiple allowed		
                  The early_vote_site_id specifies a link to the state's early vote or ballot drop locations. If early vote centers or ballot drop locations are state-wide (e.g., anyone in the state can use them), they should be specified here.
                  If the early_vote_site_id field is missing or invalid, the implementation is required to ignore it.
		

              
            


            
Example XML for a state element:

            


            
If your office is producing flat files, the state element is in a comma-delimited .txt file named state.txt. Example file for a state element:

            

          


          

            
Locality items

            

              The Locality object represents the jurisdiction below the state (e.g., county). Subtag data must appear in the order below.
              
		

                  Tag
                  Data type
                   
                  Description
                  Error handling
		

              
              
		

                  name
                  String
                  Required
                  The name specifies the locality's name
                  If the name field is invalid or not present, the
		    implementation is required to ignore the locality element
		    containing it.
		

		

                  state_id
                  Integer
                  Required
                  The state_id links to the locality's state
                  If the state_id field is invalid or not present, the
		    implementation is required to ignore the locality element
		    containing it.
		

		

                  type
                  String
                  Required
                  The type specifies the locality's type. Valid values are: county, city, town, township, borough, parish, village, and region (for Alaska). 
                  If the type field is invalid or not present, the
		    implementation is required to ignore the locality element
		    containing it.
		

		

                  election_administration_id
                  Integer
                  Optional
                  The election_administration_id links to the locality's election administration object.
                  If the election_administration_id field is invalid the
		    implementation is required to ignore it.
		

		
		

                  early_vote_site_id
                  Integer
                  Optional;
multiple allowed		
                  The early_vote_site_id specifies a link to the locality's early vote or ballot drop locations. If early vote centers or ballot drop locations are locality-wide, they should be specified here.
                  If the early_vote_site_id field is missing or invalid, the implementation is required to ignore it. However, the implementation should still check to see if there are any early vote sites associated with this locality's state.
		

		
              
            


            
Example XML for a locality element:

            


            
If your office is producing flat files, the locality elements are in a comma-delimited .txt file named locality.txt. Example file for localities:

            

          


          

            
Precinct


            

              The Precinct object represents a precinct, which is contained within a Locality. Subtag data must appear in the order below. 

While the id attribute does not have to be static across feeds for one election, the combination of vip_id, locality.name, precinct.ward, precinct.name, and precinct.number should remain constant across feeds for one election. (Note that not all of the fields just mentioned are required -- omitting those non-required fields is fine.
              
		

                  Tag
                  Data type
                   
                  Description
                  Error handling
		

              
              
		

                  name
                  String
                  Required
                  The name specifies the precinct's name (or number if no name exists)
                  If the name field is invalid or not present, the
		    implementation is required to ignore the precinct element
		    containing it.
		

		

                  number
                  String
                  Optional
                  The number specifies the precinct's number (e.g., 32 or 32A -- alpha characters are legal). Should be used if the name field is populated by a name and not a number.
                  If the code field is invalid or not present, the
		    implementation is required to ignore it.
		

		

                  locality_id
                  Integer
                  Required
                  The locality_id links to the locality that comprises
		    the precinct
                  If the locality_id field is invalid or not present,
		    the implementation is required to ignore the precinct element
		    containing it.
		

		

                  electoral_district_id
                  Integer
                  Optional;
multiple allowed		
                  The electoral_district_id links to an electoral district (e.g., congressional district, state house district, school board district) that the precinct belongs to. Highly Recommended if candidate information is to be provided. Multiple allowed and recommended to specify the geography of multiple electoral districts. If an electoral district splits a precinct, use the precinct_split object and do not specify that particular electoral district in this object.
                  If the electoral_district_id field is invalid or not present,
		    the implementation is required to ignore the precinct element
		    containing it.
		

		

                  ward
                  String
                  Optional
                  The ward specifies the ward the precinct is contained
		    within
                  If the ward field is missing or invalid, the implementation is required
		    to ignore it.
		

		

                  mail_only
                  yesNoEnum
                  Optional
                  The mail_only specifies whether voters in the precinct vote only by mailing their ballots (with the possible option of dropping off their ballots as well). Valid values are "yes" and "no", with "no" being the default if the tag is not present.
                  If the mail_only field is missing or invalid, the implementation is required to default to "no".
		

		

                  polling_location_id
                  Integer
                  Optional;
multiple allowed		
                  The polling_location_id specifies a link to the
		    precinct's polling location object. Multiple polling_location_id tags may be specified, but this use should be reserved for when multiple Election-Day-only vote locations serve specific precincts. Use the early_vote_site for early vote centers.
                  If the polling_location_id field is missing or invalid, the
		    implementation is required to ignore it.
		

		

                  early_vote_site_id
                  Integer
                  Optional;
multiple allowed		
                  The early_vote_site_id specifies a link to the
		    precinct's early vote sites or ballot drop location. This tag is especially important for precinct-specific vote sites or drop locations, but should be disregarded for locality-level (i.e., county-level) sites where multiple drop locations serve multiple precincts. In this case, precinct multiple early_vote_site_id tags may be specified, but would constitute redundant information.
                  If the early_vote_site_id field is missing or invalid, the implementation is required to ignore it with the following exception. In all cases, but especially if the precinct is mail-only: if the early_vote_site_id field is missing then the implementation is required to assume that any early_vote_site objects linked from this precinct's locality object are valid early vote/drop locations for this precinct.
		

		

                  ballot_style_image_url
                  String
                  Optional
                  The ballot_style_image_url specifies a URL that points to an image of the ballot that a person who lives in this precinct will vote on. If multiple ballot styles exist in this precinct, ignore this field.
                  If the ballot_style_image_url field is missing or invalid, the implementation is required to ignore it.
		

              
            


            
Three example XML's for a precinct element. The first is a standard, in-person precinct. The second is a mail-in precinct with a precinct specific drop location. The third is a mail-in precinct with multiple drop locations spread around the county.


            

            

            


            
If your office is producing flat files, the precinct elements are in a comma-delimited .txt file named precinct.txt. Example file for precincts:

            

          


          

            
Precinct Split


            

              The Precinct Split object represents a part of a precinct. The Precinct Split object will link to its "parent" Precinct object. Subtag data must appear in the order below.
              
		

                  Tag
                  Data type
                   
                  Description
                  Error handling
		

              
              
		

                  name
                  String
                  Required
                  The name specifies the precinct split's name (or
		    number)
                  If the name field is invalid or not present, the
		    implementation is required to ignore the precinct split element
		    containing it.
		

		

                  precinct_id
                  Integer
                  Required
                  The precinct_id specifies the precinct that comprises
		    the precinct split.
                  If the precinct_id field is invalid or not present,
		    the implementation is required to ignore the precinct split
		    element containing it.
		

		

                  electoral_district_id
                  Integer
                  Optional;
multiple allowed		
                  The electoral_district_id links to an electoral district (e.g., congressional district, state house district, school board district) that the precinct split belongs to. Highly Recommended if candidate information is to be provided. Multiple allowed and recommended to specify the geography of multiple electoral districts.
                  If the electoral_district_id field is invalid or not present,
		    the implementation is required to ignore the precinct element
		    containing it. Takes precedence over any conflicting information in the parent precinct object.
		

		

                  polling_location_id
                  Integer
                  Optional;
multiple allowed		
                  The polling_location_id specifies a link to the
		    precinct split's polling location object. Multiple polling_location_id tags may be specified, but this use should be reserved for when multiple Election-Day-only vote locations serve specific precincts splits. Use the early_vote_site for early vote centers.
                  If the polling_location_id field is invalid, the
		    implementation is required to ignore it.
		

		

                  early_vote_site_id
                  Integer
                  Optional;
multiple allowed		
                  The early_vote_site_id specifies a link to the
		    precinct split's early vote sites or ballot drop location. This tag is especially important for precinct split-specific vote sites or drop locations, but should be disregarded for precinct-level or locality-level (i.e., county-level) sites where multiple drop locations serve multiple precinct splits. In this case, multiple early_vote_site_id tags at the precinct-split level may be specified, but would constitute redundant information.
                  If the early_vote_site_id field is missing or invalid, the implementation is required to ignore it with the following exception. In all cases, but especially if the precinct-split is mail-only: if the early_vote_site_id field is missing then the implementation is required to assume that any early_vote_site objects linked from this precinct split's precinct object or (failing that) this precinct split's locality object are valid early vote/drop locations for this precinct split.
		

		

                  ballot_style_image_url
                  String
                  Optional
                  The ballot_style_image_url specifies a URL that points to an image of the ballot that a person who lives in this precinct split will vote on.
                  If the ballot_style_image_url field is missing or invalid, the implementation is required to ignore it.
		

              
            


            
Example XML for a precinct split element:

            


            
If your office is producing flat files, the precinct split elements are in a comma-delimited .txt file named precinct_split.txt. Example file for precinct_splits:

            

          


          

            
Election Administration


            

              The Election Administration represents an institution for serving a locality's (or state's) election functions.
              
		

                  Tag
                  Data type
                   
                  Description
                  Error handling
		

              
              
		

                  name
                  String
                  Optional
                  The name specifies the name of the office/administration. While this field is optional for backwards compatibility reasons, it is recommended to be specified. Note the default value if unspecified.
                  If the name field is invalid or not present,
		    the implementation is required to use "Election Administration" as the default.
		

		

                  eo_id
                  Integer
                  Optional
                  The eo_id links to the election official object for the person in charge of the office/administration.
                  If the eo_id field is invalid or not present,
		    the implementation is required to ignore it.
		

		

                  ovc_id
                  Integer
                  Optional
                  The ovc_id links to the election official object for the contact person for overseas voters.
                  If the ovc_id field is invalid or not present,
		    the implementation is required to ignore it.
		

		

                  physical_address
                  simpleAddressType
                  Optional
                  The physical_address element specifies the election administration's office street address.
                  If the physical_address field is invalid or not present,
		    the implementation is required to ignore it.
		

		

                  mailing_address
                  simpleAddressType
                  Optional
                  The mailing_address element specifies the election administration's mailing address.
                  If the mailing_address field is invalid or not present,
		    the implementation is required to ignore it.
		

		

                  elections_url
                  String
                  Optional
                  The elections_url specifies web address the administration's website.
                  If the elections_url field is invalid or not present,
		    the implementation is required to ignore it.
		

		

                  registration_url
                  String
                  Optional
                  The registration_url specifies web address for information on registering to vote.
                  If the registration_url field is invalid or not present,
		    the implementation is required to ignore it.
		

		

                  am_i_registered_url
                  String
                  Optional
                  The am_i_registered_url specifies the web address for information on whether an individual is registered.
                  If the am_i_registered_url field is invalid or not present,
		    the implementation is required to ignore it.
		

		

                  absentee_url
                  String
                  Optional
                  The absentee_url specifies the web address for information on absentee or early voting.
                  If the absentee_url field is invalid or not present,
		    the implementation is required to ignore it.
		

		

                  where_do_i_vote_url
                  String
                  Optional
                  The where_do_i_vote_url specifies web address for information on where an individual votes based on their address.
                  If the where_do_i_vote_url field is invalid or not present,
		    the implementation is required to ignore it.
		

		

                  what_is_on_my_ballot_url
                  String
                  Optional
                  The what_is_on_my_ballot_url specifies web address for information on what is on an individual's ballot.
                  If the whats_on_my_ballot_url field is invalid or not present,
		    the implementation is required to ignore it.
		

		

                  rules_url
                  String
                  Optional
                  The rules_url specifies a URL for the election rules
		    and laws (if any) for the jurisdiction of the administration
                  If the rules_url field is invalid the implementation
		    is required to ignore it.
		

		

                  voter_services
                  String
                  Optional
                  The voter_services item specify the services available
		    voters at the election administration building. Services might include:
		    registration, absentee ballot request, or early voting. Please use
		    complete sentences. 
                  If the voter_services field is invalid or not present,
		    the implementation is required to ignore it.
		

		

                  hours
                  String
                  Optional
                  The hours element specifies the hours of operation (in local time) of the election administration office.
                  If the hours field is invalid or not present,
		    the implementation is required to ignore it.
		

              
            


            
Example XML for an election administration element:


            


            
If your office is producing flat files, the election administration elements are in a comma-delimited .txt file named election_administration.txt. Example file for election administration offices:

            

          


          

            
Election Official


            

              The Election Official object comprises the name and contact information for an election official.
              
		

                  Tag
                  Data type
                   
                  Description
                  Error handling
		

              
              
		

                  name
                  String
                  Required
                  The name specifies the election official's name
                  If the name field is invalid or not present, the
		    implementation is required to ignore the Election Official element
		    containing it.
		

		

                  title
                  String
                  Optional
                  The title element specifies the election official's title in the office.
                  If the title field is invalid or not present,
		    the implementation is required to ignore it.
		

		

                  phone
                  String
                  Optional
                  The phone element specifies the election official's phone number, optionally including the extension.
                  If the phone field is invalid or not present,
		    the implementation is required to ignore it.
		

		

                  fax
                  String
                  Optional
                  The fax element specifies the election official's fax number.
                  If the fax field is invalid or not present,
		    the implementation is required to ignore it.
		

		

                  email
                  String
                  Optional
                  The email element specifies the election official's email address.
                  If the email field is invalid or not present,
		    the implementation is required to ignore it.
		

              
            


            
Example XML for an election official element:

            


            
If your office is producing flat files, the election official elements are in a comma-delimited .txt file named election_official.txt. Example file for election officials:

            

          


          

            
Polling Location


            

              The Polling Location object represents a site where voters cast ballots on Election Day.
              
		

                  Tag
                  Data type
                   
                  Description
                  Error handling
		

              
              
		

                  address
                  simpleAddressType
                  Required
                  The address specifies the polling location's address. It also optionally includes the polling location's name (e.g., Springfield Elementary).
                  If the address field is invalid or not present, the
		    implementation is required to ignore the polling location
		    element containing it.
		

		

                  directions
                  String
                  Optional
                  The directions specify further instructions for
		    locating the polling location.
                  If the directions field is invalid or not present,
		    the implementation is required to ignore it.
		

		

                  polling_hours
                  String
                  Optional
                  The polling_hours field contains the hours (in local
		    time) that Election Day polling locations are open. This information
		    overrides any information specified in the Election object.
                  If the polling_hours field is invalid or missing, the
		    implementation is required to ignore it.
		

		

                  photo_url
                  String
                  Optional
                  The photo_url is a url that points to a picture of this polling location. At the moment, one picture is permitted per polling location, though multiple pictures may be allowed in future revisions.
                  If the photo_url field is invalid or missing, the
		    implementation is required to ignore it.
		

              
            


            
Example XML for a polling location element:

            


            
If your office is producing flat files, the polling location elements are in a comma-delimited .txt file named polling_location.txt. Example file for polling locations:

            


            
If your office is producing flat files, the polling location elements are linked to precincts or precinct splits through a comma-delimited .txt file named precinct_polling_location.txt or precinct_split_polling_location.txt. Example files for polling locations linked to precincts or precinct splits:

            

            

          


          

            
Early Vote Site items


            

              The Early Vote Site object represents a place where ballots can be cast prior to the election, or drop boxes on Election Day. This object can represent: a registrar's office that offers early voting, a temporary early vote site, a ballot drop box, or similar location.
              
		

                  Tag
                  Data type
                  

                  		
                  Description
                  Error handling
		

              
              
		

                  name
                  String
                  Optional
                  The name specifies the ballot drop location's name. Including the name of the main service will be helpful: "Springfield Ballot Drop Location 2" or "East Springfield Early Vote Center" is preferred to "Springfield Center 2".
                  If the name field is invalid or not present, the
		    implementation is required to ignore it.
		

		

                  address
                  simpleAddressType
                  Required
                  The address specifies the ballot drop location's
		    address
                  If the address field is invalid or not present, the
		    implementation is required to ignore the ballot drop location
		    element containing it.
		

		

                  directions
                  String
                  Optional
                  The directions specify further instructions for
		    locating the ballot drop location.
                  If the directions field is invalid or not present,
		    the implementation is required to ignore it.
		

		

                  voter_services
                  String
                  Optional
                  The voter_services item specify the services available
		    voters at the early vote/ballot drop location. Services might include:
		    registration, absentee ballot request, or early voting. Please use
		    complete sentences. 
                  If the voter_services field is invalid or not present,
		    the implementation is required to ignore it.
		

		

                  start_date
                  Date
                  Optional
                  Highly recommended. The start_date specifies the first date for early voting (or ballot drop-off) at this site. 
                  If the start_date field is invalid or not present,
		    the implementation is required to ignore it and assume that the early vote site is operational.
		

		

                  end_date
                  Date
                  Optional
                  Highly recommended. The end_date specifies the last date for early voting (or ballot drop-off) at this site. 
                  If the end_date field is invalid or not present,
		    the implementation is required to ignore it and assume that the early vote site is operational.
		

		

                  days_times_open
                  String
                  Optional
                  The days_times_open item specify dates and times that the location is open for voter services. Please specify the days of the week (e.g., "Monday through Saturday") and times (e.g., "9am to 6pm"). 
                  If the days_times_open field is invalid or not present,
		    the implementation is required to ignore it.
		

              
            


            
Example XML for an early vote element:

            


            
If your office is producing flat files, the early vote site elements are in a comma-delimited .txt file named early_vote_site.txt. Example file for early vote sites:

            


            
If your office is producing flat files, the early vote site elements are linked to localities, state or precincts through a comma-delimited .txt file named locality_early_vote_site.txt, state_early_vote_site.txt or precinct_early_vote_site.txt. Example files for early vote sites linked to localities, state or precincts:

            

            

            

          


          

            
Contest items


            

              The Contest object represents a single contest, which could be between candidates, adoption of a resolution, or retention of judges (among other possibilities). The geographic scope of the Contest object is the Electoral District, which the Contest object links to.
              
		

                  Tag
                  Data type
                   
                  Description
                  Error handling
		

              
              
		

                  election_id
                  Integer
                  Required
                  The election_id specifies a link to the election
		    under which this contest is being held.
                  If the election_id is not present or invalid, the
		    implementation is required to ignore the contest element
		    containing it.
		

		

                  electoral_district_id
                  Integer
                  Required
                  The electoral_district_id specifies a link to the
		    electoral district for the contest (e.g., congressional district, state senate district).
                  If the electoral_district_id is not present or invalid,
		    the implementation is required to ignore the contest element
		    containing it.
		

		

                  type
                  String
                  Required
                  The type specifies the type of contest that is being
		    run (i.e., general, primary, run-off, referendum).
                  If the type field is invalid or not present, the
		    implementation is required to ignore the contest element
		    containing it.
		

		

                  partisan
                  yesNoEnum
                  Optional
                  The partisan field specifies whether the contest is
		    partisan (i.e., the candidates are official affiliated with a party,
		    including contests that are partisan primaries). Data should be either
		    "yes" or "no". (This field may is a candidate for deletion.)
                  If the partisan field is invalid, the implementation
		    is required to ignore it.
		

		

                  primary_party
                  String
                  Optional
                  The primary_party field specifies the name of the
		    party the contest is for, if this is a single-party contest (such as a
		    Democratic primary).
                  If the primary_party field is invalid, the
		    implementation is required to ignore it.
		

		

                  electorate_specifications
                  String
                  Optional
                  The electorate_specifications field specifies any changes to the eligible electorate for this contest past the usual, "all registered voters" electorate. This subtag will most often be used for primaries and local elections. In primaries, voters may have to be registered as a specific party to vote, or there may be special rules for which ballot a voter can pull. In some local elections, non-citizens can vote.
                  If the electorate_specifications field is invalid, the
		    implementation is required to ignore it, and the implementation may assume that all registered voters are eligible to vote.
		

		

                  special
                  yesNoEnum
                  Optional
                  The special field specifies whether the contest is
		    being held outside of the normal cycle for that office. Data should be
		    either "yes" or "no"; the default is "no".
                  If the special field is invalid, the implementation
		    defaults to "no".
		

		

                  office
                  String
                  Optional
                  Highly recommended (except for referenda). The office field specifies the name of the office
		    that the contest is deciding and should be identical to what the voter sees on his/her ballot. Should only be blank for referenda.
                  If the office field is invalid, the implementation is
                    required to ignore it.
		

		

                  filing_closed_date
                  Date
                  Optional
                  The filing_closed_date field specifies the last date to file as a candidate for this contest.
                  If the filing_closed_date field is invalid, the implementation is required to ignore it.
		

		

                  number_elected
                  Integer
                  Optional
                  The number_elected field specifies the number of
		    candidates elected to the office in this contest.
                  If the number_elected field is invalid or missing,
		    the implementation defaults to 1.
		

		

                  number_voting_for
                  Integer
                  Optional
                  The number_voting_for field specifies the number of
		    candidates elected to the office in this contest.
                  If the number_voting_for field is invalid or missing,
		    the implementation defaults to 1.
		

		

                  ballot_id
                  Integer
                  Optional
                  The ballot_id field specifies a link to the ballot for this contest.
                  If the ballot_id field is invalid, the implementation
		    is required to ignore it.
		

		

                  ballot_placement
                  Integer
                  Optional
                  The ballot_placement the placement of this contest among the other contests in the election. For instance, the gubernatorial contest, on the top of the ballot, would have an a ballot_placement value of "1" and all of the congressional contests might have a value attribute of "2". Since each voter only votes in one congressional contest, there would be no ambiguity for ballot placement. Numbers need not be consecutive.
                  If the ballot_placement field is invalid, the implementation is required to ignore it. In this case, the implementation should order a ballot in a logical way (i.e., more important elections toward the top) but note that the actual order by be different.
		

              
            


            
Example XML for a contest element:

            


            
If your office is producing flat files, the contest elements are in a comma-delimited .txt file named contest.txt. Example file for contests:

            

          


          

            
Electoral District items


            

              The Electoral District object represents the geographic area in which a single contest is held. Examples of Electoral District include: statewide, congressional district, a state senate district, and a fire district. The geographic area that comprises a Electoral District is defined by which precinct or precinct splits link to the Electoral District.
              
		

                  Tag
                  Data type
                   
                  Description
                  Error handling
		

              
              
		

                  name
                  String
                  Required
                  The name specifies the electoral area's name
                  If the name field is invalid or not present, the
		    implementation is required to ignore the electoral area
		    element containing it.
		

		

                  type
                  String
                  Optional
                  The type specifies the type of electoral area (e.g.,
		    statewide, state senate district, state house district, fire district,
		    congressional district, school district, etc.)
                  If the type field is invalid or not present, the
		    implementation is required to ignore it.
		

		

                  number
                  Integer
                  Optional
                  The number specifies the district number of the district. Example: 34, in the case of the 34th State Senate District. If a number is not applicable, instead of leaving the field blank, leave this field out of the object; empty strings are not valid for xs:integer fields.
                  If the number field is invalid or not present, the
		    implementation is required to ignore it.
		

              
            


            
Two examples of electoral area element.

            

            


            
If your office is producing flat files, the electoral district elements are in a comma-delimited .txt file named electoral_districts.txt. Example file for electoral districts:

            


            
If your office is producing flat files, the electoral district elements are linked to precincts or precinct splits through a comma-delimited .txt file named precinct_electoral_district.txt or precinct_split_electoral_district.txt. Example files for electoral districts linked to precincts or precinct splits:

            

            

          


          


            
Ballot items


            

              The Ballot object represents the ballot item for one contest. The Ballot object is linked to by the corresponding Contest object. The Ballot object links to the Candidate objects or Referendum objects that compose the ballot. Subtag data must appear in the order below.
              
		

                  Tag
                  Data type
                  

                  		
                  Description
                  Error handling
		

              
              
		

                  referendum_id
                  Integer
                  Optional
                  The referendum_id specifies a link to a referendum
		    element, and is used to link to a single referendum item on a ballot.
                  If the referendum_id field is invalid, the
		    implementation is required to ignore it.
		

		

                  candidate_id
                  Integer
                  Optional;
multiple allowed		
                  The candidate_id specifies a link to a candidate
		    element, and is used to link to a single candidate on a ballot.
		    Multiple (or zero) candidate_id tags may be present. Deprecated and flagged for removal: This
		    element has an optional attribute named sort_order that may be
		    specified, giving the ordering of the candidates as they appear on the
		    actual ballot; however, this tag is deprecated -- use candidate.sort_order instead.
                  If the candidate_id field is invalid, the
		    implementation is required to ignore it. If the sort_order attribute is invalid or missing the implementation is required to ignore it. In this case, the implementation should check for sort_order data in the candidate element. If none exists, the candidates should be ordered either alphabetically or randomly with a note specifying this ordering and that the true ballot ordering is likely to be different.
		

		

                  custom_ballot_id
                  Integer
                  Optional
                  The custom_ballot_id specifies a link to a custom
		    ballot element, and is used to place an uncommon ballot element (e.g.,
		    recall, retention) on the ballot.
                  If the candidate_id field is invalid, the
		    implementation is required to ignore it.
		

		

                  write_in
                  yesNoEnum
                  Optional
                  The write_in field specifies whether the ballot
		    includes a place for write-ins. Valid items are "yes" and "no".
                  If the write_in field is invalid, the implementation
		    is required to default to "yes" if a candidate_id
		    element is present and "no" otherwise.
		

		

                  image_url
                  String
                  Optional
                  The image_url links to a picture of this specific ballot item (i.e., one contest). This is not a link to the entire ballot with multiple contests. Because of the hundreds (or thousands) of possible permutations of ballot items combining into one full ballot, this schema does not provide for the linking to a full ballot.
                  If the image_url field is invalid, the implementation
		    is required to ignore it.
		

              
            


            
Example XML for a ballot element:

            


            
If your office is producing flat files, the ballot elements are in a comma-delimited .txt file named ballot.txt. Example file for ballot records (races or referenda):

            

          


          

            
Candidate items


            

              The candidate object represents a candidate. If a candidate is running in multiple contests, the same Candidate object may be used provided that the candidate's name, party, etc. appear the same in the ballot items for both contests.
              
		

                  Tag
                  Data type
                  

                  		
                  Description
                  Error handling
		

              
              
		

                  name
                  String
                  Required
                  The name specifies the full complete name of the
		    candidate, as it will appear on the ballot.
                  If the name field is not present or invalid, the
		    implementation is required to ignore the candidate element
		    containing it.
		

		

                  party
                  String
                  Optional
                  The party specifies the candidate's party affiliation
                  If the party field is invalid the implementation is required
		    to ignore it.
		

		

                  candidate_url
                  String
                  Optional
                  The candidate_url specifies the URL for the
		    candidate's official website
                  If the candidate_url field is invalid the
		    implementation is required to ignore it.
		

		

                  biography
                  String
                  Optional
                  The biography specifies the candidate's biographical
		    information.
                  If the biography field is invalid the implementation
		    is required to ignore it.
		

		

                  phone
                  String
                  Optional
                  The phone specifies the candidate's phone number.
                  If the phone field is invalid the implementation is required
		    to ignore it.
		

		

                  photo_url
                  String
                  Optional
                  The photo_url specifies the URL for a photo of the
		    candidate.
                  If the photo_url field is invalid the implementation
		    is required to ignore it.
		

		

                  filed_mailing_address
                  simpleAddressType
                  Optional
                  The filed_mailing_address specifies the mailing address the candidate when the candidate filed.
                  If the filed_mailing_address field is invalid the
		    implementation is required to ignore it.
		

		

                  email
                  String
                  Optional
                  The email specifies the email address of the
		    candidate.
                  If the email field is invalid the
		    implementation is required to ignore it.
		

		

                  sort_order
                  Integer
                  Optional
                  Recommended. The sort_order specifies position of the candidate on the ballot item for that contest.
                  If the sort_order field is invalid the
		    implementation is required to: order the candidates either alphabetically or randomly with a note specifying this ordering and that the true ballot ordering is likely to be different.
		

              
            


            
Example XML for a candidate element:


            


            
If your office is producing flat files, the candidate elements are in a comma-delimited .txt file named candidate.txt. Example file for candidates:

            


            
If your office is producing flat files, the ballot elements are linked to candidates through a comma-delimited .txt file named ballot_candidate.txt. Example file for candidates linked to ballot records:

            

          


          

            
Referendum items


            

              The Referendum object provides information about a referendum before the voters, including summary statements on each side.
              
		

                  Tag
                  Data type
                   
                  Description
                  Error handling
		

              
              
		

                  title
                  String
                  Required
                  The title specifies the full title of the referendum,
		    as it will appear on the ballot.
                  If the title field is not present or invalid, the
		    implementation is required to ignore the referendum element
		    containing it.
		

		

                  subtitle
                  String
                  Optional
                  The subtitle specifies the subtile for a referendum, as it appears on the ballot below the title.
                  If the subtitle field is invalid the implementation
		    is required to ignore it.
		

		

                  brief
                  String
                  Optional
                  The brief specifies a short summary of the referendum that is on the ballot below the title but above the text.
                  If the brief field is invalid the implementation is required
		    to ignore it.
		

		

                  text
                  String
                  Required
                  The text specifies the full text of the referendum as it appears on the ballot.
                  If the text field is not present or invalid the
		    implementation is required to treat it as if the text was an
		    empty string.
		

		

                  pro_statement
                  String
                  Optional
                  The pro_statement specifies a statement in favor of
		    the referendum. It does not necessarily appear on the ballot.
                  If the pro_statement field is invalid the
		    implementation is required to ignore it.
		

		

                  con_statement
                  String
                  Optional
                  The con_statement specifies a statement in opposition
		    to the referendum. It does not necessarily appear on the ballot.
                  If the con_statement field is invalid the
		    implementation is required to ignore it.
		

		

                  passage_threshold
                  String
                  Optional
                  The passage_threshold specifies the threshold of votes that the referendum needs in order to pass. The default is a simple majority (50% plus one vote). Other common thresholds are "three-fifths" and "two-thirds".
                  If the passage_threshold field is invalid or not present
		    the implementation defaults to "simple majority" or 50% + one vote.
		

		

                  effect_of_abstain
                  String
                  Optional
                  The effect_of_abstain specifies what effect abstaining
		    (not voting) on this proposition will have (i.e., whether abstaining is
		    considered a vote against it.)
                  If the effect_of_abstrain field is invalid or not present
		    the implementation is required to ignore it.
		

		

                  ballot_response_id
                  Integer
                  Required; multiple allowed
                  The ballot_response_id specifies a link to a ballot
		    response element. Multiple ballot_response_id tags may be
		    present. This element has an optional attribute named order that may be specified, giving the ordering of the responses as they appear on the
		    actual ballot.
                  If no ballot_response_id field is present or the field is invalid, the
		    implementation is required to ignore the referendum element
		    containing it.
		

              
            


            
Example XML for a referendum element:

            


            
If your office is producing flat files, the referendum elements are in a comma-delimited .txt file named referendum.txt. Example file for a referendum element:

            


            
If your office is producing flat files, the referendum elements are linked to ballot responses through comma-delimited .txt files named ballot_response.txt and referendum_ballot_response.txt. Example file for a referendum element linked to ballot responses and referendum ballot responses:

            

            

          


          

            
Custom Ballot items


            

              A Custom Ballot object represents a ballot for a contest that neither pits candidates against each other nor is a referendum. Examples include recall elections and the retention of judges. A Custom Ballot object consists of multiple Ballot Response objects and it links to these objects.
              
		

                  Tag
                  Data type
                   
                  Description
                  Error handling
		

              
              
		

                  heading
                  String
                  Required
                  The heading specifies the text at the top of the
		    ballot item.
                  If the heading field is not present or invalid, the
		    implementation is required to ignore the custom ballot element
		    containing it.
		

		

                  ballot_response_id
                  Integer
                  Required; multiple allowed
                  The ballot_response_id specifies a link to a ballot
		    response element. Multiple ballot_response_id tags may be
		    present. This element has an optional attribute named sort_order
		    that may be specified, giving the ordering of the elements as they
		    appear on the actual ballot. 
                  If the ballot_response_id field is missing or invalid, the
		    implementation is required to ignore the custom ballot element
		    containing it.
		

              
            


            
Example XML for a custom ballot element:

            


            
If your office is producing flat files, the custom ballot elements are in a comma-delimited .txt file named custom_ballot.txt. Example file for custom ballot records:

            

          


          


            
Ballot Response items


            

              A Ballot Response object represents a line on the ballot. Common examples might include "yes" or "no" for referenda, or a judge's name for a retention contest.
              
		

		  Tag
		  Data type
		   
		  Description
		  Error handling
		

              
              
		

		  text
		  String
		  Required
		  The text specifies the text of the response.
		  If the text field is not present or invalid, the
		    implementation is required to ignore the ballot response
		    element containing it.
		

		

                  sort_order
                  Integer
                  Optional
                  Recommended. The sort_order specifies position of the punches on the ballot item for that type of contest. Recommended for types of contests where the positions of the punches are fixed. Numbers are relative (with lowest appearing first) and need not be consecutive.
                  If the sort_order field is invalid the
		    implementation is required to ignore it. The implementation should check for a sort order in the ballot element. If none exists, the candidates should be ordered either alphabetically or randomly with a note specifying this ordering and that the true ballot ordering is likely to be different.
		

              
            


            
Four example XML's for a custom ballot response element:

            

	    

	    

	    


            
If your office is producing flat files, the custom ballot response elements are in a comma-delimited .txt file named custom_ballot_response.txt. Example file for custom ballot responses:

            

          


          

            
Street Segment


            

              A Street Segment objection represents a portion of a street and the links to the precinct (and possibly precinct split) that this geography (i.e., segment) is contained within. The start address house number must be less than the end address house number unless the segment consists of only one address in which case these values are equal.
              
		

                  Tag
                  Data type
                   
                  Description
                  Error handling
		

              
              
		

                  start_house_number
                  Integer
                  Required
                  The start_house_number is the house number that street segment start at. This value is very necessary for the street segment to make any sense. It must be less than (or equal to) the end_house_number. To specify any house on the street (or when using the "*" wildcard for street name), the best practice is to put 0 in this field.
                  If the start_house_number field is not present or invalid, the
		    implementation is required to ignore the street segment
		    element containing it. If the start_house_number is greater than the end_house_number the implementation may reverse the start or or end points or it may ignore the element containing it.
		

		

                  end_house_number
                  Integer
                  Required
                  The end_house_number is the house number that street segment ends at. This value is very necessary for the street segment to make any sense. It must be greater than (or equal to) the start_house_number. To specify any house on the street (or when using the "*" wildcard for street name), the best practice is to put a very large number such as 999999 in this field.
                  If the end_house_number field is not present or invalid, the
		    implementation is required to ignore the street segment
		    element containing it. If the end_house_number is less than the start_house_number the implementation may reverse the start or or end points or it may ignore the element containing it.
		

		

                  odd_even_both
                  oebEnum
                  Optional
                  The odd_even_both field specifies whether the odd side of the street (in terms of house numbers), the even side, or both are in included in the street segment. Valid strings are "odd", "even", or "both". It does not apply to start_apartment_number or end_apartment_number
                  If the odd_even_both field is not present or invalid, the
		    implementation is required default to odd.
		

		

                  start_apartment_number
                  Integer
                  Optional
                  The start_apartment_number is the apartment number that street segment start at. If this value is present then start_house_number must be equal to end_house_number.
                  If the start_apartment_number field is not present or invalid, the
		    implementation is required to ignore it and assume no distinction is made between apartment along the street segment.
		

		

                  end_apartment_number
                  Integer
                  Optional
                  The end_apartment_number is the apartment number that street segment ends at. If this value is present then start_house_number must be equal to end_house_number.
                  If the end_apartment_number field is not present or invalid, the
		    implementation is required to ignore it and assume no distinction is made between apartment along the street segment.
		

		

                  non_house_address
                  detailAddressType
                  Required
                  The non_house_address is the common street address (as well as city, state, and zip) of the start and end points of the segment. Note the type is a detailAddressType; specific information such as street direction should be included. 
                  If the non_house_address field is not present or invalid, the
		    implementation is required to ignore the street segment
		    element containing it. 
		

		

                  precinct_id
                  Integer
                  Required
                  The precinct_id references the precinct that contains the entire street segment
                  If the precinct_id field is not present or invalid, the implementation is required to ignore the street segment element containing it.
		

		

                  precinct_split_id
                  Integer
                  Optional
                  The precinct_split_id references the precinct split that contains the entire street segment
                  If the precinct_split_id field is not present or invalid, the
		    implementation is required to ignore the it.
		

              
            


            
Example XML for a street segment element: 

            


            
If your office is producing flat files, the street segment elements are in a comma-delimited .txt file named street_segment.txt. Example file for street segments:

            

          


          

            
Contest Result


            

              A Contest Result item gives the contest-wide information (e.g., overvotes) for a given contest and a specified geography. In addition to id attribute, includes required attribute called certification of type certificationEnum.
              
		

                  Tag
                  Data type
                   
                  Description
                  Error handling
		

              
              
		

                  contest_id
                  Integer
                  Required
                  The contest_id references the contest that this result element refers to.
                  If the contest_id field is not present or invalid, the
		    implementation is required to ignore the contest result element containing it.
		

		

                  jurisdiction_id
                  Integer
                  Required
                  The jurisdiction_id references the jurisdiction (e.g., state, locality, precinct, precinct split) that these results are from. This id number can refer to a state_id, locality_id, precinct_id, precinct_split_id, or (in the case of complete results) an electoral_district_id. Districts that split jurisdictions are fine, these results need not be for the entire referenced jurisdiction, just the part of the jurisdiction that intersects with the district.
                  If the jurisdiction_id field is not present or invalid, the implementation is required to ignore the contest result element containing it.
		

		

                  entire_district
                  yesNoEnum
                  Required
                  The entire_district field specifies whether the results represent the entire electoral district of the contest. The default is "no."
                  If the entire_district field is not present or invalid, the implementation is required default to no.
		

		

                  total_votes
                  Integer
                  Optional
                  The total_votes field represents the total number of all votes, including blank votes, overvotes, write-ins, and accepted provisional ballot. In the schema, total_votes = total_valid_votes + overvotes + blank votes.
                  If the total_votes field is not present or invalid, the implementation is required to ignore it.
		

		

                  total_valid_votes
                  Integer
                  Optional
                  The total_valid_votes field represents the total number of votes that counted for a candidate, including write-ins that were counted and accepted provisional ballot. This total excludes write-ins that were not tabulated, overvotes, blank votes, and rejected provisional ballots. 
                  If the total_valid_votes field is not present or invalid, the implementation is required to ignore it.
		

		

                  overvotes
                  Integer
                  Optional
                  The overvotes field represents the  number of votes in which the voter marked the ballot for more candidates than allowed.
                  If the overvotes field is not present or invalid, the implementation is required to ignore it.
		

		

                  blank_votes
                  Integer
                  Optional
                  The blank_votes field represents the number of votes that did not contribute to any valid candidate's total. Most common examples are: completely blank ballots and write-in ballots that were not aggregated. 
                  If the blank_votes field is not present or invalid, the implementation is required to ignore it.
		

		

                  accepted_provisional_votes
                  Integer
                  Optional
                  The accepted_provisional_votes field represents the number of provisional votes that were accepted.
                  If the accepted_provisional_votes field is not present or invalid, the implementation is required to ignore it. 
		

		

                  rejected_votes
                  Integer
                  Optional
                  The rejected_votes field represents the number of votes that were rejected, including both provisional ballots and judicially-rejected ballots. 
                  If the rejected_votes field is not present or invalid, the implementation is required to ignore it. 
		

              
            


            
Example XML for a contest result element:

            


            
If your office is producing flat files, the contest result elements are in a comma-delimited .txt file named contest_results.txt. Example file for contest results:

            

          


          

            
Ballot Line Result (e.g. Candidate Result)


            

              A Ballot Line Result provides the candidates' or referenda responses' vote totals. In addition to id attribute, includes required attribute called certification of type certificationEnum.
              
		

                  Tag
                  Data type
                   
                  Description
                  Error handling
		

              
              
		

                  contest_id
                  Integer
                  Required
                  The contest_id references the contest that this result element refers to.
                  If the contest_id field is not present or invalid, the
		    implementation is required to ignore the ballot line result element containing it.
		

		

                  jurisdiction_id
                  Integer
                  Required
                  The jurisdiction_id references the jurisdiction (e.g., state, locality, precinct, precinct split) that these results are from. This id number can refer to a state_id, locality_id, precinct_id, precinct_split_id, or (in the case of complete results) an electoral_district_id. Districts that split jurisdictions are fine, these results need not be for the entire referenced jurisdiction, just the part of the jurisdiction that intersects with the district.
                  If the jurisdiction_id field is not present or invalid, the implementation is required to ignore the ballot line result element containing it.
		

		

                  entire_district
                  yesNoEnum
                  Required
                  The entire_district field specifies whether the results represent the entire electoral district of the contest. The default is "no."
                  If the entire_district field is not present or invalid, the implementation is required default to no.
		

		

                  candidate_id
                  Integer
                  Optional
                  The candidate_id references the candidate that these results apply to.
                  If the candidate_id field is not present or invalid, the implementation should look for a ballot_response_id. If neither a candidate_id nor a ballot_response_id is present, the implementation is required to ignore the ballot line result element.
		

		

                  ballot_response_id
                  Integer
                  Optional
                  The ballot_response_id references the ballot response element that these results apply to. Ignore this item for contests with candidates; use for referenda and custom ballots.
                  If the ballot_response_id field is not present or invalid, the implementation should look for a ballot_response_id. If neither a ballot_response_id nor a candidate_id is present, the implementation is required to ignore the ballot line result element.
		

		

                  votes
                  Integer
                  Required
                  The votes field represents the total number of votes that the candidate received.
                  If the votes field is not present or invalid, the implementation is required to ignore the element containing it.
		

		

                  victorious
                  yesNoEnum
                  Optional
                  Whether the candidate or referendum response was elected/won. Multiple candidates can have victorious=yes in elections which elect multiple candidates. This field is very optional and feed providers should feel no compunction to perform the interesting queries that may be needed to calculate this information. The victorious items always reflects the district-wide results, even in ballot_line_response objects that correspond to sub-jurisdictions of the district (e.g., a precinct in a congressional district).
                  If the victorious field is not present or invalid, the implementation is required to ignore it.
		

              
            

            
Example XML for a ballot line result element:

            


            
If your office is producing flat files, the ballot line result elements are in a comma-delimited .txt file named ballot_line_result.txt. Example file for ballot line results:

            

          


          

            
Detail Address (Type) items


            

              A Detail Address is an address that includes details such as street direction. It is a type and not an object, so no ID is required.
              
		

                  Tag
                  Data type
                   
                  Description
                  Error handling
		

              
              
		

                  house_number
                  Integer
                  Optional
                  The house_number is the house number part of a street address. It may only be numeric. It is optional because: (1) some addresses do not have numbers ("A Second St."), (2) some addresses only have house number suffixes ("1/2 Second St."), and (3) a DetailAddress within a street_segment should not have a house number as it represents only the common aspects of the address. 
                  If the house_number field is not present or invalid, the
		    implementation is required to ignore it. If each of house_number, house_number_suffix, and house_number_prefix is blank, the address represents the entire street.
		

		

                  house_number_prefix
                  String
                  Optional
                  The house_number_prefix is the house number part of a street address. It may contain letters or slashes (e.g., 'B' in 'B22 Main St').
                  If the house_number_prefix field is not present or invalid, the implementation is required to ignore it. If each of house_number, house_number_suffix, and house_number_prefix is blank, the address represents the entire street.
		

		

                  house_number_suffix
                  String
                  Optional
                  The house_number_suffix is the house number part of a street address. It may contain letters or slashes (e.g., B or 1/2).
                  If the house_number_suffix field is not present or invalid, the
		    implementation is required to ignore it. If each of house_number, house_number_suffix, and house_number_prefix is blank, the address represents the entire street.
		

		

                  street_direction
                  String
                  Optional
                  The street_direction specifies the (inter-)cardinal direction of the street address (e.g., the "E" in "100 E Capitol St NE").
                  If the street_direction field is not present or invalid, the implementation is required to ignore it.
		

		

                  street_name
                  String
                  Required
                  The street_name is the name of the street for the address. A special wildcard, "*", denotes every street in the given city/town. It optionally may contain street direction, street suffix or address direction (e.g., both "Capitol" and "E Capitol St NE" are acceptable for the address "100 E Capitol St NE"), however this is not preferred. Preferred is street name alone (e.g. "Capitol").
                  If the street_name field is not present or invalid, the implementation is required to ignore the address element containing it.
		

		

                  street_suffix
                  String
                  Optional
                  The street_suffix is the abbreviated, non-directional suffix to the street name. An example is "St" for the address "100 E Capitol St NE".
                  If the street_suffix field is not present or invalid, the implementation is required to ignore it.
		

		

                  address_direction
                  String
                  Optional
                  The address_direction specifies the (inter-)cardinal direction of the entire address. An example is "NE" for the address "100 E Capitol St NE".
                  If the address_direction field is not present or invalid, the implementation is required to ignore it.
		

		

                  apartment
                  String
                  Optional
                  The apartment specifies the intra-building address. A prefix (e.g. "Apt", "Suite") is optional. Examples are "Apt 303", "303", "4G", "4th Floor".
                  If the apartment field is not present or invalid, the implementation is required to ignore it.
		

		

                  city
                  String
                  Required
                  The city specifies the city or town of the address.
                  If the city field is not present or invalid, the implementation is required to ignore the address element containing it.
		

		

                  state
                  String
                  Required
                  The state specifies the two-letter state abbreviation of the address.
                  If the state field is not present or invalid, the implementation is required to ignore the address element containing it.
		

		

                  zip
                  String
                  Required
                  Highly recommended. The zip specifies the zip code of the address. It may be 5 or 9 digits, and it may include a hyphen ('-'). It is required as it helps with geocoding, which is crucial for distributors.
                  If the zip field is not present or invalid, the implementation is required to ignore the address element containing it.
		

              
            

            
Example XML for Detail Addresses, which would appear within Street Segment objects: 

            

            

	    


          


          

            
Simple Address (Type) items


            

              A Simple Address is an address that combines each address line into one string. It is a type and not an object, so no ID is required.
              
		

                  Tag
                  Data type
                   
                  Description
                  Error handling
		

              
              
		

                  location_name
                  String
                  Optional
                  The location_name is names of the location specified by the address. It is optional. Example: Martin Luther King, Jr. Library. 
                  If the location_name field is not present or invalid, the
		    implementation is required to ignore it.
		

		

                  line1
                  String
                  Required
                  The line1 field is the first line of the address. It is required. Example: 1 Main St. NW
                  If the line1 field is not present or invalid, the
		    implementation is required to ignore the address element containing it.
		

		

                  line2
                  String
                  Optional
                  The line2 field specifies the second line of the address. Example: Second Floor
                  If the line2 field is not present or invalid, the implementation is required to ignore it.
		

		

                  line3
                  String
                  Optional
                  The line3 field specifies the third line of the address. Example: Cambridge University, Carlton Hall
                  If the line3 field is not present or invalid, the implementation is required to ignore it.
		

		

                  city
                  String
                  Required
                  The city specifies the city or town of the address.
                  If the city field is not present or invalid, the implementation is required to ignore the address element containing it.
		

		

                  state
                  String
                  Required
                  The state specifies the two-letter state abbreviation of the address.
                  If the state field is not present or invalid, the implementation is required to ignore the address element containing it.
		

		

                  zip
                  String
                  Optional
                  The zip specifies the zip code of the address. It may be 5 or 9 digits, and it may include a hypen ('-'). It is requires as it helps with geocoding, which is crucial for distributors.
                  If the zip field is not present or invalid, the implementation is required to ignore it.
		

              
            


            
Example XML for a Simple Addresses, which would appear within Polling Locations, Early Vote Sites, Candidates, and Election Administrations:


            

	    

            

          


          

            
Certification Enumeration

            

              The Certification Enumeration provides information of the level of completeness of results.
              
		

                  Enumeration
                  Description
		

              
              
		

                  unofficial_partial
                  Results are unofficial and incomplete. Total is expected to increase.
		

		

                  unofficial_complete
                  Results are unofficial, but complete. All sub-jurisdictions have reported. Results may change.
		

		

                  certified
                  Results are complete and certified.
		

              
            

          


          

            
Term definitions

            

              
Required

              
Any implementation that does not implement things noted as required is not considered a conforming implementation.

              
Optional

              
Conforming implementations may validly ignore anything marked optional and still be considered conforming.

            

          


          

            
Field types


            

              
		

                  Field type
                  Description
		

              
              
		

                  Date
                  Date fields are required to be valid xs:date format (as defined by The XML Schema specification), which is yyyy-mm-dd <optional timezone info>
		

		

                  DateTime
                  DateTime fields are required to be valid xs:dateTime format (as defined by The XML Schema specification), which is "YYYY-MM-DDThh:mm:ss" <optional timezone info>

                  		
		

		

                  String
                  String fields contain arbitrary UTF-8 text. These fields are required to be valid UTF-8. Further restrictions on the content of a String field may be included in each field description
		

		

                  Integer
                  Integer fields describe a numeric value. The value of an integer field is required to be representable as a two's complement 64 bit signed integer. That is, the value must be between -9223372036854775807 and 9223372036854775807
		

              
            

          


          
An implementation must not rely on identifiers being the same over multiple fetches of the same data.


	

	

	  
Top-Level Items

          
    
            
  1. Source
    2. 
            
  2. Election
    3. 
            
  3. State
    4. 
            
  4. Locality
    5. 
            
  5. Precinct
    6. 
            
  6. Precinct Split
    7. 
            
  7. Election Administration
    8. 
            
  8. Election Official
    9. 
            
  9. Polling Location
    10. 
            
  10. Early Vote Site
    11. 
            
  11. Contest
    12. 
            
  12. Electoral District
    13. 
            
  13. Ballot
    14. 
            
  14. Candidate
    15. 
            
  15. Referendum
    16. 
            
  16. Custom Ballot
    17. 
            
  17. Ballot Response
    18. 
            
  18. Street Segment
    19. 
            
  19. Contest Result
    20. 
            
  20. Ballot Line Result
    21. 
            
  21. Comma-delimited flat files (CSV)
    22. 
          

          
Custom Types

          
    
            
  1. Detail Address
    2. 
            
  2. Simple Address
    3. 
            
  3. Certification Enum
    4. 
          

	

      

    

    

      

	

	  
Partners

	  

	    Pew
	    Google
	  

	  
Collaborators

	  

	    Wordpress
	    Disqus
	    foursquare
	  

	  
	

	

	  
	    
	  
	  

	    Voting Information Project 

	    901 E St. NW 

	    Washington, DC 20004-2008
	  

	  
	  
	

	
	

	  ABOUT|
	  NEWS|
	  PROJECTS|
	  GET INVOLVED
	

	

	   TERMS OF SERVICE  |
	   PRIVACY POLICY  |
	   Website design by Oxide Design Co.  |
	   ©2014 Voting Information Project