Search properties
search_propertiesSearch PropertyList's full Spanish property MLS by structured filters. Use for queries that translate cleanly to fields: bedrooms, bathrooms, price ceiling, property type, area name. For free-form briefs use find_properties_by_description instead.
Free use, with or without an API key, is for an assistant answering a
person's questions and has a daily allowance of results. Reading
listings in bulk, or showing them on a website, needs MCP Pro or the
agency's website feed. When the day's allowance is used the result is
empty and carries error and limits.
Returns a paginated list with summary text plus structured JSON. Every
property carries oracle_verified and oracle_attestation_url —
true when PropertyList Oracle holds a verified attestation for the listing's municipality and segment.
A location we do not hold returns zero results with
error: location_not_found and location_match.matched: false. It
never substitutes listings from other areas. location_id takes an
area id from autocomplete_location instead of a name; a group id
(type group, e.g. a region or a coast) searches every area in the
group. When several places share the name, the results are for
the one holding at least 80% of their live listings, and
location_match.other_places names the others; when the listings
are split, the results cover all of them and
location_match.ambiguous is true, with the places in
location_match.candidates (id, municipality, province). Pass one
as location_id, or add the town after a comma ('El Limonar, Mijas').
features keeps only listings that have ALL the features asked
for: pool (any pool, communal included), private_pool,
communal_pool, sea_view, garden, parking (a garage or parking space)
and terrace. Each
result then carries matched_features, saying which tags (and, for
parking and terrace, which space count or terrace size) the listing
matched on. private_pool means the listing is tagged with a private
or heated pool; many agency feeds tag every pool that way, communal
ones included, so use pool for "with a pool" and check the listing
when a pool must be private. communal_pool means the listing is
tagged with a communal (shared) pool: use it when the user asks for
a communal pool; pool also finds the communal pools a feed tagged
as private, so widen to pool when communal_pool finds too few.
location.city is whatever tier the listing was filed under and
may be a municipality OR a locality inside one. To place a listing
administratively use location.municipality (with its INE
municipality_code); it is null, never guessed, when we cannot
resolve it.
location.latitude / location.longitude are present whenever
we can place the listing; the fields are absent otherwise, and
are never 0,0. location.coordinates_precision says what the
point is: exact or street is the property itself, approximate is
a pin the agent keeps private, rounded to about 1 km, locality or
administrative_area is an area centroid (accurate to the town or
neighbourhood, not the building: a listing whose agent placed no
map pin carries the centre of its area, shared by its
neighbours), unknown is a pin we hold no precision record for.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| tenure | No | Commercial sales only: traspaso finds business transfers (the lease and the business taken over), freehold the premises sold outright. | |
| features | No | Only listings with ALL of these: pool (any pool), private_pool (tagged private or heated pool), communal_pool (tagged communal pool), sea_view, garden (private, landscaped or communal), parking (garage or parking space), terrace. Results say what each matched on in matched_features. | |
| language | No | Preferred language for property titles and description excerpts. | en |
| location | No | Free-text place name (city, suburb, or urbanisation). e.g. 'Marbella', 'Nueva Andalucia', 'Sotogrande'. Pre-resolved with autocomplete_location if you need to confirm match. | |
| page_size | No | ||
| price_max | No | Maximum price in euros (sale) or monthly euros (rent). | |
| price_min | No | Minimum price in euros (sale) or monthly euros (rent). | |
| location_id | No | Area id from autocomplete_location. Takes precedence over location. A group id (a region or coast, type group) searches every area in the group. | |
| rent_to_buy | No | Only rent-to-buy listings (alquiler con opcion a compra): homes for sale AND let long term, whose tenant may buy at the sale price. Works with for-sale or for-rent. Results carry rent_to_buy with the years and the share of the price paid up front. | |
| search_type | No | Listing market. Defaults to 'for-sale'. | |
| bedrooms_max | No | ||
| bedrooms_min | No | ||
| bathrooms_min | No | ||
| buildable_min | No | Land only: the least floor area in m² a plot may be built to (edificabilidad, m² edificables, m² de techo). Use with property_types plots or commercial-land. Listings that do not state a buildable figure cannot be known to qualify and are left out; buildable_unstated in the response says how many plots were left out for that reason. | |
| property_types | No | Comma-separated slugs: apartments, villas, penthouses, plots, townhouses, or commercial (every commercial type; a family such as offices, retail, cafes-bars-restaurants, hotels-leisure, industrial-warehouses, garages-storage-rooms, buildings or commercial-land; office, shop, restaurant, hotel, warehouse and the other commercial types also work alone). Without it the search covers homes only. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | ||
| error | No | ||
| total | Yes | ||
| limits | No | ||
| page_size | Yes | ||
| properties | Yes | ||
| location_match | No | ||
| buildable_unstated | No | With buildable_min: how many plots meet every other filter but state no buildable m², so were left out. |