Collectors · Real estate
Idealista Scraper API in Python
Property listings from Idealista Spain/Italy/Portugal — price, rooms, size, agency. One POST from Python with location, rows back as JSON with 28 fields, $0.001 per delivered listing. No proxies or parsers to maintain.
First call
Install, call, read the rows.
pip install requestsimport os, requests
r = requests.post(
"https://api.quanticdata.io/v1/scraper/collectors/idealista_search/run",
headers={"Authorization": f"Bearer {os.environ['QD_API_KEY']}"},
json={
"location": "madrid-madrid",
"operation": "sale",
"site": "es",
"max_results": 30,
},
timeout=120,
)
r.raise_for_status()
run = r.json()["payload"]
print(run["count"], "rows,", run["cost"]["usd"], "USD")
for row in run["results"]:
print(row.get("listing_id"), row.get("title"), row.get("url"), row.get("price"))The key comes from an environment variable, never from the code. The run answers in the same request when it finishes in time; payload.results holds the rows and payload.cost what they cost.
Request parameters
What the collector takes.
| Parameter | Type | Required | Meaning |
|---|---|---|---|
location | string | yes | Idealista location slug ("madrid-madrid") or a full listing URL. |
operation | string: sale, rent | no (default sale) | sale (default) or rent. |
site | string: es, it, pt | no (default es) | Country site: es (default), it, pt. |
max_results | integer | no (default 30) | How many listings to deliver at most (1–100). You pay only for delivered listings. |
Response fields
28 fields per listing.
| Field | Type | What it holds |
|---|---|---|
rank | integer | 1-based position. |
listing_id | string, nullable | Idealista listing id. |
title | string | Listing title (type + street/zone). |
url | string, nullable | Listing URL. |
price | string, nullable | Price as shown. |
price_value | number, nullable | Parsed price. |
price_per_m2 | string, nullable | Price per m² as shown. |
rooms | integer, nullable | Rooms. |
size_m2 | number, nullable | Size in m². |
details | string[] | Detail chips as shown (floor, elevator…). |
description | string, nullable | Listing description excerpt. |
agency | string, nullable | Listing agency (null for private). |
thumbnail | string, nullable | First photo. |
property_type | string, nullable | Property type from the title, in the site language (Piso, Ático, Trilocale, Apartamento…). |
location | string, nullable | Street, neighbourhood and city from the title. |
price_per_m2_value | number, nullable | Price per m² as a number: the figure the card prints, or price ÷ size when the card shows a price drop in its place. |
previous_price | string, nullable | Price before the latest reduction, as shown. |
previous_price_value | number, nullable | Numeric previous price. |
price_drop_pct | number, nullable | Reduction in percent, as the card states it. |
floor | string, nullable | Floor line as shown, e.g. "6ª planta exterior con ascensor". |
parking | string, nullable | Parking line when the card has one, e.g. "Garaje incluido". |
photo_count | integer, nullable | Number of photos on the listing. |
has_video | boolean | True when the listing has a video. |
has_3d_tour | boolean | True when the listing has a 3D tour. |
has_floor_plan | boolean | True when the listing has a floor plan. |
tags | string[], nullable | Tags on the card, e.g. "Lujo", "Luminoso". |
is_professional | boolean, nullable | True when listed by an agency, false when listed by a private owner. |
agency_url | string, nullable | Agency page on Idealista. |
Add ?format=csv to the runs endpoint to get the same rows as CSV.
Long runs
Run in the background, then poll.
A run that needs more time can go to the background: send "async": true, get 202 with the run id, and poll the runs endpoint until the status is done. Reading a run is free.
import os, time, requests
H = {"Authorization": f"Bearer {os.environ['QD_API_KEY']}"}
r = requests.post("https://api.quanticdata.io/v1/scraper/collectors/idealista_search/run", headers=H,
json={**{"location":"madrid-madrid","operation":"sale","site":"es","max_results":30}, "async": True}, timeout=30)
run_id = r.json()["payload"]["run_id"]
while True:
run = requests.get(f"https://api.quanticdata.io/v1/scraper/collectors/runs/{run_id}", headers=H, timeout=30).json()["payload"]
if run["status"] in ("done", "failed"):
break
time.sleep(5)
print(run["status"], run["count"])Errors
What can come back, and what is billed.
| Status | Meaning | Billed |
|---|---|---|
400 | The input does not match the collector (payload.errors) | No |
401 | Missing or wrong API key | No |
402 | Balance and free credit do not cover the run: top up | No |
422 | The input can never resolve; retrying the same input cannot help | No |
424 | The run failed at the source (blocked, timed out, layout changed); safe to retry | No |
429 | Rate limit or a per-account brake; wait for Retry-After | No |
Only delivered rows are billed: a run that delivers nothing costs nothing.
Price
$0.001 per delivered listing.
| Rows | Cost |
|---|---|
| 1 | $0.001 |
| 1,000 | $1.00 |
| 10,000 | $10.00 |
Up to 100 listings per run; split larger jobs into several runs. The $2 free credit every month covers about 2,000 listings. No subscription; paid tiers lower the unit price. All collector prices: collector pricing.
Before you run it
Questions developers ask
Is there a free Idealista listings API?
Every account gets $2 of free usage each month, about 2,000 listings of this collector at $0.001 each, with no card.
Do I have to handle proxies, retries or blocks?
No. The collector runs on our network and handles them; a run blocked at the source returns 424 and is not billed.
How many rows can one run return?
Up to 100 listings per run (the max_results input, where the collector has one).
Can an AI agent run it?
Yes: the MCP server exposes it as the run_collector tool, with the same input and price. See the MCP server.
Run it on the free credit.
Create an API key, export it as QD_API_KEY and run the example. $0.001 per delivered listing, no subscription.