REST API
crates/farnsworth-server - the graduation step past farnsworth-cli serve's stdin/stdout REPL: queryable from curl/a browser/another service over real HTTP, not just a local terminal. Built on axum (already had tokio as an unused workspace dependency - this put it to use).
No auth, no rate limiting, no TLS, no write endpoints - matches this project's standing read-only, learning-project boundary (see index.md), not a deployable service.
Running it
farnsworth-server <index-dir> [port] # opens <index-dir>/{poi,localities,geocode}, default port 8080
Opens all three persisted indices once at startup (~21s at full world scale - world-index-v3's real measured time), then serves on 127.0.0.1:8080. farnsworth-cli build now also builds and persists the localities index alongside poi/geocode (it previously only built two of the three - LocalitiesIndex::build_persistent existed in code but nothing called it until this item).
Endpoints
GET /autocomplete
The merged POI+locality+address search (see world-scale.md) - "kind" can be "poi", "locality", or "address".
| Param | Meaning |
|---|---|
q |
required, the query text |
lat, lon |
optional bias point |
radius_km |
geo filter radius, POI side only. <= 0.0 (including the field's own default when omitted) no longer means "no hard cutoff" - it falls back to a real bound, MAX_BIAS_RADIUS_KM = 50.0, same as an explicit radius that exceeds it. A POI outside that radius is still excluded unless it's popular enough to bypass the cap entirely - see below |
distance_skew |
proximity skew (POI side only) |
popularity_skew |
popularity skew (POI side only) |
country_codes |
comma-separated, e.g. fr,gb |
include_sub_types / exclude_sub_types |
comma-separated |
limit |
default 10 |
curl "http://127.0.0.1:8080/autocomplete?q=restaurant&country_codes=fr&limit=10"
Response shape (one hit):
{
"kind": "address",
"public_id": "address:fr::n3akJXtyXwatCwZ3sISQ/kmBd4w=",
"name": "Rue de la Paix",
"formatted_address": "Rue de la Paix, 75002 Paris, France",
"location": { "lat": 48.868546, "lon": 2.33031 },
"text_score": 1.0,
"kind_priority": 1.0
}
"formatted_address" is built from real structured data, not name alone: address hits add postal_code/locality (both imported straight from the source parquet, not derived from context/full_indexed_string - that field is a search-indexing artifact whose format varies by country and gets padded with literal " §" tokens when short, confirmed by reading full_indexed_string.py directly, so an earlier attempt to reuse it for display text was reverted) plus a country name resolved from the public_id's embedded ISO code via rust_iso3166 (country_name_from_public_id in geocode.rs). POI/locality hits currently just echo name.
"kind" is always exactly "poi", "locality", or "address" - a fixed, tested string constant (MergedKind::as_str()), not format!("{:?}", ...). That distinction matters for real client code: Debug output happens to look the same today, but it's Rust's own type-name formatting, not a contract - a future internal rename could silently change what a client parses, with no compile error to catch it. Both /autocomplete and /details derive "kind" from the same as_str(), so the two endpoints can't drift out of sync with each other either.
"location" is null only when the underlying record genuinely has no location (rare) - not withheld just because no bias point was passed. Real integration feedback surfaced this: coordinates were entirely missing from every response before this, on both the POI side (data existed internally, just never serialized) and the locality side (never imported from the source data at all - see localities.md).
Real, verified limitation - country_codes/include_sub_types/exclude_sub_types only filter the POI side of the merged pool. Neither LocalitiesIndex nor GeocodeIndex takes SearchFilters at all (that item was scoped to POI search specifically - see support-country-and-type-filtering-in-poi-search in the roadmap). Confirmed against real data: ?q=restaurant&country_codes=fr correctly narrows every poi-kind hit to poi:fr:* public_ids, while locality/address-kind hits are returned unfiltered regardless of country_codes. Not a bug in the sense of doing the wrong thing - it does exactly what's implemented - but a real gap a caller needs to know about, not silently glossed over. Extending filtering to the other two indices is a natural future item, not done here.
Fixed - POI results no longer get silently crowded out. Found via real testing, not a unit test: "stonehenge" used to return a 30-result pool of unrelated localities with ZERO of the real Stonehenge POI, even though it genuinely matched (/details could always find it directly). Root cause: kind_priority's real magnitude gap (locality up to 100 vs POI's flat 2) made the old plain sort-then-truncate a near-total override, not a tie-break. Fixed with a reserved-slot allocation - each kind now gets at least half of limit when both have real candidates (see world-scale.md). "stonehenge" now returns 22 poi + 8 locality out of 30.
Real, POI-side-only recall constraints a caller needs to know about, not just an internal implementation detail (previously only documented in world-scale.md):
- No lat/lon given: a POI needs popularity > 5 (the real p90 across the full corpus) to be reachable at all. Keeps generic/chain POIs out of a worldwide, unbiased search, but means a genuinely small/local POI (any address or locality is unaffected) simply won't appear without a bias point, no matter how well it matches the query text.
- lat/lon given: a POI within the 50km radius is always reachable regardless of popularity, same as before. A POI outside the radius is excluded unless it clears a real, much higher bar - popularity > 22 (real p99.99, ~1,338 POIs worldwide - landmark-tier: Stonehenge, Buckingham Palace, Westminster Abbey, the real Eiffel Tower at 72). This is deliberately not the same threshold as the no-bias floor above: reusing > 5 here let ordinary chain branches (e.g. real Europcar locations, popularity up to 9) bypass the radius and flood back in from anywhere in the world - a real regression caught via live testing before this was documented, fixed by giving the two cases separate, independently-justified real floors (NO_BIAS_POPULARITY_FLOOR vs RADIUS_BYPASS_POPULARITY_FLOOR in crates/farnsworth-core/src/lib.rs).
- A single /autocomplete call now finds both "famous places anywhere" (via the popularity bypass) and "small local places near me" (via the radius) at once - a caller does NOT need two parallel calls merged client-side for this. q=tour+eiffel&lat=<montpellier>&lon=<montpellier> correctly returns the real Eiffel Tower (~750km away) alongside genuinely local Montpellier results, verified live against the real index.
Known gap, not yet fixed - the JSON response never exposes distance_km, only location. A client wanting "X km away" has to compute it itself from location and its own bias point, even though search() already computes it internally when a bias point is given.
Fixed - the overfetch window no longer costs every query the same. search() overfetches a real BM25-ranked candidate pool before re-ranking it by the ported fuzzy algorithm (see ranking.md) - a flat (limit*100).max(2000) was paid even by a single-token query like q=paris, even though the 2000 figure was only ever justified by a 5-token adversarial case ("rue de la paix paris" needing that large a pool before its true best match, excluded from BM25's own top ranks by an unrelated decoy's EXACT_MATCH_BOOST, was even reachable). ranking::overfetch_window(limit, token_count) now scales the floor down for short queries (1 token -> 100, 2 -> 500, 3+ -> 2000, still .max(limit*100)) - real measured effect, same running index: ?q=paris&limit=8&popularity_skew=1 dropped from ~250ms to ~170ms, with the 5-token decoy case and the radius-bypass regression tests unaffected.
Known gap, not yet fixed - distance_skew only affects POI ordering. locality/address hits in the merged pool are not sorted or filtered by proximity to a bias point at all, even when one is given - a locality/address hit's position is decided purely by (text_score, kind_priority). Within the POI side's 50km cap, ordering is also not strictly nearest-first: distance_skew (when set) linearly discounts score by distance, it doesn't hard-sort by it, so a farther-but-more-textually-relevant POI can still outrank a closer one.
GET /details/{id}
Exact lookup by public_id. Checks PoiSearchIndex first, then LocalitiesIndex. 404 if neither has it. Response includes "kind"/"location" with the same shape and stability guarantees as /autocomplete above, plus "type_boost" for locality results.
curl "http://127.0.0.1:8080/details/locality:fr:city:fzeHfrgd2PzHDM3Beq46U2%2FzE0o="
GET /geocode?q=...
Forward geocode (GeocodeIndex::geocode) - street number parsing + interpolation. 404 with {"error": "no match"} when nothing resolves.
GET /reverse_geocode?lat=...&lon=...
Nearest known address to a point (GeocodeIndex::reverse_geocode).
Real-data verification
All four endpoints run against the real full-scale world-index-v3 (13.9M POIs, 8.8M localities, 9.3M streets):
/autocomplete?q=paris&limit=5- all 5 hits are genuine "Paris"/"París" localities (admin-level Paris entries outrank the city onkind_priority, matching production's own real weighting - see world-scale.md), each with real, distinct, geographically correct coordinates (e.g. FR Paris at48.859052, 2.320082, Puerto Rico's "París" at18.049218, -67.10347)./autocomplete?q=restaurant&country_codes=fr&limit=20- POI hits correctly narrowed topoi:fr:*(wereid/ie/inunfiltered); locality hits correctly unaffected (the documented limitation above, verified not assumed)./details/{a real locality public_id}- correct name,location, andtype_boostreturned; unknown id correctly404s./details/{a real POI public_id}(Stonehenge) -"kind": "poi", real coordinates51.178829, -1.826183./geocode?q=route+de+nantes- resolves street-only, correct real coordinates./reverse_geocode?lat=48.8566&lon=2.3522(Paris) - "Place de l'Hôtel de Ville-esplanade de la Libération", 0.017km away - the same real result the CLI REPL proved earlier in world-scale.md, now reachable over HTTP.
Real integration feedback that drove this
Someone actually wiring a proxy in front of the real search box reported: "Farnsworth isn't ready to power the search box yet: it lacks coordinates, has a weak/missing POI index, no proximity bias, and shaky geocoding, though reverse geocoding works well." Verified against the code, not taken on faith, and fixed the concrete, actionable part: location is now real on every response that has one. "Weak/missing POI index" and "no proximity bias" were downstream symptoms of the same root cause (kind_priority swamping POI results, with no locality coordinate to bias by even if a caller wanted to) - location being real now is what makes a client-side proximity feature possible at all, even though Farnsworth itself still applies no automatic bias. "Shaky geocoding" is a separate, already-documented, still-open limitation (FR-schema-centric interpolation, a simple leading/trailing number heuristic, not a full 11-country address parser).
Separately, explicit review feedback on the API surface itself: don't make client code wrap around bad choices. The one found - "kind" was serialized via format!("{:?}", ...), leaning on Debug derive output for a public contract - is fixed as described above.