docs(showcase): CityPulse - AI-powered Geospatial Search with Sonar API

[anevsky]

Description

CityPulse - AI-Powered Geospatial Discovery Search showcase project to the Perplexity AI cookbook. This is a complete location-based discovery app that demonstrates real-time information retrieval, structured data extraction, and AI-powered reasoning using Perplexity's Sonar models with geographic context.

Type of Contribution

• Example Tutorial
• Showcase Project
• Article/Integration Guide
• Documentation Update
• Bug Fix
• Other (please describe)

Checklist

• My code follows the cookbook's style guidelines
• I have included comprehensive documentation
• I have tested my code and it works as expected
• I have included all necessary dependencies and setup instructions
• My MDX file includes proper frontmatter (title, description, keywords)
• I have linked to any external repositories or live demos

Project Details

What problem does this solve?
CityPulse addresses the challenge of discovering relevant, real-time local information in a personalized way. Traditional location apps provide static listings, but CityPulse leverages Perplexity AI to:

• Provide current, real-time information about events, restaurants, and local alerts
• Generate personalized insights and recommendations using AI reasoning
• Validate information with proper citations and source tracking
• Combine geographic context with natural language search capabilities

What makes this contribution valuable to other developers?
This project serves as a comprehensive reference implementation for developers wanting to build location-aware applications with Perplexity AI. It demonstrates:

• Real-world Sonar API usage with both sonar and sonar-reasoning models
• Structured output implementation with JSON schema validation
• Geographic context queries showing how to incorporate coordinates and location data
• Citation handling for reliable information verification
• Full-stack integration combining FastHTML backend with interactive frontend
• Production deployment example with working live demo

The codebase shows practical patterns for handling real-time data, managing API responses, and creating user-friendly interfaces for AI-powered location services.

External Links (if applicable):

• GitHub Repository: https://github.com/anevsky/CityPulse
• Live Demo: https://citypulse-ppx.uc.r.appspot.com/
• Video Demo: https://youtu.be/Y0UIhh3diJg

Testing

The project has been thoroughly tested with:

• Live deployment on Google Cloud Platform with real user interactions
• API integration testing with Perplexity Sonar models for various geographic locations
• Cross-browser compatibility testing on desktop and mobile devices
• Real-time data validation ensuring accurate location information and proper citation handling
• Geographic accuracy testing across different cities and coordinate systems
• Load testing with multiple concurrent users and API requests

Screenshots (if applicable)

The MDX file includes comprehensive screenshots showing:

• Main interface with interactive map and location markers
• Search functionality with AI-powered suggestions
• Detailed location modals with real-time information
• AI-generated insights and personalized recommendations
• Video demo showcasing full user workflow

Additional Notes

• Perplexity Hackathon: This project was developed for the official Perplexity AI Hackathon, showcasing best practices for Sonar API integration
• Educational Value: Includes detailed code explanations and implementation patterns that other developers can learn from and adapt
• Production Ready: Features proper error handling, fallback mechanisms, and production deployment configuration
• Extensible Architecture: Modular design allows for easy customization and feature additions
• Performance Optimized: Implements efficient data loading, caching strategies, and responsive UI patterns

This contribution adds significant value to the cookbook by providing a real-world, production-quality example of building sophisticated AI-powered location applications with Perplexity API.

[kesku]

Great demo, but it's 270+ lines and reads more like a full developer README than a showcase.

Should trim this to just focus on:

• What CityPulse is
• What it does
• How it uses Sonar
• Repo/Demo link

[kesku]

Live on https://docs.perplexity.ai/cookbook/showcase/citypulse-ai-search