Civic

Overview

Google Civic is an API which provides helpful information about elections. In order to access Google Civic you must create a Google Developer Key in their API console. In order to use Google Civic, you must enable this specific end point.

The Google Civic API utilizes the Voting Information Project to collect key civic information such as personalized ballots and polling location information.

Quickstart

To instantiate the GoogleCivic class, you can pass the constructor a string containing the Google Civic API key you’ve generated for your project, or set the environment variable GOOGLE_CIVIC_API_KEY to that value.

Set the credentials as an environment variable
from parsons import GoogleCivic

# May either be the file name or a JSON encoding of the credentials.
os.environ['GOOGLE_CIVIC_API_KEY'] = 'AIzaSyAOVZVeL-snv3vNDUdw6QSiCvZRXk1xM'

google_civic = GoogleCivic()
Pass the credentials in as an argument
google_civic = GoogleCivic(api_key='AIzaSyAOVZVeL-snv3vNDUdw6QSiCvZRXk1xM')
Retrieve election information
elections = google_civic.get_elections()

address = '1600 Pennsylvania Avenue, Washington DC'
election_id = '7000'  # General Election
google_civic.get_polling_location(election_id=election_id, address=address)
Retrieve represntative information such as offices, officals, etc
address = '1600 Pennsylvania Avenue, Washington DC'
representatives = google_civic.get_representatives_by_address(address=address)

API

class parsons.google.google_civic.GoogleCivic(api_key=None)[source]
Parameters:

api_key – str A valid Google api key. Not required if GOOGLE_CIVIC_API_KEY env variable set.

Returns:

class

get_elections()[source]

Get a collection of information about elections and voter information.

Returns:

Table

See Table for output options.

get_polling_location(election_id, address)[source]

Get polling location information for a given address.

Parameters:

  • election_id – int A valid election id. Election ids can be found by running the get_elections() method.

  • address – str A valid US address in a single string.

Returns:

Table

See Table for output options.

get_polling_locations(election_id, table, address_field='address')[source]

Get polling location information for a table of addresses.

Parameters:

  • election_id – int A valid election id. Election ids can be found by running the get_elections() method.

  • address – str A valid US address in a single string.

  • address_field – str The name of the column where the address is stored.

Returns:

Table

See Table for output options.

get_representative_info_by_address(address: str, include_offices=True, levels=None, roles=None)[source]

Get representative information for a given address.

This method returns the raw JSON response from the Google Civic API. It is a complex response that is not easily parsed into a table. Here is the information on how to parse the response: https://developers.google.com/civic-information/docs/v2/representatives/representativeInfoByAddress

Parameters:

  • address (str) – str A valid US address in a single string.

  • include_offices – bool Whether to return information about offices and officials. If false, only the top-level district information will be returned. (Default: True)

  • levels –

    list of str A list of office levels to filter by. Only offices that serve at least one of these levels will be returned. Divisions that don’t contain a matching office will not be returned. Acceptable values are:

    • ”administrativeArea1”

    • ”administrativeArea2”

    • ”country”

    • ”international”

    • ”locality”

    • ”regional”

    • ”special”

    • ”subLocality1”

    • ”subLocality2”

  • roles –

    list of str A list of office roles to filter by. Only offices fulfilling one of these roles will be returned. Divisions that don’t contain a matching office will not be returned. Acceptable values are:

    • ”deputyHeadOfGovernment”

    • ”executiveCouncil”

    • ”governmentOfficer”

    • ”headOfGovernment”

    • ”headOfState”

    • ”highestCourtJudge”

    • ”judge”

    • ”legislatorLowerBody”

    • ”legislatorUpperBody”

    • ”schoolBoard”

    • ”specialPurposeOfficer”

Returns:

Table

See Table for output options.