Route Explorer

A Next.js 15 application that intelligently discovers points of interest along your travel routes. Plan personalized journeys with multiple travel modes, customizable POI preferences, and smart time management to make the most of every trip.

Demo

A Demo site can be found here

✨ Features

🚗 Multi-Modal Travel Planning

• Driving: Traffic-aware routing with car-accessible POIs
• Walking: Local discoveries within walking distance
• Public Transport: Intelligent fallback system with global coverage - works worldwide even in areas with limited transit data
• Cycling: Bike-friendly paths and destinations

🎯 Smart POI Discovery

• Customizable Categories: Choose from 8 categories (Restaurants, Museums, Parks, Shopping, Attractions, Entertainment, Culture, Outdoors)
• Time-Based Filtering: Only shows POIs where you actually have time to visit
• Available Time Calculation: Shows exactly how many minutes you can spend at each location
• Intelligent Research: Remove unwanted places and discover fresh alternatives

⏰ Time Management

• Time Validation: Prevents impossible itineraries by checking route duration against available time
• Per-POI Time Allocation: Calculates visit time for each destination
• Smart Exclusion: Automatically filters out locations with no available time

🔍 Advanced Features

• POI Removal & Research: Remove places you don't want and find new options
• Detailed Route Views: Click any POI for step-by-step directions and timing
• Travel Mode Optimization: Different POI types and search radiuses per travel mode
• Interactive Maps: Embedded Google Maps with route visualization
• Global Public Transport: Smart fallback system that works in Tokyo, New York, London, and anywhere with walking data
• Robust Error Handling: Graceful degradation when APIs fail or data is unavailable

Tech Stack

• Framework: Next.js 15 with TypeScript
• Styling: Tailwind CSS v4 with dark theme
• Authentication: Clerk
• Maps & Routing: Google Maps API (Places, Routes, Directions)
• Development: Turbopack for fast development builds

Getting Started

Prerequisites

• Node.js 18+ and npm
• Google Maps API key with the following APIs enabled:
  • Places API (Text Search and Nearby Search)
  • Routes API
  • Maps Embed API
• Clerk account for authentication

Installation

1. Clone the repository:

git clone <repository-url>
cd route-explorer

2. Install dependencies:

npm install

3. Set up environment variables: Create a .env.local file with:

GOOGLE_MAPS_API_KEY=your_google_maps_api_key
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key
CLERK_SECRET_KEY=your_clerk_secret_key

4. Start the development server:

npm run dev

Open http://localhost:3000 in your browser.

Available Scripts

• npm run dev - Start development server with Turbopack
• npm run build - Create production build
• npm start - Start production server
• npm run lint - Run ESLint with Next.js config

Project Structure

├── app/
│   ├── api/
│   │   ├── locations/          # Main route and POI calculation API
│   │   ├── detailed-route/     # Detailed route through specific POI
│   │   └── research-pois/      # Alternative POI discovery
│   ├── app/                    # Protected main application page
│   ├── sign-in/               # Authentication pages
│   └── sign-up/
├── components/
│   ├── ClientPage.tsx         # Main state container with POI management
│   ├── PlanYourAdventure.tsx  # Route planning form with POI preferences
│   ├── RouteResults.tsx       # Results display with removal/research features
│   ├── RouteMap.tsx           # Google Maps embed
│   └── ReadySection.tsx       # Landing page CTA
├── types/                        # Organized TypeScript interfaces
│   ├── location.ts           # Location and coordinate types
│   ├── poi.ts               # Point of Interest and preference types  
│   ├── route.ts             # Route and travel mode types
│   ├── form.ts              # Form input types
│   ├── components.ts        # Component prop interfaces
│   ├── api.ts               # API request/response types
│   └── index.d.ts           # Main export file and legacy types
├── lib/
│   └── apiKey.ts             # Google Maps API key utility
└── middleware.ts             # Clerk authentication middleware

How It Works

1. 🎯 Route Planning

• Location Input: Enter start and destination locations
• Travel Mode Selection: Choose from driving, walking, public transport, or cycling
• Time Budget: Set available time in minutes
• POI Preferences: Select from 8 categories of interests
• Time Validation: Ensures route is possible within time budget

2. 🧠 Intelligent Processing

• Geocoding: Converts location text to coordinates using Google Places API
• Route Calculation: Uses Google Routes API (driving/walking/cycling) or Directions API (transit)
• Public Transport Fallback: When transit data unavailable, estimates times using walking routes (40% of walking time)
• POI Discovery: Searches for places matching selected categories near route midpoint
• Time Analysis: Calculates actual travel time through each POI
• Smart Filtering: Only shows POIs with available visit time

3. 📋 Results & Management

• POI Cards: Display places with available time, travel time, and ratings
• Detailed Routes: Click any POI for step-by-step directions
• POI Removal: Remove unwanted places with ✕ button
• Research Mode: Find alternative POIs excluding removed ones
• Interactive Maps: Embedded Google Maps with route visualization

🔧 API Architecture

Core APIs

• /api/locations: Main route and POI calculation
• /api/detailed-route: Detailed routing through specific POI
• /api/research-pois: Alternative POI discovery with exclusions

Google Maps Integration

• Places Text Search: Location geocoding
• Routes API v2: Modern routing for driving/walking/cycling
• Directions API: Legacy API optimized for transit routing
• Places Nearby Search: POI discovery with custom categories
• Maps Embed: Route and POI visualization

Smart Features

• Dynamic API Selection: Uses optimal Google API based on travel mode
• Public Transport Intelligence: Automatic fallback system for global transit coverage
• Time-based Filtering: Only viable POIs are shown
• Exclusion System: Prevents showing removed POIs in research
• Category Mapping: Translates user preferences to Google Place types
• Error Recovery: Handles API failures and unsupported location types gracefully

Authentication & Routes

• Public Routes: /, /sign-in, /sign-up
• Protected Routes: /app (requires authentication)
• Middleware: Clerk handles route protection automatically

🎉 Development Status

Core Features ✅

• Landing Page with modern UI
• Clerk Authentication (Sign-in/Sign-up)
• Multi-modal Route Planning (Drive/Walk/Transit/Cycle)
• Customizable POI Category Selection
• Time Budget Management and Validation
• Smart POI Discovery with Time Calculations
• Interactive Google Maps Integration
• Mobile-Responsive Design

Advanced Features ✅

• POI Removal and Research System
• Detailed Route Views with Step-by-Step Directions
• Time-based POI Filtering
• Travel Mode Optimization
• Global Public Transport Support with Intelligent Fallback
• Alternative POI Discovery
• Exclusion-based Research
• Dynamic API Selection
• TypeScript Interface Organization
• Robust Error Handling and Recovery

User Experience ✅

• Glassmorphism Dark Theme
• Smooth Animations and Transitions
• Loading States and Error Handling
• Intuitive POI Management
• Visual Feedback and Tooltips

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run npm run lint to check code style
5. Submit a pull request