feat(places): local gazetteer place search API #1190
Loading…
Reference in a new issue
No description provided.
Delete branch "feat/place-search-api"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Adds the forward-geocoding counterpart to the existing reverse place lookup: an authenticated (standard user, no admin)
GET /api/places/search?q=<string>&limit=<int>endpoint that searches the already-imported local GeoNames gazetteer by name and alternative names.Contract
q: required, 2–100 chars after trim, else 400 (IllegalArgumentException→ existingApiExceptionHandler).limit: optional, default 10, allowed 1–50, else 400.{"results": [{providerNativeId, name, level, latitude, longitude, countryCode, admin1Code, featureCode}]}— camelCase, consistent with all other API responses (no global naming strategy is configured). No match or no imported dataset → 200 with emptyresults.SQL approach
Search runs over
name_variants(main names + imported alternates) with a single parameterized ILIKE-styleLIKE(LOWER(name) LIKE '%' || :escaped || '%', user wildcards escaped, LIMIT enforced, no dynamic SQL). Match classes (exact/prefix/substring) are computed in SQL via a CASE expression;DISTINCT ON (provider_native_id)deduplicates to the best variant per place; outer ranking: match class →prominence_score DESC NULLS LAST(the import stores log10(population), so this is the data-driven population surrogate —place_name_candidateshas no population column) → level weight (city/locality/venue before admin_region before geographic_area before country) → display name as stable tiebreaker. Scope mirrorsPlaceLookupService.lookup(): only enabled providers joined withcompleteddatasets; the syntheticfallbacklevel is excluded. No results also for schemas without any import.Migration V163
pg_trgmwas not enabled anywhere, so V163 addsCREATE EXTENSION IF NOT EXISTS pg_trgmplus a GIN trigram index onlower(name_variants.name)so '%q%' substring search is index-backed instead of seq-scanning the full gazetteer, and a(dataset_id, provider_native_id)index onplace_name_candidatesfor the join path. A prefix-only plan without trigram would leave substring search quadratic on the variants table, which is the dominant query shape here.Tests
PlaceSearchServiceTest(15, Testcontainers + PostGIS, reusesimportFixture): exact/prefix/substring, case-insensitivity, ranking within classes (prominence, level weight, NULLS LAST), German alternate-name hit returning the display name, dedup across multiple variants, disabled-provider/draft-dataset exclusion, fallback exclusion, literal wildcard handling, empty/no-data → empty list, q/limit validation, and an EXPLAIN check that the trigram index is a usable access path.PlaceSearchControllerTest(5): auth required, standard user without admin role, validation propagation, default limit, camelCase serialization.:apps:apisuite: 1990 tests, 0 failures (includes all 34 existing places tests).