gedcom-ts 2026.5.0 → 2026.5.1

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes of gedcom-ts
 
 ## [Unreleased]
 
+### Added
+
+- **`src/geocode/`** : géocodage Nominatim (`GET /search?q=…&format=jsonv2`), contexte arbre (`inferGeocodeContext`), ranking (`rankGeocodeCandidates`), harmonisation des lieux (`findHarmonizationClusters`, `applyGeocodeCandidateToActs`), utilitaires ville (`normalizeCityKey`, `findCanonicalCityLabel`). `fetch` et `User-Agent` configurables pour les tests.
+
+### Changed
+
+- **`getCityCoordinates`** : marqué `@deprecated` ; utilise la nouvelle API Nominatim (plus `search.php?city=` ni `XMLHttpRequest`).
+
 ## [2026.5.0] - 2026-05-15
 
 ### Versioning

package/README.md

@@ -492,18 +492,32 @@ import { remainingTypesAct, Acts } from "gedcom-ts";
 const available = remainingTypesAct(new Acts());
 ```
 
-#### `getCityCoordinates(cityName, callback)`
+#### Geocoding (Nominatim)
 
-Queries OpenStreetMap’s Nominatim API and returns a list of candidate `Place` objects with coordinates. Browser-only (uses `XMLHttpRequest`).
+Place search uses the official Nominatim endpoint `GET https://nominatim.openstreetmap.org/search` with `q`, `format=jsonv2`, and `addressdetails=1` (not the legacy `search.php?city=` API). A `User-Agent` header is required (`gedcom-ts/<version> (genealogy library)` by default).
 
 ```ts
-import { getCityCoordinates } from "gedcom-ts";
+import {
+  inferGeocodeContext,
+  searchPlacesWithContext,
+  rankGeocodeCandidates,
+  findHarmonizationClusters,
+  applyGeocodeCandidateToActs,
+} from "gedcom-ts";
 
-getCityCoordinates("Paris", (places) => {
-  console.log(places[0]?.coordinate.latitude, places[0]?.coordinate.longitude);
-});
+const context = inferGeocodeContext(ged);
+const candidates = await searchPlacesWithContext("Valence", context);
+// candidates are ranked (French tree → Valence FR before ES)
+
+const clusters = findHarmonizationClusters(ged);
 ```
 
+For tests or Node without a global `fetch`, pass `fetchFn` in options. Low-level API: `searchPlaces(query, { countryCodes, limit, userAgent, fetchFn })`.
+
+#### `getCityCoordinates(cityName, callback)` (deprecated)
+
+Legacy callback API; delegates to `searchPlaces` and maps results to `Place[]`. Prefer `searchPlaces` / `searchPlacesWithContext`.
+
 #### `resolveDatasetVersion(headerLines)` / `GedcomDatasetVersion`
 
 Inspects the lines of a `0 HEAD` block and returns `"7.0"`, `"5.5"` or `"unknown"`. Useful to branch UI behaviour for legacy datasets.

package/dist/geocode/index.d.ts

@@ -0,0 +1,3 @@
+export { normalizeCityKey, tidyCityDisplay, findCanonicalCityLabel, } from "./place-city-utils";
+export { type GeocodeCandidate, type GeocodeContext, type GeocodeFetchFn, type GeocodeSearchOptions, NOMINATIM_SEARCH_URL, defaultGeocodeUserAgent, parseCityQuery, countryLabelToIso, isoToCountryLabel, inferGeocodeContext, buildGeocodeQuery, geocodeContextWithHint, rankGeocodeCandidates, searchPlaces, searchPlacesWithContext, } from "./place-geocode";
+export { type CoordVariant, type CityHarmonizationCluster, levenshteinDistance, citiesAreSimilar, clusterKeyForCity, findHarmonizationClustersFromActs, findHarmonizationClusters, applyCoordinatesToActs, applyGeocodeCandidateToActs, } from "./place-clusters";

package/dist/geocode/place-city-utils.d.ts

@@ -0,0 +1,11 @@
+import type { Act } from "../commons/Act";
+import type { ReadGed } from "../import/ReadGed";
+/** Clé de regroupement : casse, espaces, compatibilité Unicode (NFKC). */
+export declare function normalizeCityKey(city: string): string;
+/** Libellé affiché : trim + espaces internes unifiés (sans forcer la casse). */
+export declare function tidyCityDisplay(city: string): string;
+/**
+ * Harmonise l’écriture avec le reste de l’arbre : même clé normalisée → libellé le plus fréquent
+ * (exclut l’acte en cours d’édition pour le décompte).
+ */
+export declare function findCanonicalCityLabel(ged: ReadGed, cityInput: string, excludeAct: Act | null): string;

package/dist/geocode/place-clusters.d.ts

@@ -0,0 +1,34 @@
+import type { Act } from "../commons/Act";
+import type { ReadGed } from "../import/ReadGed";
+import { type GeocodeCandidate } from "./place-geocode";
+export interface CoordVariant {
+    readonly lat: number;
+    readonly lng: number;
+    readonly actCount: number;
+}
+/** Groupe de lieux similaires à harmoniser (libellés ou coordonnées divergents). */
+export interface CityHarmonizationCluster {
+    readonly clusterKey: string;
+    readonly labels: readonly string[];
+    readonly coordVariants: readonly CoordVariant[];
+    readonly acts: readonly Act[];
+    readonly actsWithoutCoord: number;
+}
+/** Distance de Levenshtein (petites chaînes de noms de villes). */
+export declare function levenshteinDistance(a: string, b: string): number;
+/** Ville proche : même clé, faute légère, ou inclusion évidente (Saint-X / St-X). */
+export declare function citiesAreSimilar(a: string, b: string): boolean;
+/**
+ * Regroupe les actes dont les villes se ressemblent (libellés uniques + clés normalisées).
+ * Complexité ~ O(m²) sur le nombre de villes distinctes, pas sur le nombre d’actes.
+ */
+export declare function findHarmonizationClustersFromActs(acts: readonly Act[]): CityHarmonizationCluster[];
+/** Analyse toute l’arbre (préférer {@link findHarmonizationClustersFromActs} sur un sous-ensemble). */
+export declare function findHarmonizationClusters(ged: ReadGed): CityHarmonizationCluster[];
+export declare function applyCoordinatesToActs(acts: readonly Act[], lat: number, lng: number, patch?: {
+    city?: string;
+    country?: string | null;
+}): void;
+export declare function applyGeocodeCandidateToActs(acts: readonly Act[], candidate: GeocodeCandidate, preferredCityLabel?: string): void;
+/** Clé de regroupement carte : villes similaires → un marqueur. */
+export declare function clusterKeyForCity(city: string): string;

package/dist/geocode/place-geocode.d.ts

@@ -0,0 +1,50 @@
+import type { ReadGed } from "../import/ReadGed";
+/** Résultat Nominatim présenté à l’utilisateur. */
+export interface GeocodeCandidate {
+    readonly label: string;
+    readonly shortLabel: string;
+    readonly lat: number;
+    readonly lng: number;
+    readonly country: string | null;
+    readonly countryCode: string | null;
+    readonly region: string | null;
+    readonly kind: string | null;
+    readonly importance: number;
+}
+export interface GeocodeContext {
+    /** Codes ISO 3166-1 alpha-2 (ex. `fr`), du plus au moins probable. */
+    readonly countryCodes: readonly string[];
+    readonly defaultCountryLabel: string | null;
+    readonly centroid: {
+        lat: number;
+        lng: number;
+    } | null;
+}
+export type GeocodeFetchFn = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export interface GeocodeSearchOptions {
+    readonly countryCodes?: readonly string[];
+    readonly limit?: number;
+    /** Défaut : `gedcom-ts/<version> (genealogy library)` */
+    readonly userAgent?: string;
+    /** Client HTTP injectable (tests, Node sans fetch global). */
+    readonly fetchFn?: GeocodeFetchFn;
+}
+export declare const NOMINATIM_SEARCH_URL = "https://nominatim.openstreetmap.org/search";
+export declare function defaultGeocodeUserAgent(): string;
+/** Parse « Valence », « Valence, Drôme », « Valence, France ». */
+export declare function parseCityQuery(raw: string): {
+    city: string;
+    countryHint: string | null;
+};
+export declare function countryLabelToIso(label: string): string | null;
+export declare function isoToCountryLabel(code: string | null | undefined): string | null;
+/** Contexte géographique déduit de l’arbre (pays et centroïde des lieux déjà géolocalisés). */
+export declare function inferGeocodeContext(ged: ReadGed | null): GeocodeContext;
+export declare function buildGeocodeQuery(cityInput: string, context: GeocodeContext, extraCountryHint?: string | null): string;
+/** Priorise le pays saisi par l’utilisateur pour filtre Nominatim et classement. */
+export declare function geocodeContextWithHint(context: GeocodeContext, extraCountryHint?: string | null): GeocodeContext;
+/** Trie les candidats : pays de l’arbre, proximité du centroïde, correspondance du nom. */
+export declare function rankGeocodeCandidates(candidates: GeocodeCandidate[], cityInput: string, context: GeocodeContext): GeocodeCandidate[];
+export declare function searchPlaces(query: string, options?: GeocodeSearchOptions): Promise<GeocodeCandidate[]>;
+/** Recherche avec repli sans filtre pays si trop peu de résultats. */
+export declare function searchPlacesWithContext(cityInput: string, context: GeocodeContext, extraCountryHint?: string | null, options?: GeocodeSearchOptions): Promise<GeocodeCandidate[]>;