Idealista API

The Idealista endpoints power the map-first source on the Properties surface. They proxy the RealtyAPI Idealista gateway behind one Fondaro-owned key, so there are no per-organization credentials. The source is free and ungated: when the key is configured every organization can use it.

All endpoints require the standard dashboard auth: a Clerk bearer token plus the x-organization-id header.

Base URL: https://api.fondaro.com

Availability

GET /idealista/status

{ "connected": true }

connected is true when the RealtyAPI key is configured server-side. When false, the source is hidden in the UI.

Search

POST /idealista/search

Provide exactly one of polygon, circle, or locationId / place:

Field	Type	Notes
`polygon`	`[lon, lat][]`	A GeoJSON ring → `/search/bypolygon`.
`circle`	`{ lat, lon, radiusKm }`	Centre + radius → `/search/bycoordinates`.
`locationId`	`string`	Resolved place id → `/search/bylocation` (full filters).
`place`	`string`	Free-text place (used with or instead of `locationId`).
`searchType`	`"For_Sale" \| "For_Rent"`	Operation. Default `For_Sale`.
`propertyType`	`string`	CSV of Idealista types, e.g. `flat,duplex`.
`minPrice` / `maxPrice`	`number`	EUR.
`minSize` / `maxSize`	`number`	m².
`bedrooms`	`number[]`	Idealista codes: `0`=studio, `1`,`2`,`3`,`4`(=4+).
`amenities`	`string[]`	Server-side amenity flags, honoured on the place path only.
`page`	`number`	1-based; 50 results per page.

curl -X POST 'https://api.fondaro.com/idealista/search' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-organization-id: <org>' \
  -H 'Content-Type: application/json' \
  -d '{"circle":{"lat":40.4168,"lon":-3.7038,"radiusKm":2},"maxPrice":800000,"bedrooms":[3]}'

Response:

{
  "properties": [ { "id": "104588621", "source": "idealista", "price": 1750000, "currency": "EUR", "latitude": 40.43, "longitude": -3.69, "externalAgency": { "name": "...", "phone": "...", "micrositeShortName": "..." }, "deeplinkUrl": "https://www.idealista.com/inmueble/104588621/" } ],
  "total": 3165,
  "page": 1,
  "totalPages": 1055,
  "pageSize": 50
}

Each properties[] item is a normalized UnifiedProperty carrying coordinates, amenity booleans, the listing deeplink, and the externalAgency block.

Place autocomplete

GET /idealista/autocomplete?input=Marbella&country=es

{ "locations": [ { "name": "Marbella, Málaga", "locationId": "0-EU-ES-29-...", "subTypeText": "Municipio", "total": 12345, "divisible": true } ] }

Sublocations

GET /idealista/sublocations?locationId=0-EU-ES-28&country=es

Drills the geography tree one level down (province → municipalities → districts), with per-area counts.

Listing detail

GET /idealista/detail/:propertyCode?locale=en

Returns the full UnifiedProperty (all photos, energy rating, full description, community costs, deeplink, agency).

{ "property": { "id": "106387165", "source": "idealista", "bedrooms": 4, "bathrooms": 5, "livingArea": 263, "energyRating": "b", "images": ["..."], "deeplinkUrl": "..." } }

Agency profile

GET /idealista/agent/:micrositeShortName?country=es
GET /idealista/agent/:micrositeShortName/locations?country=es

/agent/:micrositeShortName returns the agency profile (name, phone, email, website, languages, active-since year, total listings). The /locations variant returns the provinces, municipalities, and districts where the agency has active listings, with per-area counts.

Notes

Polygon and radius searches accept only the common filter subset (price, size, beds, type, operation). Amenity filtering on those paths happens client-side over the fetched pins; on the place path amenities are passed through to the server.
Results and detail are cached in-process for ~5 minutes to keep the shared credit budget low. There is no usage metering or billing for this source.

Idealista