F-020: Similar Listings

Status: Done · Priority: P2 · Branch: feature/F-020-similar-listings · Updated: Mar 5, 2026

Summary

Show similar/related listings on the listing detail page. Uses a simple weighted scoring formula based on bedrooms, price proximity, and geographic distance. No vector embeddings or AI — pure SQL scoring.

Requirements

• [x] API: GET /listings/:id/similar?limit=6 endpoint
• [x] Frontend: "Similar Listings" section at bottom of detail page
• [x] Bilingual translations (EN/FR)
• [x] Documentation updates

Design

Scoring Formula

Three signals, all scored 0–1, then weighted:

Signal	Weight	Scoring
Bedrooms	40	Same = 1.0, ±1 = 0.5, ±2+ = 0
Price	35	1 - (price_diff / reference_price), clamped to 0. Within 30% = good match
Distance	25	1 - (km / 10), clamped to 0. Within 10km = some score, same block = max

Final score = (bedrooms × 40) + (price × 35) + (distance × 25), max 100.

Minimum threshold: score > 20 (skip section if no decent matches).

API

GET /listings/:id/similar?limit=6

Returns { listings: ListingSummary[] } — same shape as browse endpoint, reuses listing card component.

Filters: active listings only, excludes the current listing.

Frontend

Grid of 4-6 listing cards below the main detail content. Uses existing ListingCard component. Hidden if no similar listings found.

Discussion Notes

Mar 5, 2026

• Feature created. Simple formula approach — no vectors/embeddings.
• Excluded amenities and property type from scoring for now — can add later.
• Three signals: bedrooms (most important), price proximity, geographic distance.

Implementation Notes

To be added.