### Install pyfunda

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Install the pyfunda library using pip. This is the only setup required to start using the library.

```bash
pip install pyfunda
```

--------------------------------

### Install pyfunda and dependencies

Source: https://github.com/0xmh/pyfunda/blob/main/examples/analysis.ipynb

Install the necessary packages to run the analysis notebook.

```bash
uv pip install pyfunda pandas matplotlib
```

--------------------------------

### Get Detailed Listing Information

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Retrieve detailed information for a specific listing using its ID. This example prints a summary and then iterates through all characteristics.

```python
from funda import Funda

f = Funda()
listing = f.get_listing(43117443)

print(listing.summary())

# Access all characteristics
for key, value in listing['characteristics'].items():
    print(f"{key}: {value}")
```

--------------------------------

### Using Listing Methods

Source: https://context7.com/0xmh/pyfunda/llms.txt

Utilize built-in methods of the listing object to get a text summary, convert to a dictionary, list available keys, or retrieve a value with a default.

```python
print(listing.summary())    # Text summary
data = listing.to_dict()    # Plain dictionary
keys = listing.keys()       # List of available keys
val = listing.get('key', 'default')  # Get with default
```

--------------------------------

### Search Listings by Location and Price

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Find apartments in a specific city with a maximum price using the Funda search functionality. This example iterates through results and prints basic listing details.

```python
from funda import Funda

f = Funda()
results = f.search_listing('amsterdam', price_max=400000)

for listing in results:
    print(f"{listing['title']}")
    print(f"  Price: €{listing['price']:,}")
    print(f"  Area: {listing.get('living_area', 'N/A')}")
    print(f"  Bedrooms: {listing.get('bedrooms', 'N/A')}")
    print()
```

--------------------------------

### Get price history for a listing

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Retrieve historical price data for a specific listing and calculate percentage changes.

```python
from funda import Funda

f = Funda()
listing = f.get_listing(43032486)

# Fetch historical prices (WOZ assessments, previous asking prices, sales)
history = f.get_price_history(listing)

print(f"Price history for {listing['title']}:")
for change in history:
    print(f"  {change['date']}: {change['human_price']} ({change['status']})")

# Calculate price change over time
funda_prices = [c for c in history if c['source'] == 'Funda']
if len(funda_prices) >= 2:
    newest, oldest = funda_prices[0]['price'], funda_prices[-1]['price']
    change_pct = ((newest - oldest) / oldest) * 100
    print(f"\nPrice change: {change_pct:+.1f}%")
```

--------------------------------

### GET /get_listing

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Retrieves detailed information for a specific property listing by its ID.

```APIDOC
## GET /get_listing

### Description
Retrieves detailed information for a specific property listing using its unique identifier.

### Method
GET

### Parameters
#### Path Parameters
- **listing_id** (integer) - Required - The unique ID of the listing.

### Request Example
```python
from funda import Funda
f = Funda()
listing = f.get_listing(43117443)
```

### Response
#### Success Response (200)
- **listing** (object) - A listing object containing property details, media, and metadata.
```

--------------------------------

### Get Funda Listing by ID or URL

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Demonstrates how to retrieve a specific real estate listing using its unique ID or a full URL. Ensure the Funda object is initialized before making calls.

```python
from funda import Funda

f = Funda()

# Get a listing by ID
listing = f.get_listing(43117443)
print(listing['title'], listing['city'])
# Reehorst 13 Luttenberg

# Get a listing by URL
listing = f.get_listing('https://www.funda.nl/detail/koop/amsterdam/appartement-123/43117443/')
```

--------------------------------

### Listing Object Methods

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Utilize methods of the Listing object to get a text summary, convert to a dictionary, list available keys, or retrieve values with a default.

```python
listing.summary()       # Text summary of the listing
listing.to_dict()       # Convert to plain dictionary
listing.keys()          # List available keys
listing.get('key')      # Get with default (like dict.get)
listing.getID()         # Get listing ID
```

--------------------------------

### GET /search_listing

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Searches for property listings based on location and price criteria.

```APIDOC
## GET /search_listing

### Description
Searches for property listings based on location and optional price filters.

### Method
GET

### Parameters
#### Query Parameters
- **location** (string) - Required - The city or area to search in.
- **price_max** (integer) - Optional - The maximum price for the search.

### Request Example
```python
from funda import Funda
f = Funda()
results = f.search_listing('amsterdam', price_max=400000)
```

### Response
#### Success Response (200)
- **results** (list) - A list of listing objects.
```

--------------------------------

### Get Single Listing by ID or URL

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Retrieve details for a specific property listing. Supports both numeric IDs (tinyId or globalId) and full URLs from funda.nl.

```python
# By numeric ID (tinyId or globalId)
listing = f.get_listing(43117443)
```

```python
# By URL
listing = f.get_listing('https://www.funda.nl/detail/koop/city/house-name/43117443/')
```

--------------------------------

### Get Price History API

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Get historical price data for a listing, including previous asking prices, WOZ tax assessments, and sale history. This fetches data from the Walter Living API and is only called when explicitly requested (lazy-loaded).

```APIDOC
## get_price_history

### Description
Get historical price data for a listing, including previous asking prices, WOZ tax assessments, and sale history. This fetches data from the Walter Living API and is only called when explicitly requested (lazy-loaded).

### Method
GET (implied by fetching data)

### Endpoint
Not explicitly defined, but associated with a specific listing.

### Parameters
#### Path Parameters
- **listing** (object) - Required - The listing object for which to retrieve price history.

### Request Example
```python
listing = f.get_listing(43032486)
history = f.get_price_history(listing)

for change in history:
    print(change['date'], change['human_price'], change['status'])
```

### Response
#### Success Response (200)
- **history** (array) - A list of price changes.
  - Each item in the array is an object containing:
    - **price** (number) - Numeric price.
    - **human_price** (string) - Formatted price (e.g., "€435.000").
    - **date** (string) - Human readable date.
    - **timestamp** (string) - ISO timestamp.
    - **source** (string) - "Funda" or "WOZ".
    - **status** (string) - `asking_price`, `sold`, or `woz`.

#### Response Example
```json
[
  {
    "price": 435000,
    "human_price": "€435.000",
    "date": "22 okt, 2025",
    "timestamp": "2025-10-22T00:00:00Z",
    "source": "Funda",
    "status": "asking_price"
  },
  {
    "price": 472000,
    "human_price": "€472.000",
    "date": "1 jan, 2025",
    "timestamp": "2025-01-01T00:00:00Z",
    "source": "WOZ",
    "status": "woz"
  }
]
```
```

--------------------------------

### Access Property Details

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Get detailed property information including object type, house type, construction details, number of rooms and bedrooms, living area, plot area, energy label, and the full description.

```python
listing['object_type']      # House, Apartment, etc.
listing['house_type']       # Type of house (e.g., "Tussenwoning")
listing['construction_type'] # New or existing construction
listing['construction_year'] # Year built
listing['bedrooms']         # Number of bedrooms
listing['rooms']            # Total number of rooms
listing['living_area']      # Living area in m²
listing['plot_area']        # Plot area in m²
listing['energy_label']     # Energy label (A, B, C, etc.)
listing['description']      # Full description text
```

--------------------------------

### Get Listing by ID

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Retrieves details for a single real estate listing using its unique ID (either `tinyId` or `globalId`) or its full URL.

```APIDOC
## GET /api/listings/{listing_id}

### Description
Fetches the details of a specific real estate listing. The listing can be identified by its numeric ID (tinyId or globalId) or by its full URL from the funda.nl website.

### Method
GET

### Endpoint
/api/listings/{listing_id}

### Parameters
#### Path Parameters
- **listing_id** (integer or string) - Required - The unique ID (numeric) or URL of the listing.

### Request Example
```python
# Using numeric ID
f.get_listing(43117443)

# Using URL
f.get_listing('https://www.funda.nl/detail/koop/city/house-name/43117443/')
```

### Response
#### Success Response (200)
Returns a detailed object for the specified listing, including identifiers, address, price, media, characteristics, and more (similar structure to the search response).

#### Response Example
```json
{
  "globalId": "some-global-id",
  "tinyId": "some-tiny-id",
  "addressDetails": {
    "title": "Example House",
    "city": "Amsterdam",
    "postcode": "1000 AA",
    "province": "North Holland",
    "neighbourhood": "Centrum",
    "houseNumber": "1"
  },
  "price": {
    "sellingPrice": 500000,
    "formattedPrice": "€ 500.000",
    "isAuction": false
  },
  "fastView": {
    "bedrooms": 3,
    "livingArea": 120,
    "plotArea": 150,
    "energyLabel": "A"
  },
  "media": {
    "photos": [{"url": "http://cdn.example.com/photo.jpg"}]
  },
  "kenmerkSections": {},
  "coordinates": {"latitude": 52.370216, "longitude": 4.895168},
  "objectInsights": {"viewCount": 100, "saveCount": 10},
  "advertising": {"targetingOptions": {"garden": true, "constructionYear": 1990, "roomCount": 5}},
  "share": {"url": "http://www.funda.nl/listing/example-id"},
  "googleMapsObjectUrl": "https://maps.google.com/?q=...",
  "publicationDate": "2023-10-27T10:00:00Z",
  "tracking": {"values": {"brokers": {"id": "broker123", "association": "NVM"}}}
}
```
```

--------------------------------

### Access Location Data

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Get geographical location data for the listing, including coordinates, latitude, longitude, and a direct Google Maps URL.

```python
listing['coordinates']      # (lat, lng) tuple
listing['latitude']         # Latitude
listing['longitude']        # Longitude
listing['google_maps_url']  # Direct Google Maps link
```

--------------------------------

### Get Historical Price Data with Funda

Source: https://context7.com/0xmh/pyfunda/llms.txt

Fetches historical price data for a listing using the Walter Living API. Includes previous asking prices, WOZ tax assessments, and sale history. Can accept a listing object or a URL.

```python
from funda import Funda

f = Funda()

# Get listing first
listing = f.get_listing(43032486)
print(f"Current price: {listing['price_formatted']}")

# Fetch price history
history = f.get_price_history(listing)

# history is a list of dicts with:
# - price: numeric value
# - human_price: formatted string (e.g., "€435.000")
# - date: human readable date
# - timestamp: ISO timestamp
# - source: "Funda" or "WOZ"
# - status: "asking_price", "sold", or "woz"

print(f"Price History ({len(history)} records):")
for change in history:
    print(f"  {change['date']}: {change['human_price']} ({change['status']})")
# Output:
#   22 okt, 2025: €435.000 (asking_price)
#   1 jan, 2025: €472.000 (woz)
#   19 aug, 2019: €300.000 (asking_price)

# Calculate price change over time
funda_prices = [c for c in history if c['source'] == 'Funda']
if len(funda_prices) >= 2:
    newest, oldest = funda_prices[0]['price'], funda_prices[-1]['price']
    change_pct = ((newest - oldest) / oldest) * 100
    print(f"Price change: {change_pct:+.1f}%")

# Can also pass URL directly
history = f.get_price_history('https://www.funda.nl/detail/koop/amsterdam/..../43032486/')

```

--------------------------------

### Get Latest Listing ID with Funda

Source: https://context7.com/0xmh/pyfunda/llms.txt

Retrieves the highest listing ID from Funda's search index. Useful for initializing a poll for new listings.

```python
from funda import Funda

f = Funda()

# Get the latest ID from search index
latest_id = f.get_latest_id()
print(f"Latest listing ID: {latest_id}")
# Output: Latest listing ID: 7852306

# Use as starting point for polling
for listing in f.poll_new_listings(since_id=latest_id):
    print(f"New: {listing['title']}")
```

--------------------------------

### get_price_history - Get Historical Price Data

Source: https://context7.com/0xmh/pyfunda/llms.txt

Fetches historical price data for a specific property listing, including past asking prices, WOZ valuations, and sale records from the Walter Living API.

```APIDOC
## get_price_history - Get Historical Price Data

### Description
Fetches historical price data for a listing from the Walter Living API, including previous asking prices, WOZ tax assessments (Dutch property tax valuations), and sale history.

### Method
GET (Implicit)

### Endpoint
N/A (Function call within the library)

### Parameters
#### Query Parameters
- **listing** (integer or string) - Required - The listing ID or URL of the property.

### Request Example
```python
from funda import Funda

f = Funda()

# Get listing first
listing_data = f.get_listing(43032486)
print(f"Current price: {listing_data['price_formatted']}")

# Fetch price history using listing ID
history_by_id = f.get_price_history(43032486)

# Fetch price history using URL
history_by_url = f.get_price_history('https://www.funda.nl/detail/koop/amsterdam/..../43032486/')

print(f"Price History ({len(history_by_id)} records):")
for change in history_by_id:
    print(f"  {change['date']}: {change['human_price']} ({change['status']})")
```

### Response
#### Success Response (200)
- **history** (array) - A list of dictionaries, where each dictionary represents a price change or valuation record. Each record contains:
  - **price** (numeric) - The price value.
  - **human_price** (string) - The formatted price string (e.g., "€435.000").
  - **date** (string) - Human-readable date of the record.
  - **timestamp** (string) - ISO format timestamp.
  - **source** (string) - Source of the data ('Funda' or 'WOZ').
  - **status** (string) - Type of record ('asking_price', 'sold', or 'woz').

#### Response Example
```json
[
  {
    "price": 435000,
    "human_price": "€435.000",
    "date": "22 okt, 2025",
    "timestamp": "2025-10-22T00:00:00Z",
    "source": "Funda",
    "status": "asking_price"
  },
  {
    "price": 472000,
    "human_price": "€472.000",
    "date": "1 jan, 2025",
    "timestamp": "2025-01-01T00:00:00Z",
    "source": "WOZ",
    "status": "woz"
  }
]
```
```

--------------------------------

### Initialize environment and imports

Source: https://github.com/0xmh/pyfunda/blob/main/examples/analysis.ipynb

Import required libraries and configure matplotlib figure size.

```python
import pandas as pd
import matplotlib.pyplot as plt
from funda import Funda

plt.rcParams['figure.figsize'] = (10, 6)
```

--------------------------------

### Initialize Funda Client

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Instantiate the Funda client with an optional timeout. This is the main entry point for all API interactions.

```python
from funda import Funda

f = Funda(timeout=30)
```

--------------------------------

### Initialize Funda Client

Source: https://context7.com/0xmh/pyfunda/llms.txt

The Funda class manages HTTP sessions and TLS fingerprinting. It can be used as a context manager for automatic cleanup.

```python
from funda import Funda

# Initialize with optional timeout (default 30 seconds)
f = Funda(timeout=30)

# Use as context manager for automatic cleanup
with Funda() as f:
    listing = f.get_listing(43117443)
    print(listing['title'], listing['price'])
    # Output: Reehorst 13 695000
```

--------------------------------

### Fetch multi-city data

Source: https://github.com/0xmh/pyfunda/blob/main/examples/analysis.ipynb

Retrieve listing data for multiple cities to compare market prices.

```python
cities = ['amsterdam', 'rotterdam', 'utrecht', 'den-haag']
city_data = []

with Funda() as f:
    for city in cities:
        results = f.search_listing(city, page=0)
        for r in results:
            city_data.append({'city': city.title(), 'price': r['price']})

df_cities = pd.DataFrame(city_data)
print(f"Fetched {len(df_cities)} listings from {len(cities)} cities")
```

--------------------------------

### Visualize median price by city

Source: https://github.com/0xmh/pyfunda/blob/main/examples/analysis.ipynb

Create a horizontal bar chart comparing the median house prices across selected cities.

```python
city_medians = df_cities.groupby('city')['price'].median().sort_values(ascending=False)

fig, ax = plt.subplots()
city_medians.plot(kind='barh', ax=ax, color='steelblue', edgecolor='black')
ax.set_xlabel('Median Price (EUR)')
ax.set_title('Median House Price by City')
ax.xaxis.set_major_formatter(plt.FuncFormatter(lambda x, p: f'{x/1e3:.0f}K'))
plt.tight_layout()
plt.show()
```

--------------------------------

### Export Funda Listings to CSV

Source: https://context7.com/0xmh/pyfunda/llms.txt

Fetches property listings for a given location across multiple pages and exports selected details to a CSV file. Requires the 'funda' and 'csv' libraries.

```python
from funda import Funda
import csv
from pathlib import Path

# Define columns to export
COLUMNS = [
    "title", "city", "postcode", "price", "living_area",
    "plot_area", "bedrooms", "rooms", "energy_label",
    "construction_year", "object_type", "house_type",
    "url", "latitude", "longitude",
]

def export_to_csv(location: str, output_file: str, max_pages: int = 3):
    all_listings = []

    with Funda() as f:
        for page in range(max_pages):
            print(f"Fetching page {page + 1}...")
            results = f.search_listing(
                location=location,
                offering_type='buy',
                price_max=600000,
                area_min=50,
                sort='newest',
                page=page,
            )
            if not results:
                break
            all_listings.extend([r.to_dict() for r in results])

    # Write CSV
    output = Path(output_file)
    with output.open("w", newline="", encoding="utf-8") as f:
        writer = csv.DictWriter(f, fieldnames=COLUMNS)
        writer.writeheader()
        for listing in all_listings:
            row = {col: listing.get(col, "") for col in COLUMNS}
            writer.writerow(row)

    print(f"Exported {len(all_listings)} listings to {output_file}")

# Usage
export_to_csv('amsterdam', 'amsterdam_listings.csv', max_pages=5)
```

--------------------------------

### Fetch Listing Details

Source: https://context7.com/0xmh/pyfunda/llms.txt

Retrieve comprehensive property data using a numeric ID or a full Funda URL. The returned object contains over 70 fields including media, coordinates, and characteristics.

```python
from funda import Funda

f = Funda()

# Get listing by numeric ID (tinyId from URL)
listing = f.get_listing(43117443)
print(listing['title'])           # "Reehorst 13"
print(listing['city'])            # "Luttenberg"
print(listing['price'])           # 695000
print(listing['price_formatted']) # "€ 695.000 k.k."
print(listing['living_area'])     # 200
print(listing['bedrooms'])        # 5
print(listing['energy_label'])    # "A"
print(listing['coordinates'])     # (52.4234, 6.3456)
print(listing['url'])             # "https://www.funda.nl/detail/koop/luttenberg/reehorst-13/43117443/"

# Get listing by Funda URL
listing = f.get_listing('https://www.funda.nl/detail/koop/amsterdam/appartement-123/43117443/')

# Access photos and media
print(listing['photo_urls'][:3])  # List of CDN URLs for photos
print(listing['floorplan_urls'])  # List of floorplan image URLs
print(listing['brochure_url'])    # PDF brochure URL if available

# Access property features (booleans)
if listing['has_garden']:
    print("Property has a garden")
if listing['has_solar_panels']:
    print("Solar panels installed")
if listing['is_energy_efficient']:
    print(f"Energy efficient - label: {listing['energy_label']}")

# Get all detailed characteristics
for key, value in listing['characteristics'].items():
    print(f"{key}: {value}")
```

--------------------------------

### Get Latest Listing ID

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Retrieve the highest listing ID currently present in Funda's search index. Useful for tracking or incremental updates.

```python
latest = f.get_latest_id()  # e.g., 7852306
```

--------------------------------

### get_latest_id - Get Latest Listing ID

Source: https://context7.com/0xmh/pyfunda/llms.txt

Retrieves the highest listing ID from Funda's search index. This is useful for initializing the polling process for new listings.

```APIDOC
## get_latest_id - Get Latest Listing ID from Search Index

### Description
Returns the highest listing ID currently in Funda's Elasticsearch search index. Useful as a starting point for `poll_new_listings` when you don't have a previously saved ID.

### Method
GET (Implicit)

### Endpoint
N/A (Function call within the library)

### Parameters
None

### Request Example
```python
from funda import Funda

f = Funda()
latest_id = f.get_latest_id()
print(f"Latest listing ID: {latest_id}")
```

### Response
#### Success Response (200)
- **latest_id** (integer) - The highest listing ID found in the search index.

#### Response Example
```json
7852306
```
```

--------------------------------

### Access Media Information

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Retrieve lists of IDs and URLs for photos, floorplans, and videos associated with the listing, as well as brochure URLs.

```python
listing['photos']           # List of photo IDs
listing['photo_urls']       # List of full CDN URLs for photos
listing['photo_count']      # Number of photos
listing['floorplans']       # List of floorplan IDs
listing['floorplan_urls']   # List of full CDN URLs for floorplans
listing['videos']           # List of video IDs
listing['video_urls']       # List of video URLs
listing['photos_360']       # List of 360° photo dicts with name, id, url
listing['brochure_url']     # PDF brochure URL (if available)
```

--------------------------------

### Download listing photos

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Iterate through photo URLs in a listing and save them locally using the requests library.

```python
from funda import Funda
import requests

f = Funda()
listing = f.get_listing(43117443)

# Photo URLs are ready to use
for i, url in enumerate(listing['photo_urls'][:5]):
    response = requests.get(url)
    with open(f"photo_{i}.jpg", "wb") as file:
        file.write(response.content)

# Also available: floorplan_urls, video_urls
```

--------------------------------

### Get Latest Listing ID

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Retrieves the highest listing ID currently present in Funda's search index. This can be useful for determining the range of available listings.

```APIDOC
## GET /api/listings/latest/id

### Description
Fetches the highest listing ID that is currently indexed and searchable on Funda. This can be used to understand the scale of the available data or to iterate through listings if needed.

### Method
GET

### Endpoint
/api/listings/latest/id

### Response
#### Success Response (200)
- **latestId** (integer) - The highest listing ID found in the index.

#### Response Example
```json
{
  "latestId": 7852306
}
```
```

--------------------------------

### Listing Class - Property Data Access

Source: https://context7.com/0xmh/pyfunda/llms.txt

The `Listing` class provides a convenient way to access property data with dict-like access and helpful aliases for over 70 fields.

```APIDOC
## Listing Class - Property Data Access

### Description
The `Listing` class provides dict-like access to property data with convenient aliases. Supports over 70 fields including address details, pricing, property characteristics, media, coordinates, and broker information.

### Method
GET (Implicit, via `f.get_listing()`)

### Endpoint
N/A (Function call within the library)

### Parameters
#### Query Parameters
- **listing_id** (integer) - Required - The ID of the listing to retrieve.

### Request Example
```python
from funda import Funda

f = Funda()
listing = f.get_listing(43117443)

# Dict-like access
print(listing['title'])
print(listing['city'])
print(listing['postcode'])
print(listing['province'])
print(listing['neighbourhood'])
print(listing['price'])
print(listing['price_formatted'])

# Key aliases
print(listing['name'])
print(listing['address'])
print(listing['location'])
print(listing['area'])
print(listing['size'])
print(listing['type'])
print(listing['images'])
print(listing['zip'])
```

### Response
#### Success Response (200)
- **listing** (object) - A dictionary-like object representing the property listing. Contains numerous fields such as:
  - **title** (string) - The address or title of the listing.
  - **city** (string) - The city where the property is located.
  - **postcode** (string) - The postal code.
  - **province** (string) - The province.
  - **neighbourhood** (string) - The neighbourhood name.
  - **price** (integer) - The current price of the property.
  - **price_formatted** (string) - The formatted price string.
  - **living_area** (integer) - The living area in square meters.
  - **object_type** (string) - The type of property (e.g., 'Appartement', 'Huis').
  - **photos** (array) - A list of URLs for property images.
  - **global_id** (integer) - The unique global ID of the listing.

#### Response Example
```json
{
  "title": "Dorpsstraat 1, 1234 AB Amsterdam",
  "city": "Amsterdam",
  "postcode": "1234 AB",
  "province": "Noord-Holland",
  "neighbourhood": "Centrum",
  "price": 500000,
  "price_formatted": "€500.000",
  "living_area": 120,
  "object_type": "Appartement",
  "photos": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ],
  "global_id": 43117443
}
```
```

--------------------------------

### Access Listing Data with Funda's Listing Class

Source: https://context7.com/0xmh/pyfunda/llms.txt

Provides dict-like access to property data with convenient aliases for over 70 fields, including address, pricing, characteristics, media, and broker information.

```python
from funda import Funda

f = Funda()
listing = f.get_listing(43117443)

# Dict-like access
print(listing['title'])           # Address/title
print(listing['city'])            # City name
print(listing['postcode'])        # Postal code
print(listing['province'])        # Province
print(listing['neighbourhood'])   # Neighbourhood name
print(listing['price'])           # Numeric price
print(listing['price_formatted']) # Formatted price string

# Key aliases - these all work
print(listing['name'])      # Same as 'title'
print(listing['address'])   # Same as 'title'
print(listing['location'])  # Same as 'city'
print(listing['area'])      # Same as 'living_area'
print(listing['size'])      # Same as 'living_area'
print(listing['type'])      # Same as 'object_type'
print(listing['images'])    # Same as 'photos'
print(listing['zip'])       # Same as 'postcode'

```

--------------------------------

### Visualize price distribution

Source: https://github.com/0xmh/pyfunda/blob/main/examples/analysis.ipynb

Generate a histogram showing the distribution of prices in Amsterdam.

```python
fig, ax = plt.subplots()
df['price'].hist(bins=20, ax=ax, edgecolor='black')
ax.set_xlabel('Price (EUR)')
ax.set_ylabel('Count')
ax.set_title('Price Distribution in Amsterdam')
ax.xaxis.set_major_formatter(plt.FuncFormatter(lambda x, p: f'{x/1e6:.1f}M'))
plt.tight_layout()
plt.show()
```

--------------------------------

### get_listing - Fetch Single Listing

Source: https://context7.com/0xmh/pyfunda/llms.txt

Retrieves complete property details for a single listing using its ID or Funda URL.

```APIDOC
## get_listing - Fetch Single Listing by ID or URL

Retrieves complete property details for a single listing. Accepts either a numeric ID (tinyId or globalId) or a full Funda URL. Returns a `Listing` object with 70+ fields including address, price, media, coordinates, and property characteristics.

### Method
`GET` (Implicit)

### Endpoint
`/api/listings/{id}` (Internal, handled by the library)

### Parameters
#### Path Parameters
- **id** (integer or string) - Required - The numeric ID (tinyId or globalId) or the full Funda URL of the listing.

### Request Example
```python
from funda import Funda

f = Funda()

# Get listing by numeric ID
listing = f.get_listing(43117443)

# Get listing by Funda URL
listing = f.get_listing('https://www.funda.nl/detail/koop/amsterdam/appartement-123/43117443/')
```

### Response
#### Success Response (200)
- **Listing Object** (object) - Contains over 70 fields detailing the property.
  - **title** (string) - The title of the listing.
  - **city** (string) - The city where the property is located.
  - **price** (integer) - The price of the property.
  - **price_formatted** (string) - The formatted price string (e.g., "€ 695.000 k.k.").
  - **living_area** (integer) - The living area in square meters.
  - **bedrooms** (integer) - The number of bedrooms.
  - **energy_label** (string) - The energy label (e.g., "A").
  - **coordinates** (tuple) - A tuple containing latitude and longitude.
  - **url** (string) - The URL of the listing on Funda.
  - **photo_urls** (list) - A list of URLs for property photos.
  - **floorplan_urls** (list) - A list of URLs for floorplans.
  - **brochure_url** (string) - URL for the property brochure (if available).
  - **has_garden** (boolean) - Indicates if the property has a garden.
  - **has_solar_panels** (boolean) - Indicates if solar panels are installed.
  - **is_energy_efficient** (boolean) - Indicates if the property is energy efficient.
  - **characteristics** (object) - A dictionary of detailed property characteristics.

#### Response Example
```json
{
  "title": "Reehorst 13",
  "city": "Luttenberg",
  "price": 695000,
  "price_formatted": "€ 695.000 k.k.",
  "living_area": 200,
  "bedrooms": 5,
  "energy_label": "A",
  "coordinates": [52.4234, 6.3456],
  "url": "https://www.funda.nl/detail/koop/luttenberg/reehorst-13/43117443/",
  "photo_urls": ["url1", "url2", ...],
  "floorplan_urls": ["url3", "url4", ...],
  "brochure_url": "http://example.com/brochure.pdf",
  "has_garden": true,
  "has_solar_panels": false,
  "is_energy_efficient": true,
  "characteristics": {
    "key1": "value1",
    "key2": "value2"
  }
}
```
```

--------------------------------

### Calculate price statistics

Source: https://github.com/0xmh/pyfunda/blob/main/examples/analysis.ipynb

Compute and print basic price statistics for the Amsterdam dataset.

```python
print("Price Statistics (EUR)")
print("=" * 30)
print(f"Mean:   {df['price'].mean():>12,.0f}")
print(f"Median: {df['price'].median():>12,.0f}")
print(f"Min:    {df['price'].min():>12,.0f}")
print(f"Max:    {df['price'].max():>12,.0f}")
```

--------------------------------

### Access Basic Listing Info

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Access basic property information such as title, city, postcode, province, neighbourhood, municipality, house number, and extension.

```python
listing['title']            # Property title/address
listing['city']             # City name
listing['postcode']         # Postal code
listing['province']         # Province
listing['neighbourhood']    # Neighbourhood name
listing['municipality']     # Municipality (gemeente)
listing['house_number']     # House number
listing['house_number_ext'] # House number extension (e.g., "A", "II")
```

--------------------------------

### Find energy-efficient homes with a garden

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Retrieve specific listing details to check for property features like gardens, solar panels, and energy labels.

```python
from funda import Funda

f = Funda()
listing = f.get_listing(43117443)

# Check property features
if listing['has_garden'] and listing.get('has_solar_panels'):
    print("Energy efficient with garden!")

if listing['is_energy_efficient']:
    print(f"Energy label: {listing['energy_label']}")
```

--------------------------------

### Search Listings with Filters

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Perform a search for property listings using various criteria. Specify location, offering type, price range, area, plot size, object type, energy label, sort order, and pagination.

```python
results = f.search_listing(
    location='amsterdam',           # City or area name
    offering_type='buy',            # 'buy' or 'rent'
    price_min=200000,               # Minimum price
    price_max=500000,               # Maximum price
    area_min=50,                    # Minimum living area (m²)
    area_max=150,                   # Maximum living area (m²)
    plot_min=100,                   # Minimum plot area (m²)
    plot_max=500,                   # Maximum plot area (m²)
    object_type=['house'],          # Property types (default: house, apartment)
    energy_label=['A', 'A+'],       # Energy labels to filter
    sort='newest',                  # Sort order (see below)
    page=0,                         # Page number (15 results per page)
)
```

--------------------------------

### Access Price & Status

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Retrieve price-related information and the listing's current status (available/sold) and offering type (Sale/Rent).

```python
listing['price']            # Numeric price
listing['price_formatted']  # Formatted price string (e.g., "€ 450.000 k.k.")
listing['price_per_m2']     # Price per m² (from characteristics)
listing['status']           # "available" or "sold"
listing['offering_type']    # "Sale" or "Rent"
```

--------------------------------

### Access Property Features (Booleans)

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Check for the presence of various property features using boolean flags, such as garden, balcony, solar panels, parking, and energy efficiency.

```python
listing['has_garden']           # Has garden
listing['has_balcony']          # Has balcony
listing['has_roof_terrace']     # Has roof terrace
listing['has_solar_panels']     # Has solar panels
listing['has_heat_pump']        # Has heat pump
listing['has_parking_on_site']  # Parking on property
listing['has_parking_enclosed'] # Enclosed parking
listing['is_energy_efficient']  # Energy efficient property
listing['is_monument']          # Listed/protected building
listing['is_fixer_upper']       # Fixer-upper (kluswoning)
listing['is_auction']           # Sold via auction
listing['open_house']           # Has open house scheduled
```

--------------------------------

### Access Date Information

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Retrieve dates related to the listing, including publication date, offered since date, and acceptance terms.

```python
listing['publication_date'] # When listed on Funda
listing['offered_since']    # "Offered since" date (from characteristics)
listing['acceptance']       # Acceptance terms (e.g., "In overleg")
```

--------------------------------

### Search rentals in multiple cities

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Perform a multi-location search for rental properties with a maximum price filter.

```python
from funda import Funda

f = Funda()
results = f.search_listing(
    location=['amsterdam', 'rotterdam', 'den-haag'],
    offering_type='rent',
    price_max=2000,
)

print(f"Found {len(results)} rentals")
```

--------------------------------

### Visualize price vs living area

Source: https://github.com/0xmh/pyfunda/blob/main/examples/analysis.ipynb

Create a scatter plot to analyze the relationship between living area and price.

```python
fig, ax = plt.subplots()
ax.scatter(df_area['living_area'], df_area['price'], alpha=0.6)
ax.set_xlabel('Living Area (m²)')
ax.set_ylabel('Price (EUR)')
ax.set_title('Price vs Living Area')
ax.yaxis.set_major_formatter(plt.FuncFormatter(lambda x, p: f'{x/1e6:.1f}M'))
plt.tight_layout()
plt.show()
```

--------------------------------

### Search Properties with Filters

Source: https://context7.com/0xmh/pyfunda/llms.txt

Perform filtered searches for listings based on location, price, area, energy labels, and availability status. Results are paginated with 15 items per page.

```python
from funda import Funda

f = Funda()

# Basic search in a city
results = f.search_listing('amsterdam', price_max=500000)
for listing in results:
    print(f"{listing['title']} - €{listing['price']:,}")

# Search with multiple filters
results = f.search_listing(
    location='amsterdam',
    offering_type='buy',        # 'buy' or 'rent'
    price_min=200000,
    price_max=500000,
    area_min=50,                # Minimum living area (m²)
    area_max=150,               # Maximum living area (m²)
    plot_min=100,               # Minimum plot area (m²)
    object_type=['house', 'apartment'],
    energy_label=['A', 'A+', 'A++'],
    construction_type='resale', # 'resale' or 'newly_built'
    construction_year_min=2000,
    sort='newest',              # Sort by most recent
    page=0,                     # Pagination (15 per page)
)

# Search within radius from postcode (valid: 1, 2, 5, 10, 15, 30, 50 km)
results = f.search_listing(
    location='1012AB',
    radius_km=15,
    price_max=750000,
    energy_label=['A', 'A+'],
    sort='price_asc',
)

# Search multiple cities
results = f.search_listing(
    location=['amsterdam', 'rotterdam', 'den-haag'],
    offering_type='rent',
    price_max=2000,
)

# Search for sold properties
results = f.search_listing(
    location='amsterdam',
    availability='sold',  # Filter by status: 'available', 'negotiations', 'sold'
    sort='newest',
)
```

--------------------------------

### Retrieve listing price history

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Fetches historical price data including WOZ assessments and sale history via the Walter Living API.

```python
listing = f.get_listing(43032486)
history = f.get_price_history(listing)

for change in history:
    print(change['date'], change['human_price'], change['status'])
# 22 okt, 2025    €435.000     asking_price
# 1 jan, 2025     €472.000     woz
# 19 aug, 2019    €300.000     asking_price
```

--------------------------------

### Search by radius from postcode

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Search for listings within a specific radius of a postcode, filtered by price and energy label.

```python
from funda import Funda

f = Funda()
results = f.search_listing(
    location='1012AB',
    radius_km=15,
    price_max=600000,
    energy_label=['A', 'A+', 'A++'],
    sort='newest',
)

for r in results:
    print(f"{r['title']} - €{r['price']:,}")
```

--------------------------------

### Calculate price per square meter

Source: https://github.com/0xmh/pyfunda/blob/main/examples/analysis.ipynb

Compute the price per square meter for listings with valid living area data.

```python
df_area = df[df['living_area'].notna() & (df['living_area'] > 0)].copy()
df_area['price_per_m2'] = df_area['price'] / df_area['living_area']

print(f"Mean price/m²:   {df_area['price_per_m2'].mean():,.0f}")
print(f"Median price/m²: {df_area['price_per_m2'].median():,.0f}")
```

--------------------------------

### Fetch Amsterdam listings

Source: https://github.com/0xmh/pyfunda/blob/main/examples/analysis.ipynb

Retrieve multiple pages of real estate listings for Amsterdam using the Funda client.

```python
all_listings = []

with Funda() as f:
    for page in range(5):
        results = f.search_listing('amsterdam', page=page)
        if not results:
            break
        all_listings.extend([r.to_dict() for r in results])

print(f"Fetched {len(all_listings)} listings")
```

--------------------------------

### Access Stats & Metadata

Source: https://github.com/0xmh/pyfunda/blob/main/README.md

Retrieve statistical data like views and saves, along with metadata such as IDs, URLs, broker information, and characteristics.

```python
listing['views']            # Number of views on Funda
listing['saves']            # Number of times saved
listing['highlight']        # Highlight text (blikvanger)
listing['global_id']        # Internal Funda ID
listing['tiny_id']          # Public ID (used in URLs)
listing['url']              # Full Funda URL
listing['share_url']        # Shareable URL
listing['broker_id']        # Broker ID
listing['broker_association'] # Broker association (e.g., "NVM")
listing['characteristics']  # Dict of all detailed characteristics
```