🌆 CityPulse - AI-powered Geospatial Search
CityPulse is an intelligent location-based discovery search that helps users explore what's happening around them right now. Built from 0 to 1, it leverages advanced AI reasoning to provide personalized, real-time insights about local events, restaurants, alerts, and activities.
- Available on Google Cloud: https://citypulse-ppx.uc.r.appspot.com/
- Featured in Perplexity.AI Cookbook: https://docs.perplexity.ai/cookbook/showcase/citypulse-ai-search
- Real-time location detection with custom markers
- Auto-zoom functionality to fit discovered locations
- Custom pin styling with category-based colors (events, restaurants, alerts)
- Clickable markers with detailed popup information
- AI-powered search suggestions as you type
- Natural language queries (e.g., "coffee shops", "live music tonight")
- Location-aware results based on your current position
- Quick action buttons for common discovery categories
- AI-powered reasoning for personalized location insights
- Real-time information retrieval
- Structured data extraction
- Location-based search
- Citation and source verification
- Personalized recommendations using AI reasoning model
- What to try, what to avoid for each location
- Best times to visit and pro tips
- Budget considerations and insider knowledge
- Progressive loading with elegant spinners
- Responsive design for mobile and desktop
- Modal popups with rich location details
- Share functionality with generated links
- Navigation integration with maps apps
- Structured JSON responses with validation
- Citation tracking with source verification
- Real-time data from multiple sources
- Fallback mechanisms for reliability
- Python 3.11+
- AI API key
- Google Maps API key
- Clone the repository
git clone <repository-url>
cd citypulse- Install dependencies
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt- Set up environment variables
Create a .env file with API keys:
GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here
PERPLEXITY_API_KEY=your_perplexity_api_key_here- Run the application
python3 main.py- Open your browser
Navigate to http://localhost:5001
- Allow location access when prompted (optional)
- See your current location marked on the map
- View the welcome message with quick action options
- Click "🌟 Discover Nearby" for automatic local discovery
- Use Quick Explore cards for specific categories:
- 🎭 What to Do (events & activities)
- 📸 What to See (attractions & landmarks)
- ☕ What to Eat (restaurants & food)
- 🛍️ What to Buy (shopping & markets)
- 📰 What's Happening (local news & events)
- Type in the search box for specific queries
- Get AI-powered suggestions as you type
- Use natural language (e.g., "best pizza near me", "outdoor activities")
-
Click on colored map pins to see basic info
-
Click "Learn more" for detailed modal with:
- 📅 Date and time information
- 📍 Clickable address links
- 🌐 Official websites and sources
- 💡 AI-powered insights and recommendations
- Click "💡 Get Insights" in any location modal
- Receive AI-generated advice on:
- Best times to visit
- What to try and what to avoid
- Pro tips and budget considerations
- Personalized recommendations
- Share locations with friends via generated links
- Get directions using your preferred maps app
- Copy shareable URLs for easy distribution
- FastHTML framework for rapid web development
- AI API integration with multiple models
- JSON schema validation for structured responses
- In-memory data storage for shared locations
- RESTful API endpoints for all functionality
- Google Maps JavaScript API for interactive mapping
- Bootstrap 5 for responsive UI components
- Custom CSS for enhanced styling
- Progressive enhancement with loading states
- Real-time search suggestions with debouncing
- Basic models for real-time information retrieval
- Reasoning for personalized insights
- Structured output with JSON schema enforcement
- Citation tracking for source verification
- Geographic context for location-aware results
| Endpoint | Method | Description |
|---|---|---|
/ |
GET | Main application interface |
/api/local-data |
GET | Get nearby events, restaurants, alerts |
/api/search-local |
GET | Search for specific local content |
/api/search-suggestions |
GET | Get AI-powered search suggestions |
/api/location-insights |
GET | Get personalized location recommendations |
/api/share-location |
POST | Create shareable location links |
/api/get-shared-location/{id} |
GET | Retrieve shared location data |
/shared/{id} |
GET | View shared location page |
- Perplexity
sonar- Real-time information retrieval - Perplexity
sonar-reasoning- Advanced reasoning for insights
- Real-time data access for current information
- Geographic search with coordinate-based queries
- Structured output with JSON schema validation
- Citation tracking for source verification
- Reasoning capabilities for personalized advice
# Location-based discovery
api.geo_structured_output_with_citations(
prompt="Find events, restaurants, and alerts near coordinates 37.7749, -122.4194",
schema=LOCAL_INFO_SCHEMA
)
# Personalized insights
api.get_location_insights(
location_name="Blue Bottle Coffee",
location_type="restaurant",
description="Specialty coffee roaster",
address="315 Linden St, Oakland, CA"
)- Clean, modern interface with intuitive navigation
- Color-coded categories for easy recognition
- Smooth animations and hover effects
- Mobile-first responsive design
- Professional loading states with progress indicators
- Accessible UI with proper contrast and sizing
- User accounts with saved favorites
- Push notifications for location-based alerts
- Social features with reviews and ratings
- Advanced filtering by price, rating, distance
- Offline mode with cached data
- Multi-language support for international users
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
- Google Maps for the interactive mapping platform
- Google Cloud for Cloud Computing Services that easy to use
- FastHTML for the rapid development Python framework
- Bootstrap for the responsive UI components
- Perplexity.AI for providing the AI-powered Sonar API
- Perplexity.AI - Cookbook for including CityPulse to official Perplexity.AI Cookbook
Discover your city like never before with AI-powered local insights
Built with ❤️ by Alex Nevsky