Idealista

Search real estate listings on Idealista for Spain, Portugal, and Italy

Overview

Access property listings from Idealista — the leading real estate portal in Spain, Portugal, and Italy. The typical flow is: search for a location ID with /locations, then pass that ID to /properties to get listings.

Base path: https://api.datacaiman.com/v1/idealista

Cost: 1 credit per call

GET /v1/idealista/locations

Resolve a location name into a location ID required by /properties.

Parameters

Name Type Required Description
query string Yes Location name (e.g. madrid, barcelona)
country string No es, pt, or it (default: es)
operation string No sale or rent (default: sale)

Response

[
  {
    "name": "Madrid",
    "locationId": "0-EU-ES-28-07-001-079",
    "type": "municipality",
    "subTypeText": "Municipality",
    "total": 12500
  }
]

Example

curl "https://api.datacaiman.com/v1/idealista/locations?query=madrid&country=es" \
  -H "X-API-Key: dc_your_key_here"

GET /v1/idealista/properties

Search property listings for a location. Returns up to 50 results per page. Use nextPageToken to paginate.

Parameters

Name Type Required Description
locationId string Yes ID from /locations (e.g. 0-EU-ES-28-07-001-079)
locationName string No Display name for the location
country string No es, pt, or it (default: es)
operation string No sale or rent (default: sale)
propertyType string No homes, newDevelopments, offices, premises, garages, lands, storageRooms, buildings, bedrooms (default: homes)
sortBy string No mostRecent, relevance, lowestPrice, highestPrice, biggest, smallest, and more
limit integer No Results per page, max 50 (default: 50)
pageToken string No Token from previous response
minPrice integer No Minimum price filter
maxPrice integer No Maximum price filter
minSize integer No Minimum size in m²
maxSize integer No Maximum size in m²
publicationDate string No T (today), Y (yesterday), W (this week), M (this month)
bedrooms string No Comma-separated: studio, 1, 2, 3, 4
bathrooms string No Comma-separated: 1, 2, 3
condition string No Comma-separated: newDevelopment, good, renew
floor string No Comma-separated: topFloor, intermediateFloor, groundFloor
airConditioning boolean No Filter by air conditioning
lift boolean No Filter by lift/elevator
balcony boolean No Filter by balcony
terrace boolean No Filter by terrace
garage boolean No Filter by garage
swimmingPool boolean No Filter by swimming pool
garden boolean No Filter by garden

Response

{
  "hasNextPage": true,
  "nextPageToken": "eyJj...",
  "items": [
    { "propertyCode": "106316721", "price": 350000, "size": 85, ... }
  ]
}

Example

Search apartments for sale in Madrid under €400,000:

curl "https://api.datacaiman.com/v1/idealista/properties?locationId=0-EU-ES-28-07-001-079&operation=sale&propertyType=homes&maxPrice=400000&sortBy=mostRecent" \
  -H "X-API-Key: dc_your_key_here"

GET /v1/idealista/details

Fetch raw details for a single property.

Parameters

Name Type Required Description
propertyCode string Yes Property code from a /properties result
country string No es, pt, or it (default: es)

Example

curl "https://api.datacaiman.com/v1/idealista/details?propertyCode=106316721&country=es" \
  -H "X-API-Key: dc_your_key_here"

GET /v1/idealista/stats

Fetch statistics for a single property (price history, views, etc.).

Parameters

Name Type Required Description
propertyCode string Yes Property code from a /properties result
country string No es, pt, or it (default: es)

Example

curl "https://api.datacaiman.com/v1/idealista/stats?propertyCode=106316721" \
  -H "X-API-Key: dc_your_key_here"
← Twitter / XFlight Award →