Autocomplete place names into Idealista location IDs

View all Idealista Property Listings API for Spain, Portugal & Italy endpoints →

Resolves the beginning of a place name to matching Idealista locations in Spain, Portugal or Italy. Send location (es, pt or it), operation (sale or rent), prefix (the text typed so far, for example madrid) and propertyType (homes, newDevelopments, bedrooms, offices, premises, garages, lands, storageRooms or buildings); all four are required. The response is a JSON object with a locations array and an integer total. In a live check with location=es, operation=sale, prefix=madrid and propertyType=homes, every locations entry carried name, locationId, divisible, type, suggestedLocationId, subTypeText and its own total, and the matches mixed municipalities, the Madrid province and individual districts. The per-entry total counts the properties offered for the chosen operation and property type, and the locationId values are the identifiers the listing endpoints take as their locationId input.

API Features

Prefix-based place autocomplete Send the first letters of a city, province or district and get the matching Idealista places back, the way a type-ahead search box expects.
Ready-to-use locationId values Every match carries a locationId such as 0-EU-ES-28-07-001-079 for the Madrid municipality, plus a numeric suggestedLocationId, so the result can be passed straight into listing searches.
Counts that follow your search context The total on each match reflects the chosen operation (sale or rent) and propertyType, so suggestions can show how much inventory exists before the user commits to a search.
Place level and drill-down flags subTypeText labels each match, for example Municipio, Provincia or Distrito, and the divisible flag shows whether a place can be split into smaller areas.
Three country sites in one call shape The location parameter switches between Spain (es), Portugal (pt) and Italy (it) without changing any other input.
Nine property categories propertyType covers homes, newDevelopments, bedrooms, offices, premises, garages, lands, storageRooms and buildings, with bedrooms limited to the rent operation.

Live API Demo

GET /api/project/idealista/get-suggestions

Request cost is temporarily unavailable. No price is assumed.

View pricing

API Response (JSON)

{}
curl -X GET 'https://api.opendata-api.com/api/project/idealista/get-suggestions?key=<API_KEY>&location=es&operation=sale&prefix=madrid&propertyType=homes'
📢
Need Help?
If you encounter API issues or need other API requirements, please contact us.
Contact Us

Use Cases

Frequently asked questions

What does the Idealista location suggestions endpoint return?

A JSON object with a locations array and an integer total. In a live check each locations entry contained name, locationId, divisible, type, suggestedLocationId, subTypeText and its own total.

Which parameters are required?

All four: location (es, pt or it), operation (sale or rent), prefix (the place-name text) and propertyType (homes, newDevelopments, bedrooms, offices, premises, garages, lands, storageRooms or buildings).

What do operation and propertyType change in the response?

They change the total field of each suggestion, which counts the properties offered under that operation and of that property type.

Can I request bedrooms together with sale?

No. The endpoint documentation states that the bedrooms property type only works with the rent operation, so pair bedrooms with operation=rent.

How do I use the returned locationId in other endpoints?

Copy the locationId of the chosen match into the locationId input of a listing endpoint. For example, the check for madrid returned 0-EU-ES-28-07-001-079 for the Madrid municipality, which is the same value the buildings listing uses as its example.

What kinds of places can be suggested?

The live check returned municipalities (Municipio), a province (Provincia) and districts (Distrito) whose names contain the typed text, each with a divisible flag. Other place levels may exist but were not observed.

How should I handle a prefix with no matches?

Treat an empty locations array as no match and let the user retype. The response also carries an integer total at the top level.

Related operations

Guides

View Subscription Plans →