Search for property listings using text queries, structured filters, geographic search, and sorting.

Endpoint

POST /properties/search

Authentication: Required (API key or JWT)

Query Parameters

These are passed as URL query parameters, not in the request body.

Parameter	Type	Default	Description
`filterByOrganization`	boolean	`false`	When `true`, only return properties belonging to your organization
`includeBranding`	boolean	`false`	Include organization branding settings in results
`includeAdCount`	boolean	`false`	Include ad creative count per property
`includeAdCreatives`	boolean	`false`	Include full ad creative data per property

Request Body

All fields are optional. An empty body {} returns all properties with default pagination.

Text Search

Field	Type	Description
`query`	string	Natural language text search. Supports queries like `"3 bedroom villa with pool in Dubai Marina"` or structured field:value syntax like `"bedrooms:3 AND hasPool:true"`

ID Filter

Field	Type	Description
`ids`	string[]	Fetch specific properties by their UUIDs. When provided, other filters still apply but progressive filter relaxation is skipped. Useful for batch-fetching a known set of properties.

Array Filters

Each accepts a single value or an array of values to match against.

Field	Type	Values
`propertyType`	string[]	`apartment`, `condominium`, `house_detached`, `house_semi_detached`, `house_terraced`, `townhouse`, `multi_family_home`, `penthouse`, `studio`, `land_residential`, `land_commercial`, `land_agricultural`, `land_other`, `office`, `retail`, `commercial_other`, `industrial_warehouse`, `industrial_other`, `hospitality`, `other`
`propertyCategory`	string[]	`residential`, `commercial`, `industrial`, `land`
`listingType`	string[]	`sale`, `rent`, `sale_or_rent`, `fraction`
`countryCode`	string[]	ISO 3166-1 alpha-2 codes (e.g., `ES`, `AE`, `US`)
`region`	string[]	Region names (e.g., `Costa del Sol`, `Dubai`)
`city`	string[]	City names (e.g., `Marbella`, `Dubai Marina`)
`status`	string[]	`active`, `inactive`, `pending`, `sold`, `rented`, `deleted`

Range Filters

Each range filter is an object with optional min and max fields.

Field	Type	Description
`bedrooms`	`{ min?, max? }`	Number of bedrooms
`bathrooms`	`{ min?, max? }`	Number of bathrooms
`price`	`{ min?, max? }`	Price in the property's currency
`livingArea`	`{ min?, max? }`	Living area in the property's area unit
`plotArea`	`{ min?, max? }`	Plot area in the property's area unit
`commission`	`{ min?, max? }`	Agent commission percentage (0–100)

Feature Filters

Nest these inside a features object. Each is a boolean.

Field	Type	Description
`hasPool`	boolean	Swimming pool
`hasSeaView`	boolean	Sea or ocean view
`hasGarage`	boolean	Garage or covered parking
`hasTerrace`	boolean	Terrace or balcony
`hasGarden`	boolean	Garden
`isFurnished`	boolean	Comes furnished
`hasAirConditioning`	boolean	Air conditioning
`hasLift`	boolean	Elevator / lift

Geographic Filters

Use one of these — not both.

Radius search (location):

Field	Type	Required	Description
`location.lat`	number	Yes	Latitude of center point
`location.lon`	number	Yes	Longitude of center point
`location.distance`	string	No	Search radius (default: `"10km"`)

Bounding box (boundingBox):

Field	Type	Required	Description
`boundingBox.northEast.lat`	number	Yes	North-east corner latitude
`boundingBox.northEast.lon`	number	Yes	North-east corner longitude
`boundingBox.southWest.lat`	number	Yes	South-west corner latitude
`boundingBox.southWest.lon`	number	Yes	South-west corner longitude

Sorting

Use either the sort array or the flat sortBy/sortOrder fields.

sort array:

{
  "sort": [{ "field": "price", "order": "asc" }]
}

Flat fields:

Field	Type	Description
`sortBy`	string	Sort field name
`sortOrder`	`"asc"` or `"desc"`	Sort direction (default: `desc`)

Allowed sort fields: price, createdAt, updatedAt, publishedAt, bedrooms, bathrooms, livingArea, plotArea, commission, yearBuilt, city, countryCode, referenceNumber, status, propertyType, propertyCategory, listingType

Pagination

Field	Type	Default	Description
`page`	integer	`1`	Page number (1-indexed)
`limit`	integer	`20`	Results per page (1–100)

Price Distribution

Request histogram data for building price range charts.

Field	Type	Default	Description
`priceDistribution.interval`	number	`50000`	Bucket size
`priceDistribution.min`	number	—	Minimum price for distribution
`priceDistribution.max`	number	—	Maximum price for distribution

Response

{
  "results": [
    {
      "id": "a1b2c3d4-...",
      "referenceNumber": "HQL-12345",
      "listingType": "sale",
      "propertyCategory": "residential",
      "propertyType": "villa",
      "city": "Marbella",
      "countryCode": "ES",
      "price": 1250000,
      "currency": "EUR",
      "bedrooms": 4,
      "bathrooms": 3,
      "livingArea": 320,
      "hasPool": true,
      "hasSeaView": true,
      "status": "active",
      ...
    }
  ],
  "total": 142,
  "priceDistribution": {
    "interval": 50000,
    "minPrice": 200000,
    "maxPrice": 5000000,
    "buckets": [
      { "key": 200000, "count": 5 },
      { "key": 250000, "count": 12 },
      ...
    ]
  },
  "relaxedFilters": ["bedrooms"]
}

Field	Type	Description
`results`	array	Array of property listing objects
`total`	number	Total matching properties (for pagination)
`priceDistribution`	object	Only present if `priceDistribution` was included in the request
`relaxedFilters`	string[]	If the search returned few results, lists which filters were progressively relaxed to find more matches

Examples

Basic Search

curl -X POST https://api.fondaro.com/properties/search \
  -H "Authorization: Bearer fondaro_pk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "villa with pool in Marbella",
    "limit": 10
  }'

Filtered Search

curl -X POST https://api.fondaro.com/properties/search \
  -H "Authorization: Bearer fondaro_pk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "propertyType": ["villa", "townhouse"],
    "listingType": ["sale"],
    "countryCode": ["ES"],
    "price": { "min": 500000, "max": 2000000 },
    "bedrooms": { "min": 3 },
    "features": {
      "hasPool": true,
      "hasSeaView": true
    },
    "sort": [{ "field": "price", "order": "asc" }],
    "page": 1,
    "limit": 20
  }'

Geo Radius Search

curl -X POST https://api.fondaro.com/properties/search \
  -H "Authorization: Bearer fondaro_pk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "location": {
      "lat": 36.5101,
      "lon": -4.8824,
      "distance": "5km"
    },
    "propertyType": ["apartment"],
    "limit": 20
  }'

Batch Fetch by IDs

curl -X POST "https://api.fondaro.com/properties/search?includeBranding=true" \
  -H "Authorization: Bearer fondaro_pk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "b2c3d4e5-f6a7-8901-bcde-f12345678901"
    ]
  }'

Organization Properties with Branding

curl -X POST "https://api.fondaro.com/properties/search?filterByOrganization=true&includeBranding=true" \
  -H "Authorization: Bearer fondaro_pk_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "status": ["active"],
    "sort": [{ "field": "createdAt", "order": "desc" }]
  }'

Search Properties