Chat with Google Maps

A voice-driven conversational interface for exploring locations using Gemini Live API and Photorealistic 3D Maps.

Built with 'Apex Spec System' - https://github.com/moshehbenavraham/apex-spec-system

Note: This sample app is for illustration only. Review the applicable Terms of Service for your region before use.

Features

• Real-time voice conversations with Gemini AI
• Photorealistic 3D map visualization
• Location grounding with Google Maps data
• Interactive itinerary planning

Quick Start

# 1. Clone and install
git clone <repository-url>
cd chat_with_google_maps
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env with your API keys

# 3. Run
npm run dev

Open http://localhost:3003

Prerequisites

• Node.js 18+
• Gemini API Key
• Google Maps API Key

Required Google Maps APIs

Enable these in your Google Cloud Console:

• Maps JavaScript API
• Places API (New)
• Geocoding API
• Maps Elevation API
• Maps Grounding API

Environment Variables

Variable	Required	Description
GEMINI_API_KEY	Yes	Gemini API key for voice conversations
GOOGLE_MAPS_API_KEY	Yes	Google Maps Platform API key
DATABASE_URL	Yes	PostgreSQL connection string
BETTER_AUTH_SECRET	Yes	Auth secret key (min 32 chars)
BETTER_AUTH_URL	Yes	Frontend URL for auth callbacks

See .env.example for detailed configuration.

Documentation

Guide	Description
Onboarding	Getting started checklist
Development	Dev scripts and workflow
Local Deployment	Development setup and troubleshooting
Vercel Deployment	Production hosting on Vercel
Database Setup	Local PostgreSQL with Docker
Database Deployment	Production database options
Authentication	Better Auth setup and usage
Architecture	Application structure and key concepts
Customization	Creating personas and adding tools
Prompts	System prompt management
Contributing	Development workflow and guidelines

Project Status

See PRD for current progress and roadmap.

Scripts

Command	Description
npm run dev	Start development server
npm run build	Build for production
npm run preview	Preview production build
npm run lint	Run ESLint
npm run lint:fix	Run ESLint with auto-fix
npm run format	Format code with Prettier
npm run format:check	Check code formatting
npm run typecheck	Run TypeScript type checking
npm run test	Run tests
npm run test:watch	Run tests in watch mode
npm run test:coverage	Run tests with coverage report
npm run quality	Run all quality checks
npm run db:start	Start PostgreSQL container
npm run db:stop	Stop PostgreSQL container
npm run db:migrate	Apply database migrations
npm run db:reset	Reset database (deletes data)

Tech Stack

Frontend

• React 19 + TypeScript
• Vite (build tooling)
• Zustand (state management)
• Tailwind CSS 4 (utility-first styling)
• shadcn/ui (accessible Radix primitives)
• Framer Motion (animations)
• Lucide React (icons)
• next-themes (dark/light mode)
• @vis.gl/react-google-maps
• @google/genai (Gemini SDK)

Backend

• Hono (vendor-neutral web framework)
• PostgreSQL 16 (database)
• Drizzle ORM (type-safe database access)
• Better Auth (open-source authentication)

Attribution

Based on Google's AI Studio Maps demo. Original code Copyright 2024 Google LLC, licensed under Apache 2.0.

For more information on the original project and Google's Maps + Gemini integration:

• Grounding with Google Maps Announcement
• Google AI Studio Starter Apps
• Original Code Source