Home API Documentation Similar Properties

Similar Properties

Last updated on Dec 06, 2025

Similar Properties API

Find properties similar to a specific property based on type, location, bedrooms, and price range. Perfect for "You may also like" features and property comparison tools.

Endpoint

GET /properties/:id/similar

Authentication

Required. All API requests must be authenticated using your API key. See the Authentication section in the API Overview documentation.

Path Parameters

Parameter Type Required Description id string (UUID) Yes The unique identifier of the reference property

Query Parameters

Parameter Type Description Default limit number Maximum number of similar properties to return (1-100) 5 filterByOrganization boolean Only return properties from your organization false includeBranding boolean Include organization branding information false includeAdCount boolean Include count of active ads for each property false includeAdCreatives boolean Include ad creative details (max 3 most recent per property) false

How Similarity Works

The API finds similar properties using the following criteria:

  1. Same Property Type - Matches exact property type (e.g., apartment, villa)

  2. Same Property Category - Matches category (residential, commercial, etc.)

  3. Similar Location - Same city OR same community

  4. Similar Bedrooms - Within ±1 bedroom (e.g., 2-4 bedrooms for a 3-bedroom property)

  5. Similar Price - Within ±25% of the reference property price

  6. Active Status - Only returns active listings (by default)

  7. Excludes Reference - Never returns the reference property itself

Results are ordered by most recently published first.

Response

Success Response (200 OK)

Returns an array of similar property objects:

Error Responses

404 Not Found

401 Unauthorized

400 Bad Request

Example Requests

Basic Request (5 Similar Properties)

Request More Results

With Branding and Ad Information

Similar Properties from Same Organization

Code Examples

JavaScript/TypeScript

Python

PHP

Use Cases

1. "You May Also Like" Section

Display similar properties on a property detail page:

2. Property Comparison Tool

Allow users to compare similar properties:

3. Alternative Suggestions

When a property becomes unavailable, suggest alternatives:

4. Cross-Selling Within Organization

Show other properties from your organization:

5. Email Marketing

Generate property recommendations for email campaigns:

Tips and Best Practices

  1. Adjust Limit Based on UI:

    • 3-4 for carousel displays

    • 6-8 for grid layouts

    • 10+ for list views or dedicated "similar properties" pages

  2. Handle Empty Results: There may be no similar properties if:

    • The property is very unique

    • It's in a location with few other properties

    • The price range is extreme

    • Consider falling back to a broader search

  3. Combine with Favorites: Show similar properties to items users have favorited

  4. Performance: Similar properties queries are fast since they use indexed fields

  5. Organization Filtering: Use filterByOrganization=true to:

    • Cross-sell within your portfolio

    • Avoid showing competitor properties

    • Keep users within your ecosystem

  6. Caching: Consider caching similar properties for a few hours to reduce API calls

  7. No Pagination: The similar properties endpoint returns all results up to the limit (no page parameter needed)

Similarity Algorithm Details

The matching criteria in priority order:

  1. Must Match:

    • Property type (exact match)

    • Property category (exact match)

    • Status = active (unless specified otherwise)

    • Not the same property

  2. Should Match (at least one):

    • Same city OR same community

    • Bedrooms within ±1

    • Price within ±25%

  3. Sorting:

    • Most recently published first

Example Similarity Calculation

For a reference property:

  • Type: Apartment

  • Category: Residential

  • City: Dubai

  • Community: Dubai Marina

  • Bedrooms: 3

  • Price: 1,500,000 AED

Similar properties will match:

  • Type: Apartment ✓

  • Category: Residential ✓

  • City: Dubai OR Community: Dubai Marina ✓

  • Bedrooms: 2, 3, or 4 ✓

  • Price: 1,125,000 - 1,875,000 AED ✓