Skip to main content

GitHub Issue: Google Maps Integration for Project Address

Copy the text below for the GitHub issue:

📍 Google Maps Integration for Project Address (Phase 1.5)​

Overview​

Enhance the Project Settings UI with Google Maps integration to provide intelligent address autocomplete and visual location confirmation. This builds on the completed Project Metadata Management (Issue #227 - Phase 1).

Problem Statement​

Current State:

  • ✅ Project address editing is implemented (Issue #227)
  • ✅ Chrome browser autocomplete works (native HTML behavior)
  • ❌ No intelligent address suggestions from Google Places database
  • ❌ No visual confirmation of project location on a map

User Pain Points:

  • Users must manually type complete addresses without smart suggestions
  • No way to validate if an address actually exists
  • No visual confirmation of where the project is located
  • Ambiguous addresses can't be disambiguated

Goals​

  1. Intelligent Address Autocomplete: Google Places-powered suggestions as users type
  2. Visual Location Confirmation: Display project location on an interactive map
  3. Preserve Existing Behavior: Keep Chrome's autocomplete alongside Google suggestions
  4. Mobile-Friendly: Excellent experience on all devices

User Stories​

Story 1: Google Places Address Autocomplete​

As a project owner
I want to see address suggestions from Google Places as I type
So that I can quickly enter accurate, validated addresses

Acceptance Criteria:

  • Google Places dropdown appears below street address field when typing (3+ characters)
  • Suggestions are restricted to USA addresses (configurable by country field)
  • Selecting a suggestion auto-fills street, city, state, and postal code
  • Chrome's native autocomplete remains functional
  • Works on desktop, tablet, and mobile devices
  • API errors handled gracefully with fallback to manual entry

Story 2: Interactive Map Widget​

As a project owner
I want to see my project location on a map
So that I can visually confirm the project address is correct

Acceptance Criteria:

  • Map card appears to the right of Project Metadata card (responsive layout)
  • Map displays project location if address is complete and geocodable
  • Map shows "Address not available" state if no address is set
  • Map shows "Unable to geocode address" state if address is invalid
  • Map marker centered on project address
  • Map is interactive (pan, zoom) but read-only (no dragging marker)
  • Map uses street-level zoom (15-17) by default
  • Map respects Material Design card styling

Story 3: Address Geocoding​

As a system
I want to automatically geocode project addresses
So that I can store precise location data for future features

Acceptance Criteria:

  • When user selects Google Places suggestion, store place_id
  • Automatically geocode address using Google Geocoding API
  • Store latitude and longitude in project metadata
  • Store formatted address from Google for consistency
  • Geocoding happens in background (non-blocking)
  • Failed geocoding doesn't block metadata save
  • Re-geocode when address is edited

Technical Implementation​

Frontend Changes​

New Files:

  • web-ng-m3/src/app/shared/google-maps.service.ts - Google Maps API wrapper
  • web-ng-m3/src/app/components/project/settings/project-location-map/ - Map widget component

Modified Files:

  • web-ng-m3/src/app/components/project/settings/project-settings/project-settings.component.ts - Integrate autocomplete
  • web-ng-m3/src/app/components/project/settings/project-settings/project-settings.component.html - Two-column layout
  • web-ng-m3/src/app/components/project/settings/project-settings/project-settings.component.scss - Responsive grid

Environment Configuration:

  • web-ng-m3/src/environments/environment.ts - Add googleMapsApiKey
  • web-ng-m3/src/environments/environment.prod.ts - Production API key from Secret Manager

Backend Changes (Minimal)​

Proto Updates:

message ProjectAddress {
  string street = 1;
  string city = 2;
  string state = 3;
  string postal_code = 4;
  string country = 5;
  
  // NEW: Google Maps metadata (optional)
  string google_place_id = 6;
  double latitude = 7;
  double longitude = 8;
  string formatted_address = 9;
}

Modified Files:

  • src/main/proto/api.proto - Update ProjectAddress message
  • Regenerate proto classes (Java + TypeScript)
  • No changes to ProjectMetadataService - new fields are optional

Google APIs Required​

  1. Places Autocomplete API

    • Price: $2.83 per 1,000 sessions
    • Free tier: First 100k sessions/month

  2. Maps JavaScript API

    • Price: $7.00 per 1,000 loads
    • Free tier: First 28k loads/month

  3. Geocoding API (included in Places API)

    • No additional cost

Estimated Monthly Cost: ~$40 (covered by $200 free tier credit)

Setup Requirements​

Google Cloud Configuration​

  1. Create Google Cloud project (or use existing)
  2. Enable Maps JavaScript API
  3. Enable Places API
  4. Create restricted API key:
    • Restrict to specific domains (*.codeproof.app, *.run.app)
    • Restrict to Maps JavaScript API and Places API only
    • Set daily quota limit (10,000 requests/day)
  5. Store API key in Secret Manager
  6. Configure Cloud Run to inject as environment variable

Development Environment​

# .env (not committed)
GOOGLE_MAPS_API_KEY=AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Production Environment​

# Google Secret Manager
gcloud secrets create google-maps-api-key --data-file=-

# Cloud Run configuration
gcloud run services update construction-code-expert-prod \
  --update-secrets=GOOGLE_MAPS_API_KEY=google-maps-api-key:latest

Testing Plan​

Unit Tests​

  • GoogleMapsService - API loading, autocomplete creation, geocoding
  • ProjectLocationMapComponent - Map initialization, marker placement, states
  • ProjectSettingsComponent - Autocomplete integration, place selection

Integration Tests​

  • End-to-end address entry flow
  • Fallback behavior when Google Maps unavailable
  • API error handling
  • Responsive layout on mobile/tablet

Manual Testing​

  • Autocomplete on desktop Chrome
  • Autocomplete on mobile Safari
  • Chrome native autocomplete still works
  • Map displays correct location
  • Map handles invalid addresses gracefully
  • Layout responsive on all screen sizes

Success Metrics​

User Engagement:

  • % of projects with complete addresses (target: 80%+)
  • % of address entries using Google Places (target: 60%+)
  • Average time to enter address (target: < 30 seconds)

System Performance:

  • Map load time (target: < 2 seconds)
  • Autocomplete response time (target: < 300ms)
  • Geocoding success rate (target: > 95%)

API Usage:

  • Daily Places API calls < quota
  • Daily Maps API calls < quota
  • Monthly cost within free tier

Security Considerations​

  1. API Key Security

    • Restrict API key to specific domains
    • Use separate keys for dev/staging/prod
    • Rotate keys periodically
    • Monitor for unauthorized usage

  2. Data Privacy

    • Don't send sensitive data to Google
    • Follow Google Maps Platform terms of service
    • Update privacy policy about Google Maps usage

  3. Input Validation

    • Validate all address components before saving
    • Sanitize user input
    • Prevent injection attacks

Future Enhancements​

Phase 2: Enhanced Visualization Widgets​

  • 3D Flyover Widget (High Priority) - Google Earth-style aerial view with 45° tilt
    • Understand terrain, elevation, and surrounding context
    • Interactive rotation and tilt control
    • Essential for hillside projects and urban infill
    • Implementation: 3-5 days
  • Street View Widget (Medium Priority) - Ground-level perspective
    • See street access and neighborhood character
    • Interactive pan/rotate with historical imagery
    • Implementation: 2-3 days

Phase 3: Smart Location Features​

  • Jurisdiction auto-lookup based on address
  • Building code suggestion by location
  • Nearby projects feature
  • Custom map markers per project type
  • Batch geocoding for existing projects
  • Address history/favorites

Phase 4: Advanced Planning Tools​

  • Lot boundary drawing tools
  • Distance measurement on map
  • Sun path visualization (solar/daylighting)
  • Flood zone overlay (FEMA data)
  • Zoning boundary overlay

Documentation​

New Documentation:

  • /docs/04-prd/google-maps-integration.md - Product Requirements
  • /docs/05-tdd/google-maps-integration.md - Technical Design

Related Documentation:

  • /docs/04-prd/project-metadata-management.md - Parent feature (Issue #227)
  • /docs/05-tdd/project-metadata-management.md - Parent implementation

Deployment Checklist​

  • Run automated setup script: cli/sdlc/new-environment-provisioning/setup-google-maps-api.sh <env>
    • Creates API key with restrictions
    • Stores in Secret Manager
    • Grants service account access
    • Tests API connectivity

Manual Configuration​

  • Update Cloud Run service to mount secret as environment variable
  • Update environment.prod.ts to read API key from config
  • Set API quotas in GCP Console (10k req/day)
  • Enable billing alerts ($50/month threshold)

Testing & Validation​

  • Test on staging environment with restricted API key
  • Verify API key restrictions (domains, APIs)
  • Run E2E tests on staging
  • Test on mobile devices
  • Monitor API usage for first week
  • Verify costs stay within free tier

Documentation​

  • Document API key location in environment docs
  • Update provisioning guide with Google Maps step
  • Add monitoring dashboard links

Implementation Tasks​

Phase 1: Core Infrastructure​

  • Create GoogleMapsService with API loader
  • Set up environment configuration for API keys
  • Update ProjectAddress proto with new fields
  • Regenerate proto classes (Java + TypeScript)

Phase 2: Address Autocomplete​

  • Integrate Google Places Autocomplete in ProjectSettingsComponent
  • Implement place selection handler
  • Auto-fill city, state, postal code fields
  • Add geocoding on save
  • Handle API errors gracefully

Phase 3: Map Widget​

  • Create ProjectLocationMapComponent
  • Implement map initialization and display
  • Add marker with project location
  • Handle loading, error, and "no address" states
  • Style with Material Design

Phase 4: Layout & UX​

  • Update project-settings.component.html with two-column grid
  • Update styles for responsive layout
  • Test on mobile, tablet, desktop
  • Polish loading states and transitions

Phase 5: Testing & Documentation​

  • Write unit tests for all new components
  • Write integration tests for E2E flow
  • Manual testing on all devices
  • Update documentation
  • Create deployment guide

Dependencies​

  • Parent Issue: #227 (Project Metadata Management - Phase 1) ✅ Complete
  • Google Maps Platform account with billing enabled
  • API key stored in Secret Manager
  • Cloud Run environment variable configuration

Estimated Effort​

  • Development: 5-7 days
  • Testing: 2-3 days
  • Documentation: 1 day
  • Total: 8-11 days

Priority​

Medium-High - Enhances existing feature with significant UX improvement

Labels​

enhancement, frontend, google-maps, address-management, phase-1.5, issue-227-related

Related Issues:

  • #227 - Project Metadata Management - Phase 1 (Parent feature)

Related PRs: (TBD)

Assignee: (TBD)

Milestone: Phase 1.5 - Address Management Enhancements