Nitzan Pomerantz
14 KiB
14 KiB
API Reference
Complete reference for Nadlan-MCP's MCP tools and Python library.
Table of Contents
- MCP Tools - For AI agents (Claude, etc.)
- Python Client - For direct library usage
- Data Models - Pydantic models reference
- 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:
{
"search_text": "רוטשילד תל אביב"
}
find_recent_deals_for_address
Find all recent real estate deals for a specific address.
Parameters:
address(string, required): Address to searchyears_back(int, default: 2): Number of years to look backradius_meters(int, default: 30): Search radius in metersmax_deals(int, default: 100): Maximum deals to returndeal_type(int, default: 2): Deal type (1=new construction, 2=resale)
Returns: JSON with deals, sorted by priority and date
Example:
{
"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 coordinatelongitude(float, required): Longitude coordinateradius_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 IDlimit(int, default: 100): Maximum deals to returndeal_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 IDlimit(int, default: 100): Maximum deals to returndeal_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 analyzeyears_back(int, default: 3): Years of data to analyzeradius_meters(int, default: 100): Search radiusmax_deals(int, default: 100): Maximum deals to analyzedeal_type(int, default: 2): Deal type filter
Returns: JSON with:
- Deal statistics (prices, price/m², trends)
- Time-series analysis
- Market summary
Example:
{
"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:
{
"addresses": [
"רוטשילד 1 תל אביב",
"דיזנגוף 50 תל אביב",
"ז'בוטינסקי 1 רמת גן"
]
}
Valuation Tools
get_valuation_comparables
Get comparable properties for valuation analysis.
Parameters:
address(string, required): Address to find comparables foryears_back(int, default: 2): Years to look backproperty_type(string, optional): Filter by property type (e.g., "דירה")min_rooms(float, optional): Minimum roomsmax_rooms(float, optional): Maximum roomsmin_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 floormax_floor(int, optional): Maximum floorradius_meters(int, default: 100): Search radiusmax_comparables(int, default: 50): Max comparables to return
Returns: JSON with filtered comparable deals and statistics
Example:
{
"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 analyzeyears_back(int, default: 2): Years to analyzeproperty_type(string, optional): Filter by property typemin_rooms(float, optional): Minimum roomsmax_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 analyzeyears_back(int, default: 2): Years to analyzeradius_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
from nadlan_mcp.govmap import GovmapClient
client = GovmapClient()
Main Methods
autocomplete_address()
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:
result = client.autocomplete_address("רוטשילד תל אביב")
for address in result.results:
print(f"{address.text} - {address.coordinates}")
find_recent_deals_for_address()
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:
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()
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:
filtered = client.filter_deals_by_criteria(
deals,
property_type="דירה",
min_rooms=3,
max_rooms=4,
min_price=1000000,
max_price=2000000
)
calculate_deal_statistics()
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()
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()
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()
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.
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.
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.
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.
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.
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
# 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
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
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 lookupmarket_analysis.py- Trend analysisinvestment_analysis.py- Multi-location comparisonvaluation.py- Property valuation
For more information, see:
- README.md - Overview and quickstart
- DEPLOYMENT.md - Deployment guide
- CONTRIBUTING.md - Development guide