Metadata-Version: 2.2
Name: indian-address-matcher
Version: 0.1.0
Summary: A tool for matching Indian addresses to determine if they refer to the same location
Home-page: https://github.com/your-github-username/indian-address-matcher
Author: Karan
Author-email: your.email@example.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fuzzywuzzy>=0.18.0
Requires-Dist: python-Levenshtein>=0.12.2
Requires-Dist: rapidfuzz>=2.13.7
Requires-Dist: jellyfish>=0.9.0
Requires-Dist: nltk>=3.7
Requires-Dist: colorama>=0.4.6
Requires-Dist: tabulate>=0.9.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: numpy>=1.24.3
Requires-Dist: pandas>=2.0.2
Requires-Dist: geopandas>=0.13.2
Requires-Dist: geopy>=2.3.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Indian Address Matcher

A Python library for matching Indian addresses to determine if they refer to the same location, even when formatted differently or containing variations.

## Features

- **Robust Address Matching**: Determine if two differently formatted Indian addresses refer to the same location
- **Component Extraction**: Extract key components from addresses (pincode, state, city, district, locality, etc.)
- **Fuzzy Matching**: Handle typos, abbreviations, and formatting differences
- **Detailed Analysis**: Get detailed similarity scores and component-wise comparison
- **Command-line Interface**: Easy-to-use CLI for quick address matching
- **Interactive Demo**: Visual demonstration of the matching process
- **Configurable Neighboring Cities**: Easy to add neighboring city relationships for improved matching

## Installation

```bash
# Install directly from GitHub
pip install git+https://github.com/your-github-username/indian-address-matcher.git

# Or clone and install from source
git clone https://github.com/your-github-username/indian-address-matcher.git
cd indian-address-matcher
pip install -e .
```

## Quick Start

### Python API

```python
from address_matcher.src.address_matcher import AddressMatcher

# Initialize the matcher
matcher = AddressMatcher(threshold=0.75)

# Compare two addresses
address1 = "123, Lakshmi Nagar, Bangalore, Karnataka - 560001"
address2 = "123 Lakshmi Ngr, Bengaluru, KA, 560001"

# Get simple match result
score, is_match = matcher.match(address1, address2)
print(f"Match score: {score:.2f}")
print(f"Is match: {is_match}")

# Get detailed match information
details = matcher.match_with_details(address1, address2)
print(details)
```

### Command-line Interface

```bash
# Basic usage
address-matcher "123, Lakshmi Nagar, Bangalore, Karnataka - 560001" "123 Lakshmi Ngr, Bengaluru, KA, 560001"

# With detailed output
address-matcher --detailed "123, Lakshmi Nagar, Bangalore, Karnataka - 560001" "123 Lakshmi Ngr, Bengaluru, KA, 560001"

# Output as JSON
address-matcher --json "123, Lakshmi Nagar, Bangalore, Karnataka - 560001" "123 Lakshmi Ngr, Bengaluru, KA, 560001"

# Adjust matching thresholds
address-matcher --threshold 0.8 --fuzzy-threshold 90 "123, Lakshmi Nagar, Bangalore, Karnataka - 560001" "123 Lakshmi Ngr, Bengaluru, KA, 560001"
```

### Interactive Demo

```bash
# Run the interactive demo
python -m address_matcher.demo
```

## How It Works

The address matcher uses a multi-step approach to determine if two addresses refer to the same location:

1. **Preprocessing**: Normalizes addresses by removing punctuation, converting to lowercase, etc.
2. **Component Extraction**: Extracts key components like pincode, state, city, district, locality, etc.
3. **Similarity Calculation**:
   - **Pincode Similarity**: Exact match of pincodes (with tolerance for typos)
   - **Full Address Similarity**: Overall text similarity using weighted algorithms
   - **Component Similarity**: Component-wise comparison using fuzzy matching
4. **Final Score Calculation**: Weighted combination of the above similarities
5. **Match Determination**: Comparison of final score against a threshold

## Advanced Usage

### Customizing Weights

You can customize the weights for different components of the matching algorithm:

```python
# Custom weights for address components
component_weights = {
    'pincode': 0.3,
    'full_address': 0.3,
    'components': 0.4
}

# Initialize matcher with custom weights
matcher = AddressMatcher(threshold=0.75, component_weights=component_weights)
```

### Configuring Neighboring Cities

You can configure city relationships to handle neighboring cities that are often used interchangeably in addresses:

```python
# Define neighboring cities during initialization
neighboring_cities = {
    'mumbai': ['thane', 'navi mumbai'],
    'bangalore': ['electronic city', 'whitefield'],
    'delhi': ['gurgaon', 'noida', 'faridabad']
}

matcher = AddressMatcher(neighboring_cities=neighboring_cities)

# Or add them after initialization
matcher = AddressMatcher()
matcher.add_neighboring_cities('pune', ['pimpri-chinchwad', 'hinjewadi', 'wakad'])
matcher.add_neighboring_cities('chennai', ['tambaram', 'chromepet', 'porur'])
```

### Adjusting Fuzzy Matching Threshold

```python
# Set a higher threshold for fuzzy matching (more strict)
matcher = AddressMatcher(threshold=0.75, fuzzy_threshold=90)

# Set a lower threshold for fuzzy matching (more lenient)
matcher = AddressMatcher(threshold=0.75, fuzzy_threshold=70)
```

## Project Structure

```
address_matcher/
├── __init__.py
├── cli.py           # Command-line interface
├── demo.py          # Interactive demo
├── src/
│   ├── __init__.py
│   ├── address_matcher.py    # Main address matcher class
│   ├── data_loader.py        # Dataset loader for address components
│   ├── entity_extraction.py  # Address component extraction
│   ├── fuzzy_matching.py     # Fuzzy matching algorithms
│   ├── similarity.py         # Similarity calculation functions
│   └── utils.py              # Utility functions
└── tests/
    ├── __init__.py
    └── test_*.py             # Unit tests
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Acknowledgments

- Thanks to all the contributors who have helped with the development of this project.
- Special thanks to the open-source community for providing the tools and libraries that made this project possible. 
