Files
TREK/server/src/nest/maps/providers/photon.mapping.ts
T
Maurice 4203dcd91f 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.
2026-10-30 16:52:12 +01:00

390 lines
14 KiB
TypeScript

/**
* Photon's answers in the shape Nominatim gives, so search and reverse read
* the same to every caller whichever of the two answered.
*
* Photon is a GeoJSON service: one feature per hit, the coordinate as
* [lon, lat], the OSM type as a letter and the address as flat properties.
* Nominatim names the type in full, spells the coordinate as text and carries
* 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 } from '../maps-merge.helpers';
import { toApiLang } from '../maps.helpers';
import type { NominatimResult, NominatimReverse } from './osm.client';
import type { MapsAutocompleteResult } from '@trek/shared';
import { z } from 'zod';
/** The languages the TREK services imported names for; anything else gets the names used on the spot. */
const PHOTON_LANGS: ReadonlySet<string> = new Set([
'ar',
'az',
'ca',
'cs',
'de',
'el',
'en',
'es',
'et',
'fr',
'hu',
'id',
'it',
'ja',
'ko',
'nl',
'pl',
'pt',
'ru',
'sk',
'sv',
'th',
'tr',
'uk',
'vi',
'zh',
]);
const OSM_TYPES: Readonly<Record<string, string>> = { N: 'node', W: 'way', R: 'relation' };
const text = z.string().optional();
const photonFeatureSchema = z.object({
geometry: z.object({ coordinates: z.array(z.number()).min(2) }),
properties: z.object({
osm_type: text,
osm_id: z.number().int().optional(),
osm_key: text,
osm_value: text,
type: text,
name: text,
housenumber: text,
street: text,
postcode: text,
locality: text,
district: text,
city: text,
county: text,
state: text,
country: text,
countrycode: text,
extra: z.record(z.string(), z.unknown()).optional(),
// [west, north, east, south], on areas only.
extent: z.array(z.number()).length(4).optional(),
}),
});
export const photonAnswerSchema = z.object({ features: z.array(photonFeatureSchema) });
export type PhotonFeature = z.infer<typeof photonFeatureSchema>;
type PhotonProperties = PhotonFeature['properties'];
type Suggestion = MapsAutocompleteResult['suggestions'][number];
/**
* The language Photon is asked in: TREK's code through toApiLang (`br` is
* Brazilian Portuguese, `gr` Greek), cut to its base (`pt-BR` to `pt`, `zh-TW`
* to `zh`). A language the import has no names for, or none at all, asks for
* `default`, the names written on the spot.
*/
export function photonLang(lang: string | undefined): string {
if (!lang?.trim()) return 'default';
const base = toApiLang(lang).split('-')[0].toLowerCase();
return PHOTON_LANGS.has(base) ? base : 'default';
}
/**
* The address line Nominatim calls `display_name`: the place's own name first,
* then house number and street as parts of their own ("12, Main Street", the
* way Nominatim writes them), quarter, town, county, region, postcode and
* country. A part that repeats one before it is left out, so Berlin reads
* "Berlin, Germany" rather than naming the city state twice.
*/
export function photonDisplayName(p: PhotonProperties): string {
const parts = [
p.name,
p.housenumber,
p.street,
p.district ?? p.locality,
p.city,
p.county,
p.state,
p.postcode,
p.country,
];
const seen = new Set<string>();
for (const part of parts) {
const value = part?.trim();
if (value) seen.add(value);
}
return [...seen].join(', ');
}
/** A search hit as Nominatim would have answered it, or null for one without an OpenStreetMap id. */
export function asNominatimHit(feature: PhotonFeature): NominatimResult | null {
const p = feature.properties;
const osmType = p.osm_type ? OSM_TYPES[p.osm_type] : undefined;
if (!osmType || p.osm_id === undefined) return null;
const [lon, lat] = feature.geometry.coordinates;
return {
osm_type: osmType,
osm_id: String(p.osm_id),
class: p.osm_key,
type: p.osm_value,
name: p.name,
display_name: photonDisplayName(p),
lat: String(lat),
lon: String(lon),
extratags: stringTags(p.extra),
};
}
/**
* A search hit as one row of the suggestion list, in the id form the details
* lookup reads (`node:123`, as the index's OpenStreetMap layer hands it over),
* or null for one without an id or a name to show.
*/
export function asSuggestion(feature: PhotonFeature): Suggestion | null {
const hit = asNominatimHit(feature);
const [lng, lat] = feature.geometry.coordinates;
if (!hit || !Number.isFinite(lat) || !Number.isFinite(lng)) return null;
// A house without a name is titled by its number, as Nominatim does, and
// the rest of the line says where it is.
const name = feature.properties.name?.trim();
const [head = '', ...rest] = suggestionLine(feature.properties);
const mainText = name || head;
if (!mainText) return null;
return {
placeId: `${hit.osm_type}:${hit.osm_id}`,
mainText,
secondaryText: (name ? [head, ...rest] : rest).filter(Boolean).join(', '),
source: 'openstreetmap',
lat,
lng,
};
}
/**
* Where a suggestion is, below its name: house number and street, quarter,
* town and country, and the region only where there is no town. Shorter than
* the address line on purpose. The rows of the index beside it read "Mitte,
* Germany", and a postcode or a county ("Троицкий муниципальный округ", which
* has no English name) next to them only made the list harder to read.
*/
function suggestionLine(p: PhotonProperties): string[] {
const name = p.name?.trim();
const parts = [p.housenumber, p.street, p.district ?? p.locality, p.city, p.city ? undefined : p.state, p.country];
const seen = new Set<string>(name ? [name] : []);
const line: string[] = [];
for (const part of parts) {
const value = part?.trim();
if (value && !seen.has(value)) {
seen.add(value);
line.push(value);
}
}
return line;
}
/**
* Photon's hits with notable places before their namesakes. Photon ranks an
* artwork called "Neuschwanstein" above the castle and a street called
* "Colosseum" above the monument; a Wikidata link marks the place people
* mean, and streets, unlinked shops and unlinked artworks step back. Photon's
* own order stays the base and breaks ties. Measured on 74 queries without a
* context, the first hit went from 68 % to 76 % right, and from 61 % to 73 %
* asked from a map somewhere else.
*/
export function rankFeatures(features: PhotonFeature[]): PhotonFeature[] {
return features
.map((feature, index) => ({ feature, index, score: notability(feature.properties) - index }))
.sort((a, b) => b.score - a.score || a.index - b.index)
.map(({ feature }) => feature);
}
function notability(p: PhotonProperties): number {
const linked = typeof p.extra?.wikidata === 'string';
let score = linked ? 2.5 : 0;
if (p.osm_key === 'highway') score -= 2.5;
if (!linked && (p.osm_key === 'shop' || p.osm_key === 'office' || p.osm_key === 'craft')) score -= 1.5;
if (!linked && p.osm_key === 'tourism' && p.osm_value === 'artwork') score -= 2;
return score;
}
/**
* The place a name stands for, which the result lists put first
* (`mergeRanked`): a country or a region, which is what its name means
* wherever the traveller is looking; a town, or a sight with a Wikidata link,
* which is what its name means from not too far away. The index beside Photon
* is a dataset of businesses and answers a town's name with shops that carry
* it, so without a lead "Tokyo" opened on a restaurant chain.
*/
export interface PhotonLead {
placeId: string;
name: string;
reach: 'everywhere' | 'nearby';
/** What it is: Photon's value for the place (`city`, `town`, `municipality`), or `landmark` for a sight. */
kind: string;
lat: number;
lng: number;
/** [west, north, east, south], or null where Photon gave none. */
extent: [number, number, number, number] | null;
}
const REGIONS = new Set(['country', 'state', 'province', 'region', 'territory']);
/** An island is what its name means too: Spitzbergen, Gran Canaria. */
const ISLANDS = new Set(['island', 'archipelago']);
/** The keys a sight is filed under; `landuse` is left out, it named a field in Italy "Eiffel". */
const SIGHT_KEYS = new Set([
'tourism',
'historic',
'aeroway',
'man_made',
'building',
'railway',
'natural',
'amenity',
'leisure',
'bridge',
'waterway',
]);
/** A three-letter code in capitals is an airport to a traveller, never the village or the country it spells. */
const AIRPORT_CODE = /^[A-Z]{3}$/;
export function asLead(feature: PhotonFeature): PhotonLead | null {
const p = feature.properties;
if (p.osm_key !== 'place' && p.osm_key !== 'boundary') return null;
const reach =
REGIONS.has(p.osm_value ?? '') || p.type === 'country' || p.type === 'state'
? 'everywhere'
: p.type === 'city' || p.type === 'county' || ISLANDS.has(p.osm_value ?? '')
? 'nearby'
: null;
const row = reach ? asSuggestion(feature) : null;
if (!row || !reach || row.lat === undefined || row.lng === undefined) return null;
return {
placeId: row.placeId,
name: row.mainText,
reach,
// A town filed as an administrative boundary (Mérida) is a town.
kind: (p.osm_key === 'boundary' ? p.type : p.osm_value) ?? p.type ?? 'place',
lat: row.lat,
lng: row.lng,
// The schema holds it to four numbers.
extent: (p.extent as PhotonLead['extent']) ?? null,
};
}
/** A sight as a lead: one with a Wikidata link, under a key sights are filed under. */
function asSightLead(feature: PhotonFeature): PhotonLead | null {
const p = feature.properties;
if (typeof p.extra?.wikidata !== 'string' || !SIGHT_KEYS.has(p.osm_key ?? '')) return null;
const row = asSuggestion(feature);
if (!row || row.lat === undefined || row.lng === undefined) return null;
return {
placeId: row.placeId,
name: row.mainText,
reach: 'nearby',
kind: 'landmark',
lat: row.lat,
lng: row.lng,
extent: null,
};
}
/**
* The lead of a Photon answer (ranked by `rankFeatures`), or null. A country
* or a region in first place leads under any name, which keeps an exonym
* ("Mauretanien" answers Mauritania); anything else among the first three
* leads only when it is called what was typed, or a typo of it, when it may
* lead from where the traveller is looking (`leadsHere`), and when no
* namesake ranks above it. Without the name check "Paramraibo" opened on a
* district called Centrum and "Sagrada Familia" on a municipality in Brazil.
*/
export function pickLead(
features: PhotonFeature[],
query: string,
bias?: { lat: number; lng: number },
): PhotonLead | null {
if (AIRPORT_CODE.test(query.trim())) return null;
const first = features[0] ? asLead(features[0]) : null;
if (first?.reach === 'everywhere') return first;
for (const feature of features.slice(0, 3)) {
const lead = asLead(feature) ?? asSightLead(feature);
const named = nameLike(query, lead?.name ?? feature.properties.name ?? '');
if (lead && named && leadsHere(lead, bias)) return lead;
// A place of that name Photon ranks higher and that may not lead (the
// borough of Greenwich in London, a quarter, a municipality with nothing
// to say where the traveller is) outranks the ones behind it: leading with
// the next Greenwich put the town in Connecticut above London. A street or
// a shop of the name does not.
if (named && (feature.properties.osm_key === 'place' || feature.properties.osm_key === 'boundary')) return null;
}
return null;
}
/** Whether a name is what was typed: the same, the start of it, a word of it, or a typo away. */
export function nameLike(query: string, name: string): boolean {
const typed = foldName(query);
const called = foldName(name);
if (typed.length < 3 || !called) return false;
if (called.startsWith(typed) || typed.startsWith(called) || called.includes(` ${typed}`)) return true;
return editDistance(typed, called) <= (typed.length >= 8 ? 2 : 1);
}
/**
* Edits between two strings, a swap of neighbours counting as one: the
* optimal string alignment distance. "Paramraibo" is one from "Paramaribo".
*/
export function editDistance(a: string, b: string): number {
if (Math.abs(a.length - b.length) > 2) return 3;
const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array<number>(b.length).fill(0)]);
for (let j = 1; j <= b.length; j++) d[0][j] = j;
for (let i = 1; i <= a.length; i++) {
for (let j = 1; j <= b.length; j++) {
const cost = a[i - 1] === b[j - 1] ? 0 : 1;
d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost);
if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1])
d[i][j] = Math.min(d[i][j], d[i - 2][j - 2] + 1);
}
}
return d[a.length][b.length];
}
/**
* The point a reverse lookup found, in the fields Nominatim's reverse answer
* has. A town itself is its own `city`, and a named place is filed under its
* main tag the way Nominatim files it (`tourism` for the Eiffel Tower), so the
* readers that look for a sight's name before the road find it here too.
*/
export function asNominatimReverse(feature: PhotonFeature): NominatimReverse {
const p = feature.properties;
const address: Record<string, string> = {};
const put = (key: string, value: string | undefined): void => {
if (value?.trim() && !(key in address)) address[key] = value.trim();
};
put('road', p.street);
put('house_number', p.housenumber);
put('postcode', p.postcode);
put('suburb', p.district ?? p.locality);
put('city', p.type === 'city' ? p.name : p.city);
put('county', p.county);
put('state', p.state);
put('country', p.country);
put('country_code', p.countrycode?.toLowerCase());
if (p.osm_key && p.type !== 'city') put(p.osm_key, p.name);
const displayName = photonDisplayName(p);
return { display_name: displayName || undefined, name: p.name, address };
}
/** The extra tags Photon passes through, the text ones only. */
function stringTags(extra: Record<string, unknown> | undefined): Record<string, string> | null {
if (!extra) return null;
const tags: Record<string, string> = {};
for (const [key, value] of Object.entries(extra)) {
if (typeof value === 'string') tags[key] = value;
}
return tags;
}