Idealista Property Scraper

Fast, lightweight Idealista scraper for Spain (.com), Italy (.it) and Portugal (.pt) — powered by the official Idealista mobile API (app.idealista.com).

v2 rewrite: this version replaces HTML scraping with the mobile JSON API. No proxy, no browser, no DataDome, no credentials — just run it. Output fields are unchanged, so existing pipelines keep working.

Instead of scraping HTML behind DataDome anti-bot (browser solves, sticky residential proxies, per-session delays), this actor talks to the same JSON API the Idealista Android app uses:

• Pure HTTP, structured JSON — no Cheerio parsing, no Playwright, no anti-bot challenges
• No proxy required — the mobile API is not behind DataDome
• No credentials required — works out of the box, no Idealista developer account needed
• Richer than search pages — GPS coordinates, agency phone numbers, price-drop info and energy ratings come straight from the API
• 1500-result cap bypass — Idealista caps every single query at 1,500 results; large searches are automatically split by price band so you get the full set
• Output-compatible with the HTML-based idealista-property-scraper — same field names, so downstream pipelines keep working

Credentials: none needed

The actor ships with the application credentials reverse-engineered from the official Android app (OAuth client pair + HMAC-SHA256 request signing, matching the app's exact request pipeline: k/t query params, seed/Signature headers, app_version/device_identifier identity headers).

Just run it — no API keys, no secrets, no setup.

If Idealista ever rotates the embedded secrets, you can override them via input (clientKey, clientSecret, signingSecret) or the IDEALISTA_CLIENT_KEY / IDEALISTA_CLIENT_SECRET / IDEALISTA_SIGNING_SECRET env vars / secrets. Request personal credentials at https://developers.idealista.com/access-request. Prefer Apify secrets over plain input fields.

Input

Field	Description
country	es (Spain), it (Italy) or pt (Portugal). Default es.
operation	sale or rent. Default sale.
propertyType	homes, offices, premises, garages, bedrooms, newDevelopments, lands, storageRooms, buildings. Default homes.
location	City / district / neighborhood name (auto-resolved, e.g. Madrid, Chamberí) or a direct Idealista locationId (0-EU-ES-28-07-001-079).
centers	GPS radius search, e.g. [{"lat": 40.4168, "lng": -3.7038, "distance": 5000}]. Overrides location.
startUrls	Direct property URLs (/inmueble/, /immobile/, /imovel/) — fetched via the detail API.
maxItems	Max listings (0 = unlimited). Default 50.
minPrice / maxPrice, minSize / maxSize, minRooms / maxRooms, minBathrooms	Search filters.
sort	asc or desc. Default asc.
fetchDetails	Enrich every listing (full description, all photos, energy rating, year built, fees). Default false — search-level rows are ~50× cheaper.
debug	Save raw API JSON to the Key-Value store. Default false.

Output

One dataset row per listing: id, title, url, price, priceText, currency, pricePerSqm, rooms, bathrooms, size, floor, propertyType, country, location, city, district, neighborhood, province, latitude, longitude, description, photos, agency (name, phone, website, address), features, energyRating, yearBuilt, communityFees, propertyTax, priceHistory, publishedDate, lastUpdate, reference, partial.

How it works

1. OAuth token via POST app.idealista.com/api/oauth/token (client_credentials grant, Basic auth).
2. Every request is signed: seed = uuid(), HMAC-SHA256(seed + METHOD + sorted(query) + sorted(body)) with the base64-encoded signing secret, sent as seed / Signature headers plus app_version, device_identifier and the Android User-Agent.
3. GET /api/3/{country}/locations resolves free-text locations to locationIds.
4. POST /api/3.5/{country}/search paginates (50/page); queries over 1,500 results are price-band split recursively.
5. Optional GET /api/3/{country}/detail/{propertyCode} enrichment with concurrency 10.

Cost comparison

The HTML scraper needs residential proxies + browser DataDome solves per session. This actor makes ~1 request per 50 listings (search mode) — no proxy, no browser — so runs are an order of magnitude cheaper and faster. Only fetchDetails: true adds ~1 request per listing.

Technical notes

• The Docker image pins Node 22 (apify/actor-node:22). Idealista's edge (Fastly) rejects the TLS fingerprint of older Node/OpenSSL stacks with an empty HTTP 406 — do not downgrade the base image.
• The debugProbe input only checks API reachability (no dataset output) — useful to diagnose edge blocking from a new network.
• A standard proxy input is available as a fallback, but normal runs need no proxy.

Limitations

• Requires approved Idealista API credentials (free tier is rate/quote limited — keep maxItems tight while testing).
• The 1,500/query cap still applies at the API level; the actor works around it by price splitting, which can multiply request counts on huge searches.
• This is an independent tool, not affiliated with Idealista.