Elections: voterInfoQuery

Looks up information relevant to a voter based on the voter's registered address. Try it now.

The returned information may include
  • Polling places (including early polling sites) for a given residential street address
  • Contest and candidate information
  • Election official information

Request

HTTP request

GET https://www.googleapis.com/civicinfo/v2/voterinfo

Parameters

Parameter name Value Description
Required query parameters
address string The registered address of the voter to look up.
Optional query parameters
electionId long

The unique ID of the election to look up. A list of election IDs can be obtained at https://www.googleapis.com/civicinfo/{version}/elections.

If no election ID is specified in the query and there is more than one election with data for the given voter, the additional elections are provided in the otherElections response field.

If there is no live election for the voter address given, the response only returns the data if the election ID is specified.

We recommend, in this case, that any tool issue a second query with the election ID specified to ensure the correct polling location, contest, and election official information (when applicable) is provided to the user.

officialOnly boolean If set to true, only data from official state sources will be returned. (Default: false)

Request body

Do not supply a request body with this method.

Response

If successful, this method returns a response body with the following structure:

{
  "kind": "civicinfo#voterInfoResponse",
  "election": elections Resource,
  "otherElections": [
    elections Resource
  ],
  "normalizedInput": {
    "locationName": string,
    "line1": string,
    "line2": string,
    "line3": string,
    "city": string,
    "state": string,
    "zip": string
  },
  "pollingLocations": [
    {
      "address": {
        "locationName": string,
        "line1": string,
        "line2": string,
        "line3": string,
        "city": string,
        "state": string,
        "zip": string
      },
      "notes": string,
      "pollingHours": string,
      "name": string,
      "voterServices": string,
      "startDate": string,
      "endDate": string,
      "latitude": double,
      "longitude": double,
      "sources": [
        {
          "name": string,
          "official": boolean
        }
      ]
    }
  ],
  "earlyVoteSites": [
    {
      "address": {
        "locationName": string,
        "line1": string,
        "line2": string,
        "line3": string,
        "city": string,
        "state": string,
        "zip": string
      },
      "notes": string,
      "pollingHours": string,
      "name": string,
      "voterServices": string,
      "startDate": string,
      "endDate": string,
      "latitude": double,
      "longitude": double,
      "sources": [
        {
          "name": string,
          "official": boolean
        }
      ]
    }
  ],
  "dropOffLocations": [
    {
      "address": {
        "locationName": string,
        "line1": string,
        "line2": string,
        "line3": string,
        "city": string,
        "state": string,
        "zip": string
      },
      "notes": string,
      "pollingHours": string,
      "name": string,
      "voterServices": string,
      "startDate": string,
      "endDate": string,
      "latitude": double,
      "longitude": double,
      "sources": [
        {
          "name": string,
          "official": boolean
        }
      ]
    }
  ],
  "contests": [
    {
      "type": string,
      "primaryParty": string,
      "electorateSpecifications": string,
      "special": string,
      "ballotTitle": string,
      "office": string,
      "level": [
        string
      ],
      "roles": [
        string
      ],
      "district": {
        "name": string,
        "scope": string,
        "id": string
      },
      "numberElected": long,
      "numberVotingFor": long,
      "ballotPlacement": long,
      "candidates": [
        {
          "name": string,
          "party": string,
          "candidateUrl": string,
          "phone": string,
          "photoUrl": string,
          "email": string,
          "orderOnBallot": long,
          "channels": [
            {
              "type": string,
              "id": string
            }
          ]
        }
      ],
      "referendumTitle": string,
      "referendumSubtitle": string,
      "referendumUrl": string,
      "referendumBrief": string,
      "referendumText": string,
      "referendumProStatement": string,
      "referendumConStatement": string,
      "referendumPassageThreshold": string,
      "referendumEffectOfAbstain": string,
      "referendumBallotResponses": [
        string
      ],
      "sources": [
        {
          "name": string,
          "official": boolean
        }
      ]
    }
  ],
  "state": [
    {
      "name": string,
      "electionAdministrationBody": {
        "name": string,
        "electionInfoUrl": string,
        "electionRegistrationUrl": string,
        "electionRegistrationConfirmationUrl": string,
        "electionNoticeText": string,
        "electionNoticeUrl": string,
        "absenteeVotingInfoUrl": string,
        "votingLocationFinderUrl": string,
        "ballotInfoUrl": string,
        "electionRulesUrl": string,
        "voter_services": [
          string
        ],
        "hoursOfOperation": string,
        "correspondenceAddress": {
          "locationName": string,
          "line1": string,
          "line2": string,
          "line3": string,
          "city": string,
          "state": string,
          "zip": string
        },
        "physicalAddress": {
          "locationName": string,
          "line1": string,
          "line2": string,
          "line3": string,
          "city": string,
          "state": string,
          "zip": string
        },
        "electionOfficials": [
          {
            "name": string,
            "title": string,
            "officePhoneNumber": string,
            "faxNumber": string,
            "emailAddress": string
          }
        ]
      },
      "local_jurisdiction": (AdministrationRegion),
      "sources": [
        {
          "name": string,
          "official": boolean
        }
      ]
    }
  ],
  "mailOnly": boolean
}
Property name Value Description Notes
kind string Identifies what kind of resource this is. Value: the fixed string "civicinfo#voterInfoResponse".
election nested object The election that was queried.
otherElections[] list When there are multiple elections for a voter address, the otherElections field is populated in the API response and there are two possibilities:

1. If these elections occur on different days, the API returns the voting information of the first/earliest election. If the earliest election is not the intended election, specify the election ID of the desired election in a second API request using the electionId field.

2. If these elections occur on the same day, the API doesn’t return any polling location, contest, or election official information to ensure that an additional query is made. For user-facing applications, we recommend displaying these elections to the user to disambiguate. A second API request using the electionId field should be made for the election that is relevant to the user.
normalizedInput nested object The normalized version of the requested address
normalizedInput.locationName string The name of the location.
normalizedInput.line1 string The street name and number of this address.
normalizedInput.line2 string The second line the address, if needed.
normalizedInput.line3 string The third line of the address, if needed.
normalizedInput.city string The city or town for the address.
normalizedInput.state string The US two letter state abbreviation of the address.
normalizedInput.zip string The US Postal Zip Code of the address.
mailOnly boolean Specifies whether voters in the precinct vote only by mailing their ballots (with the possible option of dropping off their ballots as well).

Polling Locations, Early Vote Locations, and Drop Off Locations

Property name Value Description Notes
pollingLocations[] list Locations where the voter is eligible to vote on election day.
pollingLocations[].address nested object The address of the location.
pollingLocations[].address.locationName string The name of the location.
pollingLocations[].address.line1 string The street name and number of this address.
pollingLocations[].address.line2 string The second line the address, if needed.
pollingLocations[].address.line3 string The third line of the address, if needed.
pollingLocations[].address.city string The city or town for the address.
pollingLocations[].address.state string The US two letter state abbreviation of the address.
pollingLocations[].address.zip string The US Postal Zip Code of the address.
pollingLocations[].notes string Notes about this location (e.g. accessibility ramp or entrance to use).
pollingLocations[].pollingHours string A description of when this location is open.
pollingLocations[].name string The name of the early vote site or drop off location. This field is not populated for polling locations.
pollingLocations[].voterServices string The services provided by this early vote site or drop off location. This field is not populated for polling locations.
pollingLocations[].startDate string The first date that this early vote site or drop off location may be used. This field is not populated for polling locations.
pollingLocations[].endDate string The last date that this early vote site or drop off location may be used. This field is not populated for polling locations.
pollingLocations[].latitude string Latitude of the location, in degrees north of the equator. Note this field may not be available for some locations.
pollingLocations[].longitude string Longitude of the location, in degrees east of the Prime Meridian. Note this field may not be available for some locations.
pollingLocations[].sources[] list A list of sources for this location. If multiple sources are listed the data has been aggregated from those sources.
pollingLocations[].sources[].name string The name of the data source.
pollingLocations[].sources[].official boolean Whether this data comes from an official government source.
earlyVoteSites[] list Locations where the voter is eligible to vote early, prior to election day.
earlyVoteSites[].address nested object The address of the location.
earlyVoteSites[].address.locationName string The name of the location.
earlyVoteSites[].address.line1 string The street name and number of this address.
earlyVoteSites[].address.line2 string The second line the address, if needed.
earlyVoteSites[].address.line3 string The third line of the address, if needed.
earlyVoteSites[].address.city string The city or town for the address.
earlyVoteSites[].address.state string The US two letter state abbreviation of the address.
earlyVoteSites[].address.zip string The US Postal Zip Code of the address.
earlyVoteSites[].notes string Notes about this location (e.g. accessibility ramp or entrance to use).
earlyVoteSites[].pollingHours string A description of when this location is open.
earlyVoteSites[].name string The name of the early vote site or drop off location. This field is not populated for polling locations.
earlyVoteSites[].voterServices string The services provided by this early vote site or drop off location. This field is not populated for polling locations.
earlyVoteSites[].startDate string The first date that this early vote site or drop off location may be used. This field is not populated for polling locations.
earlyVoteSites[].endDate string The last date that this early vote site or drop off location may be used. This field is not populated for polling locations.
earlyVoteSites[].latitude string Latitude of the location, in degrees north of the equator. Note this field may not be available for some locations.
earlyVoteSites[].longitude string Longitude of the location, in degrees east of the Prime Meridian. Note this field may not be available for some locations.
earlyVoteSites[].sources[] list A list of sources for this location. If multiple sources are listed the data has been aggregated from those sources.
earlyVoteSites[].sources[].name string The name of the data source.
earlyVoteSites[].sources[].official boolean Whether this data comes from an official government source.
dropOffLocations[] list Locations where a voter is eligible to drop off a completed ballot. The voter must have received and completed a ballot prior to arriving at the location. The location may not have ballots available on the premises. These locations could be open on or before election day as indicated in the pollingHours field.
dropOffLocations[].address nested object The address of the location.
dropOffLocations[].address.locationName string The name of the location.
dropOffLocations[].address.line1 string The street name and number of this address.
dropOffLocations[].address.line2 string The second line the address, if needed.
dropOffLocations[].address.line3 string The third line of the address, if needed.
dropOffLocations[].address.city string The city or town for the address.
dropOffLocations[].address.state string The US two letter state abbreviation of the address.
dropOffLocations[].address.zip string The US Postal Zip Code of the address.
dropOffLocations[].notes string Notes about this location (e.g. accessibility ramp or entrance to use).
dropOffLocations[].pollingHours string A description of when this location is open.
dropOffLocations[].name string The name of the early vote site or drop off location. This field is not populated for polling locations.
dropOffLocations[].voterServices string The services provided by this early vote site or drop off location. This field is not populated for polling locations.
dropOffLocations[].startDate string The first date that this early vote site or drop off location may be used. This field is not populated for polling locations.
dropOffLocations[].endDate string The last date that this early vote site or drop off location may be used. This field is not populated for polling locations.
dropOffLocations[].latitude string Latitude of the location, in degrees north of the equator. Note this field may not be available for some locations.
dropOffLocations[].longitude string Longitude of the location, in degrees east of the Prime Meridian. Note this field may not be available for some locations.
dropOffLocations[].sources[] list A list of sources for this location. If multiple sources are listed the data has been aggregated from those sources.
dropOffLocations[].sources[].name string The name of the data source.
dropOffLocations[].sources[].official boolean Whether this data comes from an official government source.

Contests

Property name Value Description Notes
contests[] list Contests that will appear on the voter's ballot.
contests[].type string The type of contest. Usually this will be 'General', 'Primary', or 'Run-off' for contests with candidates. For referenda this will be 'Referendum'.
contests[].primaryParty string If this is a partisan election, the name of the party it is for.
contests[].electorateSpecifications string A description of any additional eligibility requirements for voting in this contest.
contests[].special string "Yes" or "No" depending on whether this a contest being held outside the normal election cycle.
contests[].ballotTitle string The official title on the ballot for this contest when available.
contests[].office string The name of the office for this contest.
contests[].level[] list The levels of government of which the office for this contest. There may be more than one in cases where a jurisdiction effectively acts at two different levels of government; for example, the mayor of the District of Columbia acts at locality level, but also effectively at both administrativeArea2 and administrativeArea1.

Valid values include: 
  • international -- International governments, such as the United Nations or European Union.
  • country -- National-level governments, such as the US Federal Government.
  • administrativeArea1 -- Governments of the top-level administrative subdivision of a country, such as US states.
  • regional -- Regional governments whose jurisdiction may cross standard administrative subdivisions; these are uncommon in the US but are common around large cities in other countries.
  • administrativeArea2 -- Governments of the second-level administrative subdivision of a country, such as US counties.
  • locality -- City or municipal governments.
  • subLocality1 -- Governments of the top-level administrative subdivision of a city, such as Washington, DC's wards.
  • subLocality2 -- Governments of the second-level administrative subdivision of a city,such as Washington, DC's Advisory Neighborhood Councils.
  • special -- Local districts that exist only for special-purpose governments, such as soil and water conservation districts.
contests[].roles[] list The roles which the office this contest is for fulfills. Roles are not meant to be exhaustive, or to exactly specify the entire set of responsibilities of a given office, but are meant to be rough categories that are useful for general selection from or sorting of a list of offices.

Valid values include:
  • headOfState -- The chief public representative of a government. The head of state of a country is usually called the President.
  • headOfGovernment -- The chief executive officer of a government. In the US, this is the President; in other countries, it is often the Prime Minister. At lower levels this may be a governor or mayor.
  • deputyHeadOfGovernment -- The officer responsible for assuming the head of government role in the event of the death or incapacity of the elected head of government. In the US, this is the Vice President. This office may have other duties as well.
  • governmentOfficer -- An elected executive-branch officer. In US states, this may include roles such as attorney general, comptroller, secretary or state, or treasurer.
  • executiveCouncil -- A member of an executive council that fulfills executive-branch roles as a group. Examples include Indiana county commissioners.
  • legislatorUpperBody -- A member of the upper body of a bicameral legislature, or the only body of a unicameral legislature.
  • legislatorLowerBody -- A member of the lower body of a bicameral legislature.
  • highestCourtJudge -- A justice of the top court of a particular government, such as a state Supreme Court.
  • judge -- A judge in any court that is not the top court of the government it serves.
  • schoolBoard -- A member of a local school board.
  • specialPurposeOfficer -- An officer that serves a single, defined purpose, such as a member of a soil-and-water conservation board or mosquito abatement officer.
contests[].district nested object Information about the electoral district that this contest is in.
contests[].district.name string The name of the district.
contests[].district.scope string The geographic scope of this district. If unspecified the district's geography is not known. One of: national, statewide, congressional, stateUpper, stateLower, countywide, judicial, schoolBoard, cityWide, township, countyCouncil, cityCouncil, ward, special

Acceptable values are:
  • "cityCouncil"
  • "citywide"
  • "congressional"
  • "countyCouncil"
  • "countywide"
  • "judicial"
  • "national"
  • "schoolBoard"
  • "special"
  • "stateLower"
  • "stateUpper"
  • "statewide"
  • "township"
  • "ward"
contests[].district.id string An identifier for this district, relative to its scope. For example, the 34th State Senate district would have id "34" and a scope of stateUpper.
contests[].numberElected long The number of candidates that will be elected to office in this contest.
contests[].numberVotingFor long The number of candidates that a voter may vote for in this contest.
contests[].ballotPlacement long A number specifying the position of this contest on the voter's ballot.
contests[].candidates[] list The candidate choices for this contest.
contests[].candidates[].name string The candidate's name.
contests[].candidates[].party string The full name of the party the candidate is a member of.
contests[].candidates[].candidateUrl string The URL for the candidate's campaign web site.
contests[].candidates[].phone string The voice phone number for the candidate's campaign office.
contests[].candidates[].photoUrl string A URL for a photo of the candidate.
contests[].candidates[].email string The email address for the candidate's campaign.
contests[].candidates[].orderOnBallot long The order the candidate appears on the ballot for this contest.
contests[].candidates[].channels[] list A list of known (social) media channels for this candidate.
contests[].candidates[].channels[].type string The type of channel. The following is a list of types of channels, but is not exhaustive. More channel types may be added at a later time. One of:
  • GooglePlus
  • YouTube
  • Facebook
  • Twitter
contests[].candidates[].channels[].id string The unique public identifier for the candidate's channel.
contests[].referendumTitle string The title of the referendum (e.g. 'Proposition 42'). This field is only populated for contests of type 'Referendum'.
contests[].referendumSubtitle string A brief description of the referendum. This field is only populated for contests of type 'Referendum'.
contests[].referendumUrl string A link to the referendum. This field is only populated for contests of type 'Referendum'.
contests[].referendumBrief string Specifies a short summary of the referendum that is typically on the ballot below the title but above the text. This field is only populated for contests of type 'Referendum'.
contests[].referendumText string The full text of the referendum. This field is only populated for contests of type 'Referendum'.
contests[].referendumProStatement string A statement in favor of the referendum. It does not necessarily appear on the ballot. This field is only populated for contests of type 'Referendum'.
contests[].referendumConStatement string A statement in opposition to the referendum. It does not necessarily appear on the ballot. This field is only populated for contests of type 'Referendum'.
contests[].referendumPassageThreshold string The threshold of votes that the referendum needs in order to pass, e.g. "two-thirds". This field is only populated for contests of type 'Referendum'.
contests[].referendumEffectOfAbstain string Specifies what effect abstaining (not voting) on the proposition will have (i.e. whether abstaining is considered a vote against it). This field is only populated for contests of type 'Referendum'.
contests[].referendumBallotResponses[] list The set of ballot responses for the referendum. A ballot response represents a line on the ballot. Common examples might include "yes" or "no" for referenda, or a judge's name for a retention contest. This field is only populated for contests of type 'Referendum'.
contests[].sources[] list A list of sources for this contest. If multiple sources are listed, the data has been aggregated from those sources.
contests[].sources[].name string The name of the data source.
contests[].sources[].official boolean Whether this data comes from an official government source.

Election Officials

Property name Value Description Notes
state[] list Local Election Information for the state that the voter votes in. For the US, there will only be one element in this array.
state[].name string The name of the jurisdiction.
state[].electionAdministrationBody nested object The election administration body for this area.
state[].electionAdministrationBody.name string The name of this election administrative body.
state[].electionAdministrationBody.electionInfoUrl string A URL provided by this administrative body for looking up general election information.
state[].electionAdministrationBody.electionRegistrationUrl string A URL provided by this administrative body for looking up how to register to vote.
state[].electionAdministrationBody.electionRegistrationConfirmationUrl string A URL provided by this administrative body for confirming that the voter is registered to vote.
state[].electionAdministrationBody.electionNoticeText string A last minute or emergency notification text provided by this administrative body.
state[].electionAdministrationBody.electionNoticeUrl string A URL provided by this administrative body for additional information related to the last minute or emergency notification.
state[].electionAdministrationBody.absenteeVotingInfoUrl string A URL provided by this administrative body for information on absentee voting.
state[].electionAdministrationBody.votingLocationFinderUrl string A URL provided by this administrative body for looking up where to vote.
state[].electionAdministrationBody.ballotInfoUrl string A URL provided by this administrative body to give contest information to the voter.
state[].electionAdministrationBody.electionRulesUrl string A URL provided by this administrative body describing election rules to the voter.
state[].electionAdministrationBody.voter_services[] list A description of the services this administrative body may provide.
state[].electionAdministrationBody.hoursOfOperation string A description of the hours of operation for this administrative body.
state[].electionAdministrationBody.correspondenceAddress nested object The mailing address of this administrative body.
state[].electionAdministrationBody.correspondenceAddress.locationName string The name of the location.
state[].electionAdministrationBody.correspondenceAddress.line1 string The street name and number of this address.
state[].electionAdministrationBody.correspondenceAddress.line2 string The second line the address, if needed.
state[].electionAdministrationBody.correspondenceAddress.line3 string The third line of the address, if needed.
state[].electionAdministrationBody.correspondenceAddress.city string The city or town for the address.
state[].electionAdministrationBody.correspondenceAddress.state string The US two letter state abbreviation of the address.
state[].electionAdministrationBody.correspondenceAddress.zip string The US Postal Zip Code of the address.
state[].electionAdministrationBody.physicalAddress nested object The physical address of this administrative body.
state[].electionAdministrationBody.physicalAddress.locationName string The name of the location.
state[].electionAdministrationBody.physicalAddress.line1 string The street name and number of this address.
state[].electionAdministrationBody.physicalAddress.line2 string The second line the address, if needed.
state[].electionAdministrationBody.physicalAddress.line3 string The third line of the address, if needed.
state[].electionAdministrationBody.physicalAddress.city string The city or town for the address.
state[].electionAdministrationBody.physicalAddress.state string The US two letter state abbreviation of the address.
state[].electionAdministrationBody.physicalAddress.zip string The US Postal Zip Code of the address.
state[].electionAdministrationBody.electionOfficials[] list The election officials for this election administrative body.
state[].electionAdministrationBody.electionOfficials[].name string The full name of the election official.
state[].electionAdministrationBody.electionOfficials[].title string The title of the election official.
state[].electionAdministrationBody.electionOfficials[].officePhoneNumber string The office phone number of the election official.
state[].electionAdministrationBody.electionOfficials[].faxNumber string The fax number of the election official.
state[].electionAdministrationBody.electionOfficials[].emailAddress string The email address of the election official.
state[].local_jurisdiction nested object The city or county that provides election information for this voter. This object can have the same elements as state.
state[].sources[] list A list of sources for this area. If multiple sources are listed the data has been aggregated from those sources.
state[].sources[].name string The name of the data source.
state[].sources[].official boolean Whether this data comes from an official government source.

Try it!