📚 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

# 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

# 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

# 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

# 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

# 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

# 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

{
    "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

{
    "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

{
    "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)

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

# 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

Location filters (cheapest - indexed)
Price filters (range queries)
Bed/Bath filters (numeric comparisons)
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

# 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

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

Use specific terms

# Good
?q=3 bedroom house in lahore defence

# Less specific
?q=house

Combine filters

# Good
?q=house&city=Lahore&min_price=50000

# Can be improved
?q=house in lahore under 50000

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

# 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

# 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. 🎉

Downloads last month: -; Downloads are not tracked for this model. How to track

Inference Providers NEW

This model isn't deployed by any Inference Provider. 🙋 Ask for provider support