Stumble Guides 🍻

Plan your perfect night out with the best bars in your area

Stumble Guides is an intelligent bar crawl planning application that helps you discover, organize, and navigate the perfect night out. Using Google Places API and advanced route optimization, it finds the best bars near you and creates an optimized walking route for your bar crawl adventure.

✨ Features

🎯 Smart Bar Discovery

• Location-Aware Search: Uses GPS location or custom address input
• Customizable Filters: Search radius (0.5-5 miles) and price range ($-$$$$)
• Detailed Bar Information: Ratings, prices, photos, and addresses
• High-Quality Results: Up to 20 bars sorted by rating

🗺️ Intelligent Route Planning

• Route Optimization: Uses the nearest neighbor algorithm to minimize walking distance
• Real Walking Directions: Powered by Google Directions API with actual walking paths
• Interactive Map: Visual route display with numbered markers and polylines
• Distance & Time Estimates: Total walking distance and estimated time

🎨 User Experience

• Dark/Light Mode: Toggle between themes for any lighting condition
• Drag & Drop Ordering: Manually reorder bars in your crawl
• Responsive Design: Works seamlessly on desktop, tablet, and mobile
• Real-time Updates: Live route recalculation when bars are reordered

📱 Mobile-Optimized

• Touch-Friendly Interface: Optimized for mobile interaction
• Responsive Layout: Adapts to any screen size
• GPS Integration: Automatically detects your location on mobile devices

🚀 Getting Started

Prerequisites

• Python 3.7+
• Google Maps API Key with the following APIs enabled:
  • Places API
  • Directions API
  • Maps JavaScript API
  • Geocoding API

Installation

1. Clone the repository

   git clone https://github.com/yourusername/stumble-guides.git
   cd stumble-guides

2. Install dependencies

   pip install flask requests

3. Set up your Google Maps API Key

   export GOOGLE_MAPS_API_KEY="your_api_key_here"

   Or create a .env file:

   GOOGLE_MAPS_API_KEY=your_api_key_here
   

4. Run the application

   python app.py

5. Open your browser Navigate to http://localhost:5000

🏗️ Project Structure

stumble-guides/
├── app.py                          # Main Flask application
├── services/
│   ├── google_places.py           # Google Places API integration
│   ├── google_directions.py       # Google Directions API integration
│   └── route_optimizer.py         # Route optimization algorithms
├── static/
│   ├── css/
│   │   └── style.css             # Application styles
│   ├── js/
│   │   ├── app.js                # Main application logic
│   │   └── map.js                # Google Maps integration
│   └── images/
│       └── default-bar.jpg       # Fallback bar image
├── templates/
│   └── index.html                # Main HTML template
└── README.md

🔧 API Endpoints

POST /api/bars

Find nearby bars based on location and filters.

Request Body:

{
  "latitude": 39.9566,
  "longitude": -75.1899,
  "radius": 1609,
  "priceRange": [1, 4],
  "limit": 20
}

POST /api/route

Generate an optimized route for selected bars.

Request Body:

{
  "selectedBars": [
    {
      "id": "place_id",
      "name": "Bar Name",
      "location": {"lat": 39.9566, "lng": -75.1899}
    }
  ]
}

🧠 How It Works

1. Location Detection: The app first determines your location using GPS or a custom address
2. Bar Discovery: Searches for bars within your specified radius and price range using Google Places API
3. Selection: You browse and select bars you want to visit
4. Route Optimization: The app calculates the shortest walking route using the nearest neighbor algorithm
5. Navigation: Provides turn-by-turn walking directions between each bar

---

Ready to stumble smartly? Start planning your perfect night out with Stumble Guides! 🍻🗺️