Search Properties

Search Properties API

Search and filter property listings using various criteria including natural language queries, structured filters, and geospatial searches.

Endpoint

Authentication

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

Query Parameters

Parameter Type Description Default filterByOrganization boolean Filter results to only your organization's properties 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) false

Request Body

The request body supports extensive filtering options. All fields are optional.

Natural Language Query

The query field supports:

• Natural language searches

• Automatic extraction of numeric values (bedrooms, bathrooms, price)

• Property features (pool, garden, terrace, etc.)

• Location matching

• Reference number lookup

Structured Filters

Property Filters

Field Type Description Example query string Natural language or keyword search "luxury penthouse sea view" status string[] Filter by listing status ["active", "pending"] propertyType string[] Filter by property type ["apartment", "penthouse"] propertyCategory string[] Filter by category ["residential"]

Numeric Range Filters

Each range filter accepts min and/or max values:

Feature Filters

Geospatial Filters

Option 1: Circular Radius Search

Distance formats: "10km", "5mi", "2000m"

Option 2: Bounding Box (Map View)

Note: Bounding box takes precedence over location if both are provided.

Sorting

Available sort fields: price, bedrooms, bathrooms, livingArea, publishedAt, createdAt, updatedAt

Pagination

• page: Page number (1-indexed), default: 1

• limit: Items per page (1-100), default: 20 for list view, 1000 for map view

Price Distribution

Request price histogram data for filters/charts:

Response

Success Response (200 OK)

Response Fields

Conditional Fields

These fields are only included based on query parameters:

• agent: Included when includeAdCount=true or includeAdCreatives=true (if property has an agent)

• adCount: Included when includeAdCount=true

• adCreatives: Included when includeAdCreatives=true (max 3 most recent)

• organizationBranding: Included when includeBranding=true

• clerkOrganizationId: Included when includeBranding=true

• priceDistribution: Included when priceDistribution is in request body

Error Responses

401 Unauthorized

400 Bad Request

Example Requests

Basic Search - All Active Properties

Search with Natural Language Query

Advanced Filter Search

Map View Search (Bounding Box)

Organization's Properties with Branding

Search with Price Distribution

Code Examples

JavaScript/TypeScript

Python

PHP

Tips and Best Practices

1. Use Natural Language Queries: The query field is powerful and can understand natural language like "3 bedroom villa with pool under 2 million"

2. Optimize for Performance:

   • Only request includeBranding and includeAdCreatives when needed

   • Use pagination for large result sets

   • Use bounding box for map views (higher default limit)

3. Geospatial Search:

   • Bounding box is more efficient for map views

   • Location radius is better for "near me" searches

   • Distance can be specified in km, mi, or m

4. Filter by Organization:

   • Use filterByOrganization=true to show only your properties

   • Omit it (or set to false) to search all properties for public-facing listings

5. Price Distribution:

   • Useful for creating price range filters/sliders in your UI

   • The API automatically calculates appropriate intervals if not specified

6. Sorting:

   • Default sort is by publishedAt DESC (newest first)

   • Multiple sort fields are supported and applied in order