# API Reference

Complete reference for Nadlan-MCP's MCP tools and Python library.

## Table of Contents

- [MCP Tools](#mcp-tools) - For AI agents (Claude, etc.)
- [Python Client](#python-client) - For direct library usage
- [Data Models](#data-models) - Pydantic models reference
- [Configuration](#configuration) - Environment variables and settings

---

## MCP Tools

These tools are available when running Nadlan-MCP as an MCP server.

### Core Tools

#### `autocomplete_address`

Search and validate Israeli addresses.

**Parameters:**
- `search_text` (string, required): Address to search (Hebrew or English)

**Returns:** JSON with matching addresses and coordinates

**Example:**
```json
{
  "search_text": "רוטשילד תל אביב"
}
```

---

#### `find_recent_deals_for_address`

Find all recent real estate deals for a specific address.

**Parameters:**
- `address` (string, required): Address to search
- `years_back` (int, default: 2): Number of years to look back
- `radius_meters` (int, default: 30): Search radius in meters
- `max_deals` (int, default: 100): Maximum deals to return
- `deal_type` (int, default: 2): Deal type (1=new construction, 2=resale)

**Returns:** JSON with deals, sorted by priority and date

**Example:**
```json
{
  "address": "רוטשילד 1 תל אביב",
  "years_back": 2,
  "radius_meters": 50
}
```

---

#### `get_deals_by_radius`

Get polygon metadata within a radius of coordinates.

**Parameters:**
- `latitude` (float, required): Latitude coordinate
- `longitude` (float, required): Longitude coordinate
- `radius_meters` (int, default: 500): Search radius in meters

**Returns:** JSON with polygon metadata (NOT individual deals)

**Note:** This returns **polygon metadata**, not deals. Use `get_street_deals` or `find_recent_deals_for_address` for actual deals.

---

#### `get_street_deals`

Get deals for a specific street polygon.

**Parameters:**
- `polygon_id` (string, required): Street polygon ID
- `limit` (int, default: 100): Maximum deals to return
- `deal_type` (int, default: 2): Deal type filter

**Returns:** JSON with street-level deals

---

#### `get_neighborhood_deals`

Get deals for a neighborhood polygon.

**Parameters:**
- `polygon_id` (string, required): Neighborhood polygon ID
- `limit` (int, default: 100): Maximum deals to return
- `deal_type` (int, default: 2): Deal type filter

**Returns:** JSON with neighborhood-level deals

---

### Analysis Tools

#### `analyze_market_trends`

Analyze market trends and price patterns for an area.

**Parameters:**
- `address` (string, required): Address to analyze
- `years_back` (int, default: 3): Years of data to analyze
- `radius_meters` (int, default: 100): Search radius
- `max_deals` (int, default: 100): Maximum deals to analyze
- `deal_type` (int, default: 2): Deal type filter

**Returns:** JSON with:
- Deal statistics (prices, price/m², trends)
- Time-series analysis
- Market summary

**Example:**
```json
{
  "address": "דיזנגוף 50 תל אביב",
  "years_back": 3
}
```

---

#### `compare_addresses`

Compare real estate markets between multiple addresses.

**Parameters:**
- `addresses` (array of strings, required): List of addresses to compare

**Returns:** JSON with comparative analysis

**Example:**
```json
{
  "addresses": [
    "רוטשילד 1 תל אביב",
    "דיזנגוף 50 תל אביב",
    "ז'בוטינסקי 1 רמת גן"
  ]
}
```

---

### Valuation Tools

#### `get_valuation_comparables`

Get comparable properties for valuation analysis.

**Parameters:**
- `address` (string, required): Address to find comparables for
- `years_back` (int, default: 2): Years to look back
- `property_type` (string, optional): Filter by property type (e.g., "דירה")
- `min_rooms` (float, optional): Minimum rooms
- `max_rooms` (float, optional): Maximum rooms
- `min_price` (float, optional): Minimum price (NIS)
- `max_price` (float, optional): Maximum price (NIS)
- `min_area` (float, optional): Minimum area (m²)
- `max_area` (float, optional): Maximum area (m²)
- `min_floor` (int, optional): Minimum floor
- `max_floor` (int, optional): Maximum floor
- `radius_meters` (int, default: 100): Search radius
- `max_comparables` (int, default: 50): Max comparables to return

**Returns:** JSON with filtered comparable deals and statistics

**Example:**
```json
{
  "address": "רוטשילד 10 תל אביב",
  "min_rooms": 3,
  "max_rooms": 4,
  "min_area": 70,
  "max_area": 100
}
```

---

#### `get_deal_statistics`

Calculate statistical aggregations on deal data.

**Parameters:**
- `address` (string, required): Address to analyze
- `years_back` (int, default: 2): Years to analyze
- `property_type` (string, optional): Filter by property type
- `min_rooms` (float, optional): Minimum rooms
- `max_rooms` (float, optional): Maximum rooms

**Returns:** JSON with statistics (mean, median, percentiles, std dev)

---

#### `get_market_activity_metrics`

Get comprehensive market activity and investment analysis.

**Parameters:**
- `address` (string, required): Address to analyze
- `years_back` (int, default: 2): Years to analyze
- `radius_meters` (int, default: 100): Search radius

**Returns:** JSON with:
- Market activity score and trends
- Market liquidity metrics
- Investment potential analysis
- Price appreciation and volatility

---

## Python Client

For direct Python usage without MCP.

### Installation

```python
from nadlan_mcp.govmap import GovmapClient
client = GovmapClient()
```

### Main Methods

#### `autocomplete_address()`

```python
def autocomplete_address(search_text: str) -> AutocompleteResponse:
    """
    Search for addresses using autocomplete.

    Args:
        search_text: Address to search (Hebrew or English)

    Returns:
        AutocompleteResponse with matching addresses

    Raises:
        ValueError: If search text is invalid
        requests.RequestException: On API errors
    """
```

**Example:**
```python
result = client.autocomplete_address("רוטשילד תל אביב")
for address in result.results:
    print(f"{address.text} - {address.coordinates}")
```

---

#### `find_recent_deals_for_address()`

```python
def find_recent_deals_for_address(
    address: str,
    years_back: int = 2,
    radius: int = 50,
    max_deals: int = 100,
    deal_type: int = 2
) -> List[Deal]:
    """
    Find all relevant deals for an address.

    Args:
        address: Address to search
        years_back: Years to look back (default: 2)
        radius: Search radius in meters (default: 50)
        max_deals: Maximum deals to return (default: 100)
        deal_type: 1=new construction, 2=resale (default: 2)

    Returns:
        List of Deal models, sorted by priority and date

    Raises:
        ValueError: If address invalid or no results found
    """
```

**Example:**
```python
deals = client.find_recent_deals_for_address(
    "רוטשילד 1 תל אביב",
    years_back=3,
    radius=100
)

for deal in deals[:5]:
    print(f"{deal.address_description}: ₪{deal.deal_amount:,.0f}")
```

---

#### `filter_deals_by_criteria()`

```python
def filter_deals_by_criteria(
    deals: List[Deal],
    property_type: Optional[str] = None,
    min_rooms: Optional[float] = None,
    max_rooms: Optional[float] = None,
    min_price: Optional[float] = None,
    max_price: Optional[float] = None,
    min_area: Optional[float] = None,
    max_area: Optional[float] = None,
    min_floor: Optional[int] = None,
    max_floor: Optional[int] = None,
) -> List[Deal]:
    """
    Filter deals by various criteria.

    Args:
        deals: List of Deal models to filter
        property_type: Property type (Hebrew, e.g., "דירה")
        min_rooms/max_rooms: Room count range
        min_price/max_price: Price range (NIS)
        min_area/max_area: Area range (m²)
        min_floor/max_floor: Floor range

    Returns:
        Filtered list of Deal models

    Raises:
        ValueError: If filter ranges are invalid
    """
```

**Example:**
```python
filtered = client.filter_deals_by_criteria(
    deals,
    property_type="דירה",
    min_rooms=3,
    max_rooms=4,
    min_price=1000000,
    max_price=2000000
)
```

---

#### `calculate_deal_statistics()`

```python
def calculate_deal_statistics(deals: List[Deal]) -> DealStatistics:
    """
    Calculate statistical aggregations.

    Args:
        deals: List of Deal models

    Returns:
        DealStatistics model with mean, median, percentiles, etc.

    Raises:
        ValueError: If deals list is empty
    """
```

---

#### `calculate_market_activity_score()`

```python
def calculate_market_activity_score(
    deals: List[Deal],
    time_period_months: Optional[int] = None
) -> MarketActivityScore:
    """
    Calculate market activity metrics.

    Args:
        deals: List of Deal models
        time_period_months: Time period to analyze (None = all data)

    Returns:
        MarketActivityScore model

    Raises:
        ValueError: If deals list is empty
    """
```

---

#### `get_market_liquidity()`

```python
def get_market_liquidity(
    deals: List[Deal],
    time_period_months: Optional[int] = None
) -> LiquidityMetrics:
    """
    Calculate market liquidity metrics.

    Args:
        deals: List of Deal models
        time_period_months: Time period to analyze

    Returns:
        LiquidityMetrics model

    Raises:
        ValueError: If deals list is empty
    """
```

---

#### `analyze_investment_potential()`

```python
def analyze_investment_potential(deals: List[Deal]) -> InvestmentAnalysis:
    """
    Analyze investment potential of an area.

    Args:
        deals: List of Deal models

    Returns:
        InvestmentAnalysis model

    Raises:
        ValueError: If deals list is empty or insufficient data
    """
```

---

## Data Models

All models are Pydantic v2 models with validation.

### Deal

Primary model for real estate transaction data.

```python
class Deal(BaseModel):
    objectid: int
    deal_amount: Optional[float]
    deal_date: date | str
    property_type_description: Optional[str]
    rooms: Optional[float]
    asset_area: Optional[float]
    floor_number: Optional[int]
    floor: Optional[str]
    address_description: Optional[str]

    # Computed field
    @computed_field
    @property
    def price_per_sqm(self) -> Optional[float]:
        """Calculate price per square meter."""
        if self.deal_amount and self.asset_area and self.asset_area > 0:
            return self.deal_amount / self.asset_area
        return None
```

### DealStatistics

Statistical aggregations on deal data.

```python
class DealStatistics(BaseModel):
    count: int
    mean_price: float
    median_price: float
    min_price: float
    max_price: float
    std_dev_price: float
    percentile_25_price: float
    percentile_75_price: float
    mean_price_per_sqm: Optional[float]
    median_price_per_sqm: Optional[float]
    # ... more fields
```

### MarketActivityScore

Market activity metrics.

```python
class MarketActivityScore(BaseModel):
    activity_score: float  # 0-100
    activity_level: str  # very_high, high, moderate, low, very_low
    trend: str  # improving, stable, declining
    deals_per_month: float
    unique_months: int
    total_deals: int
```

### InvestmentAnalysis

Investment potential analysis.

```python
class InvestmentAnalysis(BaseModel):
    investment_score: float  # 0-100
    price_trend: str
    price_appreciation_rate: float  # % per year
    market_stability: str
    volatility_score: float
    recommendation: str
```

### LiquidityMetrics

Market liquidity analysis.

```python
class LiquidityMetrics(BaseModel):
    liquidity_score: float  # 0-100
    total_deals: int
    avg_deals_per_month: float
    deal_velocity: float
    market_activity_level: str
    trend_direction: str
```

---

## Configuration

### Environment Variables

```bash
# API Settings
GOVMAP_BASE_URL=https://www.govmap.gov.il/api/
GOVMAP_USER_AGENT=NadlanMCP/2.0.0

# Timeouts (seconds)
GOVMAP_CONNECT_TIMEOUT=10
GOVMAP_READ_TIMEOUT=30

# Retry Settings
GOVMAP_MAX_RETRIES=3
GOVMAP_RETRY_MIN_WAIT=1
GOVMAP_RETRY_MAX_WAIT=10

# Rate Limiting
GOVMAP_REQUESTS_PER_SECOND=5.0

# Defaults
GOVMAP_DEFAULT_RADIUS=50
GOVMAP_DEFAULT_YEARS_BACK=2
GOVMAP_DEFAULT_DEAL_LIMIT=100

# Performance
GOVMAP_MAX_POLYGONS=10
```

### Programmatic Configuration

```python
from nadlan_mcp.config import GovmapConfig, set_config

config = GovmapConfig(
    connect_timeout=15,
    read_timeout=45,
    max_retries=5,
    requests_per_second=3.0,
    max_polygons=5
)
set_config(config)
```

---

## Error Handling

### Common Errors

**ValueError**
- Invalid input parameters
- Empty results
- Invalid filter ranges

**requests.RequestException**
- Network errors
- API timeouts
- HTTP errors

**pydantic.ValidationError**
- Invalid model data (handled internally, logged as warnings)

### Example

```python
from nadlan_mcp.govmap import GovmapClient

client = GovmapClient()

try:
    deals = client.find_recent_deals_for_address("invalid")
except ValueError as e:
    print(f"Invalid input: {e}")
except requests.RequestException as e:
    print(f"API error: {e}")
```

---

## Rate Limiting

Built-in rate limiting respects API limits:
- Default: 5 requests/second
- Configurable via `GOVMAP_REQUESTS_PER_SECOND`
- Automatic retry with exponential backoff

---

## Examples

See `examples/` directory for complete usage examples:
- `basic_search.py` - Simple address lookup
- `market_analysis.py` - Trend analysis
- `investment_analysis.py` - Multi-location comparison
- `valuation.py` - Property valuation

---

For more information, see:
- [README.md](README.md) - Overview and quickstart
- [DEPLOYMENT.md](DEPLOYMENT.md) - Deployment guide
- [CONTRIBUTING.md](CONTRIBUTING.md) - Development guide