Google Civic Information API Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Google Civic Information API integration is a core component of the Actionmap project, enabling the application to retrieve real-time data about political representatives based on geographic locations. This integration allows users to input an address or select a region on a map to identify the elected officials serving that specific area.
The system acts as a bridge between user-provided location data and the Google Civic Information service. It processes API responses to populate the local Representative model, facilitating features such as viewing representative profiles and managing related news items.
Architecture and Data Flow
The integration follows a standard request-response pattern where the Rails backend communicates with Google's API via the google-api-client gem. The flow is triggered either by a direct search form or by interaction with the geographic map interfaces.
Search Request Pipeline
When a user provides an address, the SearchController initializes a connection to the Google Civic Information service using a secure API key stored in the application's credentials.
Mapping API Responses to Models
The Representative model contains a specialized class method, civic_api_to_representative_params, which iterates through the Google API response. It extracts specific fields such as official names, titles, and party affiliations to ensure data consistency within the local database.
| Field | Source from API | Description |
|---|---|---|
name | official.name | The full name of the representative. |
ocdid | office.division_id | Open Civic Data Identifier for the region. |
title | office.name | The official title of the office held. |
party | official.party | Political party affiliation. |
photo_url | official.photo_url | URL to the official's photograph. |
address | official.address | The official office address. |
Sources: app/models/representative.rb, db/schema.rb:52-61
Key Components
SearchController
The controller manages the lifecycle of a search request. It extracts the :address parameter from the request and invokes service.representative_info_by_address.
- Endpoint:
/search/(:address) - Service Class:
Google::Apis::CivicinfoV2::CivicInfoService
Sources: app/controllers/search_controller.rb:6-10, config/routes.rb:58
Representative Model Integration
The model is responsible for the persistence and transformation of civic data. The schema supports storing various attributes returned by the API to minimize subsequent external calls.
Map-Based Integration
Beyond text-based search, the integration is triggered via geographic interactions. The JavaScript utilities for state maps generate search queries based on county names and state symbols when a user clicks on a specific region.
Implementation Details
API Configuration
The integration requires a GOOGLE_API_KEY defined in Rails.application.credentials. This key is assigned to the CivicInfoService instance before every request to authenticate the application with Google's servers.
service = Google::Apis::CivicinfoV2::CivicInfoService.new
service.key = Rails.application.credentials[:GOOGLE_API_KEY]
Sources: app/controllers/search_controller.rb:8-9
Routing
The application defines a specific route for the search functionality, supporting both standard parameter passing and optional path-based addresses.
get '/search/(:address)' => 'search#search', :as => 'search_representatives'
Sources: config/routes.rb:58
Conclusion
The Google Civic Information API Integration provides the foundational data layer for the Actionmap platform. By mapping complex geographic and political data structures from Google into a simplified local Representative model, the system enables users to seamlessly transition from geographic exploration to active engagement with their local officials.