Looking for the overview — what this API returns, what it costs, and a call you can run without a key? See the Fotocasa API page →

docs / fotocasa

Fotocasa

Spanish homes for sale and to rent, with the agency behind each listing.

base /fotocasa/v14 endpoints

post/fotocasa/v1/location_searchfree

Resolve a Spanish place name, district, postcode or street to fotocasa locations. Returns up to ten ranked matches with the combined-location id that `search` takes, the administrative level, and coordinates.

Parameter		Allowed / range	Description
query	required	—	Place to resolve: a town, district, neighbourhood, province, postcode or street, in Spanish.
limit = 10	optional	1–10	How many matches to return. Fotocasa always computes ten, so ten is also the ceiling.

Try in playground →

post/fotocasa/v1/search2 credits

Search Spanish property listings by location — for sale or to rent — with fotocasa's own filters: price range, rooms, bathrooms, surface, property type, state of repair, new-build vs resale, amenities, free text and sort order. Location is mandatory in one of four forms (location, location_slug, location_id or url). 30 listings per page; paginate with page/max_pages.

Parameter		Allowed / range	Description
location	optional	—	Where to search — REQUIRED unless you pass location_slug, location_id or url. Free text in Spanish ('Madrid', 'Chamberí, Madrid', 'Las Rozas de Madrid', 'Bilbao'): it is resolved through fotocasa's own location service and the match that was used is reported in meta.location_resolved. Spain is searched by place, so one of these four location inputs must always be supplied.
location_slug	optional	—	A fotocasa location slug, used verbatim as the URL segment and therefore the cheapest option (no resolver call). Examples: madrid-capital, barcelona-capital, bilbao, valencia-capital, malaga, las-rozas-de-madrid, espana. Note the pattern: 'madrid' is the PROVINCE and 'madrid-capital' is the city.
location_id	optional	—	A fotocasa combined-location id, exactly as location_search returns it (nine comma-separated numbers). This targets a province, town, district or neighbourhood precisely. Zip-code and street suggestions do NOT carry one and cannot be used here.
zone = todas-las-zonas	optional	—	District/zone slug inside the location (default todas-las-zonas = the whole town). Only meaningful together with location_slug.
transaction = buy	optional	buy · rent · comprar · alquiler · sale · for-sale · to-rent	Sale or rental market. Default buy.
property_type = viviendas	optional	viviendas · pisos · aticos · chalets · duplex · estudios · garajes · locales · oficinas · naves-industriales · terrenos · trasteros · edificios · homes · flats · houses · land · offices	Which fotocasa catalogue to search. These are the segments the site itself serves; anything else is rejected rather than quietly returning the wrong catalogue.
price_min	optional	0–	Minimum price in EUR (monthly rent when transaction=rent).
price_max	optional	0–	Maximum price in EUR (monthly rent when transaction=rent).
rooms_min	optional	0–20	Minimum number of rooms (bedrooms).
rooms_max	optional	0–20	Maximum number of rooms (bedrooms).
bathrooms_min	optional	0–20	Minimum number of bathrooms.
bathrooms_max	optional	0–20	Maximum number of bathrooms.
surface_min	optional	0–	Minimum built surface in m².
surface_max	optional	0–	Maximum built surface in m².
features	optional	air_conditioning · balcony · furnished · garden · heating · laundry_room · lift · parking · parquet · patio · storage_room · swimming_pool · terrace · wardrobes	Amenities the property must have — ALL of them (fotocasa intersects them: lift + pool returned 1 170 of 11 979 Madrid listings). Pass a list or a comma-separated string; a raw numeric fotocasa feature id is also accepted. Note that swimming_pool matches a COMMUNAL pool as well as a private one — 26 of the 31 rows on the first filtered page came back with the amenity `community_pool`.
condition	optional	almost_new · for_renovation · good · needs_renovation · new_home · refurbished · very_good	State of repair. Several values may be combined.
construction	optional	new_build · second_hand · any	New build vs resale. On Madrid this split 270 vs 11 713 of 11 984.
extras	optional	bank_owned · finished · price_drop · quality_seal · subsidised_housing · with_building_specs · with_photos · with_video_or_virtual_tour · with_videos	Listing-level flags fotocasa filters on: price_drop, bank_owned, with_videos, with_video_or_virtual_tour, quality_seal, subsidised_housing and friends.
subtypes	optional	—	Numeric fotocasa property-subtype ids to include (UNION, unlike features): 2 apartment, 3 house/chalet, 5 semi-detached, 6 penthouse, 7 duplex, 8 loft, 9 rural, 52 ground floor, 54 studio, 14/58/59/60 land. Usually the property_type segment is easier; this exists for combinations the segments cannot express.
keywords	optional	—	Free-text term matched against the listing (Spanish). 'piscina' cut Madrid from 11 984 to 1 704.
sort	optional	relevance · newest · price_asc · price_desc	Result order. These four are the orders fotocasa actually serves — its other sort keys return a server error, so they are not offered.
page = 1	optional	1–333	First page to fetch (30 listings per page). Fotocasa stops at page 333; beyond that it silently re-serves page 333, so deeper requests are refused here instead.
max_pages = 1	optional	1–20	How many consecutive pages to fetch in one call (1-20). Each page is one upstream request.
include_promoted = true	optional	—	Fotocasa injects ONE extra promoted listing above each results page (31 rows where its own page size is 30) and rotates it per request. It is a real property, so it is returned by default flagged `promoted: true` and counted in meta.promoted_count. Set false to receive only the 30 organic rows.
url	optional	—	Alternatively paste a fotocasa search URL straight from the browser; its path and query are used as-is and page/max_pages still apply.

Try in playground →

post/fotocasa/v1/property_detail2 credits

The full fotocasa listing: price and price per m², rooms, bathrooms, surface and land surface, floor, orientation, state of repair, age band, heating and hot-water type, energy-performance certificate, the agency's own feature list, the whole description, every photo, exact-or-approximate coordinates, breadcrumbs and the listing agency.

Parameter		Allowed / range	Description
property_id	optional	—	Fotocasa property id — the digits before /d in a listing URL, or a search result's property_id.
url	optional	—	Alternatively the full fotocasa listing URL. Pass this OR property_id.
transaction = buy	optional	buy · rent · comprar · alquiler · sale · for-sale · to-rent	Sale or rental market. Default buy.
property_type = viviendas	optional	viviendas · pisos · aticos · chalets · duplex · estudios · garajes · locales · oficinas · naves-industriales · terrenos · trasteros · edificios · homes · flats · houses · land · offices	Which fotocasa catalogue to search. These are the segments the site itself serves; anything else is rejected rather than quietly returning the wrong catalogue.

Try in playground →

post/fotocasa/v1/agency1 credit

An estate agency's fotocasa profile and its live stock: address, town, website, opening hours, quality seal and registration numbers, plus the listings it is advertising (15 per page, same listing shape as search).

Parameter		Allowed / range	Description
agency	required	—	Agency slug as it appears in its fotocasa profile URL (/es/pro/<slug>/), or the full profile URL. Every search result carries it as agency.profile_url.
page = 1	optional	1–200	Agency listing page (15 listings per page).
transaction = buy	optional	buy · rent · comprar · alquiler · sale · for-sale · to-rent	Sale or rental market. Default buy.
property_type = viviendas	optional	viviendas · pisos · aticos · chalets · duplex · estudios · garajes · locales · oficinas · naves-industriales · terrenos · trasteros · edificios · homes · flats · houses · land · offices	Which fotocasa catalogue to search. These are the segments the site itself serves; anything else is rejected rather than quietly returning the wrong catalogue.

Try in playground →

Example request · location_search

curl -X POST https://api.reefapi.com/fotocasa/v1/location_search \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"Madrid"}'

Response shape

{
  "ok": true,
  "data": { /* the result */ },
  "meta": {
    "latency_ms": 240,
    "record_count": 12,
    "completeness_pct": 100
  },
  "error": null
}

Comparing scraping APIs?ReefAPI vs Bright Data