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[]>;