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
`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
`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
`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
`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.