An asynchronous, full-stack web application designed to solve the age-old question: "Where should we eat?"
Food Roulette integrates multiple real-world mapping and location APIs (Foursquare, OpenStreetMap) to discover local restaurants based on your GPS coordinates, allowing you to select your favorites and let a "Slot Machine" algorithm randomly decide your fate.
Users can auto-detect their location via GPS, and filter results dynamically by Cuisine or Rating.
A custom-built Slot Machine animation builds suspense before revealing the chosen restaurant.
Displays the winning location, a randomly generated 'Chef's Choice' dish/drink, and a direct deep-link to Google Maps for navigation.
- Multi-API Fallback System: Prioritizes high-quality Foursquare data. If Foursquare fails, hits rate limits, or lacks regional coverage, it automatically falls back to an OpenStreetMap (Overpass API) architecture with reverse-geocoding.
- Asynchronous Performance: Built with FastAPI and
asyncio.gather. Concurrent reverse-geocoding fetches 30+ addresses simultaneously, reducing load times drastically. - Zero-Dependency Frontend: The UI is built entirely with Vanilla JavaScript and pure CSS. No heavy React bundles, resulting in lightning-fast initial load times.
- Fault-Tolerant UX: Features explicit form validation, preventing "silent failures" or confusing location guesses if the user forgets to input data.
- Backend: Python, FastAPI, Uvicorn, Httpx (Async HTTP requests)
- Frontend: Vanilla HTML, CSS, JavaScript (No frameworks)
- APIs Used:
- Foursquare Places API v3
- OpenStreetMap (Overpass API)
- Nominatim (Reverse Geocoding)
-
Clone the repository
git clone https://github.com/YourUsername/food-roulette.git cd food-roulette -
Set up environment variables Copy the example file and configure your API keys (optional, the app will fallback to OpenStreetMap if left blank).
cp .env.example .env
-
Install dependencies
pip install -r requirements.txt
-
Run the server
uvicorn main:app --reload
-
Open in Browser Navigate to
http://localhost:8000
- Why not use Google Places API exclusively? Google Places is expensive. This project demonstrates how to build a robust, cost-effective system by layering free APIs and using graceful degradation (Foursquare → OpenStreetMap).
- Why the explicit input validation? Originally, the backend used an IP-Geolocation service to silently guess the user's city if inputs were empty. I replaced this with strict frontend validation to prevent "magic behavior" and ensure the user always understands why a specific location was searched.