Fotocasa ES Property Scraper (Spain — residential lane)

A conservative, non-browser, residential-API lane Apify Actor that extracts public property listings from Fotocasa.es (Spain) into the Navent family record shape (same schema family as actors/navent-realestate-scraper/: price + currency, area, rooms/bedrooms/bathrooms, address, listing URL, image).

Access lane (verified live 2026-09-04, issue #27)

• www.fotocasa.es returns 403 on plain/datacenter egress; Spanish residential egress (e.g. DataImpulse __cr.es country suffix) returns 200 for both the search page and the internal API.
• The search page is server-rendered: listing cards ride the initial HTML, so plain HTTP (httpx + browser-grade headers) is sufficient — no browser, no OAuth, no challenge solving, no Camofox.
• The internal API host is web.gw.fotocasa.es (not search.gw). The Actor uses its location-resolution endpoint (/v2/propertysearch/urllocationsegments) as a helper that logs the numeric location ids for the requested location/zone; the full search POST body schema was never captured and is unnecessary — the SSR page takes location slugs directly.
• Listing URL grammar: /es/comprar/vivienda/{location}/{slug}/{numericId}/d.

Egress

The Actor needs Spanish residential egress. Two supported configurations, in order of preference:

1. External residential proxy (default for portability): pass proxyUrl (+ proxyUsername/proxyPassword or URL-embedded credentials). For DataImpulse, a username without a country suffix automatically gains __cr.es (Spanish exits).
2. Apify platform proxy: with no proxy input, the Actor requests a RESIDENTIAL configuration pinned to ES and rides it.

A 403 is treated as a retryable egress verdict: each retry goes out on a fresh proxy session (new exit IP), and only a 403 persisting to exhaustion raises ChallengeError naming the lane. A local run without any proxy credentials falls back to a direct connection with a loud warning (expect 403 — the lane is residential-only by design).

Input

• location — Fotocasa location slug (madrid-provincia default; free text is slugified, accents stripped)
• zone — zone slug within the location (todas-las-zonas default = all zones)
• operation — sale (comprar, default) or rental (alquiler)
• sortType — scoring (default), publication, price-asc, price-desc
• maxPages — 1–5 search pages (~30 cards per SSR page)
• maxResults — 1–200 listings (default 50)
• requestDelaySecs — 0.5–10 s between page requests (default 1.0)
• proxyUrl / proxyUsername / proxyPassword — residential egress credentials (see above)

Output (dataset)

One record per listing card, Navent-family shape:

field	notes
id / listingKey	Fotocasa numeric id from the URL; listingKey = fotocasa.es:{id}
url	canonical listing URL (/es/{comprar|alquiler}/vivienda/.../{id}/d), tracking params stripped
price + currency	Spanish format parsed (365.000 € → 365000 EUR; rentals carry monthly €/mes amounts with the suffix dropped); null for Precio a consultar
areaM2 / rooms / bedrooms / bathrooms	card detail chips (120 m², 3 hab., 2 baños)
address	card location line
imageUrl	primary card image (Fotocasa CDN)
operation / propertyType / portal / country / source	fotocasa / ES / www.fotocasa.es by construction
scrapedAt	UTC ISO-8601 run timestamp

Development

uv venv && uv pip install -r requirements.txt -r requirements-dev.txt pytest
python -m pytest tests/ -q

Fixtures under tests/fixtures/ mirror the DOM markers verified live in the research thread (article cards with data-panot-component="link-box", re-Card* classes, Tailwind @container/w-full wrappers, 31 cards per page, 2 JSON-LD blocks incl. BreadcrumbList). The live ES-residential capture was not re-run from this workspace (no proxy credentials available); see docs/FINDINGS.md.