Search properties by description
POST
https://platform.casafari.com/v1/property-sourcing/searches/describeAPI key100 units per page12 parameters
Send Authorization: Bearer $CASAFARI_API_KEY: a platform API key or OAuth access token; see platform sign-in. Costs 100 units per page (1 unit = EUR 0.04).
Over MCP: none; this product is REST only.
Description
Plain-language search: say what you look for as tags (up to 20 phrases) or one description (split into phrases at commas, semicolons and "and"), in the places named by location_ids, optionally within a price or price-per-m² range. Each result lists the phrases it matched in matched_tags. Structured filters (types, bedrooms, features) belong to POST /v1/property-sourcing/searches. 100 units per page.
Request body
Content type application/json. Required. Type: object.
location_idsinteger[]required1 to 100 location ids, from GET /v1/locations/search?query=<place>.
1–100 items
countrystringISO 3166-1 alpha-2 code, e.g. "ES".
operationstringFor sale or for rent.
sale rentdefault "sale"
tagsstring[]Up to 20 phrases, e.g. ["close to the beach", "sea views"]. Send tags or description, not both.
1–20 itemsat most 200 characters
descriptionstringWhat you look for in plain words, split into phrases at commas, semicolons and "and" (at most 20).
at most 1000 characters
priceobjectAsking price range.
2 properties
minintegerLowest value, inclusive.
maxintegerHighest value, inclusive.
price_per_sqmobjectAsking price per m² range.
2 properties
minintegerLowest value, inclusive.
maxintegerHighest value, inclusive.
page_sizeintegerResults per page: up to 100 (25 on Free).
1–100default 25
Example request
Placeholders only: replace the token and the values with your own.
curl -X POST "https://platform.casafari.com/v1/property-sourcing/searches/describe" \
-H "Authorization: Bearer $CASAFARI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"location_ids": [
12345
],
"country": "ES",
"operation": "sale",
"description": "close to the beach, sea views and a garden",
"price": {
"max": 900000
},
"page_size": 25
}'Responses
200 One page of properties, each with the phrases it matched.
Type: object.
Show the response shape (21 fields)
resultsobject[]10 properties
idstringOpaque property id,
prop_....typestringnullableProperty type.
operationstringsale rentpriceobject3 properties
amountnumbernullableAsking price; null when the price is on request.
currencystringnullableISO 4217 currency code.
per_sqmnumbernullableAsking price per m².
bedroomsnumbernullableliving_area_sqmnumbernullablelocationobject3 properties
idintegernullableLocation id.
namestringnullableLocation name.
coordinatesobjectnullableLatitude and longitude.
2 properties
latnumberlonnumberfirst_seenstringnullableWhen the property came on the market for this operation.
listings_countintegernullableHow many listings advertise it; known on a property read with expand=listings, null in search results.
matched_tagsstring[]nullableThe phrases of a plain-language search this property matched; null for structured searches.
totalintegernullableHow many properties match, when known.
nextstringnullableURL of the next page (valid one hour), or null.
Example with sample values (ids and figures are illustrative) (long arrays shortened)
{
"results": [
{
"id": "prop_2Lm9xQ4rT6vB1nC8kD5wZa",
"type": "villa",
"operation": "sale",
"price": {
"amount": 870000,
"currency": "EUR",
"per_sqm": 4142
},
"bedrooms": 4,
"living_area_sqm": 210,
"location": {
"id": 12345,
"name": "Sample town",
"coordinates": {
"lat": 36.51,
"lon": -4.88
}
},
"first_seen": "2026-08-14",
"listings_count": null,
"matched_tags": [
"close to the beach",
"sea views"
]
}
],
"total": 48,
"next": "https://platform.casafari.com/v1/property-sourcing/searches/cur_SAMPLE"
}400 Invalid request: the problem names each field to fix (`invalid_request`).
Type: object.
Show the response shape (10 fields)
typestringThe problem's documentation URL.
titlestringstatusintegerdetailstringWhat happened and how to fix it.
instancestringcodestringe.g. invalid_request, payment_required, not_entitled, not_found, page_depth_exceeded, request_limit_reached.
request_idstringerrorsobject[]One entry per field to fix.
2 properties
fieldstringmessagestring401 Missing or unknown API key or token.
Type: object.
Show the response shape (10 fields)
typestringThe problem's documentation URL.
titlestringstatusintegerdetailstringWhat happened and how to fix it.
instancestringcodestringe.g. invalid_request, payment_required, not_entitled, not_found, page_depth_exceeded, request_limit_reached.
request_idstringerrorsobject[]One entry per field to fix.
2 properties
fieldstringmessagestring402 No units left to fund the call (`payment_required`).
Type: object.
Show the response shape (10 fields)
typestringThe problem's documentation URL.
titlestringstatusintegerdetailstringWhat happened and how to fix it.
instancestringcodestringe.g. invalid_request, payment_required, not_entitled, not_found, page_depth_exceeded, request_limit_reached.
request_idstringerrorsobject[]One entry per field to fix.
2 properties
fieldstringmessagestring403 The account is not entitled to this product or country (`not_entitled`).
Type: object.
Show the response shape (10 fields)
typestringThe problem's documentation URL.
titlestringstatusintegerdetailstringWhat happened and how to fix it.
instancestringcodestringe.g. invalid_request, payment_required, not_entitled, not_found, page_depth_exceeded, request_limit_reached.
request_idstringerrorsobject[]One entry per field to fix.
2 properties
fieldstringmessagestring429 A request limit of the plan was reached (`request_limit_reached`).
Type: object.
Show the response shape (10 fields)
typestringThe problem's documentation URL.
titlestringstatusintegerdetailstringWhat happened and how to fix it.
instancestringcodestringe.g. invalid_request, payment_required, not_entitled, not_found, page_depth_exceeded, request_limit_reached.
request_idstringerrorsobject[]One entry per field to fix.
2 properties
fieldstringmessagestring