Nitzan Pomerantz
166 lines
4.4 KiB
Markdown
166 lines
4.4 KiB
Markdown
# 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
|