Examples and code quality

2025-10-31 00:31:14 +02:00
parent e4aa6487ff
commit 739d4f8578
9 changed files with 508 additions and 27 deletions
@@ -0,0 +1,165 @@
+# Nadlan-MCP Usage Examples
+
+This directory contains practical examples demonstrating how to use the Nadlan-MCP library for Israeli real estate data analysis.
+
+## Prerequisites
+
+```bash
+# Install nadlan-mcp
+pip install -r requirements.txt
+
+# Or if installed as package
+pip install nadlan-mcp
+```
+
+## Running the Examples
+
+All examples can be run directly:
+
+```bash
+python examples/basic_search.py
+python examples/market_analysis.py
+python examples/investment_analysis.py
+python examples/valuation.py
+```
+
+## Examples
+
+### 1. Basic Address Search (`basic_search.py`)
+
+**What it does:**
+- Searches for recent real estate deals near a specific address
+- Displays deal details including price, rooms, area, and price per m²
+
+**Use case:** Quick lookup of recent transactions in a specific location
+
+**Run:**
+```bash
+python examples/basic_search.py
+```
+
+### 2. Market Analysis (`market_analysis.py`)
+
+**What it does:**
+- Analyzes market trends for a specific area over multiple years
+- Calculates price statistics, market activity, liquidity, and investment potential
+- Provides comprehensive metrics for understanding local market dynamics
+
+**Use case:** Deep-dive analysis of a neighborhood's real estate market
+
+**Run:**
+```bash
+python examples/market_analysis.py
+```
+
+### 3. Investment Comparison (`investment_analysis.py`)
+
+**What it does:**
+- Compares multiple neighborhoods side-by-side
+- Evaluates investment potential based on activity, liquidity, trends, and appreciation
+- Recommends the best investment opportunity
+
+**Use case:** Comparing different areas to identify the best investment location
+
+**Run:**
+```bash
+python examples/investment_analysis.py
+```
+
+### 4. Property Valuation (`valuation.py`)
+
+**What it does:**
+- Finds comparable properties based on size, rooms, and floor
+- Calculates estimated property value using price per m² from comparables
+- Provides valuation range (25th-75th percentile)
+
+**Use case:** Estimating the fair market value of a specific property
+
+**Run:**
+```bash
+python examples/valuation.py
+```
+
+## Modifying the Examples
+
+All examples are designed to be easily customizable:
+
+1. **Change the address:** Edit the `address` variable to analyze different locations
+2. **Adjust time period:** Modify `years_back` parameter to look further back
+3. **Change search radius:** Adjust `radius` parameter (in meters)
+4. **Add filters:** Use `filter_deals_by_criteria()` to filter by property type, rooms, price, etc.
+
+### Example Modifications
+
+```python
+# Analyze last 5 years instead of 2
+deals = client.find_recent_deals_for_address(address, years_back=5)
+
+# Use wider search radius (500m instead of default)
+deals = client.find_recent_deals_for_address(address, radius=500)
+
+# Filter for apartments only
+filtered = client.filter_deals_by_criteria(
+    deals,
+    property_type="דירה",
+    min_rooms=3,
+    max_rooms=4,
+    min_price=1000000,
+    max_price=2000000
+)
+```
+
+## Tips for Best Results
+
+1. **Use Hebrew addresses:** The API works best with Hebrew street names and city names
+   - Good: `"רוטשילד 1 תל אביב"`
+   - OK: `"Rothschild 1 Tel Aviv"`
+
+2. **Adjust radius based on density:**
+   - High-density areas (Tel Aviv, Jerusalem): 50-100m
+   - Medium-density (Ramat Gan, Herzliya): 100-200m
+   - Low-density areas: 200-500m
+
+3. **Time periods:**
+   - Quick analysis: 1-2 years
+   - Trend analysis: 3-5 years
+   - Historical perspective: 5+ years (data availability varies)
+
+4. **Use filters for precision:**
+   - When valuing property: filter by similar size, rooms, and floor
+   - When comparing markets: don't filter too much (need enough data)
+
+## Common Use Cases
+
+### 1. Pre-Purchase Research
+```bash
+# Run market analysis and valuation for target property
+python examples/market_analysis.py  # Understand the market
+python examples/valuation.py        # Estimate fair value
+```
+
+### 2. Investment Decision
+```bash
+# Compare multiple locations
+python examples/investment_analysis.py
+```
+
+### 3. Market Monitoring
+```bash
+# Regular analysis to track market changes
+python examples/basic_search.py
+```
+
+## Need More Help?
+
+- See main [README.md](../README.md) for full API documentation
+- Check [CLAUDE.md](../CLAUDE.md) for development guide
+- Review [ARCHITECTURE.md](../ARCHITECTURE.md) for system design
+
+## Contributing
+
+Have an idea for a new example? Please submit a pull request! Good examples should:
+- Solve a real use case
+- Be well-commented
+- Include error handling
+- Be easy to modify