Spain's property market as JSON, by town, district or neighbourhood
The Fotocasa API returns Spain's second-largest property marketplace as clean JSON in four actions.
4 active endpoints, on 0, 1 and 2 credit tiers.
- POST/fotocasa/v1/location_search
- POST/fotocasa/v1/search
- POST/fotocasa/v1/property_detail
- POST/fotocasa/v1/agency
What Fotocasa endpoints does ReefAPI ship?
4 live read endpoints. Read-only data API: no writes, no account actions, no dashboard access on the target site.
Fotocasa API
4 of 4 endpoints, ready to run
Spanish listings for sale or to rent: price and price per square metre, rooms, bathrooms, surface, floor, orientation, condition, amenities, coordinates, photos, publication date and the listing agency. 30 a page.
// Press "Try it" and this pane shows exactly what the // live site returned this second — including an empty // result, if that is the truth. No key, no account.
How the Fotocasa API works
Fotocasa is a normal ReefAPI surface — the same four rules that hold for every other engine on the key.
No OAuth app, no request signing, no per-site account. One key covers all 294 engines.
Every route is a POST with a JSON body. Parameters are validated against the published schema before anything is charged.
Credits, not seats. Failed and blocked calls are never charged, and cache hits cost nothing.
One envelope everywhere. meta carries latency_ms, record_count and the endpoint that answered.
Settle the location first, because it is free
The province-versus-city question is the one thing that silently changes what a Spanish search means. Resolving it costs nothing, so there is no reason to guess.
{"query": "Chamberí, Madrid"}Zero credits. Returns up to ten ranked matches with their administrative level and the location_id search takes. This is where madrid the province and madrid-capital the city stop being the same word.
{"location_id": "<from above>", "price_min": 200000, "rooms_min": 2, "sort": "newest"}2 credits for 30 rows. Read total_results to see how big the market actually is before you page. Page with page and max_pages, up to 20 pages in one call and 333 in total, and de-duplicate on property_id.
{"property_id": "<a row's property_id>"}2 credits. The street address, the energy certificate and the agency's own feature list, none of which is on the results list. The id matches the search row exactly.
{"agency": "<the row's agency slug>"}1 credit for the agency's whole book: its profile, its town, its opening hours and the listings it currently has, 15 a page.
A location you can prove, a market total you can budget against, and a listing enriched with the fields the results list never carries.
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"}'{
"ok": true,
"data": { … },
"meta": {
"api": "fotocasa",
"endpoint": "search",
"mode": "live",
"latency_ms": …,
"record_count": …
},
"error": null
}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.
All of Spain, and the four values that are not what they look like
Measured 2026-09-24 on 90 live calls across twelve Spanish towns: Madrid, Barcelona, Valencia, Sevilla, Bilbao, Málaga, Zaragoza, Alicante, Palma, Las Rozas, Gijón and Murcia. Two of these lines go against us.
Thirteen fotocasa catalogues, from flats and houses through garages, offices, industrial units, land and whole buildings, for sale and to rent, searchable by province, town, district or neighbourhood. There is no nationwide default: a call with no location at all is rejected rather than answered with a random page.
madrid is the province and madrid-capital is the city inside it, and the same holds for Barcelona, Valencia, Sevilla and Zaragoza. Free text follows fotocasa's own top suggestion, which was the city for Madrid and the province for Málaga. Whatever it picked is echoed in location.slug and location.resolved, so it is visible rather than silent.
A floor value of 12 is fotocasa's id for the seventh floor. The readable label comes back in floor and the raw id in floor_code, so a code that has never been seen shows up as unknown rather than as a wrong storey. Rooms, bathrooms and surface really are counts, checked against each listing's own page at 25 of 25, 25 of 25 and 26 of 26.
Fotocasa promotes one extra listing above each results page and rotates it on every request, which is why a page whose own size is 30 returns 31 rows. It is a real property with a real price, so it comes back flagged promoted and counted in promoted_count. Set include_promoted to false for the 30 organic rows only.
Run in the same minute as an unfiltered control: 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 30 of 30 returned rows satisfied each one.
0 of 493 live rows had one, so the field is simply not there and property_detail is where a street comes from, on 12 of 15 measured listings. Floor, orientation, condition and age band arrive on roughly half the rows because the advertiser left them blank, and land surface is empty on most listings for the same reason.
30 listings a page and no deeper than page 333, which is roughly 10,000 listings per query. Beyond that fotocasa silently re-serves page 333, so a deeper request is refused here instead. total_results always reports the real market size, so narrowing by district, price band or type is how you reach the rest.
Fotocasa prints it but does not publish it, so price_per_m2 is worked out from price and surface and comes back null when either is missing. A search-to-detail round trip on 15 listings matched on id, price, surface, rooms, transaction and floor, 15 of 15.
location_search is free. search and property_detail are 2 credits each, agency is 1. A 30-row page and a single listing cost the same, so ask for the page.
What people build with Fotocasa
The jobs this data is most often used for.
endpoints
credits per call
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.
What Fotocasa data costs
The cheapest call here is 0 credits, so $15/mo (Pro) buys 10,000 of them — $1.50 per 1,000 credits. Credits roll over and never expire, and failed or blocked calls are not charged.
Full pricing →- 1,000 free credits on signup, no card
- One key, all 294 APIs, one credit pool
- Failed and blocked calls are never charged
- Credits roll over and never expire
Call it in two lines
Sign up, get 1,000 credits and one key that works on every engine. Then this is the whole protocol.
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"])Have a question? We got answers.
The questions people actually ask before wiring up Fotocasa.
Get a free key →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.
16 Real Estate APIs on the same key
One key, one credit pool, one response envelope. If you are pulling Fotocasa, you are one call away from the rest of the category — no second contract, no second integration.
Need something this API does not do?
Name the endpoint, the field, or a source we do not carry yet. We ship new APIs every week and you would be first to get the key. Real people read every message and reply the same day.
Try it on your own data before you pay anything
The call above is the real endpoint, not a recording. A free key gives you 1,000 credits, the other 293 APIs, and the same envelope everywhere.
Endpoints, parameters and credit costs on this page are read from the live catalog and cannot drift from what the API accepts. Field notes were captured on 2026-09-24.