pynadlan 0.2.0

A Python wrapper for the israel Nadlan prices.

pynadlan

Lightweight async helpers to fetch Israeli real-estate data including historical price trends, city/neighborhood statistics, and detailed transaction records from the dirobot.co.il API.

Installation

pip install -e .

Quickstart

import asyncio
from pynadlan.api import (
    get_avg_prices,
    get_rent_prices,
    get_cities_summary,
    get_neighborhoods_summary,
    get_city_timeseries,
    get_street_deals,
    get_autocomplete_lists
)

async def main():
    # Historical price queries (histogram data)
    query = "רמת גן"
    sell_latest = await get_avg_prices(query)
    # => {"sell_2_price": 2500000, "sell_3_price": 3200000, ...}

    rent_latest = await get_rent_prices(query, rooms=[3, 4])
    # => {"rent_3_price": 7500, "rent_4_price": 9000}

    # Cities summary - median prices across all Israeli cities
    summary = await get_cities_summary(min_deals=100)
    # => {"total_cities": 303, "cities": [...], "total_deals_all_cities": 88081, ...}

    # Neighborhoods summary - breakdown for a specific city
    neighborhoods = await get_neighborhoods_summary(city="תל אביב יפו", min_deals=10)
    # => {"neighborhoods": [...], "average_median_price_overall": 2600725.6, ...}

    # City timeseries - historical price trends over time
    timeseries = await get_city_timeseries(city="תל אביב יפו", time_range="1year")
    # => {"timeSeriesByRooms": {...}, "summaries": {...}, "metadata": {...}}

    # Street deals - detailed transaction data for a specific street
    deals = await get_street_deals(city_street="תל אביב יפו_גורדון", per_page=100)
    # => {"deals": [...], "summary": {"medianPrice": ..., "totalDeals": ...}, ...}

    # Static autocomplete lists
    lists = get_autocomplete_lists()
    # => {"cities": [...], "cities_and_neighborhoods": [...]}

if __name__ == "__main__":
    asyncio.run(main())

API Reference

Historical Price Data (Histogram-based)

get_avg_prices(query: str, rooms: int | list[int] | None = None) -> dict

• Returns the latest sell prices per room count for a city/neighborhood
• Keyed by sell_{rooms}_price (e.g., sell_3_price, sell_4_price)
• If rooms is omitted, returns all available room-based series
• If rooms is provided but some series are missing, they are returned as None

get_rent_prices(query: str, rooms: int | list[int] | None = None) -> dict

• Returns the latest rent prices per room count for a city/neighborhood
• Keyed by rent_{rooms}_price (e.g., rent_3_price, rent_4_price)
• Same filtering behavior as get_avg_prices

Aggregate Statistics

get_cities_summary(min_deals: int = 10) -> dict

• Returns median prices and deal counts across all Israeli cities
• Results include: total_cities, total_deals_all_cities, cities array
• Each city includes: city_name, medianPrice, total_deals, date_range
• Sorted by deal volume (most active cities first)

get_neighborhoods_summary(city: str, min_deals: int = 3) -> dict

• Returns neighborhood-level statistics for a specific city
• City name should be in Hebrew (e.g., "תל אביב יפו", "רעננה")
• Results include: neighborhoods array, average_median_price_overall
• Each neighborhood includes: neighborhood, median_price, total_deals, unique_streets

Historical Trends

get_city_timeseries(city: str, property_type: str = "apartment", time_range: str = "1year") -> dict

• Returns historical price trends over time for a city, broken down by room count
• time_range options: "1year", "2years", "all"
• Results include monthly data: marketValue, askingPrice, growth, transactionCount
• Summary statistics per room category: avgPrice, minPrice, maxPrice, totalTransactions

Detailed Transaction Data

get_street_deals(city_street: str, per_page: int = 10000) -> dict

• Returns detailed transaction/deal data for a specific street
• city_street format: "city_street" in Hebrew (e.g., "תל אביב יפו_גורדון")
• Results include individual deals with: buildYear, floor, price, rooms, saleDate, squareMeters (optional)
• Summary statistics: avgPrice, medianPrice, totalDeals, avgPricePerSquareMeter
• Includes pagination information

Utilities

get_autocomplete_lists() -> dict (synchronous)

• Returns static lists for autocomplete functionality
• Keys: cities (array of city names), cities_and_neighborhoods (combined array)

Notes

• All data-fetching functions are async and must be awaited
• Query parameters (city/neighborhood names) are URL-encoded automatically
• Hebrew and English city names are supported where applicable
• All prices are in ILS (Israeli Shekels)