Best Match

Older names redirect here, permanently

Both old names keep working, permanently. /market-scan and /cheapest-listing return 308 Permanent Redirect to /best-match, and so do their /api/modules/... paths, sub-paths such as /manifest included.

The redirect is a contract, stated precisely: 308 preserves the method and the query string (your POST stays a POST, your ?q= arrives intact); both old names redirect directly here, never through each other; and /.well-known/agent.json keeps both former names as deprecated-alias keys, each listing its canonical endpoint — so an agent holding a year-old URL keeps working and can discover the new name. That is a permanent commitment, not a transitional courtesy.

Why price ranking does not exist

The catalogue does not verify the currency unit at ingest, and the precise shape of that failure is worse than a missing field: the currency column is populated with a default stamped at write time, not a measurement. Across markets whose price levels differ by orders of magnitude, that means local-currency figures wearing one shared label.

So a stored price is a raw number whose stated unit cannot be trusted. Sorting those numbers ascending produces a beautifully ordered list that is not a price ranking, because 200 of one currency and 200 of another are not the same quantity of money, and the field that claims to say which is which is a default rather than a measurement.

That sort could have shipped anyway. It would have looked correct, it would have been wrong in a way almost nobody would notice, and the agents worst affected would be the ones trusting it most. So the module reports price_ranking_available: false on every call, orders by recency, and drops the currency field from every row it returns rather than passing on a value it cannot stand behind. Ascending price ranking returns when currency is genuinely captured and verified at ingest, and not before.

How matching works

Two passes. Pass one takes title matches, highest relevance, filled first. Pass two takes description matches, filling the remaining slots up to ten. Position in the list therefore encodes something real: everything above the boundary matched a title, everything below matched only body text, and a title match is the stronger signal about what a listing actually is — descriptions mention things they are not selling. q is required; blank or missing returns 400 rather than everything. Ten results per call, ten unconfirmed-price entries per call. Public, no key required, no CAPTCHA.

The price = 0 rows, and why they are returned separately

Some rows carry price = 0. That is not a free item — it is a known write-time normalisation fault in the scraper, and the true price is unknown. These rows are not included in results. They come back in a separate array, unconfirmed_price_listings, each carrying price_status: "not_stated" and no currency field at all, with a count in unconfirmed_count. The separation is the whole point: mixed into the main results a zero reads as free, and an agent optimising for price would sort straight to the broken rows every time — the single most expensive failure this module could produce. Kept apart and labelled, the same rows are useful, being real listings whose price you must obtain another way.

Freshness — the fields to read before acting

This is a catalogue snapshot, not a live feed, and the response says how good a snapshot it is. is_stale is true when the newest organic result is older than seven days. result_max_listed_at and result_min_listed_at give the newest and oldest organic listing in this result set; market_max_listed_at breaks that down per market; freshness_caveat says the same thing in a sentence; and catalogue_max_listed_at with catalogue_age_days give background context about the whole catalogue.

One warning the manifest makes explicitly and this page repeats: do not key freshness decisions off catalogue_max_listed_at. The catalogue as a whole may contain something recent while your particular result set is a year old. result_max_listed_at describes the answer you are actually holding; the other describes a room you did not search. An agent that reads results and ignores freshness will confidently act on a listing that expired months ago. The fields exist so that never has to happen, and they cost nothing to read.

What is excluded, and what is labelled

House listings are excluded entirely: any listing whose seller contact is a @defici.com address is filtered out of every result. The platform does not put its own inventory into an agent's search results, ever — a search surface that quietly promotes its owner's rows is not a search surface. Partner listings are labelled rather than hidden: a genuine listing with a real seller contact but no market attribution comes back with placement: "partner" and is excluded from the freshness figures, because its date cannot be compared to organic inventory on the same basis. You get it, and you get told what it is. Two rules, one principle: nothing is inserted into your results because it benefits us, and nothing that reaches you is unlabelled.

The honest limits

• No price ranking. The biggest one, for the reason above.
• Ten results. There is no deep pagination here. For bulk, use GET /api/ads or the bulk feeds at feed.json / feed.csv.
• A snapshot, not a feed. No live refresh happens because you searched.
• The catalogue has no ingest schedule. Rows are as fresh as the last time they were gathered — which is why the freshness fields exist and are not decoration.
• Search is keyword, not semantic. A synonym will not find your term. Query the words a seller would have written, not the words you would have.

Stated on this page, not yet enforced in code

Ascending price ranking is blocked on currency capture at ingest, and reports price_ranking_available: false on every response until then. Semantic and synonym matching does not exist — matching is keyword-only and two-pass. Regular catalogue refresh does not exist either; there is no ingest schedule. Everything else described above — two-pass matching, the ten-result limit, unconfirmed-price separation, the full freshness block, house exclusion, partner labelling and the permanent redirects — is live code. This paragraph exists so the gap between what a page claims and what a system does is stated by us rather than discovered by you.

Six lines, if you read nothing else

1. The old name promised a price sort that does not exist. The name changed — twice — and every old name still 308s straight here, permanently, method and query intact.
2. No price ranking. The currency field is a write-time default, not a measurement — so this module drops it rather than repeat it.
3. Title matches come first, description matches after. Position in the list means something.
4. price = 0 means unknown, not free. Those rows are returned separately and labelled.
5. Read result_max_listed_at, never catalogue_max_listed_at. One describes your answer; the other describes the room.
6. Our own listings are excluded from your results. Partner listings are labelled. Nothing reaches you unmarked.