Google Civic Information API

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

POST https://www.googleapis.com/civicinfo/us_v1/voterinfo/electionId/lookup

Parameters

Parameter name Value Description
Required parameters
electionId long The unique ID of the election to look up. A list of election IDs can be obtained using the electionQuery method
Optional parameters
officialOnly boolean If set to true, only data from official state sources will be returned. (Default: false)

Request body

In the request body, supply data with the following structure:

{
  "address": string
}
Property name Value Description Notes
address string The registered address of the voter to look up.  The address should be in the same format as addresses accepted by the Google Geocoding API.

Response

The status field will return "success" when the address and election ID are accepted.  For other conditions, an error code is returned. Note that voter information data may be returned even if an error code is returned.

{
  "kind": "civicinfo#voterInfoResponse",
  "status": string,
  "election": {
    "id": long,
    "name": string,
    "electionDay": string
  },
  "normalizedInput": {
    "locationName": string,
    "line1": string,
    "line2": string,
    "line3": string,
    "city": string,
    "state": string,
    "zip": string
  },
  "pollingLocations": [
    {
      "id": string,
      "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,
      "sources": [
        {
          "name": string,
          "official": boolean
        }
      ]
    }
  ],
  "earlyVoteSites": [
    {
      "id": string,
      "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,
      "sources": [
        {
          "name": string,
          "official": boolean
        }
      ]
    }
  ],
  "contests": [
    {
      "id": string,
      "type": string,
      "primaryParty": string,
      "electorateSpecifications": string,
      "special": string,
      "office": string,
      "level": 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,
      "sources": [
        {
          "name": string,
          "official": boolean
        }
      ]
    }
  ],
  "state": [
    {
      "id": string,
      "name": string,
      "electionAdministrationBody": {
        "name": string,
        "electionInfoUrl": string,
        "electionRegistrationUrl": string,
        "electionRegistrationConfirmationUrl": 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
        }
      ]
    }
  ]
}

General Information

Property name Value Description Notes
kind string The kind, fixed to "civicinfo#voterInfoResponse".
status string The result of the request. One of:
  • success
  • noStreetSegmentFound
  • addressUnparseable
  • noAddressParameter
  • multipleStreetSegmentsFound
  • electionOver
  • electionUnknown
  • internalLookupFailure
election nested object The election that was queried.
election.id long The unique ID of this election.
election.name string A displayable name for the election.
election.electionDay string Day of the election in YYYY-MM-DD format.
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.

Polling and Early Vote Locations

Property name Value Description Notes
pollingLocations[] list Locations where the voter is eligible to vote on election day. For states with mail-in voting only, these locations will be nearby drop box locations. Drop box locations are free to the voter and may be used instead of placing the ballot in the mail.
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[].pollingHours string A description of when this location is open.
pollingLocations[].notes string Notes about this location (e.g. accessibility ramp or entrance to use)
pollingLocations[].name string The name of the early vote site. This field is not populated for polling locations.
pollingLocations[].voterServices string The services provided by this early vote site. This field is not populated for polling locations.
pollingLocations[].startDate string The first date that this early vote site may be used. This field is not populated for polling locations.
pollingLocations[].endDate string The last date that this early vote site may be used. This field is not populated for polling 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[].pollingHours string A description of when this location is open.
earlyVoteSites[].notes string Notes about this location (e.g. accessibility ramp or entrance to use)
earlyVoteSites[].name string The name of the early vote site. This field is not populated for polling locations.
earlyVoteSites[].voterServices string The services provided by this early vote site. This field is not populated for polling locations.
earlyVoteSites[].startDate string The first date that this early vote site may be used. This field is not populated for polling locations.
earlyVoteSites[].endDate string The last date that this early vote site may be used. This field is not populated for polling 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.

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[].office string The name of the office for this contest.
contests[].level string The level of office for this contest. If unspecified the office level is not known.  One of:
  • federal
  • state
  • county
  • city
  • other
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 the division. If unspecified, the division's geography is not known. One of: 
  • national
  • statewide
  • congressional
  • stateUpper
  • stateLower
  • countywide
  • judicial
  • schoolBoard
  • cityWide
  • township
  • countyCouncil
  • cityCouncil
  • ward
  • special
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[].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 Officals

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

Use the APIs Explorer below to call this method on live data and see the response. Alternatively, try the standalone Explorer.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.