NoCapRide - Demand Forecasting & Surge Pricing API

A machine learning-powered ride-hailing platform backend with intelligent demand forecasting and surge pricing capabilities.

Demo --- Repo Version while recording video

Project Overview

NoCapRide provides a robust backend API for ride-hailing platforms, focusing on:

• Machine learning-powered demand prediction
• Dynamic surge pricing
• Real-time data processing
• Spatial demand analysis

The system helps both riders and drivers by balancing supply and demand through intelligent forecasting.

Project Structure

NoCapRide/
├── cache/ # Cached forecasts and API responses (auto-generated)
│ └── forecasts/ # Stored forecast data
├── server/ # Backend server modules
│ ├── api.py # API endpoints
│ ├── cache_manager.py # Cache management logic
│ ├── custom_logger.py # Custom logging setup
│ ├── data_manager.py # Data management logic
│ └── forecaster.py # Forecasting logic
├── archive/ # Development history
│ ├── attempt-1/ # Initial implementation
│ ├── attempt-2/ # Second iteration with fetch module
│ ├── attempt-3/ # Third iteration
│ ├── data/ # Archive data files
│ └── static-data/ # Static reference data
├── client/ # Frontend client application
│ ├── app/ # Next.js app directory
│ ├── components/ # React components
│ ├── lib/ # Shared utilities
│ ├── public/ # Static assets
│ ├── README.md # Frontend documentation
│ ├── package.json # Frontend dependencies
│ ├── next.config.ts # Next.js configuration
│ └── components.json # Component configurations
├── logs/ # Application logs
│ ├── api_log.txt # API service logs
│ ├── forecast_log.txt # Forecasting engine logs
│ └── forecast_output.log # Forecast results
├── ... other default files

Features

Demand Forecasting

• Time-series forecasting for ride requests by region
• Historical trend analysis
• Feature engineering for temporal patterns
• Random Forest regression model for prediction

Surge Pricing

• Dynamic pricing based on supply-demand ratio
• Configurable pricing parameters
• Region-specific pricing adjustments
• Real-time price calculation API

Spatial Analysis

• Nearby high-demand area recommendations
• Region-based demand visualization
• Geographic demand patterns detection

API Endpoints

Forecasting

• GET /api/forecast - Get demand forecast for specified region and time window
• GET /api/forecast/all - Get forecasts for all regions
• GET /api/regions - Get available regions for forecasting

Pricing

• POST /api/surge_pricing - Calculate surge pricing for a specific trip
• POST /api/demand_forecast_ratio - Get the ratio between forecasted demand and active drivers

Recommendations

• GET /api/nearby_high_demand - Get high-demand locations near a specified region

Utility

• GET /api/health - Health check endpoint

Setup Instructions

1. Install Python dependencies:

   pip install -r requirements.txt

2. Start the FastAPI server:

   uvicorn api:app --host 127.0.0.1 --port 8888 --reload

3. Access the API documentation:

   http://127.0.0.1:8888/docs
   

Configuration

The system is configured to:

• Refresh data from endpoints automatically
• Cache forecast results for performance
• Train/update models on a schedule
• Generate visualizations of forecasts

Technical Implementation

The system uses:

• FastAPI: Modern, high-performance web framework
• pandas: Data manipulation and analysis
• scikit-learn: Machine learning model implementation
• matplotlib: Data visualization
• Threading: Parallel processing for forecasts

License

This project is licensed under the MPL v2 License.