From 4203dcd91fb39acf2692864f675871433e7602e8 Mon Sep 17 00:00:00 2001 From: Maurice Date: Fri, 30 Oct 2026 16:52:12 +0100 Subject: [PATCH] maps: keep the merge and Photon's geocoding in modules of their own maps.helpers.ts and osm.client.ts had grown past the 1000-line limit. The merge behind the search and suggestion lists, with its lead rules, moves to maps-merge.helpers.ts; the search records and Photon's half of the OpenStreetMap geocoding (search, suggestions, airport codes, identity, reverse, element details) move to osm-geocoding.ts. OsmClient keeps the same methods and hands them on, so no caller changes. --- server/src/nest/maps/maps-index.helpers.ts | 3 +- server/src/nest/maps/maps-merge.helpers.ts | 142 ++++++++++ server/src/nest/maps/maps.helpers.ts | 134 ---------- server/src/nest/maps/maps.service.ts | 3 +- .../src/nest/maps/providers/osm-geocoding.ts | 242 +++++++++++++++++ server/src/nest/maps/providers/osm.client.ts | 252 +++--------------- .../src/nest/maps/providers/photon.mapping.ts | 3 +- .../tests/unit/nest/maps.merge-search.test.ts | 2 +- .../unit/nest/maps.suggestion-merge.test.ts | 2 +- 9 files changed, 422 insertions(+), 361 deletions(-) create mode 100644 server/src/nest/maps/maps-merge.helpers.ts create mode 100644 server/src/nest/maps/providers/osm-geocoding.ts diff --git a/server/src/nest/maps/maps-index.helpers.ts b/server/src/nest/maps/maps-index.helpers.ts index 3ecf3b11b..3c284a8c0 100644 --- a/server/src/nest/maps/maps-index.helpers.ts +++ b/server/src/nest/maps/maps-index.helpers.ts @@ -5,7 +5,8 @@ * the decision to make them is MapsService's. */ import { getCountryFromCoords } from '../../utils/country-borders'; -import { buildOsmDetails, mergeRanked, parsePoiCategories, samePlace, toApiLang, type RowView } from './maps.helpers'; +import { mergeRanked, type RowView } from './maps-merge.helpers'; +import { buildOsmDetails, parsePoiCategories, samePlace, toApiLang } from './maps.helpers'; import { POI_RESULT_CAP, type PoiSearchResult } from './providers/osm.client'; import type { PhotonLead } from './providers/photon.mapping'; import { diff --git a/server/src/nest/maps/maps-merge.helpers.ts b/server/src/nest/maps/maps-merge.helpers.ts new file mode 100644 index 000000000..637b4347b --- /dev/null +++ b/server/src/nest/maps/maps-merge.helpers.ts @@ -0,0 +1,142 @@ +/** + * The one merge behind the search list and the suggestion list (`mergeRanked`), + * with the rules for the lead Photon's answer opens the list on. + * + * Kept apart from maps.helpers.ts, which it reads from: the place rows and the + * distance come from there, the ranking of a merged list lives here. + */ +import { haversineMetres, interleave, samePlace } from './maps.helpers'; +import type { PhotonLead } from './providers/photon.mapping'; + +/** + * Put the index's answer and OpenStreetMap's into one list. + * + * Overture Places is a dataset of businesses. It is very good at those and + * largely does not carry temples, bridges, riverside walks, viewpoints or + * observation decks, which is a fair share of what somebody planning a trip + * searches for. Measured against 128 places out of a real trip to Japan, saved + * through the old search: the index answered 51.6 percent inside its top five, + * and for most of the rest it returned the shops AROUND the landmark rather + * than nothing, which is worse than nothing because it looks like an answer. + * + * Three orderings were tried against that corpus, and the two clever ones lost. + * + * A score threshold cannot tell the cases apart: at 0.75 it catches 19 of 62 + * misses and throws away 6 of 66 hits. Promoting results whose name matches + * what was typed is worse than it sounds, because "Hase Station" shares a word + * with "Hase-dera" while OpenStreetMap answers in the local language and + * returns the correct temple under a name that shares nothing at all: the rule + * pushed seven weak index matches above the right answer, which landed at + * position eight. + * + * So this does not rank. It alternates, index first, and lets each source's own + * ordering stand. An exact business match still opens the list, because the + * index put it first; a landmark the index does not carry is second rather than + * eleventh. Neither source has to be judged by the other's yardstick. + * + * A place both sources know is kept once, as the index's copy, because that is + * the one carrying a stable id, contact details and hours. + */ +export function mergeSearchResults( + fromIndex: Record[], + fromOsm: Record[], + limit = 10, + opts: { lead?: PhotonLead | null; bias?: { lat: number; lng: number } } = {}, +): Record[] { + return mergeRanked(fromIndex, fromOsm, limit, recordView, opts); +} + +/** What the merge reads of a row: its id, its name, the line below it and where it is. */ +export interface RowView { + id: string | null; + name: string; + line: string; + lat?: number; + lng?: number; +} + +const recordView = (r: Record): RowView => ({ + id: typeof r.osm_id === 'string' ? r.osm_id : null, + name: String(r.name ?? ''), + line: String(r.address ?? ''), + lat: typeof r.lat === 'number' ? r.lat : undefined, + lng: typeof r.lng === 'number' ? r.lng : undefined, +}); + +/** + * The one merge behind the search list and the suggestion list, so the two + * agree on what comes first. The second list's rows the first already holds + * go (the same id, or the same place by `samePlace`), the rest alternate with + * the first's, the first leading. + * + * Then Photon's lead (`pickLead`) goes first, and rows of its name inside it + * go: "Berlin" no longer opens on a business filed as Berlin above the city. + * Rows that read the same twice, two branches of a chain with the same town + * below them, are one row: nobody can tell them apart in the list. A row + * without a line below its name is never folded that way. + */ +export function mergeRanked( + first: T[], + second: T[], + limit: number, + view: (row: T) => RowView, + { lead = null, bias }: { lead?: PhotonLead | null; bias?: { lat: number; lng: number } } = {}, +): T[] { + const asPlace = (row: T) => { + const v = view(row); + return { lat: v.lat, lng: v.lng, name: v.name }; + }; + const extra = second.filter((o) => { + const id = view(o).id; + return !first.some((i) => (id !== null && view(i).id === id) || samePlace(asPlace(i), asPlace(o))); + }); + const merged = interleave(first, extra, Number.POSITIVE_INFINITY); + // Photon's own row first; a row of its name inside it only where that row went as the same place. + const top = + lead && leadsHere(lead, bias) + ? (merged.find((row) => view(row).id === lead.placeId) ?? merged.find((row) => standsFor(view(row), lead))) + : undefined; + const ordered = top && lead ? [top, ...merged.filter((row) => row !== top && !standsFor(view(row), lead))] : merged; + const shown = new Set(); + return ordered + .filter((row) => { + const v = view(row); + // Without a line below the name two rows of one name are told apart by nothing but where they are. + if (!v.line.trim()) return true; + const reads = `${foldName(v.name)}\n${foldName(v.line)}`; + if (shown.has(reads)) return false; + shown.add(reads); + return true; + }) + .slice(0, limit); +} + +/** How far from where the traveller looks a town may lie and still be what its name means there. */ +export const LEAD_TOWN_REACH_M = 1_000_000; + +/** What may lead with nothing to say where the traveller is looking: a town, an island or a sight, not a municipality or a county. */ +const UNBIASED_LEADS = new Set(['city', 'town', 'landmark', 'island', 'archipelago', 'airport']); + +/** Whether a lead leads from where the traveller is looking. */ +export function leadsHere(lead: PhotonLead, bias: { lat: number; lng: number } | undefined): boolean { + if (lead.reach === 'everywhere') return true; + if (!bias) return UNBIASED_LEADS.has(lead.kind); + return haversineMetres(bias.lat, bias.lng, lead.lat, lead.lng) <= LEAD_TOWN_REACH_M; +} + +/** Whether a row is the lead itself, under its id or as a row of its name inside it. */ +function standsFor(row: RowView, lead: PhotonLead): boolean { + if (row.id === lead.placeId) return true; + if (row.lat === undefined || row.lng === undefined || foldName(row.name) !== foldName(lead.name)) return false; + if (!lead.extent) return haversineMetres(row.lat, row.lng, lead.lat, lead.lng) < LEAD_WITHOUT_EXTENT_M; + const [west, north, east, south] = lead.extent; + return row.lng >= west && row.lng <= east && row.lat >= south && row.lat <= north; +} + +/** Around a lead Photon gave no extent for, how near a row of its name has to be to be it. */ +const LEAD_WITHOUT_EXTENT_M = 25_000; + +/** A name as the merge compares it: without accents, case or extra spaces. */ +export function foldName(value: string): string { + return value.normalize('NFKD').replace(/\p{M}/gu, '').toLowerCase().replace(/\s+/gu, ' ').trim(); +} diff --git a/server/src/nest/maps/maps.helpers.ts b/server/src/nest/maps/maps.helpers.ts index 430ca9c49..3d55d60d1 100644 --- a/server/src/nest/maps/maps.helpers.ts +++ b/server/src/nest/maps/maps.helpers.ts @@ -2,7 +2,6 @@ import { readEnv, getAppUrl } from '../../app-config'; import { haversineMetres } from '../common/geo'; import { stripHtmlTags } from '../common/stripHtmlTags'; import { buildUserAgent, parseOverpassEndpoints } from './overpass.constants'; -import type { PhotonLead } from './providers/photon.mapping'; import { normalizePlaceWebsite } from '@trek/shared'; import { z } from 'zod'; @@ -81,139 +80,6 @@ export { haversineMetres }; * list for all of them is its own maintenance problem. Anything the pair rule * lets through has already survived the distance check. */ -/** - * Put the index's answer and OpenStreetMap's into one list. - * - * Overture Places is a dataset of businesses. It is very good at those and - * largely does not carry temples, bridges, riverside walks, viewpoints or - * observation decks, which is a fair share of what somebody planning a trip - * searches for. Measured against 128 places out of a real trip to Japan, saved - * through the old search: the index answered 51.6 percent inside its top five, - * and for most of the rest it returned the shops AROUND the landmark rather - * than nothing, which is worse than nothing because it looks like an answer. - * - * Three orderings were tried against that corpus, and the two clever ones lost. - * - * A score threshold cannot tell the cases apart: at 0.75 it catches 19 of 62 - * misses and throws away 6 of 66 hits. Promoting results whose name matches - * what was typed is worse than it sounds, because "Hase Station" shares a word - * with "Hase-dera" while OpenStreetMap answers in the local language and - * returns the correct temple under a name that shares nothing at all: the rule - * pushed seven weak index matches above the right answer, which landed at - * position eight. - * - * So this does not rank. It alternates, index first, and lets each source's own - * ordering stand. An exact business match still opens the list, because the - * index put it first; a landmark the index does not carry is second rather than - * eleventh. Neither source has to be judged by the other's yardstick. - * - * A place both sources know is kept once, as the index's copy, because that is - * the one carrying a stable id, contact details and hours. - */ -export function mergeSearchResults( - fromIndex: Record[], - fromOsm: Record[], - limit = 10, - opts: { lead?: PhotonLead | null; bias?: { lat: number; lng: number } } = {}, -): Record[] { - return mergeRanked(fromIndex, fromOsm, limit, recordView, opts); -} - -/** What the merge reads of a row: its id, its name, the line below it and where it is. */ -export interface RowView { - id: string | null; - name: string; - line: string; - lat?: number; - lng?: number; -} - -const recordView = (r: Record): RowView => ({ - id: typeof r.osm_id === 'string' ? r.osm_id : null, - name: String(r.name ?? ''), - line: String(r.address ?? ''), - lat: typeof r.lat === 'number' ? r.lat : undefined, - lng: typeof r.lng === 'number' ? r.lng : undefined, -}); - -/** - * The one merge behind the search list and the suggestion list, so the two - * agree on what comes first. The second list's rows the first already holds - * go (the same id, or the same place by `samePlace`), the rest alternate with - * the first's, the first leading. - * - * Then Photon's lead (`pickLead`) goes first, and rows of its name inside it - * go: "Berlin" no longer opens on a business filed as Berlin above the city. - * Rows that read the same twice, two branches of a chain with the same town - * below them, are one row: nobody can tell them apart in the list. A row - * without a line below its name is never folded that way. - */ -export function mergeRanked( - first: T[], - second: T[], - limit: number, - view: (row: T) => RowView, - { lead = null, bias }: { lead?: PhotonLead | null; bias?: { lat: number; lng: number } } = {}, -): T[] { - const asPlace = (row: T) => { - const v = view(row); - return { lat: v.lat, lng: v.lng, name: v.name }; - }; - const extra = second.filter((o) => { - const id = view(o).id; - return !first.some((i) => (id !== null && view(i).id === id) || samePlace(asPlace(i), asPlace(o))); - }); - const merged = interleave(first, extra, Number.POSITIVE_INFINITY); - // Photon's own row first; a row of its name inside it only where that row went as the same place. - const top = - lead && leadsHere(lead, bias) - ? (merged.find((row) => view(row).id === lead.placeId) ?? merged.find((row) => standsFor(view(row), lead))) - : undefined; - const ordered = top && lead ? [top, ...merged.filter((row) => row !== top && !standsFor(view(row), lead))] : merged; - const shown = new Set(); - return ordered - .filter((row) => { - const v = view(row); - // Without a line below the name two rows of one name are told apart by nothing but where they are. - if (!v.line.trim()) return true; - const reads = `${foldName(v.name)}\n${foldName(v.line)}`; - if (shown.has(reads)) return false; - shown.add(reads); - return true; - }) - .slice(0, limit); -} - -/** How far from where the traveller looks a town may lie and still be what its name means there. */ -export const LEAD_TOWN_REACH_M = 1_000_000; - -/** What may lead with nothing to say where the traveller is looking: a town, an island or a sight, not a municipality or a county. */ -const UNBIASED_LEADS = new Set(['city', 'town', 'landmark', 'island', 'archipelago', 'airport']); - -/** Whether a lead leads from where the traveller is looking. */ -export function leadsHere(lead: PhotonLead, bias: { lat: number; lng: number } | undefined): boolean { - if (lead.reach === 'everywhere') return true; - if (!bias) return UNBIASED_LEADS.has(lead.kind); - return haversineMetres(bias.lat, bias.lng, lead.lat, lead.lng) <= LEAD_TOWN_REACH_M; -} - -/** Whether a row is the lead itself, under its id or as a row of its name inside it. */ -function standsFor(row: RowView, lead: PhotonLead): boolean { - if (row.id === lead.placeId) return true; - if (row.lat === undefined || row.lng === undefined || foldName(row.name) !== foldName(lead.name)) return false; - if (!lead.extent) return haversineMetres(row.lat, row.lng, lead.lat, lead.lng) < LEAD_WITHOUT_EXTENT_M; - const [west, north, east, south] = lead.extent; - return row.lng >= west && row.lng <= east && row.lat >= south && row.lat <= north; -} - -/** Around a lead Photon gave no extent for, how near a row of its name has to be to be it. */ -const LEAD_WITHOUT_EXTENT_M = 25_000; - -/** A name as the merge compares it: without accents, case or extra spaces. */ -export function foldName(value: string): string { - return value.normalize('NFKD').replace(/\p{M}/gu, '').toLowerCase().replace(/\s+/gu, ' ').trim(); -} - /** One row of each list in turn, the first list leading, up to `limit` rows. */ export function interleave(first: T[], second: T[], limit: number): T[] { const out: T[] = []; diff --git a/server/src/nest/maps/maps.service.ts b/server/src/nest/maps/maps.service.ts index a521a8165..8930944b5 100644 --- a/server/src/nest/maps/maps.service.ts +++ b/server/src/nest/maps/maps.service.ts @@ -16,9 +16,10 @@ import { osmLayerRecord, PHOTON_GRACE_MS, } from './maps-index.helpers'; +import { mergeSearchResults } from './maps-merge.helpers'; import { NEARBY_DEFAULT_LIMIT, NEARBY_DEFAULT_RADIUS_M, nearbyCacheKey, nearestFirst } from './maps-nearby.helpers'; import { MapsUrlResolver, type ResolvedMapsUrl } from './maps-url.resolver'; -import { toApiLang, mergeSearchResults } from './maps.helpers'; +import { toApiLang } from './maps.helpers'; import { PlaceDetailsResolver } from './place-details.resolver'; import { PlacePhotoResolver } from './place-photo.resolver'; import { PlacesProviderSelector, type KeyedProvider } from './places-provider.selector'; diff --git a/server/src/nest/maps/providers/osm-geocoding.ts b/server/src/nest/maps/providers/osm-geocoding.ts new file mode 100644 index 000000000..487baeb61 --- /dev/null +++ b/server/src/nest/maps/providers/osm-geocoding.ts @@ -0,0 +1,242 @@ +/** + * The search records OpenStreetMap answers are read into, and Photon's half of + * the OpenStreetMap geocoding: search and suggestions with the lead they open + * on, airport codes, the identity of a place by name and coordinate, the + * reverse lookup and the details of an element Overpass placed. + * + * Free functions over the PhotonClient OsmClient holds, so OsmClient keeps one + * face for its callers while Photon's rules live in one place. Where Photon is + * the installation's geocoder these answer alone; Nominatim is OsmClient's + * business, for installations without the TREK services. + */ +import { findByIata, type Airport } from '../../airports/airports.data'; +import { buildOsmDetails, haversineMetres, namesOverlap, toApiLang } from '../maps.helpers'; +import type { NominatimResult, NominatimReverse, OverpassElement } from './osm.client'; +import type { PhotonClient } from './photon.client'; +import { + asNominatimHit, + asNominatimReverse, + asSuggestion, + photonDisplayName, + pickLead, + rankFeatures, + type PhotonFeature, + type PhotonLead, +} from './photon.mapping'; +import { readWikiIdentity } from './wiki-identity'; + +type Bias = { lat: number; lng: number }; + +function nominatimCategory(item: { class?: string; type?: string }): string | null { + if (!item.class || !item.type || item.type === 'yes') return null; + return item.class === 'shop' ? `shop_${item.type}` : item.type; +} + +/** A search row as TREK's place record. */ +export function searchRecord(item: NominatimResult) { + // Number.isFinite, not `|| null`: a place on the equator or prime + // meridian has a legitimate 0 coordinate. + const lat = Number.parseFloat(item.lat); + const lng = Number.parseFloat(item.lon); + return { + google_place_id: null, + google_ftid: null, + osm_id: `${item.osm_type}:${item.osm_id}`, + name: item.name || item.display_name?.split(',')[0] || '', + address: item.display_name || '', + lat: Number.isFinite(lat) ? lat : null, + lng: Number.isFinite(lng) ? lng : null, + rating: null, + website: null, + phone: null, + // What the place is, so the add form can preselect a category (#2282). A shop's + // value is the ware ("bakery"), so the key goes first and says it is a shop. + category: nominatimCategory(item), + source: 'openstreetmap', + ...readWikiIdentity(item.extratags), + }; +} + +export function isHit(hit: NominatimResult | null): hit is NominatimResult { + return hit !== null; +} + +/** + * Photon's search, its hits ranked (`rankFeatures`) and read as search + * records, with the lead the list opens on; or null where Photon is not in + * use or did not answer, and the caller is left to what it had before. + */ +export async function photonSearch(photon: PhotonClient, query: string, lang?: string, bias?: Bias) { + const airport = airportOfCode(query); + const found = await photon.search(airport?.name ?? query, { lang, bias: airport ?? bias }); + if (!found) return null; + const ranked = rankFeatures(found); + return { + records: ranked.map(asNominatimHit).filter(isHit).map(searchRecord), + lead: airport ? airportLead(ranked, airport) : pickLead(ranked, query, bias), + }; +} + +/** Photon's suggestions with the lead the list opens on, or null when it goes without them. */ +export async function photonSuggest( + photon: PhotonClient, + input: string, + { lang, bias, signal }: { lang?: string; bias?: Bias; signal?: AbortSignal }, +) { + const airport = airportOfCode(input); + const found = await photon.suggest(airport?.name ?? input, { lang, bias: airport ?? bias, signal }); + if (!found) return null; + const ranked = rankFeatures(found); + return { + rows: ranked.map(asSuggestion).filter((row) => row !== null), + lead: airport ? airportLead(ranked, airport) : pickLead(ranked, input, bias), + }; +} + +/** + * The airport a code in capitals names ("JFK", "LHR"), from the bundled + * dataset. Photon does not search codes: "JFK" answered with an expressway, + * "FRA" with France. So the code is asked for as the airport's name at its + * coordinate, where the aerodrome comes first. Lower case is left alone, so + * "Ber" typed on the way to "Berlin" stays a search for Berlin. + */ +function airportOfCode(query: string): Airport | null { + const code = query.trim(); + return /^[A-Z]{3}$/.test(code) ? findByIata(code) : null; +} + +/** + * The aerodrome of a code's answer, within a few kilometres of the airport, as + * a lead from everywhere; failing that a place there that calls itself an + * airport, which is how OpenStreetMap files Haneda (an island named "Tokyo + * International Airport"). + */ +function airportLead(ranked: PhotonFeature[], airport: Airport): PhotonLead | null { + const near = ranked + .map((feature) => ({ feature, row: asSuggestion(feature) })) + .filter( + ( + c, + ): c is { + feature: PhotonFeature; + row: NonNullable> & { lat: number; lng: number }; + } => + c.row?.lat !== undefined && + c.row.lng !== undefined && + haversineMetres(airport.lat, airport.lng, c.row.lat, c.row.lng) <= AIRPORT_MATCH_M, + ); + const best = + near.find((c) => c.feature.properties.osm_value === 'aerodrome') ?? + near.find((c) => c.feature.properties.osm_key === 'place' && AIRPORT_WORDS.test(c.row.mainText)); + if (!best) return null; + const { placeId, mainText, lat, lng } = best.row; + return { placeId, name: mainText, reach: 'everywhere', kind: 'airport', lat, lng, extent: null }; +} + +const AIRPORT_WORDS = /airport|flughafen|aéroport|aeropuerto|aeroporto|luchthaven|lotnisko|空港|机场|공항/iu; + +/** How far an aerodrome may lie from the dataset's coordinate of its airport and still be it. */ +const AIRPORT_MATCH_M = 8000; + +// A station or a road named after a place is not the place, unless the name +// asked for one ("Hauptbahnhof", "Tor station"). +const TRANSPORT_KEYS = new Set(['railway', 'public_transport', 'highway']); +const TRANSPORT_WORDS = + /(?:^|[^\p{L}])(?:station|bahnhof|hbf|bhf|halt|haltestelle|stop|street|straße|strasse|road|weg|gare|estación|stazione)(?:$|[^\p{L}])|駅/iu; + +export interface IdentityMatch { + tags: Record; + osmUrl: string | null; + matchedName: string; +} + +/** + * The identity of a place from Photon, inside a box of about 2 km around the + * point and through the two gates OsmClient's identity match keeps: within + * `maxDistanceM`, and a name that shares a substantial word. Photon has no + * `importance`, so a Wikidata link stands in for it, and a station or a road + * named after the place steps back unless the name asked for one: the + * Brandenburg Gate before the station beside it. Measured on eight + * landmarks: seven right, against five in Photon's order. + */ +export async function photonIdentity( + photon: PhotonClient, + { + query, + lat, + lng, + maxDistanceM, + lang, + }: { query: string; lat: number; lng: number; maxDistanceM: number; lang?: string }, +): Promise { + const d = 0.02; + const found = await photon.search(query, { lang, bbox: [lng - d, lat - d, lng + d, lat + d], limit: 5 }); + const transport = !TRANSPORT_WORDS.test(query); + const best = (found ?? []) + .map((feature) => ({ feature, hit: asNominatimHit(feature) })) + .filter((c): c is { feature: PhotonFeature; hit: NominatimResult } => c.hit !== null) + .map((c) => ({ ...c, metres: haversineMetres(lat, lng, Number(c.hit.lat), Number(c.hit.lon)) })) + .filter((c) => c.metres <= maxDistanceM && namesOverlap(query, c.hit.name || '')) + .map((c) => ({ + ...c, + score: + (c.hit.extratags?.wikidata ? -2 : 0) + + (transport && TRANSPORT_KEYS.has(c.feature.properties.osm_key ?? '') ? 3 : 0), + })) + .sort((a, b) => a.score - b.score || a.metres - b.metres)[0]; + if (!best) return null; + return { + tags: best.hit.extratags ?? {}, + osmUrl: `https://www.openstreetmap.org/${best.hit.osm_type}/${best.hit.osm_id}`, + matchedName: best.hit.name || query, + }; +} + +// How far a reverse lookup that found nothing next to the point looks again. +const WIDE_REVERSE_KM = 50; + +/** + * Photon's nearest feature, or null where it has none. Photon looks within + * a small radius by default and finds nothing in open country or at sea, + * where Nominatim named the nearest object at any distance, so an empty + * answer is asked once more with a radius of 50 km. + */ +export async function photonReverse( + photon: PhotonClient, + lat: number, + lng: number, + { lang, timeoutMs }: { lang?: string; timeoutMs?: number } = {}, +): Promise { + const near = await photon.reverse(lat, lng, lang, timeoutMs); + const found = + near?.length === 0 ? await photon.reverse(lat, lng, lang, timeoutMs, { radius: WIDE_REVERSE_KM }) : near; + return found?.[0] ? asNominatimReverse(found[0]) : null; +} + +/** + * The details of an element without Nominatim: Overpass gave the tags and + * where the element is, Photon's reverse lookup at that point names it and + * writes its address, the element itself where Photon has it. Null when + * Overpass did not say where it is, so the caller can still try Nominatim. + */ +export async function photonElementDetails( + photon: PhotonClient, + element: OverpassElement, + { osmType, osmId, placeId, lang }: { osmType: string; osmId: string; placeId: string; lang?: string }, +): Promise | null> { + const lat = element.center?.lat ?? element.lat; + const lng = element.center?.lon ?? element.lon; + if (lat === undefined || lng === undefined) return null; + const near = await photon.reverse(lat, lng, lang, undefined, { limit: 10, radius: 0.3 }); + const self = near?.find((f) => asNominatimHit(f)?.osm_type === osmType && String(f.properties.osm_id) === osmId); + const base = lang ? toApiLang(lang).split('-')[0] : ''; + const extra = self ? (asNominatimHit(self)?.extratags ?? {}) : {}; + return { + ...buildOsmDetails({ ...extra, ...(element.tags ?? {}) }, osmType, osmId), + name: (base && element.tags?.[`name:${base}`]) || self?.properties.name || element.tags?.name || '', + address: self ? photonDisplayName(self.properties) : near?.[0] ? photonDisplayName(near[0].properties) : '', + lat, + lng, + osm_id: placeId, + }; +} diff --git a/server/src/nest/maps/providers/osm.client.ts b/server/src/nest/maps/providers/osm.client.ts index 7394e3765..a32ac7728 100644 --- a/server/src/nest/maps/providers/osm.client.ts +++ b/server/src/nest/maps/providers/osm.client.ts @@ -17,14 +17,13 @@ * * Search and reverse ask Photon first (PhotonClient) where the TREK services * hold a key and the operator runs no Nominatim of their own; its answers are - * read into Nominatim's shape, so both come out of the same mapping. Lookups - * by id and the identity match stay on Nominatim: they need its id lookup and - * its extratags. + * read into Nominatim's shape, so both come out of the same mapping. Photon's + * half (osm-geocoding.ts) also matches identities and names an element + * Overpass placed; Nominatim answers installations without the services. * * Never imports MapsService: providers sit below the orchestrator * (lint:boundaries holds that). */ -import { findByIata, type Airport } from '../../airports/airports.data'; import { logWarn } from '../../audit/audit-log.logger'; import { nominatimFetch, type GeoLane } from '../../geo/nominatim.client'; import { OVERPASS_ALONG_QUERY_TIMEOUT_S, aroundPath, overpassAlongQuery } from '../maps-along.helpers'; @@ -48,27 +47,20 @@ import { } from '../maps.helpers'; import { overpassSelector, tagsMatchFilter } from '../osm-filter.helpers'; import { OverpassBusy, hedged, lastAnsweredFirst, retryAfterMs, soonestRetryMs } from '../overpass-hedge.helpers'; -import { PhotonClient } from './photon.client'; import { - asNominatimHit, - asNominatimReverse, - asSuggestion, - photonDisplayName, - pickLead, - rankFeatures, - type PhotonFeature, - type PhotonLead, -} from './photon.mapping'; -import { readWikiIdentity } from './wiki-identity'; + photonElementDetails, + photonIdentity, + photonReverse, + photonSearch, + photonSuggest, + searchRecord, + type IdentityMatch, +} from './osm-geocoding'; +import { PhotonClient } from './photon.client'; import { Injectable } from '@nestjs/common'; import { normalizePlaceWebsite } from '@trek/shared'; import type { LatLng } from '@trek/shared/roadtrip'; -function nominatimCategory(item: { class?: string; type?: string }): string | null { - if (!item.class || !item.type || item.type === 'yes') return null; - return item.class === 'shop' ? `shop_${item.type}` : item.type; -} - export interface NominatimResult { osm_type: string; osm_id: string; @@ -121,95 +113,12 @@ export interface NominatimReverse { address?: Record; } -/** A search row as TREK's place record. */ -function searchRecord(item: NominatimResult) { - // Number.isFinite, not `|| null`: a place on the equator or prime - // meridian has a legitimate 0 coordinate. - const lat = Number.parseFloat(item.lat); - const lng = Number.parseFloat(item.lon); - return { - google_place_id: null, - google_ftid: null, - osm_id: `${item.osm_type}:${item.osm_id}`, - name: item.name || item.display_name?.split(',')[0] || '', - address: item.display_name || '', - lat: Number.isFinite(lat) ? lat : null, - lng: Number.isFinite(lng) ? lng : null, - rating: null, - website: null, - phone: null, - // What the place is, so the add form can preselect a category (#2282). A shop's - // value is the ware ("bakery"), so the key goes first and says it is a shop. - category: nominatimCategory(item), - source: 'openstreetmap', - ...readWikiIdentity(item.extratags), - }; -} - -function isHit(hit: NominatimResult | null): hit is NominatimResult { - return hit !== null; -} - -/** - * The airport a code in capitals names ("JFK", "LHR"), from the bundled - * dataset. Photon does not search codes: "JFK" answered with an expressway, - * "FRA" with France. So the code is asked for as the airport's name at its - * coordinate, where the aerodrome comes first. Lower case is left alone, so - * "Ber" typed on the way to "Berlin" stays a search for Berlin. - */ -function airportOfCode(query: string): Airport | null { - const code = query.trim(); - return /^[A-Z]{3}$/.test(code) ? findByIata(code) : null; -} - -/** - * The aerodrome of a code's answer, within a few kilometres of the airport, as - * a lead from everywhere; failing that a place there that calls itself an - * airport, which is how OpenStreetMap files Haneda (an island named "Tokyo - * International Airport"). - */ -function airportLead(ranked: PhotonFeature[], airport: Airport): PhotonLead | null { - const near = ranked - .map((feature) => ({ feature, row: asSuggestion(feature) })) - .filter( - ( - c, - ): c is { - feature: PhotonFeature; - row: NonNullable> & { lat: number; lng: number }; - } => - c.row?.lat !== undefined && - c.row.lng !== undefined && - haversineMetres(airport.lat, airport.lng, c.row.lat, c.row.lng) <= AIRPORT_MATCH_M, - ); - const best = - near.find((c) => c.feature.properties.osm_value === 'aerodrome') ?? - near.find((c) => c.feature.properties.osm_key === 'place' && AIRPORT_WORDS.test(c.row.mainText)); - if (!best) return null; - const { placeId, mainText, lat, lng } = best.row; - return { placeId, name: mainText, reach: 'everywhere', kind: 'airport', lat, lng, extent: null }; -} - -const AIRPORT_WORDS = /airport|flughafen|aéroport|aeropuerto|aeroporto|luchthaven|lotnisko|空港|机场|공항/iu; - -/** How far an aerodrome may lie from the dataset's coordinate of its airport and still be it. */ -const AIRPORT_MATCH_M = 8000; - // Tighter than the wiki calls, because this one sits at the FRONT of a chain: // identity, then sitelinks, then the extract. Nominatim answers a bounded // search in 0.2-0.7s in practice, so anything past a couple of seconds is a bad // day at the provider rather than a slow answer worth waiting for. const IDENTITY_TIMEOUT_MS = 2500; -// A station or a road named after a place is not the place, unless the name -// asked for one ("Hauptbahnhof", "Tor station"). -const TRANSPORT_KEYS = new Set(['railway', 'public_transport', 'highway']); -const TRANSPORT_WORDS = - /(?:^|[^\p{L}])(?:station|bahnhof|hbf|bhf|halt|haltestelle|stop|street|straße|strasse|road|weg|gare|estación|stazione)(?:$|[^\p{L}])|駅/iu; - -// How far a reverse lookup that found nothing next to the point looks again. -const WIDE_REVERSE_KM = 50; - // The explicit search asks Nominatim alongside the index, and the pair costs // the slower one. The index gives up after 3.5 s and the browser after 8 s, so a // Nominatim that accepts the connection and then sits on it (the public service @@ -511,20 +420,14 @@ export class OsmClient { // ── Nominatim search ─────────────────────────────────────────────────────── - /** - * Photon's search, its hits ranked (`rankFeatures`) and read as search - * records, with the lead the list opens on; or null where Photon is not in - * use or did not answer, and the caller is left to what it had before. - */ - async searchPhoton(query: string, lang?: string, bias?: { lat: number; lng: number }) { - const airport = airportOfCode(query); - const found = await this.photon.search(airport?.name ?? query, { lang, bias: airport ?? bias }); - if (!found) return null; - const ranked = rankFeatures(found); - return { - records: ranked.map(asNominatimHit).filter(isHit).map(searchRecord), - lead: airport ? airportLead(ranked, airport) : pickLead(ranked, query, bias), - }; + /** Photon's search with its lead (`photonSearch`), or null where Photon is not in use or did not answer. */ + searchPhoton(query: string, lang?: string, bias?: { lat: number; lng: number }) { + return photonSearch(this.photon, query, lang, bias); + } + + /** Whether Photon is this installation's geocoder, so a miss of it is not handed to Nominatim. */ + photonIsGeocoder(): boolean { + return this.photon.inUse(); } /** @@ -544,11 +447,6 @@ export class OsmClient { * next Nominatim slot each time, so somebody typing in the place search waits * behind the whole import. */ - /** Whether Photon is this installation's geocoder, so a miss of it is not handed to Nominatim. */ - photonIsGeocoder(): boolean { - return this.photon.inUse(); - } - async searchNominatim( query: string, lang?: string, @@ -630,15 +528,8 @@ export class OsmClient { } /** The same suggestions with Photon's first hit read as a lead, for the list that merges them with the index. */ - async suggestPhoton(input: string, lang?: string, bias?: { lat: number; lng: number }, signal?: AbortSignal) { - const airport = airportOfCode(input); - const found = await this.photon.suggest(airport?.name ?? input, { lang, bias: airport ?? bias, signal }); - if (!found) return null; - const ranked = rankFeatures(found); - return { - rows: ranked.map(asSuggestion).filter((row) => row !== null), - lead: airport ? airportLead(ranked, airport) : pickLead(ranked, input, bias), - }; + suggestPhoton(input: string, lang?: string, bias?: { lat: number; lng: number }, signal?: AbortSignal) { + return photonSuggest(this.photon, input, { lang, bias, signal }); } /** @@ -664,11 +555,11 @@ export class OsmClient { lat: number, lng: number, opts: { lang?: string; maxDistanceM?: number; signal?: AbortSignal } = {}, - ): Promise<{ tags: Record; osmUrl: string | null; matchedName: string } | null> { + ): Promise { const query = (name || '').trim(); if (!query || !Number.isFinite(lat) || !Number.isFinite(lng)) return null; const maxDistanceM = opts.maxDistanceM ?? 2000; - if (this.photon.inUse()) return this.photonIdentity(query, lat, lng, maxDistanceM, opts.lang); + if (this.photon.inUse()) return photonIdentity(this.photon, { query, lat, lng, maxDistanceM, lang: opts.lang }); // ~2km box around the point, so Nominatim ranks locally instead of handing // back the most famous place on earth with this name. @@ -727,43 +618,6 @@ export class OsmClient { } } - /** - * The identity from Photon, inside the same box and through the same two - * gates. Photon has no `importance`, so a Wikidata link stands in for it, - * and a station or a road named after the place steps back unless the name - * asked for one: the Brandenburg Gate before the station beside it. - * Measured on eight landmarks: seven right, against five in Photon's order. - */ - private async photonIdentity( - query: string, - lat: number, - lng: number, - maxDistanceM: number, - lang?: string, - ): Promise<{ tags: Record; osmUrl: string | null; matchedName: string } | null> { - const d = 0.02; - const found = await this.photon.search(query, { lang, bbox: [lng - d, lat - d, lng + d, lat + d], limit: 5 }); - const transport = !TRANSPORT_WORDS.test(query); - const best = (found ?? []) - .map((feature) => ({ feature, hit: asNominatimHit(feature) })) - .filter((c): c is { feature: PhotonFeature; hit: NominatimResult } => c.hit !== null) - .map((c) => ({ ...c, metres: haversineMetres(lat, lng, Number(c.hit.lat), Number(c.hit.lon)) })) - .filter((c) => c.metres <= maxDistanceM && namesOverlap(query, c.hit.name || '')) - .map((c) => ({ - ...c, - score: - (c.hit.extratags?.wikidata ? -2 : 0) + - (transport && TRANSPORT_KEYS.has(c.feature.properties.osm_key ?? '') ? 3 : 0), - })) - .sort((a, b) => a.score - b.score || a.metres - b.metres)[0]; - if (!best) return null; - return { - tags: best.hit.extratags ?? {}, - osmUrl: `https://www.openstreetmap.org/${best.hit.osm_type}/${best.hit.osm_id}`, - matchedName: best.hit.name || query, - }; - } - // ── Nominatim lookup (by OSM ID) ─────────────────────────────────────────── async lookupNominatim( @@ -816,7 +670,10 @@ export class OsmClient { opts?: { lane?: GeoLane; timeoutMs?: number; locality?: boolean }, ): Promise<{ name: string | null; address: string | null }> { const data = this.photon.inUse() - ? await this.reversePhoton(lat, lng, lang, opts?.timeoutMs) + ? await photonReverse(this.photon, Number.parseFloat(lat), Number.parseFloat(lng), { + lang, + timeoutMs: opts?.timeoutMs, + }) : await this.reverseNominatim(lat, lng, lang, opts); if (!data) return { name: null, address: null }; const addr = data.address || {}; @@ -826,25 +683,6 @@ export class OsmClient { return { name, address: data.display_name || null }; } - /** - * Photon's nearest feature, or null where it has none. Photon looks within - * a small radius by default and finds nothing in open country or at sea, - * where Nominatim named the nearest object at any distance, so an empty - * answer is asked once more with a radius of 50 km. - */ - private async reversePhoton( - lat: string, - lng: string, - lang?: string, - timeoutMs?: number, - ): Promise { - const [y, x] = [Number.parseFloat(lat), Number.parseFloat(lng)]; - const near = await this.photon.reverse(y, x, lang, timeoutMs); - const found = - near?.length === 0 ? await this.photon.reverse(y, x, lang, timeoutMs, { radius: WIDE_REVERSE_KM }) : near; - return found?.[0] ? asNominatimReverse(found[0]) : null; - } - private async reverseNominatim( lat: string, lng: string, @@ -870,7 +708,7 @@ export class OsmClient { * coordinates are already known, so the caller still has something to return. */ async reverseRaw(lat: number, lng: number): Promise { - if (this.photon.inUse()) return (await this.reversePhoton(String(lat), String(lng))) ?? {}; + if (this.photon.inUse()) return (await photonReverse(this.photon, lat, lng)) ?? {}; const res = await nominatimFetch( 'reverse', new URLSearchParams({ lat: String(lat), lon: String(lng), format: 'json', addressdetails: '1' }), @@ -896,7 +734,7 @@ export class OsmClient { // names it; Nominatim is asked only when Overpass could not place it. const located = this.photon.inUse() ? await this.fetchOverpassDetails(osmType, osmId, true) : undefined; if (located) { - const answer = await this.photonElementDetails(located, osmType, osmId, placeId, lang); + const answer = await photonElementDetails(this.photon, located, { osmType, osmId, placeId, lang }); if (answer) return answer; } // buildOsmDetails never yields name/address/coordinates — Nominatim is @@ -922,36 +760,6 @@ export class OsmClient { }; } - /** - * The details of an element without Nominatim: Overpass gave the tags and - * where the element is, Photon's reverse lookup at that point names it and - * writes its address, the element itself where Photon has it. Null when - * Overpass did not say where it is, so the caller can still try Nominatim. - */ - private async photonElementDetails( - element: OverpassElement, - osmType: string, - osmId: string, - placeId: string, - lang?: string, - ): Promise | null> { - const lat = element.center?.lat ?? element.lat; - const lng = element.center?.lon ?? element.lon; - if (lat === undefined || lng === undefined) return null; - const near = await this.photon.reverse(lat, lng, lang, undefined, { limit: 10, radius: 0.3 }); - const self = near?.find((f) => asNominatimHit(f)?.osm_type === osmType && String(f.properties.osm_id) === osmId); - const base = lang ? toApiLang(lang).split('-')[0] : ''; - const extra = self ? (asNominatimHit(self)?.extratags ?? {}) : {}; - return { - ...buildOsmDetails({ ...extra, ...(element.tags ?? {}) }, osmType, osmId), - name: (base && element.tags?.[`name:${base}`]) || self?.properties.name || element.tags?.name || '', - address: self ? photonDisplayName(self.properties) : near?.[0] ? photonDisplayName(near[0].properties) : '', - lat, - lng, - osm_id: placeId, - }; - } - // ── Overpass API (OSM details) ───────────────────────────────────────────── /** `located` asks for the element's coordinate as well: a node's own, the centre of a way or relation. */ diff --git a/server/src/nest/maps/providers/photon.mapping.ts b/server/src/nest/maps/providers/photon.mapping.ts index f7c13af6f..57699ef89 100644 --- a/server/src/nest/maps/providers/photon.mapping.ts +++ b/server/src/nest/maps/providers/photon.mapping.ts @@ -8,7 +8,8 @@ * the address as one comma-joined line. The OsmClient keeps one mapping from * Nominatim's shape to TREK's place record, and this file feeds it. */ -import { foldName, leadsHere, toApiLang } from '../maps.helpers'; +import { foldName, leadsHere } from '../maps-merge.helpers'; +import { toApiLang } from '../maps.helpers'; import type { NominatimResult, NominatimReverse } from './osm.client'; import type { MapsAutocompleteResult } from '@trek/shared'; diff --git a/server/tests/unit/nest/maps.merge-search.test.ts b/server/tests/unit/nest/maps.merge-search.test.ts index 35f49d549..14b94a576 100644 --- a/server/tests/unit/nest/maps.merge-search.test.ts +++ b/server/tests/unit/nest/maps.merge-search.test.ts @@ -8,7 +8,7 @@ * ten plausible wrong answers look like an answer and the user never learns the * temple was one query away in OpenStreetMap. */ -import { mergeSearchResults } from '../../../src/nest/maps/maps.helpers'; +import { mergeSearchResults } from '../../../src/nest/maps/maps-merge.helpers'; import type { PhotonLead } from '../../../src/nest/maps/providers/photon.mapping'; import { describe, it, expect } from 'vitest'; diff --git a/server/tests/unit/nest/maps.suggestion-merge.test.ts b/server/tests/unit/nest/maps.suggestion-merge.test.ts index ec63fef7c..a40c8246a 100644 --- a/server/tests/unit/nest/maps.suggestion-merge.test.ts +++ b/server/tests/unit/nest/maps.suggestion-merge.test.ts @@ -7,7 +7,7 @@ * Photon found. */ import { mergeSuggestions } from '../../../src/nest/maps/maps-index.helpers'; -import { LEAD_TOWN_REACH_M } from '../../../src/nest/maps/maps.helpers'; +import { LEAD_TOWN_REACH_M } from '../../../src/nest/maps/maps-merge.helpers'; import type { PhotonLead } from '../../../src/nest/maps/providers/photon.mapping'; import { describe, it, expect } from 'vitest';