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
Live API Demo
🔒 Sign in to try it live
Log in to call this API with your own API key. New accounts get 100 free credits — no card required.
Log in / Sign upNo active API key found. Create one in your Dashboard, then reload this page. Dashboard →
/api/project/idealista/get-suggestions 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'
Query Result
Use Cases
- Power a type-ahead place picker in a rent-finder app, with suggestions scoped to the operation and property type being searched
- Convert a user-typed city name into a stable locationId before saving a search or alert
- Seed a nightly collection job's location table from a plain list of target city names
- Validate the location field of a lead form and show a no-match state when nothing is suggested
- Let overseas buyers pick the right municipality from a short suggestion list instead of guessing the exact local spelling
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.