Metadata-Version: 2.4
Name: pynadlan
Version: 0.2.0
Summary: A Python wrapper for the israel Nadlan prices.
Home-page: https://github.com/bensterenson/pynadlan
Author: Your Name
Author-email: bensterenson@gmail.com
Description-Content-Type: text/markdown
Requires-Dist: httpx
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: requires-dist
Dynamic: summary

# 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

```bash
pip install -e .
```

### Quickstart

```python
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)
