Hugging Face's logo

embedingHF
/
Property_Search_Engine

English
Urdu
property-search
real-estate
voice-search
urdu-asr
django
api
Model card Files
xet
 Community
Property_Search_Engine / README.md
embedingHF's picture
embedingHF
Update README.md
a294e40 verified
preview code
|
Raw
History Blame Contribute Delete
10.4 kB
metadata 
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-21T00:00:00.000Z
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 

# 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

  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 

# 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

  1. Use specific terms

    # Good
?q=3 bedroom house in lahore defence

# Less specific
?q=house

  2. Combine filters

    # 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 

# 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. πŸŽ‰