ShelfGap is a Python application that compares product catalogs between two retail chains to identify pricing gaps, availability differences, and product similarities. It uses fuzzy string matching to find products that are similar but have slight naming variations.
- Automated Product Matching: Compare product lists from two Excel files
- Fuzzy String Matching: Uses RapidFuzz library to find similar products with configurable similarity thresholds
- Detailed Reports: Generate comprehensive comparison reports with statistics
- Multiple Match Categories:
- Exact matches (identical product names)
- Similar matches (with similarity percentages)
- Products unique to each store
- Flexible Input: Automatically detects the first column in Excel files as product names
- Terminal & File Output: View results in terminal or save detailed reports to files
- Clone or download the repository
- Install required dependencies:
pip install -r requirements.txtpandas>=1.3.0- Data manipulation and Excel file handlingopenpyxl>=3.0.0- Excel file reading/writing supportrapidfuzz>=3.0.0- Fast fuzzy string matching
python compare.py file1.xlsx file2.xlsxpython compare.py file1.xlsx file2.xlsx --output custom_report.txtpython compare.py data/mudi.tea.xlsx data/shwapno.tea.xlsxThis will:
- Load product lists from both Excel files
- Compare products using fuzzy matching (80% similarity threshold)
- Generate a report saved to
reports/comparison.mudi.tea.shwapno.tea.txt - Display summary results in the terminal
shelfgap/
├── compare.py # Main entry point and CLI interface
├── compare_products.py # Core product matching algorithm
├── load_excel_column.py # Excel file data loader
├── report_generator.py # Report formatting and file output
├── create_test_data.py # Sample data generator
├── requirements.txt # Python dependencies
├── data/ # Sample data files
│ ├── chain1_products.xlsx
│ ├── chain2_products.xlsx
│ ├── mudi.tea.xlsx
│ └── shwapno.tea.xlsx
└── reports/ # Generated comparison reports
└── comparison.*.txt
- Data Loading: Reads the first column from each Excel file as product names
- Exact Matching: Finds products with identical names (case-insensitive)
- Fuzzy Matching: Uses RapidFuzz to find similar products with ≥80% similarity
- Categorization: Groups results into exact matches, similar matches, and unique products
- Report Generation: Creates detailed text reports with timestamps and statistics
📊 COMPARISON RESULTS:
Exact matches: 5
Similar matches: 14
Only in mudi.tea.xlsx: 25
Only in shwapno.tea.xlsx: 18
🔍 SIMILAR MATCHES (14):
1. Ispahani Blender's Choice Black Tea 200gm ≈ Ispahani Blenders Choice Tea 100gm (Bag) (81.48% match)
2. Tetley Green Tea- Pure original (25 sachet) ≈ Tetley Green Tea Pure Original (25 Tea Bag) (83.72% match)
...
The similarity threshold is set to 80% by default in compare_products.py:4. You can modify this value to make matching more or less strict:
def compare_products(products1, products2, threshold=80):- Retail Competition Analysis: Compare product offerings between competing stores
- Inventory Management: Identify gaps in product catalogs
- Market Research: Analyze product naming variations across retailers
- Price Comparison Setup: Prepare data for price comparison tools
- Supply Chain Analysis: Find common suppliers across different retailers
This is a focused tool for product comparison analysis. When contributing:
- Maintain the existing code style and structure
- Test with various Excel file formats
- Ensure fuzzy matching accuracy for your use case
- Update documentation for any new features
This project is provided as-is for product comparison and analysis purposes.