# Immobiliare.it API scraper — Italy real estate data: for-sale and for-rent property listings across every Italian city, province and region with full filters (price, rooms, surface m², bathrooms, property type, sort), each listing with price, rooms, bathrooms, surface, floor, typology, features, photos, agency and map coordinates, plus location autocomplete that resolves a city name to the search geo-ids — no API key required

> Search Immobiliare.it property listings by location (for sale or for rent), with structured filters: price (EUR), rooms, surface (m²), bathrooms, property type and sort. Each result carries price, rooms, bathrooms, surface, floor, typology, features, agency, map coordinates and the primary photo. Paginate with page.
> ReefAPI engine `immobiliare` · 3 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/immobiliare/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /immobiliare/v1/search — 1 credit
Search Immobiliare.it property listings by location (for sale or for rent), with structured filters: price (EUR), rooms, surface (m²), bathrooms, property type and sort. Each result carries price, rooms, bathrooms, surface, floor, typology, features, agency, map coordinates and the primary photo. Paginate with page.

**Parameters:**
- `location` (string, required) — Where to search — an Italian city, province or region ('Roma', 'Milano', 'Napoli', 'Toscana'). Resolved to Immobiliare's geo-ids automatically (deepest match: city > province > region).
- `contract` (enum, optional, default "sale") — Listing type. [one of: sale, rent]
- `category` (enum, optional, default "residential") — Property category. [one of: residential, rooms]
- `sort` (enum, optional, default "relevance") — Result ordering. [one of: relevance, newest, price_low, price_high, surface_high]
- `home_type` (string, optional) — Property typology — one or several comma-separated: apartment, penthouse, villa, villa_terraced, townhouse, farmhouse, building, garage. e.g. 'apartment,penthouse'.
- `page` (integer, optional, default 1) — Result page (25 listings per page; paginate with page += 1).
- `price_min` (integer, optional) — Minimum price in EUR (sale price, or monthly rent when contract=rent).
- `price_max` (integer, optional) — Maximum price in EUR.
- `rooms_min` (integer, optional) — Minimum number of rooms (locali). 3 = 3+.
- `rooms_max` (integer, optional) — Maximum number of rooms (locali).
- `surface_min` (integer, optional) — Minimum living surface in square metres (m²).
- `surface_max` (integer, optional) — Maximum living surface in square metres (m²).
- `baths_min` (integer, optional) — Minimum number of bathrooms. 2 = 2+.

**Returns:** results[]{id, url, price_eur, contract, typology, rooms, bedrooms, bathrooms, surface_m2, floor, elevator, heating, condition, features[], location{city, province, latitude, longitude}, agency{name, url}, primary_photo_url} + total + count + page + max_pages + filters_applied + geo

**Example request body:**
```json
{
  "location": "Roma"
}
```

### POST /immobiliare/v1/detail — 1 credit
Full record for a single listing by its Immobiliare id (from a search result's `id`, or the number in an immobiliare.it/annunci/<id>/ URL). Returns every structured field plus all photos at full resolution. Note: the long description text is the portal preview (~600 chars); the complete prose lives on the DataDome-protected listing page.

**Parameters:**
- `id` (string, required) — Immobiliare listing id (the number in an immobiliare.it/annunci/<id>/ URL, or a search result's `id`).
- `location` (string, optional) — Optional hint of the listing's city to speed up the lookup (otherwise the listing's own city is resolved from search).

**Returns:** listing{id, url, price_eur, typology, rooms, bathrooms, surface_m2, floor, elevator, heating, condition, features[], photos[], location{}, agency{}, description_preview, description_truncated}

### POST /immobiliare/v1/geography — 0 credits
Location autocomplete — resolve a free-text Italian place name to Immobiliare's geo-ids (comune / province / region) with centre coordinates. Use it to power a search box or to get the exact ids the search needs. Returns ready-to-use search_params for each match.

**Parameters:**
- `query` (string, required) — Free-text Italian place to autocomplete — a partial city, province or region ('Rom', 'Mil', 'Tosc').
- `limit` (integer, optional, default 10) — Max suggestions to return (1-20).

**Returns:** suggestions[]{geo_id, type_name, label, province_id, region_id, latitude, longitude, search_params{}} + count + query

**Example request body:**
```json
{
  "query": "Roma"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=immobiliare
- Human docs page: https://reefapi.com/docs/immobiliare
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt