Demographic Doppelgänger

Welcome screen guiding users to explore ZIP code “twins” by using their location or entering a ZIP code to compare communities.
Summary of data sources and APIs powering the app: U.S. Census, Google Gemini, Maps, Places, and Cloud Platform.
Doppleganger button
A screenshot of the application, displaying detailed demographic data—like median income and home value—for zip code 94403 in San Mateo, CA.
Detailed demographic and socioeconomic profile generated by the application's AI for a selected zip code.
The "Demographic Doppelgänger" app compares 94403 (blue) with a 95% match, 95014 (purple), while the sidebar lists other similar zip codes.
The "Demographic Doppelgänger" app's national search view for zip code 94403.
A demographic breakdown for zip code 94403, showing key statistics like population, income, home value, and racial/ethnic composition.
Custom Google Maps Infowindows

Inspiration

We wondered if another place has the same demographic profile. What if your ZIP code has a "twin" across the country? This led us to build a tool that turns Census data into stories and finds similar communities.

What it does

Demographic Doppelgänger is a full-stack web application that:

Explores the demographic "DNA" of any U.S. ZIP code
Uses Google Gemini AI to generate narrative community profiles
Finds similar ZIP codes (doppelgängers) across the country based on demographic similarity
Visualizes connections on an interactive map with geodesic lines connecting twins

Users simply enter a ZIP code, view the demographic data, then click "Get AI Insights" to receive an AI-generated profile and discover their doppelgänger communities.

How we built it

Frontend: React/TypeScript application deployed on Google Cloud Run, built using Google AI Studio, and Google Maps JavaScript API for visualization

Backend Architecture:

Google API Gateway - Public entry point with API key authentication
Python Flask Service - Fetches Census data, calls Gemini AI, handles Firestore caching
Firestore - Caches results for instant responses (sub-second for cached ZIP codes)

Key Technologies: Google Cloud Run, API Gateway, Firestore, Gemini AI, U.S. Census Bureau API, Google Maps Platform, MUI

Challenges we ran into

CORS & Authentication - Handling preflight OPTIONS requests without breaking API key authentication
Timeout Management - Long-running AI calls required 120s timeouts across Gateway → Cloud Run → Gunicorn
Cold Starts - Mitigated with min-instances=1 for zero cold starts
Memory Constraints - Scaled to 2Gi RAM to handle large datasets and AI libraries
Service-to-Service Auth - Configured IAM roles for secure API Gateway → Cloud Run communication

Accomplishments that we're proud of

Production-Grade Architecture - Enterprise API Gateway patterns with proper security
Smart Caching - Firestore cache reduces API costs by 99%+ for repeated requests
User-Centric Design - On-demand AI analysis respects user intent and reduces costs
Zero Cold Starts - Always-on instance for instant first requests
Beautiful UX - Custom map markers, animated load states, and geodesic connections

What we learned

LLMs as Backend Engines - Gemini can analyze structured data and perform similarity matching
API Gateway Power - Enterprise features (auth, routing, rate limiting) without custom code
Cloud Run Versatility - Works for both user-facing apps and heavy compute backends
IAM Authentication - Service-to-service auth is more secure than API keys
Decoupling Benefits - Separating frontend, gateway, and engine enables independent scaling and tuning

What's next for Demographic Doppelgänger

Temporal Analysis - Multi-year demographic trends to see how communities evolve
"Anti-Doppelgänger" Search - Find ZIP codes that are most different demographically
Rate Limiting - Configure API Gateway rate limits to prevent abuse
Social Features - Share and compare findings with friends