Representative Search Logic
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Representative Search Logic is a core module within the Actionmap application designed to bridge the gap between user location data and official government representation. It allows users to input a geographic address and retrieve a list of political representatives associated with that specific location. This system leverages external data from the Google Civic Information API to provide real-time, accurate data regarding elected officials.
The logic encompasses the retrieval of data via external service calls, the transformation of third-party API responses into internal ActiveRecord models, and the persistence of these records for further interaction, such as viewing profiles or associating news items with specific representatives.
Sources: app/controllers/search_controller.rb:7-14, app/models/representative.rb:5-20, README.md
System Architecture and Data Flow
The search process follows a traditional MVC (Model-View-Controller) pattern augmented by an external service integration. The SearchController acts as the primary orchestrator, receiving user input, communicating with the Google Civic Information API, and invoking model logic to process the results.
Search Flow Overview
The following diagram illustrates the sequence of events from the initial user request to the rendering of the search results.
Components and Implementation Details
1. Search Controller
The SearchController contains the search action, which initializes the Google::Apis::CivicinfoV2::CivicInfoService. It utilizes a secure API key stored in the Rails application credentials to authenticate requests. The controller handles the incoming :address parameter and passes the raw API result to the Representative model for processing.
Sources: app/controllers/search_controller.rb:6-15
2. Data Transformation (Representative Model)
The Representative model is responsible for parsing the complex nested structure of the Google Civic API response. The API separates "Officials" (the people) from "Offices" (the positions they hold). The logic in civic_api_to_representative_params maps these together using indices.
Key transformation methods include:
civic_api_to_representative_params: Iterates through officials and offices to link titles and OCDIDs to specific individuals.build_address: Formats the multi-line address objects from the API into a single, standardized string.update_dict: A helper method used to populate temporary attributes during the iteration process.
Sources: app/models/representative.rb:5-52
3. Data Schema
Representatives are persisted in the database to allow for relationships with news items and persistent profile pages.
| Field | Type | Description |
|---|---|---|
name | string | Full name of the representative. |
ocdid | string | Open Civic Data Identifier for the office. |
title | string | The name of the office held (e.g., "President"). |
party | string | Political party affiliation. |
photo_url | string | URL to the official's photograph. |
address | string | Formatted residential or office address. |
Sources: db/schema.rb:62-70
API Integration and Routing
The search feature is exposed via a specific route defined in config/routes.rb. It supports both standard query parameters and optional path-based addresses.
# Route definition for representative search
get '/search/(:address)' => 'search#search', :as => 'search_representatives'
Sources: config/routes.rb:58
External Service Dependencies
The system relies on the google-api-client gem. Configuration is handled within the controller, though error handling for API failures (such as invalid addresses) is validated within the test suite.
| Requirement | Description |
|---|---|
| API Key | Rails.application.credentials[:GOOGLE_API_KEY] |
| Service Class | Google::Apis::CivicinfoV2::CivicInfoService |
| Method | representative_info_by_address |
Sources: app/controllers/search_controller.rb:9-11, spec/controllers/search_controller_spec.rb:7-12
Error Handling and Validation
The system includes validation logic to ensure that search queries are restricted to valid geographic locations. As evidenced in search_controller_spec.rb, the system is expected to raise a Google::Apis::ClientError when encountering:
- Foreign addresses (e.g., Paris, France).
- Empty address strings.
Sources: spec/controllers/search_controller_spec.rb:7-15
Conclusion
The Representative Search Logic provides a robust mechanism for discovering political representatives. By integrating the Google Civic Information API with local persistence via the Representative model, the application ensures that users can quickly find their officials and access related features like local news and event tracking. The use of find_or_create_by! ensures that representative data is deduplicated while remaining up-to-date with each new search.