Find properties that are similar to a specific listing. This is useful for "you might also like" sections on property detail pages.

Endpoint

GET /properties/:id/similar

Authentication: Required (API key or JWT)

How It Works

Similarity is determined using OpenSearch's "more like this" feature, which analyzes property descriptions and characteristics to find the closest matches.

Path Parameters

| Parameter | Type | Description | |-----------|------|-------------| | id | UUID | The ID of the reference property to find similar listings for |

Query Parameters

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | limit | number | 5 | Maximum number of similar properties to return | | filterByOrganization | boolean | false | Only return properties from your organization | | includeBranding | boolean | false | Include organization branding data | | includeAdCount | boolean | false | Include ad creative count per property | | includeAdCreatives | boolean | false | Include full ad creative data |

Example

curl "https://api.leadhql.com/properties/a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/similar?limit=4" \
  -H "Authorization: Bearer leadhql_pk_abc123"

Response

Returns an array of property listing objects, ordered by similarity:

[
  {
    "id": "f1e2d3c4-...",
    "referenceNumber": "HQL-54321",
    "listingType": "sale",
    "propertyType": "villa",
    "city": "Marbella",
    "countryCode": "ES",
    "price": 1350000,
    "currency": "EUR",
    "bedrooms": 4,
    "bathrooms": 3,
    "hasPool": true,
    "status": "active",
    ...
  },
  ...
]

Errors

| Status | Condition | |--------|-----------| | 400 | Invalid UUID format for property ID |

Similar Properties