Free-text vibe search over property embeddings
Phase 7 of the semantic-search roadmap: the Hero homepage fallback for queries that don't route to a place or a structured feature.
The query is normalised and embedded (text-embedding-3-small, Redis-cached for 24 h), then cosine-ranked against properties.embedding with a permissive similarity floor. The response shape mirrors /categories/{slug}/parks and /properties/{id}/similar: a SuccessPayload whose data is a list of expanded GeoJSON features.
Fail-open semantics:
- Empty q → 200 + empty list (not 400, so the frontend can safely call this with a loading-state query).
- OpenAI outage → 200 + empty list (service degrades; the Hero falls back to rendering the same "no parks match" banner as a genuine zero-match result).
- DB vector error → 200 + empty list.
Request
- Base URL: http://localhost:8000
- URL: http://localhost:8000/properties/vibe-search
- Auth: none declared
Query parameters
Free-text vibe query. Empty string returns 200 + empty list (fail-open for misuse).
Maximum number of parks to return (1-24). Defaults to 12.
ISO country code used to scope public property inventory.
Headers
Major API version. Omit or send 1 for the current v1 surface. Retired operations use RFC 9745 Deprecation and RFC 8594 Sunset headers.
Response
Successful Response
Changes
No recorded changes to this operation across all 1 revision of this API.