Search Properties

OverviewCopy Anchor Link

Paginated property search with comprehensive filtering, sorting, and optional map markers. When includeMarkers is true, the backend runs a single pipeline execution and returns both the scored top-N results for the list view and lean map markers for all matching properties, reducing round-trips compared to separate search and map calls.

This is the primary search endpoint for Journey's property discovery experience.

AuthenticationCopy Anchor Link

Requires a valid Clerk JWT token in the Authorization header.

Request BodyCopy Anchor Link

curl -X POST "http://localhost:3000/v1/members/properties/search" \
  -H "Authorization: Bearer YOUR_CLERK_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 20,
    "offset": 0,
    "sort": "recommended",
    "includeMarkers": true,
    "dates": {
      "checkIn": "2024-06-15",
      "checkOut": "2024-06-17"
    },
    "location": {
      "city": "New York",
      "state": "NY",
      "country": "US"
    },
    "priceRange": {
      "min": 30000,
      "max": 100000
    },
    "guestRating": 4.0,
    "amenities": ["pool", "spa"],
    "propertyTypes": ["hotel", "resort"]
  }'

ResponseCopy Anchor Link

Returns a paginated list of properties matching the search criteria, with optional map markers.

{
  "items": [
    {
      "id": 123,
      "documentId": "prop_manhattan_boutique_hotel",
      "name": "Manhattan Boutique Hotel",
      "brandName": "Journey Urban Collection",
      "type": "Hotel",
      "baseRoomCategory": "Deluxe Room",
      "nightlyCost": 45000,
      "guestRating": 4.6,
      "maxGuests": 4,
      "address": {
        "city": "New York",
        "state": "NY",
        "country": "United States",
        "latitude": 40.7128,
        "longitude": -74.0060
      },
      "heroImage": {
        "url": "https://cdn.example.com/hotels/manhattan-boutique.jpg",
        "alt": "Manhattan boutique hotel exterior"
      },
      "amenities": ["WiFi", "Fitness Center", "Pool", "Spa", "Restaurant"],
      "tags": ["business", "luxury", "urban"]
    }
  ],
  "total": 245,
  "limit": 20,
  "offset": 0,
  "markers": [
    {
      "id": 123,
      "latitude": 40.7128,
      "longitude": -74.0060,
      "nightlyCost": 45000
    }
  ],
  "searchViewport": {
    "bounds": {
      "north": 40.8176,
      "south": 40.6829,
      "east": -73.9442,
      "west": -74.0859
    }
  }
}

Search BehaviorCopy Anchor Link

Unified PipelineCopy Anchor Link

When includeMarkers=true, the backend executes a single search pipeline with a limit of 3000 properties, then:

1. Returns the top-N scored results for the list view (based on requested limit/offset)
2. Provides lean map markers for all 3000 matching properties
3. Includes a suggested viewport for the map display

Scoring and RankingCopy Anchor Link

The search uses a sophisticated scoring algorithm that considers:

• Relevance: Match to search criteria and location
• Member preferences: Based on profile and search history
• Property quality: Guest ratings and amenity scores
• Availability: Real-time availability for requested dates
• Pricing: Competitive pricing within the member's range

PersonalizationCopy Anchor Link

Search results are personalized using a user seed based on the member ID, ensuring:

• Consistent ranking across pagination
• Personalized recommendations
• A/B testing capabilities
• Privacy-compliant personalization

Related EndpointsCopy Anchor Link

• Search Hydrate - Bulk property enrichment by IDs
• Get Suggestions - Location autocomplete
• Get Filters - Available filter options