README.md

---
title: Property Search API Documentation
description: Advanced property search with support for Urdu, Roman Urdu, and English natural language queries
version: 1.0.0
last_updated: 2026-05-21
author: Backend Team
maintainer: Backend Team
license: mit
language:
  - en
  - ur
tags:
  - property-search
  - real-estate
  - voice-search
  - urdu-asr
  - django
  - api
category: API Documentation
---
## 📚 **Property Search API - Complete Documentation**

### 🎯 **Overview**

The Property Search API provides advanced search functionality for properties with support for natural language queries, voice search integration, and intelligent filtering. The system includes text normalization for Roman Urdu and Urdu languages.

---

## 🚀 **Quick Start**

### Base URL
```
GET /api/property/search_properties/
```

### Simple Example
```bash
# Search for properties in Lahore
curl "http://localhost:8000/api/property/search_properties/?q=lahore"

# Voice search example
curl "http://localhost:8000/api/property/search_properties/?q=3%20bedroom%20house%20in%20lahore"
```

---

## 📋 **Query Parameters**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `q` | string | None | Search query (supports Urdu, Roman Urdu, English) |
| `city` | string | None | Filter by city name |
| `state` | string | None | Filter by state/town name |
| `society` | string | None | Filter by society/address name |
| `min_price` | number | None | Minimum price filter |
| `max_price` | number | None | Maximum price filter |
| `bed_match_type` | string | `min` | `exact` or `min` (minimum beds) |
| `bath_match_type` | string | `min` | `exact` or `min` (minimum baths) |
| `limit` | number | `20` | Results per page (max 100) |
| `offset` | number | `0` | Pagination offset |

---

## 🔍 **Search Query Examples**

### 1. **Basic Text Search**
```bash
# English
GET /search_properties/?q=house in lahore

# Roman Urdu  
GET /search_properties/?q=teen bedroom ka ghar lahore mein

# Urdu Script
GET /search_properties/?q=تین بیڈ روم کا گھر لاہور میں
```

### 2. **Price Range Search**
```bash
# Natural language
GET /search_properties/?q=under 50000
GET /search_properties/?q=above 100000
GET /search_properties/?q=between 50000 and 100000

# Explicit parameters
GET /search_properties/?min_price=50000&max_price=100000
```

### 3. **Bed/Bath Filters**
```bash
# Minimum 3 bedrooms
GET /search_properties/?q=3 bedrooms

# Exactly 5 bedrooms
GET /search_properties/?q=5 bedrooms&bed_match_type=exact

# Combined filters
GET /search_properties/?q=3 bedroom house&min_price=50000
```

### 4. **Location Filters**
```bash
# By city
GET /search_properties/?city=Lahore

# By society
GET /search_properties/?society=Defence

# Combined
GET /search_properties/?city=Lahore&society=Faisal%20Town
```

### 5. **Combined Search Examples**
```bash
# Complete example
GET /search_properties/?q=3 bedroom house in lahore&min_price=50000&max_price=100000

# Roman Urdu + price
GET /search_properties/?q=teen bedroom ka ghar&min_price=50000

# Location + bedrooms
GET /search_properties/?city=Lahore&society=DHA&q=5 bedrooms
```

---

## 📤 **Response Format**

### Success Response
```json
{
    "count": 4,
    "limit": 20,
    "search_criteria": [
        "searching for: 3 bedroom house in lahore",
        "keywords: bedroom, house, lahore",
        "beds: 3+"
    ],
    "results": [
        {
            "id": 1,
            "title": "Modern House",
            "price": 75000,
            "address": "Faisal Town",
            "city": "Lahore",
            "beds": 3,
            "baths": 2,
            "area": 5,
            "area_unit": "Marla",
            "status": "Approved"
        }
    ],
    "summary": {
        "total_found": 4,
        "showing": 4,
        "from": 1,
        "to": 4
    }
}
```

### No Results Response
```json
{
    "count": 0,
    "limit": 20,
    "search_criteria": ["searching for: unknown place"],
    "results": [],
    "suggestion": "No properties found. Try: using fewer words, checking spelling, adjusting price range, or removing filters."
}
```

### Error Response
```json
{
    "error": "An unexpected error occurred while searching properties.",
    "detail": "Error details in debug mode"
}
```

---

## 🔧 **Text Normalization Features**

The search query automatically normalizes:

### Roman Urdu to English
| Roman Urdu | Normalized |
|------------|------------|
| `ghar` | `house` |
| `makaan` | `house` |
| `teen` | `3` |
| `char` | `4` |
| `paanch` | `5` |
| `mein` | `in` |

### Number Words to Digits
| Word | Normalized |
|------|------------|
| `one` | `1` |
| `two` | `2` |
| `three` | `3` |
| `four` | `4` |
| `five` | `5` |

### Stop Words Removed
- English: `a`, `an`, `the`, `of`, `to`, `for`, `with`
- Roman Urdu: `ka`, `ki`, `ke`, `mein`, `se`, `ko`, `ne`

### Spelling Corrections
| Common Error | Corrected |
|--------------|-----------|
| `bedrrom` | `bedroom` |
| `bthroom` | `bathroom` |
| `hous` | `house` |
| `undr` | `under` |
| `lahor` | `lahore` |

---

## 🎤 **Voice Search Integration**

### Frontend Implementation (Web Speech API)

```javascript
const recognition = new webkitSpeechRecognition();
recognition.lang = 'ur-PK';  // Urdu language
recognition.onresult = (event) => {
    const query = event.results[0][0].transcript;
    fetch(`/search_properties/?q=${encodeURIComponent(query)}`)
        .then(response => response.json())
        .then(data => displayResults(data));
};
recognition.start();
```

### Supported Voice Commands Examples
```bash
# English
"3 bedroom house in lahore"
"properties under 50000"
"plot for sale in defence"

# Roman Urdu
"teen bedroom ka ghar lahore mein"
"under 50 hazar ke properties"
"defence mein plot"

# Mixed
"3 bedroom ka ghar lahore mein"
"property 50 lakh se kam"
```

---

## 🏗️ **Architecture**

### Request Flow
```
User Input → Normalization → Tokenization → Database Query → Relevance Scoring → Response
```

### Search Priority Order
1. **Location filters** (cheapest - indexed)
2. **Price filters** (range queries)
3. **Bed/Bath filters** (numeric comparisons)
4. **Text search** (most expensive - tokenized)

### Relevance Scoring Weights
| Match Type | Score |
|------------|-------|
| Exact title match | 150 |
| Exact city match | 100 |
| Exact society match | 80 |
| Bed count match | 80 |
| Bath count match | 75 |
| Title token match | 50-30 |
| Address token match | 30 |
| City token match | 35 |
| Description token match | 20-10 |

---

## ⚡ **Performance**

### Response Times
| Operation | Average Time |
|-----------|--------------|
| Simple search (no text) | 50-100ms |
| Text search (tokenized) | 100-200ms |
| Complex filters | 150-250ms |
| Full-text with relevance | 200-300ms |

### Limits
| Parameter | Limit |
|-----------|-------|
| Max results per page | 100 |
| Max tokens processed | 5 |
| Max search characters | 500 |
| Concurrent requests | 50 (recommended) |

---

## 🧪 **Testing Examples**

### cURL Commands
```bash
# Basic search
curl "http://localhost:8000/api/property/search_properties/?q=lahore"

# With pagination
curl "http://localhost:8000/api/property/search_properties/?q=house&limit=10&offset=20"

# All filters
curl "http://localhost:8000/api/property/search_properties/?q=3%20bedroom&city=Lahore&min_price=50000&max_price=100000&bed_match_type=min&limit=20"
```

### Python Client
```python
import requests

def search_properties(query, city=None, min_price=None, max_price=None):
    url = "http://localhost:8000/api/property/search_properties/"
    params = {
        "q": query,
        "city": city,
        "min_price": min_price,
        "max_price": max_price,
        "limit": 20
    }
    response = requests.get(url, params=params)
    return response.json()

# Example usage
results = search_properties("3 bedroom house in lahore", min_price=50000)
print(f"Found {results['count']} properties")
```

---

## 📝 **Error Handling**

| Error Code | Message | Solution |
|------------|---------|----------|
| 400 | No search parameters provided | Add at least one filter |
| 500 | Unexpected error | Check logs, retry with debug |
| Timeout | Request took too long | Reduce complexity or increase limit |

---

## 🔄 **Rate Limiting**

| Tier | Requests per minute | Burst |
|------|-------------------|-------|
| Anonymous | 30 | 10 |
| Authenticated | 100 | 20 |
| Admin | Unlimited | Unlimited |

---

## 📊 **Analytics**

The API automatically logs:
- Search queries (normalized)
- Result counts
- Response times
- User location (if provided)
- Device information (user agent)

---

## 🚀 **Best Practices**

### For Better Search Results

1. **Use specific terms**
   ```bash
   # Good
   ?q=3 bedroom house in lahore defence
   
   # Less specific
   ?q=house
   ```

2. **Combine filters**
   ```bash
   # Good
   ?q=house&city=Lahore&min_price=50000
   
   # Can be improved
   ?q=house in lahore under 50000
   ```

3. **Use voice search for natural language**
   - The API is optimized for speech-to-text input
   - Normalization handles common voice recognition errors

---

## 🐛 **Troubleshooting**

### Common Issues

| Issue | Solution |
|-------|----------|
| No results found | Remove filters, check spelling, try simpler query |
| Roman Urdu not recognized | Use standard Roman Urdu spellings |
| Price filters not working | Ensure numbers without commas |
| Slow response | Reduce result limit, simplify query |

### Debug Mode
```bash
# Enable debug for detailed errors
GET /search_properties/?q=test&debug=true
```

---

## 📞 **Support**

- **API Version**: 1.0
- **Last Updated**: 2026-05-21
- **Maintainer**: Backend Team
- **Documentation**: [Link to full docs]

---

## ✅ **Quick Reference Card**

```bash
# Most common searches
/search_properties/?q=lahore
/search_properties/?q=3 bedroom house
/search_properties/?q=under 50000
/search_properties/?q=plot in defence
/search_properties/?q=teen bedroom ka ghar

# With filters
/search_properties/?city=Lahore&society=DHA
/search_properties/?min_price=50000&max_price=100000
/search_properties/?q=3 beds&bed_match_type=min

# Pagination
/search_properties/?q=house&limit=20&offset=0
```

---

**This API is production-ready and supports Urdu, Roman Urdu, and English search queries with voice search optimization.** 🎉