@mailwoman/nominatim 4.15.1

package/README.md

@@ -0,0 +1,54 @@
+# @mailwoman/nominatim
+
+A **Nominatim-compatible HTTP geocoding API** over the [Mailwoman](https://mailwoman.sister.software) engine. Point an existing Nominatim client at it and forward + reverse geocoding work — no PostgreSQL, no `osm2pgsql` import.
+
+```bash
+npx @mailwoman/nominatim serve --port 8080 --data <gazetteer-or-bundle>
+```
+
+```python
+from geopy.geocoders import Nominatim
+
+geo = Nominatim(domain="localhost:8080", scheme="http")
+geo.geocode("1600 Pennsylvania Ave NW, Washington DC", addressdetails=True)
+geo.reverse((38.8977, -77.0365))
+```
+
+## Endpoints
+
+| Endpoint   | Nominatim contract                                       | Status  |
+| ---------- | -------------------------------------------------------- | ------- |
+| `/search`  | free-text `q` + structured forward geocoding             | ✓       |
+| `/reverse` | `lat`/`lon` → nearest address (`WofReverseGeocoder` PIP) | ✓       |
+| `/status`  | health + data version                                    | ✓       |
+| `/lookup`  | resolve known place ids                                  | planned |
+
+## Library use
+
+The package is engine-agnostic — embed it in your own server:
+
+```ts
+import express from "express"
+import { createNominatimRouter, type NominatimEngine } from "@mailwoman/nominatim"
+
+const engine: NominatimEngine = {
+	/* search, reverse, lookup, status — backed by your Mailwoman pipeline */
+}
+express().use(createNominatimRouter(engine)).listen(8080)
+```
+
+## Annotations
+
+Every result carries an OpenCage-style `annotations` block — coordinate formats (DMS, MGRS, geohash,
+Maidenhead, Mercator), qibla bearing, sun times, country flag, calling code, and currency, plus the IANA
+timezone, UN/LOCODE, and EU NUTS codes when their data bundles are present. Plain Nominatim returns none
+of these.
+
+## Status
+
+Shipped. `/search` and `/reverse` resolve over the live engine and return the enriched block; `/lookup`
+is not yet implemented (returns `501`). `addressdetails` goes down to the house number and road when the
+query carries them — `1600 Pennsylvania Avenue NW, Washington, DC 20500` resolves to the rooftop
+(`38.897, -77.037`) with `house_number`, `road`, `city`, `state`, `postcode`, and `country_code`.
+
+For autocomplete / type-ahead, see the companion [`@mailwoman/photon`](../photon).

package/out/cli.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman-nominatim` — boot a Nominatim-compatible endpoint via the `serve` command. Usage +
+ *   examples live in the package README.
+ *
+ *   Wires the real engine: `/search` over `geocodeAddress` (parse → resolve), `/reverse` over
+ *   `WofReverseGeocoder` (point-in-polygon over WOF admin polygons), reusing the same
+ *   resolver-backend selector GeocodeRouter uses. Results carry the OpenCage-style `annotations`
+ *   block — coordinate formats, flag, calling code, currency, and (when their DBs are present)
+ *   timezone, UN/LOCODE, NUTS — composed from the `@mailwoman/*` annotators.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/out/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;GAaG"}

package/out/cli.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman-nominatim` — boot a Nominatim-compatible endpoint via the `serve` command. Usage +
+ *   examples live in the package README.
+ *
+ *   Wires the real engine: `/search` over `geocodeAddress` (parse → resolve), `/reverse` over
+ *   `WofReverseGeocoder` (point-in-polygon over WOF admin polygons), reusing the same
+ *   resolver-backend selector GeocodeRouter uses. Results carry the OpenCage-style `annotations`
+ *   block — coordinate formats, flag, calling code, currency, and (when their DBs are present)
+ *   timezone, UN/LOCODE, NUTS — composed from the `@mailwoman/*` annotators.
+ */
+import { composeAnnotators, toOpenCage } from "@mailwoman/annotations";
+import { countryReferenceAnnotator, matchCountry } from "@mailwoman/codex/country";
+import { NeuralAddressClassifier } from "@mailwoman/neural";
+import { makeNutsAnnotator, NutsLookup } from "@mailwoman/nuts-lookup";
+import { createWofResolver } from "@mailwoman/resolver";
+import { coordinateFormatAnnotator } from "@mailwoman/spatial";
+import { makeTimezoneAnnotator, TimezoneLookup } from "@mailwoman/timezone-lookup";
+import { makeUnLocodeAnnotator, UnLocodeLookup } from "@mailwoman/un-locode-lookup";
+import express from "express";
+import { createAddressParser } from "mailwoman";
+import { geocodeAddress, ShardProvider } from "mailwoman/geocode-core";
+import { createResolverBackend, mailwomanDataRoot, resolveCandidateDbPath, wofShardPaths, } from "mailwoman/resolver-backend";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { parseArgs } from "node:util";
+import { createNominatimRouter, toNominatimResult, } from "./index.js";
+/** WOF placetype → Nominatim address key. */
+const PLACETYPE_TO_KEY = {
+    venue: "road",
+    street: "road",
+    locality: "city",
+    localadmin: "city",
+    borough: "city_district",
+    neighbourhood: "suburb",
+    county: "county",
+    region: "state",
+    macroregion: "state",
+    country: "country",
+};
+/**
+ * A real address fits comfortably; anything longer is malformed input (and would exceed the model's
+ * input window). Cap defensively so a giant query returns no results instead of faulting.
+ */
+const MAX_QUERY_LEN = 512;
+function joinNonEmpty(...parts) {
+    return parts.filter(Boolean).join(", ");
+}
+/**
+ * The resolver returns admin labels + a coordinate (often rooftop/interpolated via the situs
+ * shards) but drops the street. Recover house_number + road from the parse so the result carries
+ * the full address — Nominatim populates both `addressdetails` and `display_name` down to the house
+ * number.
+ */
+async function streetParts(parser, query) {
+    const solution = (await parser.parse(query, { verbose: true })).solutions[0];
+    const matches = solution?.toJSON()?.matches ?? [];
+    return {
+        houseNumber: matches.find((m) => m.classification === "house_number")?.value,
+        road: matches.find((m) => m.classification === "street")?.value,
+    };
+}
+/** Map a forward geocode result (admin + coordinate) into the formatter's neutral shape. */
+function forwardToResolved(r) {
+    const address = {};
+    if (r.locality)
+        address.city = r.locality;
+    if (r.region)
+        address.state = r.region;
+    if (r.postcode)
+        address.postcode = r.postcode;
+    for (const h of r.hierarchy) {
+        if (h.tag === "country")
+            address.country = h.value;
+    }
+    return {
+        lat: r.lat,
+        lon: r.lon,
+        address,
+        displayName: joinNonEmpty(address.city, address.state, address.postcode, address.country) || r.input,
+    };
+}
+async function serve() {
+    const { values } = parseArgs({
+        options: {
+            port: { type: "string", default: "8080" },
+            host: { type: "string", default: "0.0.0.0" },
+            data: { type: "string" },
+        },
+        allowPositionals: true,
+    });
+    const port = Number(values.port) || 8080;
+    const host = values.host ?? "0.0.0.0";
+    const resolverMod = await import("@mailwoman/resolver-wof-sqlite");
+    const wofPaths = wofShardPaths().filter(existsSync);
+    const adminDbPath = wofPaths[0];
+    const classifier = await NeuralAddressClassifier.loadFromWeights({ locale: "en-US" });
+    const parser = createAddressParser();
+    const backend = createResolverBackend(resolverMod, { wofPaths });
+    const resolver = createWofResolver(backend);
+    const shards = new ShardProvider(resolverMod, mailwomanDataRoot());
+    // NOT a geocode country constraint. The default-on #244 placer already routes the query's country
+    // (Berlin→DE, Boston→US) and `defaultCountry` is a HARD override that beats it (geocode-core.ts:102),
+    // so forcing "US" resolved every non-US query to its US namesake (Berlin→Berlin NH). We let the
+    // placer decide instead. This is the fallback used ONLY to annotate the flag/currency/calling-code
+    // when the resolved hierarchy omits the country tag — which on US-centric data (no candidate DB)
+    // happens for US results, where "US" is the right guess. Non-US results carry the country tag, so
+    // the fallback never mislabels them.
+    const annotationCountryFallback = resolveCandidateDbPath() ? undefined : "US";
+    const reverseGeo = adminDbPath ? new resolverMod.WofReverseGeocoder({ adminDbPath }) : undefined;
+    const annotators = [coordinateFormatAnnotator, countryReferenceAnnotator];
+    const tzDbPath = join(mailwomanDataRoot(), "timezone", "timezone.db");
+    if (existsSync(tzDbPath))
+        annotators.push(makeTimezoneAnnotator(new TimezoneLookup({ databasePath: tzDbPath })));
+    const ulDbPath = join(mailwomanDataRoot(), "un-locode", "un-locode.db");
+    if (existsSync(ulDbPath))
+        annotators.push(makeUnLocodeAnnotator(new UnLocodeLookup({ databasePath: ulDbPath })));
+    const nutsDbPath = join(mailwomanDataRoot(), "nuts", "nuts.db");
+    if (existsSync(nutsDbPath))
+        annotators.push(makeNutsAnnotator(new NutsLookup({ databasePath: nutsDbPath })));
+    const annotate = composeAnnotators(annotators);
+    const engine = {
+        async search(params) {
+            const query = (params.q ?? joinNonEmpty(params.street, params.city, params.state, params.postalcode, params.country))?.trim();
+            // Empty/whitespace → no query; absurdly long → not an address (and would blow the model's input).
+            if (!query || query.length > MAX_QUERY_LEN)
+                return [];
+            // A caller-supplied `countrycodes` is an explicit hard restriction (Nominatim semantics): honor
+            // it as the country constraint, even to the point of no result. It doubles as the manual override
+            // for the #822 placer frontier — `countrycodes=au` lands Sydney in Australia. One country is the
+            // common (geopy) case; for a list we apply the first.
+            const userCountry = params.countrycodes?.[0]?.toUpperCase();
+            const result = await geocodeAddress(query, {
+                classifier,
+                resolver,
+                shards: shards.for,
+                defaultCountry: userCountry,
+            });
+            if (result.lat == null || result.lon == null)
+                return [];
+            const resolved = forwardToResolved(result);
+            // Recover the street the resolver drops, so addressdetails + display_name carry it.
+            const { houseNumber, road } = await streetParts(parser, query);
+            if (houseNumber)
+                resolved.address.house_number = houseNumber;
+            if (road)
+                resolved.address.road = road;
+            // The country tag isn't always in the hierarchy (US admin results omit it); backfill from the
+            // US-centric-data default so the address, display_name, and flag/currency/calling-code agree.
+            const countryName = result.hierarchy.find((h) => h.tag === "country")?.value ?? annotationCountryFallback;
+            const country = matchCountry(countryName);
+            if (country) {
+                if (!resolved.address.country)
+                    resolved.address.country = country.canonical;
+                resolved.address.country_code = country.iso2.toLowerCase();
+            }
+            if (houseNumber || road) {
+                resolved.displayName =
+                    joinNonEmpty(houseNumber, road, resolved.address.city, resolved.address.state, resolved.address.postcode, resolved.address.country) || resolved.displayName;
+            }
+            const out = toNominatimResult(resolved, { addressdetails: params.addressdetails });
+            out.annotations = toOpenCage(await annotate({
+                lat: result.lat,
+                lon: result.lon,
+                countryCode: country?.iso2,
+                placeName: result.locality ?? undefined,
+            }));
+            return [out].slice(0, params.limit);
+        },
+        async reverse(params) {
+            if (!reverseGeo)
+                return null;
+            const { hierarchy } = await reverseGeo.reverseGeocode(params.lat, params.lon);
+            if (hierarchy.length === 0)
+                return null;
+            const address = {};
+            for (const place of hierarchy) {
+                const key = PLACETYPE_TO_KEY[place.placetype];
+                if (key && !address[key])
+                    address[key] = place.name;
+            }
+            const deepest = hierarchy[0];
+            if (deepest.country)
+                address.country_code = deepest.country.toLowerCase();
+            const resolved = {
+                lat: params.lat,
+                lon: params.lon,
+                address,
+                displayName: hierarchy.map((p) => p.name).join(", "),
+                placeId: deepest.id,
+                boundingbox: deepest.bbox
+                    ? [
+                        String(deepest.bbox.minLat),
+                        String(deepest.bbox.maxLat),
+                        String(deepest.bbox.minLon),
+                        String(deepest.bbox.maxLon),
+                    ]
+                    : undefined,
+            };
+            const out = toNominatimResult(resolved, { addressdetails: params.addressdetails });
+            out.annotations = toOpenCage(await annotate({ lat: params.lat, lon: params.lon, countryCode: address.country_code }));
+            return out;
+        },
+        async status() {
+            return { status: 0, message: "OK" };
+        },
+    };
+    express()
+        .use(createNominatimRouter(engine))
+        .listen(port, host, () => {
+        console.error(`[@mailwoman/nominatim] listening on http://${host}:${port}`);
+        console.error(`  wof: ${adminDbPath ?? "(none found — set MAILWOMAN_WOF_DB)"}`);
+        console.error(`  endpoints: GET /search  GET /reverse  GET /lookup  GET /status`);
+    });
+}
+const command = process.argv[2];
+switch (command) {
+    case "serve":
+        await serve();
+        break;
+    default:
+        console.error("Usage: mailwoman-nominatim serve [--port 8080] [--host 0.0.0.0] [--data <path>]");
+        process.exit(command ? 1 : 0);
+}
+//# sourceMappingURL=cli.js.map

package/out/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../cli.ts"],"names":[],"mappings":"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"}

package/out/index.d.ts

@@ -0,0 +1,147 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/nominatim` — a Nominatim-compatible HTTP geocoding API over the Mailwoman engine.
+ *
+ *   The package is intentionally engine-agnostic: {@link createNominatimRouter} takes a
+ *   {@link NominatimEngine} (the thing that actually parses + resolves) and exposes it under the
+ *   endpoint shapes + response format a Nominatim client expects. The CLI (`./cli.ts`) wires the
+ *   real Mailwoman engine; tests can inject a fake. This keeps the compat surface isolated from the
+ *   resolver wiring.
+ *
+ *   Implementation is staged across the epic (#801): #804 the result formatter, #802 `/search`, #803
+ *   `/reverse`, #805 `/lookup` + `/status`. Routes whose engine method is absent answer `501`.
+ */
+import type { OpenCageAnnotations } from "@mailwoman/annotations";
+import { Router } from "express";
+/** Output serialization formats Nominatim supports. `jsonv2` is the modern default. */
+export type NominatimFormat = "jsonv2" | "json" | "geojson";
+/**
+ * The structured address breakdown returned under `address` when `addressdetails=1`. Keys mirror
+ * Nominatim's OSM-derived tag names; populated from Mailwoman's `ComponentTag` / resolved ancestor
+ * lineage (mapping owned by #804).
+ */
+export interface NominatimAddressDetails {
+    house_number?: string;
+    road?: string;
+    neighbourhood?: string;
+    suburb?: string;
+    city?: string;
+    town?: string;
+    village?: string;
+    county?: string;
+    state?: string;
+    postcode?: string;
+    country?: string;
+    country_code?: string;
+    [key: string]: string | undefined;
+}
+/** A single Nominatim result object (the shape geopy and friends parse). */
+export interface NominatimResult {
+    place_id: number | string;
+    licence: string;
+    osm_type?: string;
+    osm_id?: number | string;
+    lat: string;
+    lon: string;
+    display_name: string;
+    /** `[south, north, west, east]` as strings, per Nominatim. */
+    boundingbox?: [string, string, string, string];
+    class?: string;
+    type?: string;
+    importance?: number;
+    place_rank?: number;
+    address?: NominatimAddressDetails;
+    /** Present when `format=geojson` or `polygon_geojson=1`. */
+    geojson?: unknown;
+    /** OpenCage-style enrichment block (timezone, coordinate formats, …); attached by the engine. */
+    annotations?: OpenCageAnnotations;
+}
+/** Parsed `/search` parameters (free-text OR structured; never both). */
+export interface NominatimSearchParams {
+    q?: string;
+    street?: string;
+    city?: string;
+    county?: string;
+    state?: string;
+    country?: string;
+    postalcode?: string;
+    countrycodes?: string[];
+    limit: number;
+    viewbox?: [number, number, number, number];
+    bounded?: boolean;
+    addressdetails?: boolean;
+    format: NominatimFormat;
+    acceptLanguage?: string;
+}
+/** Parsed `/reverse` parameters. */
+export interface NominatimReverseParams {
+    lat: number;
+    lon: number;
+    zoom?: number;
+    addressdetails?: boolean;
+    format: NominatimFormat;
+    acceptLanguage?: string;
+}
+/** Parsed `/lookup` parameters. */
+export interface NominatimLookupParams {
+    osmIds: string[];
+    addressdetails?: boolean;
+    format: NominatimFormat;
+}
+/** Nominatim `/status` payload. */
+export interface NominatimStatus {
+    status: number;
+    message: string;
+    data_updated?: string;
+}
+/**
+ * The geocoding engine the router delegates to. Each method is optional; a route whose method is
+ * not provided answers `501 Not Implemented`. The real implementation (Mailwoman parse → resolve,
+ * plus `WofReverseGeocoder`) is wired by the CLI and fleshed out across #802–#805.
+ */
+export interface NominatimEngine {
+    search?(params: NominatimSearchParams): Promise<NominatimResult[]>;
+    reverse?(params: NominatimReverseParams): Promise<NominatimResult | null>;
+    lookup?(params: NominatimLookupParams): Promise<NominatimResult[]>;
+    status?(): Promise<NominatimStatus>;
+}
+/**
+ * Build the Nominatim-compatible router around an injected {@link NominatimEngine}. Query-param
+ * parsing lives here; the result _formatting_ (jsonv2 vs geojson envelope, `address` projection) is
+ * #804 and currently passes the engine's results through verbatim.
+ */
+export declare function createNominatimRouter(engine: NominatimEngine): Router;
+/**
+ * A resolved address in a neutral shape, the input to {@link toNominatimResult}. The engine maps its
+ * native geocode/reverse result into this; the formatter renders it as a Nominatim result. This is
+ * the #804 mapping seam, kept dependency-free (no `@mailwoman/*` import) so it stays
+ * unit-testable.
+ */
+export interface ResolvedAddress {
+    lat: number | null;
+    lon: number | null;
+    address: NominatimAddressDetails;
+    /** Pre-rendered display name; falls back to the address values joined by ", ". */
+    displayName?: string;
+    category?: string;
+    type?: string;
+    importance?: number;
+    placeRank?: number;
+    boundingbox?: [string, string, string, string];
+    /** A stable id from the resolver (WOF/GERS); a deterministic hash is used when absent. */
+    placeId?: string | number;
+}
+/** The attribution string emitted as `licence` (the data sources Mailwoman resolves over). */
+export declare const MAILWOMAN_LICENCE = "Data \u00A9 Who's On First, Overture Maps, OpenAddresses, US Census TIGER";
+/**
+ * Render a {@link ResolvedAddress} as a Nominatim result. `addressdetails` gates the `address`
+ * block, matching Nominatim. The `annotations` block is attached by the caller (empty until the
+ * annotations layer lands).
+ */
+export declare function toNominatimResult(r: ResolvedAddress, opts?: {
+    addressdetails?: boolean;
+}): NominatimResult;
+//# sourceMappingURL=index.d.ts.map

package/out/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"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"}

package/out/index.js

@@ -0,0 +1,159 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `@mailwoman/nominatim` — a Nominatim-compatible HTTP geocoding API over the Mailwoman engine.
+ *
+ *   The package is intentionally engine-agnostic: {@link createNominatimRouter} takes a
+ *   {@link NominatimEngine} (the thing that actually parses + resolves) and exposes it under the
+ *   endpoint shapes + response format a Nominatim client expects. The CLI (`./cli.ts`) wires the
+ *   real Mailwoman engine; tests can inject a fake. This keeps the compat surface isolated from the
+ *   resolver wiring.
+ *
+ *   Implementation is staged across the epic (#801): #804 the result formatter, #802 `/search`, #803
+ *   `/reverse`, #805 `/lookup` + `/status`. Routes whose engine method is absent answer `501`.
+ */
+import { Router } from "express";
+const DEFAULT_LIMIT = 10;
+function parseFormat(raw) {
+    return raw === "geojson" || raw === "json" ? raw : "jsonv2";
+}
+function parseBool(raw) {
+    return raw === "1" || raw === "true";
+}
+function asString(raw) {
+    return typeof raw === "string" && raw.length > 0 ? raw : undefined;
+}
+/**
+ * Build the Nominatim-compatible router around an injected {@link NominatimEngine}. Query-param
+ * parsing lives here; the result _formatting_ (jsonv2 vs geojson envelope, `address` projection) is
+ * #804 and currently passes the engine's results through verbatim.
+ */
+export function createNominatimRouter(engine) {
+    const router = Router();
+    const search = async (req, res) => {
+        if (!engine.search) {
+            res.status(501).json({ error: "search not implemented (see #802)" });
+            return;
+        }
+        const q = req.query;
+        const params = {
+            q: asString(q["q"]),
+            street: asString(q["street"]),
+            city: asString(q["city"]),
+            county: asString(q["county"]),
+            state: asString(q["state"]),
+            country: asString(q["country"]),
+            postalcode: asString(q["postalcode"]),
+            countrycodes: asString(q["countrycodes"])?.split(","),
+            limit: Number(q["limit"] ?? DEFAULT_LIMIT) || DEFAULT_LIMIT,
+            bounded: parseBool(q["bounded"]),
+            addressdetails: parseBool(q["addressdetails"]),
+            format: parseFormat(q["format"]),
+            acceptLanguage: asString(q["accept-language"]),
+        };
+        res.json(await engine.search(params));
+    };
+    const reverse = async (req, res) => {
+        if (!engine.reverse) {
+            res.status(501).json({ error: "reverse not implemented (see #803)" });
+            return;
+        }
+        const q = req.query;
+        const lat = Number(q["lat"]);
+        const lon = Number(q["lon"]);
+        if (!Number.isFinite(lat) || !Number.isFinite(lon)) {
+            res.status(400).json({ error: "lat and lon are required" });
+            return;
+        }
+        if (lat < -90 || lat > 90 || lon < -180 || lon > 180) {
+            res.status(400).json({ error: "lat must be in [-90, 90] and lon in [-180, 180]" });
+            return;
+        }
+        const params = {
+            lat,
+            lon,
+            zoom: q["zoom"] != null ? Number(q["zoom"]) : undefined,
+            addressdetails: parseBool(q["addressdetails"]),
+            format: parseFormat(q["format"]),
+            acceptLanguage: asString(q["accept-language"]),
+        };
+        res.json(await engine.reverse(params));
+    };
+    const lookup = async (req, res) => {
+        if (!engine.lookup) {
+            res.status(501).json({ error: "lookup not implemented (see #805)" });
+            return;
+        }
+        const params = {
+            osmIds: asString(req.query["osm_ids"])?.split(",") ?? [],
+            addressdetails: parseBool(req.query["addressdetails"]),
+            format: parseFormat(req.query["format"]),
+        };
+        res.json(await engine.lookup(params));
+    };
+    const status = async (_req, res) => {
+        if (!engine.status) {
+            res.json({ status: 0, message: "OK" });
+            return;
+        }
+        res.json(await engine.status());
+    };
+    // Safety net: a malformed query (whitespace-only, absurdly long, control chars) or an engine fault
+    // must never crash the process into a stack-trace 500. Wrap every handler so an unexpected throw
+    // becomes a clean JSON error.
+    const safe = (fn) => async (req, res, next) => {
+        try {
+            await fn(req, res, next);
+        }
+        catch {
+            if (!res.headersSent)
+                res.status(500).json({ error: "internal error" });
+        }
+    };
+    router.get("/search", safe(search));
+    router.get("/reverse", safe(reverse));
+    router.get("/lookup", safe(lookup));
+    router.get("/status", safe(status));
+    return router;
+}
+/** The attribution string emitted as `licence` (the data sources Mailwoman resolves over). */
+export const MAILWOMAN_LICENCE = "Data © Who's On First, Overture Maps, OpenAddresses, US Census TIGER";
+function stableId(seed) {
+    let h = 5381;
+    for (let i = 0; i < seed.length; i++)
+        h = (h * 33) ^ seed.charCodeAt(i);
+    return h >>> 0;
+}
+/**
+ * Render a {@link ResolvedAddress} as a Nominatim result. `addressdetails` gates the `address`
+ * block, matching Nominatim. The `annotations` block is attached by the caller (empty until the
+ * annotations layer lands).
+ */
+export function toNominatimResult(r, opts = {}) {
+    const displayName = r.displayName ?? Object.values(r.address).filter(Boolean).join(", ");
+    const lat = r.lat != null ? String(r.lat) : "";
+    const lon = r.lon != null ? String(r.lon) : "";
+    const result = {
+        place_id: r.placeId ?? stableId(`${lat},${lon},${displayName}`),
+        licence: MAILWOMAN_LICENCE,
+        lat,
+        lon,
+        display_name: displayName,
+    };
+    if (r.category != null)
+        result.class = r.category;
+    if (r.type != null)
+        result.type = r.type;
+    if (r.importance != null)
+        result.importance = r.importance;
+    if (r.placeRank != null)
+        result.place_rank = r.placeRank;
+    if (r.boundingbox)
+        result.boundingbox = r.boundingbox;
+    if (opts.addressdetails)
+        result.address = r.address;
+    return result;
+}
+//# sourceMappingURL=index.js.map

package/out/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@mailwoman/nominatim",
+  "version": "4.15.1",
+  "description": "Nominatim drop-in — a Nominatim-compatible HTTP geocoding API (search / reverse / lookup / status) over the Mailwoman engine. Run it with `npx @mailwoman/nominatim serve`.",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sister-software/mailwoman.git",
+    "directory": "nominatim"
+  },
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": "./out/index.js"
+  },
+  "dependencies": {
+    "@mailwoman/annotations": "4.15.1",
+    "@mailwoman/codex": "4.15.0",
+    "@mailwoman/neural": "4.15.0",
+    "@mailwoman/nuts-lookup": "4.15.1",
+    "@mailwoman/resolver": "4.15.0",
+    "@mailwoman/resolver-wof-sqlite": "4.15.0",
+    "@mailwoman/spatial": "4.15.0",
+    "@mailwoman/timezone-lookup": "4.15.1",
+    "@mailwoman/un-locode-lookup": "4.15.1",
+    "express": "^5.2.1",
+    "mailwoman": "4.15.0"
+  },
+  "files": [
+    "out/**/*.js",
+    "out/**/*.js.map",
+    "out/**/*.d.ts",
+    "out/**/*.d.ts.map",
+    "README.md"
+  ],
+  "bin": "./out/cli.js",
+  "publishConfig": {
+    "access": "public"
+  }
+}