Fotocasa API & Scraper
The Fotocasa API returns Spain's second-largest property marketplace as clean JSON in four actions.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
search takes a location, which can be plain text such as Madrid or Chamberí, a fotocasa slug such as madrid-capital, a location id, or a pasted fotocasa URL, and returns 30 listings a page for sale or to rent across homes, flats, penthouses, houses, duplexes, studios, garages, commercial premises, offices, industrial units, land, storage rooms and whole buildings. Every row carries the price and the price per square metre, the rent period when it is a rental, rooms, bathrooms, surface, the floor as a readable label, orientation, state of repair, age band, the amenities the advertiser listed, coordinates, every photo, the publication date, how long it has been online, the full description and the agency behind it. property_detail adds the street address, the energy-performance certificate and its emissions rating, heating and hot-water type, lift and furnished flags, the agency's own feature list and the listing reference. location_search turns a place name into the exact location fotocasa uses and costs nothing. agency returns an estate agency's profile, with its address, town, website, opening hours and quality seal, together with everything it currently has on the market. Every filter was checked live against fotocasa's own market total and against the rows that came back: price range, rooms, bathrooms, surface, property type, state of repair, new-build or resale, amenities, free text, subtypes and sort order, sixteen cases in all, sixteen of which narrowed, with 30 of 30 returned rows satisfying each one. A search-to-detail round trip on 15 listings matched on id, price, surface, rooms, transaction and floor, 15 of 15. No fotocasa account, no browser, one ReefAPI key and the standard { ok, data, meta, error } envelope.
Four Fotocasa values that are not what they look like
Fotocasa's results list is compact: some fields are counts, some are internal codes wearing the same clothes, and one row on every page is an advert that is also a real property. These were read from live searches and detail pages on 2026-09-24.
| Field | Looks like | Actually is | What comes back |
|---|---|---|---|
| floor | 12 | fotocasa's internal id for the seventh floor | floor reads 7th_floor and floor_code keeps the 12, so a code we have not seen yet shows up as unknown rather than wrong |
| rooms / bathrooms / surface_m2 | counts | really are counts, checked against each listing's own page at 25 of 25, 25 of 25 and 26 of 26 | the numbers, unchanged |
| rooms on a garage or an office | 0 on the listing page, missing in the results list | the advertiser left it blank and fotocasa writes 0 in one place and nothing in the other | null in both, so a search and a detail call agree |
| one row per page | an ordinary listing | the promoted slot: 31 rows on a page whose own size is 30, and it changes on every request | promoted true, counted in promoted_count, dropped on request with include_promoted false |
Measured 2026-09-24 on Madrid, Barcelona, Valencia, Sevilla, Bilbao, Málaga, Zaragoza, Alicante, Palma, Las Rozas, Gijón and Murcia. price_per_m2 is worked out from price and surface, because fotocasa prints it but does not publish it, and is null when either is missing.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/fotocasa/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"location_slug": "madrid-capital"
}
}{
"ok": true,
"meta": {
"api": "fotocasa",
"endpoint": "search",
"mode": "live",
"latency_ms": 12812.5,
"record_count": 31,
"bytes": 1381911,
"cache_hit": false,
"completeness_pct": 100,
"stop_reason": "max_pages",
"total_results": 12041,
"promoted_count": 1,
"grid_rows": 31,
"filters_applied": {},
"field_note": "price_per_m2 is computed here as price/surface_m2 — fotocasa prints it but does not publish it — and is null when either is missing. floor/orientation/condition/antiquity arrive as numeric ids in the results list: the decoded label plus the raw *_code is returned, and the label is null for an id we have not observed.",
"charged_credits": 2,
"version": "1.0.0"
},
"data": {
"items": [
{
"promoted": true,
"property_id": 190588797,
"ad_id": "b374b98e-03e4-4177-b68d-5b4efe70f7e4",
"detail_url": "https://www.fotocasa.es/es/comprar/vivienda/madrid/aire-acondicionado-calefaccion-parking-trastero-ascensor-amueblado-piscina/190588797/d",
"transaction": "sale",
"property_type": "Flat",
"property_subtype": "Flat",
"property_type_id": 2,
"property_subtype_id": 1,
"price": 375000,
"price_display": "375.000 €",
"price_period": null,
"price_reduced_from_display": null,
"price_per_m2": 5136.99,
"currency": "EUR",
"rooms": 1,
"bathrooms": 1,
"surface_m2": 73,
"land_surface_m2": null,
"floor": "2nd_floor",
"floor_code": 7,
"orientation": null,
"orientation_code": null,
"condition": "good",
"condition_code": 3,
"antiquity": "between_20_and_30_years",
"antiquity_code": 5,
"hot_water": null,
"amenities": [
"air_conditioner",
"cabinets",
"community_pool"
],
"feature_codes": {
"air_conditioner": 1,
"cabinets": 2,
"heating": 3,
"parking": 5,
"storage_room": 11,
"elevator": 13,
"furnished": 19,
"community_pool": 94,
"equiped_kitchen": 131,
"antiquity": 5,
"bathrooms": 1,
"conservationStatus": 3,
"floor": 7,
"rooms": 1,
"surface": 73
},
"is_new_construction": false,
"is_occupied": false,
"is_auctioned": false,
"is_rented_with_tenants": false,
"is_bare_ownership": false,
"is_temporary_rental": false,
"has_floor_plans": false,
"has_virtual_tour": false,
"has_video": false,
"has_open_house": false,
"location": "Calle de Estocolmo, Rosas - Musas",
"address": {
"neighborhood": "Rosas - Musas",
"district": "San Blas",
"municipality": "Madrid",
"city": "Madrid",
"county": "Madrid, Zona de",
"province": "Madrid",
"region": "Madrid",
"zip_code": "28022",
"country": "España",
"upper_level": "Rosas - Musas"
},
"latitude": 40.4244888402685,
"longitude": -3.6015433338673453,
"images": [
"https://static.fotocasa.es/images/ads/1a1f927b-3f8b-4cc2-a386-1155755a2a6c?rule=original",
"https://static.fotocasa.es/images/ads/5d56ae74-62cd-4245-8bb1-704a2d6a4499?rule=original",
"https://static.fotocasa.es/images/ads/70076967-c1ac-449c-9f7e-9f3551e26aa3?rule=original"
],
"images_count": 27,
"videos": [],
"published_at": "2026-08-28T13:30:09.503000Z",
"days_online": 28,
"description": "VOhome Propiedades Zona San Blas / Las Rosas ofrece en exclusiva este encantador piso situado a escasos metros de la estación de metro Las Rosas, en pleno barrio de Las Rosas, Madrid. Una ocasión ideal para disfrutar de una vivienda ubicada en una urbanización apacible y con excelentes conexiones con el centro de la capital.\r\n\r\nLa vivienda cuenta con una estupenda luz natural y una distribución práctica y cómoda. Al entrar, encontramos un pequeño hall que da acceso a un amplio y luminoso salón. A continuación, se sitúa una cocina independiente tipo office con salida directa a un lavadero/tende",
"agency": {
"agency_id": 9202769991762,
"name": "VOhome Las Rosas-San Blas",
"type": "professional",
"profile_url": "https://www.fotocasa.es/es/pro/vohome-las-rosas-san-blas/",
"publisher_id": "d8963f80-c641-4cd0-89f7-bac34f314441",
"phone": "[redacted-phone]"
}
},
{
"promoted": false,
"property_id": 190399711,
"ad_id": "58c5a3b4-3efa-4148-ac8b-34dd2f30df76",
"detail_url": "https://www.fotocasa.es/es/comprar/vivienda/madrid/calefaccion-ascensor-amueblado/190399711/d",
"transaction": "sale",
"property_type": "Flat",
"property_subtype": "Flat",
"property_type_id": 2,
"property_subtype_id": 1,
"price": 489000,
"price_display": "489.000 €",
"price_period": null,
"price_reduced_from_display": null,
"price_per_m2": 11372.09,
"currency": "EUR",
"rooms": 1,
"bathrooms": 1,
"surface_m2": 43,
"land_surface_m2": null,
"floor": "1st_floor",
"floor_code": 6,
"orientation": "south",
"orientation_code": 4,
"condition": null,
"condition_code": null,
"antiquity": "between_70_and_100_years",
"antiquity_code": 8,
"hot_water": "electricity",
"amenities": [
"cabinets",
"elevator",
"equiped_kitchen"
],
"feature_codes": {
"cabinets": 2,
"heating": 3,
"elevator": 13,
"furnished": 19,
"household_appliances": 21,
"equiped_kitchen": 131,
"antiquity": 8,
"bathrooms": 1,
"floor": 6,
"hotWater": 2,
"orientation": 4,
"rooms": 1,
"surface": 43
},
"is_new_construction": false,
"is_occupied": false,
"is_auctioned": false,
"is_rented_with_tenants": false,
"is_bare_ownership": false,
"is_temporary_rental": false,
"has_floor_plans": false,
"has_virtual_tour": false,
"has_video": true,
"has_open_house": false,
"location": "Calle de Don Ramón de la Cruz, Lista",
"address": {
"neighborhood": "Lista",
"district": "Barrio de Salamanca",
"municipality": "Madrid",
"city": "Madrid",
"county": "Madrid, Zona de",
"province": "Madrid",
"region": "Madrid",
"zip_code": "28001",
"country": "España",
"upper_level": "Lista"
},
"latitude": 40.42857765397692,
"longitude": -3.67814024697511,
"images": [
"https://static.fotocasa.es/images/ads/9324543d-71ce-47cf-8931-ebcb69fdab70?rule=original",
"https://static.fotocasa.es/images/ads/05061eec-0e7d-454c-9ecb-5efac0380b4e?rule=original",
"https://static.fotocasa.es/images/ads/c2ed6bbb-d447-46a3-8450-047274acd672?rule=original"
],
"images_count": 21,
"videos": [
"https://vimeo.com/1215422678",
"https://www.youtube.com/watch?v=herOSioqMOc"
],
"published_at": "2026-08-04T11:35:30.630000Z",
"days_online": 52,
"description": "APARTAMENTO PERFECTO PARA INVERSIÓN O COMO PIED-À-TERRE\n\nAproperties presenta esta acogedora vivienda de 43 m² según catastro, situada en la calle Don Ramón de la Cruz, en pleno barrio de Goya, una de las zonas más demandadas del distrito de Salamanca. Ubicada a escasos metros de la Plaza del Marqués de Salamanca, muy próxima a la estación de metro Lista y a pocos minutos andando de El Corte Inglés de Goya, disfruta de una excelente localización, rodeada de comercios, restaurantes, servicios y algunas de las calles más representativas del barrio. Por sus características y ubicación, constituye",
"agency": {
"agency_id": 9202756368671,
"name": "Aproperties Real Estate Madrid",
"type": "professional",
"profile_url": "https://www.fotocasa.es/es/pro/aproperties-real-estate-madrid/",
"publisher_id": "5cbf9036-d1e9-422b-878f-1943c01d47df",
"phone": "[redacted-phone]"
}
},
{
"promoted": false,
"property_id": 186996613,
"ad_id": "09ac30fa-3909-433d-815d-09b195c7cc60",
"detail_url": "https://www.fotocasa.es/es/comprar/vivienda/madrid/calefaccion-terraza/186996613/d",
"transaction": "sale",
"property_type": "Flat",
"property_subtype": "Flat",
"property_type_id": 2,
"property_subtype_id": 1,
"price": 598000,
"price_display": "598.000 €",
"price_period": null,
"price_reduced_from_display": null,
"price_per_m2": 9803.28,
"currency": "EUR",
"rooms": 2,
"bathrooms": 1,
"surface_m2": 61,
"land_surface_m2": null,
"floor": "ground_floor",
"floor_code": 3,
"orientation": "south",
"orientation_code": 4,
"condition": null,
"condition_code": null,
"antiquity": "between_70_and_100_years",
"antiquity_code": 8,
"hot_water": "gas_natural",
"amenities": [
"heating",
"porter_service",
"terrace"
],
"feature_codes": {
"heating": 3,
"terrace": 10,
"porter_service": 28,
"antiquity": 8,
"bathrooms": 1,
"floor": 3,
"hotWater": 1,
"orientation": 4,
"rooms": 2,
"surface": 61
},
"is_new_construction": false,
"is_occupied": false,
"is_auctioned": false,
"is_rented_with_tenants": false,
"is_bare_ownership": false,
"is_temporary_rental": false,
"has_floor_plans": false,
"has_virtual_tour": false,
"has_video": true,
"has_open_house": false,
"location": "Cl. de Ayala, Goya",
"address": {
"neighborhood": "Goya",
"district": "Barrio de Salamanca",
"municipality": "Madrid",
"city": "Madrid",
"county": "Madrid, Zona de",
"province": "Madrid",
"region": "Madrid",
"zip_code": "28009",
"country": "España",
"upper_level": "Goya"
},
"latitude": 40.42701099807733,
"longitude": -3.6692715650998196,
"images": [
"https://static.fotocasa.es/images/ads/15eca8ff-e6c7-48d1-9b4c-8b78e1d9e818?rule=original",
"https://static.fotocasa.es/images/ads/c0244c2b-2824-4541-8873-15d70e16c999?rule=original",
"https://static.fotocasa.es/images/ads/93e81b18-e9ca-4c89-abf7-24a7ea498a48?rule=original"
],
"images_count": 11,
"videos": [
"https://www.youtube.com/watch?v=herOSioqMOc"
],
"published_at": "2025-07-07T16:55:26.960000Z",
"days_online": 445,
"description": "PISO CON MUCHAS POSIBILIDADES EN GOYA\n\nAproperties presenta piso de 61m2 en pleno corazón del barrio de Goya – Salamanca, en la calle Ayala, a dos pasos de la Plaza de Manuel Becerra y del Corte Inglés. \n\nLa vivienda actualmente cuenta con 1 dormitorio, 1 cuarto de baño y un amplio salón con diferentes ambientes. Este original espacio, configurado en 2 alturas, se presta para ser convertido en zona de despacho, en un segundo dormitorio, en vestidor... \n\nTanto desde la cocina como desde el salón, se accede a dos patios de uso privativo de 9m2 y 16m2 respectivamente. El uso y disfrute de dichos ",
"agency": {
"agency_id": 9202756368671,
"name": "Aproperties Real Estate Madrid",
"type": "professional",
"profile_url": "https://www.fotocasa.es/es/pro/aproperties-real-estate-madrid/",
"publisher_id": "5cbf9036-d1e9-422b-878f-1943c01d47df",
"phone": "[redacted-phone]"
}
}
],
"count": 31,
"total_results": 12041,
"promoted_count": 1,
"page_size": 30,
"page": 1,
"pages_fetched": 1,
"location": {
"slug": "madrid-capital",
"zone": "todas-las-zonas",
"literal": "Madrid",
"resolved": null
},
"filters_applied": {},
"transaction": "sale",
"property_type": "viviendas",
"stop_reason": "max_pages"
}
}What the Fotocasa API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| location_search | 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. | Real-estate investors call location_search to resolve a Spanish place name, district, postcode or street to fotocasa locations. | query, limit |
| search | 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. | Brokerage tools call search to search Spanish property listings by location. | location, location_slug, location_id, zone, transaction, ... |
| property_detail | 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. | Property dashboards call property_detail to get the full fotocasa listing. | property_id, url, transaction, property_type |
| agency | 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). | Lead-generation teams call agency to get an estate agency's fotocasa profile and its live stock. | agency, page, transaction, property_type |
Call search from your stack
curl -X POST https://api.reefapi.com/fotocasa/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"location_slug":"madrid-capital"}'import requests
r = requests.post(
"https://api.reefapi.com/fotocasa/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"location_slug": "madrid-capital"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/fotocasa/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"location_slug": "madrid-capital"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.fotocasa.search with {"location_slug":"madrid-capital"}.Who uses this API and why
- Track asking prices and price per square metre by district in Madrid, Barcelona or Valencia week over week.
- Build a rental yield model: pull the same neighbourhood for sale and to rent and compare price per square metre.
- Feed a buyer-alert product: filter by price band, rooms and amenities, sort by newest, and diff on property_id.
- Profile an estate agency, its stock, its towns and its price bands, from its own fotocasa profile.
- Enrich a Spanish property CRM with surface, floor, energy rating and coordinates from a listing URL.
Questions developers ask before integrating
How do I tell Fotocasa where to search?
Four ways, and you need exactly one. Pass location as plain text and it is resolved for you, with the match that was used echoed in location.resolved. Pass location_slug such as madrid-capital or bilbao if you already know it, which is the cheapest option because it skips the lookup. Pass location_id from location_search to hit a province, town, district or neighbourhood exactly. Or paste a fotocasa search URL as url. Spain is searched by place, so there is no nationwide default and a call with none of the four is rejected rather than answered with a random page.
Why did Madrid give me the city but Málaga gave me the province?
Because that is fotocasa's own ranking, and it is not second-guessed. Fotocasa names a province with the bare word and adds -capital for the city inside it: madrid is the province and madrid-capital is the city, and the same holds for Barcelona, Valencia, Sevilla and Zaragoza. Free text follows fotocasa's top suggestion, which was the city for Madrid and the province for Málaga. Whatever it picked comes back in location.slug and location.resolved, so you can see it and pass the slug you wanted instead.
How many Fotocasa listings can one search return?
30 a page, and fotocasa stops paginating at page 333, which is roughly 10,000 listings per query. Ask for a deeper page and the call is refused rather than served page 333 again under a different number. total_results always tells you how many listings fotocasa says match, whether or not you page through them, so narrowing by district, price band or property type is how you reach the rest. max_pages fetches up to 20 consecutive pages in one call.
Why does a Fotocasa page sometimes return 31 listings?
Fotocasa promotes one extra listing above each results page and rotates it on every request. It is a real property with a real price, so it is returned flagged promoted true and counted in promoted_count instead of being quietly mixed into your results. Set include_promoted to false if you only want the 30 organic rows.
Do the Fotocasa filters actually filter?
Yes, and it was checked rather than assumed. Each filter was run against the same unfiltered search in the same minute and compared with fotocasa's own market total: a 500,000 floor cut Madrid from 11,980 to 6,265, three or more rooms to 6,171, 150 square metres or more to 2,590, a lift to 7,742, a pool to 1,434, lift and pool together to 1,170, needs-renovation to 1,270, new build to 270 and penthouses to 529. Sixteen filters, sixteen narrowed, and every returned row satisfied the one asked for. Note that the pool filter includes communal pools.
Which Fotocasa sort orders are available?
Relevance, which is fotocasa's own ranking and the default, newest first, cheapest first and most expensive first. Those are the orders fotocasa genuinely serves. Its other sort keys fail at its end, so they are not offered rather than passed through as an error.
Do I get the estate agent's phone number?
The agency's name, type, logo, website and public profile link always come back, because those are business details, and the agency action adds the office address, town, opening hours, quality seal and registration numbers. The phone number and e-mail address are contact data and are only returned when you opt in with include_pii. A private seller's contact details are never returned.
What does Fotocasa leave null?
Whatever fotocasa does not publish, and it says so rather than guessing. The results list carries no street address at all, 0 of 493 live rows had one, so property_detail is where a street comes from and it had one on 12 of 15. Land surface and agency registration numbers are empty on most listings because the advertiser left them empty. Floor, orientation, condition and age band arrive on roughly half the rows for the same reason, and a floor code that has never been seen comes back with the code and a null label instead of an invented one.
What is the Fotocasa API?
Fotocasa API is a ReefAPI endpoint group for spanish homes for sale and to rent, with the agency behind each listing. It returns live JSON through POST requests under /fotocasa/v1.
Is the Fotocasa API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Fotocasa calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Fotocasa login or account?
No login to Fotocasa is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Fotocasa data?
The page example is captured from a live location_search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Fotocasa API use?
Fotocasa actions currently cost 1-2 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call Fotocasa from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call fotocasa actions with the same key, credit pool and JSON envelope used by normal REST requests.