@unmap/geocoding 0.10.0 → 0.13.0

package/dist/index.d.ts

@@ -1,10 +1,743 @@
+/**
+ * Framework-free port of Township Canada's legal-land regex grammar
+ * (`api/packages/shared/regex_rules.js` + `helpers.processInput`).
+ *
+ * A successful parse is a structured candidate, not a geocoder hit. Coordinates,
+ * civic addresses, and place names return null — those stay on the civic path.
+ */
+type LegalLandSystem = "DLS" | "NTS" | "GTS" | "FPS" | "RIVER_LOT";
+type LegalLandUnit = "lsd" | "qtr" | "half" | "sec" | "twp" | "nts" | "nts_sheet" | "lot" | "con" | "grid" | "section" | "unit" | "river_lot";
+type LegalLandComponents = {
+    meridian?: string;
+    range?: string;
+    township?: string;
+    section?: string;
+    quarter?: string;
+    half?: string;
+    lsd?: string;
+    quarterUnit?: string;
+    ntsUnit?: string;
+    block?: string;
+    series?: string;
+    mapArea?: string;
+    mapSheet?: string;
+    fpsUnit?: string;
+    fpsSection?: string;
+    latDeg?: string;
+    latMin?: string;
+    lonDeg?: string;
+    lonMin?: string;
+    lot?: string;
+    concession?: string;
+    townshipName?: string;
+    kind?: string;
+    parts?: string[];
+};
+type LegalLandParse = {
+    system: LegalLandSystem;
+    canonical: string;
+    unit: LegalLandUnit;
+    components: LegalLandComponents;
+    province?: string;
+};
+declare function parseLegalLand(q: string): LegalLandParse | null;
+/** Public `legal_land.system` values on a geocode result (LOCATION-MODEL). */
+type LegalLandLayerSystem = "dls" | "nts" | "fps" | "on" | "river_lot";
+/** True when `q` is a well-formed legal-land description, not a civic query. */
+declare function looksLikeLegalLand(q: string): boolean;
+interface LegalLandDetails {
+    system: LegalLandLayerSystem;
+    province?: string;
+    canonical: string;
+    unit: LegalLandUnit;
+    components: LegalLandComponents;
+}
+/** Map a parse onto the public result block. Does not invent coordinates. */
+declare function toLegalLandDetails(parsed: LegalLandParse): LegalLandDetails;
+
+/**
+ * Point-in-polygon identify: which catalog features contain a coordinate.
+ *
+ * Identify-capable layers are a subset of the gateway catalog. `parks`,
+ * `rail`, `aboriginal-lands`, `energy.ccs`, and `energy.geothermal` are
+ * catalogued for tiles/overlays but have no identify table, so they 400 here
+ * rather than return a silent miss. Energy tables are empty-safe: a missing
+ * relation is `[]` for that layer, not a 500.
+ */
+declare const LAND_IDENTIFY_LAYER_IDS: readonly ["municipalities", "survey.dls", "survey.nts", "survey.parcels"];
+declare const ENERGY_IDENTIFY_LAYER_IDS: readonly ["energy.wells", "energy.pipelines", "energy.facilities"];
+/** Routed through the Land container as extra tables. Not a fourth container. */
+declare const MINING_IDENTIFY_LAYER_IDS: readonly ["mining.occurrences", "mining.prospectivity", "mining.sk-potential"];
+declare const IDENTIFY_LAYER_IDS: readonly ["municipalities", "survey.dls", "survey.nts", "survey.parcels", "energy.wells", "energy.pipelines", "energy.facilities", "energy.fields", "energy.petroleum-tenure", "energy.mineral-tenure", "mining.occurrences", "mining.prospectivity", "mining.sk-potential"];
+type IdentifyLayerId = (typeof IDENTIFY_LAYER_IDS)[number];
+/** Default when `layers` is omitted: core only, so an account key without add-ons can identify. */
+declare const DEFAULT_IDENTIFY_LAYERS: readonly IdentifyLayerId[];
+declare function isIdentifyLayer(id: string): id is IdentifyLayerId;
+declare function isLandIdentifyLayer(id: IdentifyLayerId): boolean;
+declare function isEnergyIdentifyLayer(id: IdentifyLayerId): boolean;
+declare function knownIdentifyLayers(): string;
+declare function parseIdentifyLayers(raw: string | undefined): {
+    layers: IdentifyLayerId[];
+} | {
+    error: string;
+};
+declare function parseIdentifyAt(at: string | undefined, lon: string | undefined, lat: string | undefined): {
+    at: [number, number];
+} | {
+    error: string;
+};
+interface IdentifyOptions {
+    /** `[lng, lat]` in WGS84 degrees. */
+    at: [number, number];
+    /** Identify-capable catalog ids. Default `municipalities`. Survey layers need `legal-land`. Energy layers need `energy`. `survey.parcels` needs `agriculture`. Mining layers need `mining`. */
+    layers?: readonly string[];
+    /** Include polygons when the row has one. */
+    geometry?: boolean;
+    signal?: AbortSignal;
+}
+interface IdentifyResult {
+    layer: IdentifyLayerId;
+    id: string;
+    name: string;
+    province?: string;
+    unit?: string;
+    survey_system?: string;
+    uwi?: string;
+    licence?: string;
+    operator?: string;
+    status?: string;
+    pid?: string;
+    geometry?: {
+        type: "Polygon" | "MultiPolygon";
+        coordinates: number[][][] | number[][][][];
+    };
+}
+interface IdentifyResponse {
+    at: [number, number];
+    results: IdentifyResult[];
+}
+
+/**
+ * Bbox query against identify-capable catalog layers. Same PostGIS tables as
+ * `/identify`; tile-only catalog ids are rejected (gateway 501), not silently empty.
+ */
+
+declare const QUERY_LAYER_IDS: readonly ["municipalities", "survey.dls", "survey.nts", "survey.parcels", "energy.wells", "energy.pipelines", "energy.facilities", "energy.fields", "energy.petroleum-tenure", "energy.mineral-tenure", "mining.occurrences", "mining.prospectivity", "mining.sk-potential"];
+type QueryLayerId = IdentifyLayerId;
+declare const DEFAULT_QUERY_LIMIT = 50;
+declare const MAX_QUERY_LIMIT = 50;
+type QueryBbox = [number, number, number, number];
+declare function knownQueryLayers(): string;
+declare function parseQueryLayer(raw: string | undefined): {
+    layer: QueryLayerId;
+} | {
+    unknown: string;
+    error: string;
+} | {
+    error: string;
+};
+declare function parseQueryBbox(raw: string | undefined): {
+    bbox: QueryBbox;
+} | {
+    error: string;
+};
+/** Missing or non-numeric `limit` falls back; a finite value is clamped to 1–50. */
+declare function parseQueryLimit(raw: string | undefined): number;
+interface QueryOptions {
+    /** Identify-capable catalog id. Tile-only catalog ids are a 501. */
+    layer: string;
+    /** `[minLng, minLat, maxLng, maxLat]` in WGS84 degrees. */
+    bbox: QueryBbox;
+    /** Max features. Default 50, clamped to 1–50. */
+    limit?: number;
+    /** Include geometry when the row has one. */
+    geometry?: boolean;
+    signal?: AbortSignal;
+}
+interface QueryResponse {
+    layer: QueryLayerId;
+    bbox: QueryBbox;
+    results: IdentifyResult[];
+}
+
+/**
+ * Structured forward geocoding: the caller hands over the components of an address instead of
+ * one string, and the engine keeps them apart all the way through.
+ *
+ * The distinction that matters, and the one the docs state plainly: some fields CONSTRAIN the
+ * result set and some only RANK it.
+ *
+ *   - `address` and `city` are retrieval and ranking. They decide which rows are candidates and
+ *     which candidate wins.
+ *   - `region` and `postalcode` constrain, under one rule: **a supplied component excludes
+ *     records that contradict it, and never excludes records that are silent about it.** A row
+ *     in Ontario is out when you asked for Alberta; a row with no province at all stays in and
+ *     comes back with `region_not_verified` in its `match_reasons`.
+ *   - `country` is validated, not matched: the corpus is Canada only.
+ *
+ * The alternative — joining the fields into one string and running the free-text engine — is
+ * what this exists instead of. It would make `region` a scoring token that any row could match
+ * by coincidence, which is how "Kelowna, BC" used to return the province of British Columbia.
+ */
+interface StructuredQuery {
+    /** Street line: civic number and street name, as the caller would write it on an envelope. */
+    address?: string;
+    city?: string;
+    /** Two-letter code, normalised from any accepted spelling ("Québec" and "qc" both give "QC"). */
+    region?: string;
+    /** Six characters, no space, uppercase ("M5H2N2"). */
+    postalcode?: string;
+    /** Always "CA". Present so the field can be supplied and validated, not so it can vary. */
+    country?: string;
+}
+interface StructuredOptions extends StructuredQuery {
+    limit?: number;
+    lang?: string;
+    /** [minLng, minLat, maxLng, maxLat] hard filter, same semantics as `search`. */
+    bbox?: [number, number, number, number];
+    /** [lng, lat] soft proximity preference. Moves ranking toward the point, excludes nothing. */
+    focus?: [number, number];
+    /** Civic result types to allow (`address`, `street`, `locality`, `region`, `poi`). */
+    layers?: string;
+    signal?: AbortSignal;
+}
+/** The query fields, in the order the docs and the CLI list them. */
+declare const STRUCTURED_FIELDS: readonly ["address", "city", "region", "postalcode", "country"];
+type StructuredParseResult = {
+    query: StructuredQuery;
+} | {
+    error: string;
+};
+/** Normalise and validate raw structured input. Returns the cleaned query or one error string. */
+declare function parseStructuredQuery(raw: Partial<Record<string, string | undefined>>): StructuredParseResult;
+
+/**
+ * Energy-query detect for wells / facilities.
+ *
+ * UWI grammars are Township Canada's `web/server/utils/regex.js` (`uwi`, `bc_uwi`).
+ * Well licences are only treated as energy when they carry a clear prefix (`W`,
+ * `WL`, `LIC` / `LICENCE` / `LICENSE`). Bare digits stay civic.
+ * Facility names are too generic: they are energy only when the caller asks
+ * (`?layers=well|facility` or `profile`/`source=energy`).
+ */
+declare const ENERGY_SEARCH_LAYERS: readonly ["well", "facility"];
+type EnergySearchLayer = (typeof ENERGY_SEARCH_LAYERS)[number];
+type EnergyQueryKind = "uwi" | "licence";
+interface EnergyQuery {
+    kind: EnergyQueryKind;
+    /** Trimmed original. */
+    raw: string;
+    /** Lookup key: UWI uppercased, or licence digits. */
+    key: string;
+}
+declare function parseEnergyQuery(q: string): EnergyQuery | null;
+/** True when `q` is a UWI or a prefixed well licence, not a civic address. */
+declare function looksLikeEnergyQuery(q: string): boolean;
+declare function parseEnergySearchLayers(raw: string | undefined): EnergySearchLayer[];
+declare function isEnergySearchSource(raw: string | undefined): boolean;
+/**
+ * Whether this search should take the energy branch (addon gate + table lookup).
+ * Civic strings stay civic unless the caller asked for energy layers/source.
+ */
+declare function energySearchRequested(q: string, opts?: {
+    layers?: string;
+    profile?: string;
+    source?: string;
+}): boolean;
+interface EnergyDetails {
+    uwi?: string;
+    licence?: string;
+    operator?: string;
+    status?: string;
+}
+
+/**
+ * RFC 4180 CSV, streaming, with the Canadian-address-file details that break naive splitters.
+ *
+ * Hand-written rather than a dependency for two reasons that both matter here. `@unmap/cli` is
+ * deliberately a zero-runtime-dependency Node tool, and the hosted batch consumer is a
+ * Cloudflare Worker — one codec that runs in both, with no bundler shims, is worth the ~150
+ * lines. The other reason is that the failure modes below are the whole job: a parser that gets
+ * them wrong corrupts a customer's file silently, which is worse than refusing it.
+ *
+ * What it handles, and why each one is here:
+ *
+ *  - **A UTF-8 BOM.** Excel writes one. Left in place it becomes part of the first header name,
+ *    so `--query-column address` fails to find `address` and the error blames the user.
+ *  - **Quoted commas and quoted newlines.** "Gatineau, QC" and a multi-line note field are
+ *    ordinary in address exports. A record can therefore span several lines, which is why a
+ *    hosted job cannot chunk a CSV at arbitrary newlines.
+ *  - **Escaped quotes** (`""` inside a quoted field).
+ *  - **CRLF, LF and a lone CR** as record separators, mixed within one file.
+ *  - **Leading zeros** — postal codes and civic numbers. Everything stays a string, always.
+ *  - **Ragged rows.** A row with fewer or more fields than the header is a fact about the file,
+ *    not a crash: it is reported as an error for that row and the rest of the file continues.
+ *
+ * The parser is a state machine over chunks, so a 50 MiB file never has to be a 50 MiB string.
+ */
+interface CsvRecord {
+    /** 1-based index among data records, excluding the header. Stable across resumes. */
+    index: number;
+    /** Field values in header order, exactly as they appeared. Never coerced. */
+    values: string[];
+}
+interface CsvProblem {
+    index: number;
+    code: "too_few_fields" | "too_many_fields";
+    message: string;
+}
+/**
+ * Incremental parser. Feed it strings; it yields complete records.
+ *
+ * Deliberately not an async iterator: the caller owns the read loop, which is what lets the CLI
+ * and the Worker use their own very different stream APIs over the same state machine.
+ */
+declare class CsvParser {
+    private field;
+    private row;
+    private inQuotes;
+    /** A quote seen inside a quoted field: either an escape or the close. */
+    private pendingQuote;
+    /** A CR seen outside quotes: end of record, and a following LF is part of the same break. */
+    private pendingCr;
+    private started;
+    private rowHasContent;
+    /**
+     * Feed one chunk. Returns the records completed by it.
+     *
+     * A record that ends exactly at a chunk boundary is returned here; a partial one is held until
+     * the next chunk, or until `end()`.
+     */
+    write(chunk: string): string[][];
+    /** Flush a final record with no trailing newline. */
+    end(): string[][];
+    /** True when the stream ended inside an unterminated quoted field. */
+    get unterminated(): boolean;
+    private finishRow;
+}
+/**
+ * Align a raw row against the header.
+ *
+ * Ragged rows are reported, not repaired and not thrown: a short row is padded so the caller can
+ * still carry its original values into the output, and a long row keeps its extra fields for the
+ * same reason. Discarding either would lose customer data in a file we were only asked to
+ * annotate.
+ */
+declare function alignRow(header: readonly string[], values: readonly string[], index: number): {
+    record: CsvRecord;
+    problem?: CsvProblem;
+};
+/**
+ * Quote a value for output: only when it has to be, and always the same way.
+ *
+ * The tab is in the set even though RFC 4180 does not require it. It is there for
+ * `escapeForSpreadsheet` below, which neutralises a formula by prefixing one: unquoted, a
+ * leading tab is read inconsistently across spreadsheet apps, and quoted it is unambiguous
+ * everywhere. A tab anywhere else in a field is rare enough that quoting it costs nothing.
+ */
+declare function encodeField(value: string): string;
+/**
+ * Whether a value would be read as a formula by a spreadsheet.
+ *
+ * Excel, Sheets and LibreOffice all evaluate a cell beginning `=`, `+`, `-`, `@`, and CSV is the
+ * classic delivery vehicle for that (CSV injection). It matters here because a geocoder's output
+ * is a file people open in a spreadsheet, and because Canadian address data really does contain
+ * values that start this way — a negative latitude, "-123 Main St" in a malformed row.
+ *
+ * Detection is separated from mitigation on purpose: `escapeForSpreadsheet` prefixes a tab so
+ * the cell displays as text, and the caller decides whether to apply it, because prefixing
+ * changes the bytes and a pipeline reading the file programmatically wants the original.
+ */
+declare function looksLikeFormula(value: string): boolean;
+declare function escapeForSpreadsheet(value: string): string;
+/** One output line, terminated with CRLF (what RFC 4180 specifies and Excel expects). */
+declare function encodeRow(values: readonly string[], opts?: {
+    spreadsheetSafe?: boolean;
+}): string;
+
+/**
+ * The output schema a batch geocode writes, shared by the local CLI and the hosted service.
+ *
+ * One schema, one place, because the two are meant to be interchangeable: a customer who
+ * prototypes with `unmap geocode csv` and then moves the job to the dashboard should get the
+ * same columns in the same order with the same meanings, and diffing the two files should show
+ * nothing but the coordinates.
+ */
+/** Prefix on every column this adds, so a customer's own `status` column is never shadowed. */
+declare const OUTPUT_PREFIX = "unmap_";
+/**
+ * What happened to one input row. Distinct from `match_type`, which is about the QUALITY of an
+ * answer — a row can have `status: "matched"` and `match_type: "fallback"`, and that pairing is
+ * the common case worth reviewing.
+ */
+type RowStatus = 
+/** A result came back and is good enough to use without looking at it. */
+"matched"
+/** A result came back, but something about it should be looked at. See `unmap_review`. */
+ | "review"
+/** The query ran and the corpus has nothing. Not an error, and it is billed. */
+ | "no_match"
+/** The row never became a query: no address to send. Not billed. */
+ | "invalid"
+/** The query ran and failed permanently (bad credentials, exhausted budget, repeated 5xx). */
+ | "failed"
+/** Not attempted: the run was cancelled, paused or interrupted before reaching this row. */
+ | "unprocessed";
+/**
+ * Why a row is in the review file. Row-level, and deliberately a superset of the result-level
+ * `match_reasons`: two of these are about the SHAPE of the answer rather than its content.
+ */
+type ReviewReason = GeocodeMatchReason
+/** The result is coarser than the row asked for. */
+ | "fallback_match"
+/** More than one candidate scored closely; the top one may not be the intended one. */
+ | "ambiguous"
+/** Nothing came back at all. */
+ | "no_match"
+/** The row could not be turned into a query. */
+ | "invalid_input";
+declare const OUTPUT_COLUMNS: readonly ["unmap_status", "unmap_id", "unmap_name", "unmap_lng", "unmap_lat", "unmap_layer", "unmap_source", "unmap_match_type", "unmap_precision", "unmap_review"];
+type OutputColumn = (typeof OUTPUT_COLUMNS)[number];
+/**
+ * Resolve a collision between the columns this writes and the customer's own header.
+ *
+ * Silently overwriting a column called `unmap_status` would destroy data; refusing the file
+ * outright would strand anyone who ran the tool twice on its own output, which is exactly what
+ * people do. So a collision is suffixed (`unmap_status_2`) and reported, and the caller decides
+ * whether to say something. Comparison is case-insensitive because spreadsheets are.
+ */
+declare function resolveOutputHeader(inputHeader: readonly string[]): {
+    header: string[];
+    renamed: Array<{
+        column: OutputColumn;
+        to: string;
+    }>;
+};
+/**
+ * When the top result is close enough to the runner-up that picking it is a coin flip.
+ *
+ * Ratio, not a difference: BM25 scores are not on an absolute scale and are not comparable
+ * across queries, so "within 5%" means something for every query while "within 2 points" means
+ * something only for the query it was tuned on. 0.95 is deliberately tight — this flags a row
+ * for a human to look at, and a review file that flags a third of the rows gets ignored whole.
+ */
+declare const AMBIGUOUS_SCORE_RATIO = 0.95;
+/**
+ * Classify one row's outcome from what the API returned.
+ *
+ * The rule the whole review file rests on: **nothing is silently discarded.** Every input row
+ * gets exactly one record in the main output, and every row that is not plainly usable gets a
+ * reason here and a line in the review file. A row that "failed quietly" is the outcome this
+ * function exists to make impossible.
+ */
+declare function classify(results: readonly GeocodeResult[]): {
+    status: RowStatus;
+    reasons: ReviewReason[];
+};
+/** The ten values, in `OUTPUT_COLUMNS` order, for one row. */
+declare function outputValues(status: RowStatus, reasons: readonly ReviewReason[], top: GeocodeResult | undefined): string[];
+
+/**
+ * `layers=` on `/geocode/search`, `/geocode/autocomplete` and `/geocode/structured`.
+ *
+ * The parameter already existed and already meant one thing: `layers=well,facility` sends the
+ * query to the energy container instead of the civic one. Civic result types are added to the
+ * same parameter rather than to a new one, because from the caller's side they are the same
+ * question — "which kinds of thing may come back" — and two parameters answering it would have
+ * to define what happens when both are set.
+ *
+ * What the two sets do is genuinely different, and that is why they cannot be mixed:
+ * `well`/`facility` select a BACKEND (a different container, a different corpus, gated by the
+ * `energy` add-on); the civic values FILTER results inside one corpus. `layers=address,well`
+ * has no meaning that is not a guess, so it is a 400 rather than a silent choice.
+ *
+ * Unknown values are also a 400. That is a tightening: before this, unrecognised tokens were
+ * dropped silently, so `layers=adress` searched everything and looked like it had worked.
+ */
+declare const CIVIC_SEARCH_LAYERS: readonly ["address", "street", "locality", "region", "poi"];
+type CivicSearchLayer = (typeof CIVIC_SEARCH_LAYERS)[number];
+type SearchLayersParse = {
+    kind: "none";
+} | {
+    kind: "civic";
+    layers: CivicSearchLayer[];
+} | {
+    kind: "energy";
+    layers: EnergySearchLayer[];
+} | {
+    error: string;
+};
+/** Every accepted value, for error messages and docs. */
+declare function knownSearchLayers(): string;
+declare function parseSearchLayers(raw: string | undefined): SearchLayersParse;
+/**
+ * `focus=lng,lat`: a soft proximity preference.
+ *
+ * It moves ranking toward the point and excludes nothing — a relevant result on the other side
+ * of the country still comes back, behind the near ones. That is the whole distinction from
+ * `bbox`, which is a hard filter, and the docs and the UI copy have to keep saying it: "prefer
+ * nearby" is not "restrict to this area".
+ */
+type FocusParse = {
+    focus: [number, number];
+} | {
+    error: string;
+} | undefined;
+declare function parseFocus(raw: string | undefined): FocusParse;
+
+/** Every recognised spelling, lowercase, mapped to its two-letter code. */
+declare const REGIONS: Readonly<Record<string, string>>;
+/**
+ * Spellings sorted longest first, so "newfoundland and labrador" is tried before
+ * "newfoundland". Computed after the dotted-form loop, so generated keys sort with the rest.
+ */
+declare const REGION_KEYS: readonly string[];
+/** The thirteen codes, for validation messages. */
+declare const REGION_CODES: readonly string[];
+/**
+ * Resolve any accepted spelling to its two-letter code. Accent- and case-insensitive, so
+ * "Québec", "quebec" and "QC" all give "QC". Undefined when nothing matches.
+ */
+declare function parseRegion(raw: string | undefined | null): string | undefined;
+/**
+ * Every spelling the corpus may hold for a region code, uppercased: the code itself plus each
+ * name that maps to it. The loaders do not normalise `region` (OpenAddresses passes the source
+ * value through, so `ONTARIO` and `ON` both occur), so a filter or boost must match all of them.
+ */
+declare function regionForms(code: string): string[];
+
+/**
+ * ParcelMap BC PID detect. Grammar matches Township Canada
+ * `web/server/api/parcels/search.get.js`: nine digits, optional dashes
+ * (`010-867-813` or `010867813`). PIN, plan number, and parcel-name
+ * fuzzy match are not distinctive enough to steal civic search.
+ */
+interface ParcelQuery {
+    /** Trimmed original. */
+    raw: string;
+    /** Lookup key: `XXX-XXX-XXX`. */
+    pid: string;
+}
+declare function parseParcel(q: string): ParcelQuery | null;
+/** True when `q` is a ParcelMap BC PID, not a civic address. */
+declare function looksLikeParcel(q: string): boolean;
+
+/**
+ * Canadian rural and alternate delivery addresses.
+ *
+ * A rural route is not a place. `RR 2` names a mail carrier's circuit through a community, and
+ * the same number exists in hundreds of communities; the site of the mailbox is not in any open
+ * dataset. So this does not geocode the route. It splits the Canada Post delivery terms off the
+ * front of a query, hands the rest to civic search, and returns the parsed terms alongside the
+ * community that was found. "RR 2 Okotoks" resolves to Okotoks, labelled rural route 2, which is
+ * the honest answer: the town is known, the mailbox is not.
+ *
+ * Recognised, per Canada Post's addressing guide:
+ *   RR / R.R. / RURAL ROUTE      a rural route, numbered
+ *   SS / SUBURBAN SERVICE        a suburban service route, numbered
+ *   MR / MOBILE ROUTE            a mobile route, numbered
+ *   GD / GENERAL DELIVERY        counter pickup, never numbered
+ *   SITE / COMP(ARTMENT) / BOX   the position within the route
+ *   STN / RPO / LCD              the retail outlet the route runs from
+ *
+ * Deliberately not a locality detector: a query has to carry one of the delivery keywords above
+ * for this to fire, so an ordinary civic address is untouched.
+ */
+type RuralRouteKind = "rural-route" | "suburban-service" | "mobile-route" | "general-delivery";
+interface RuralRouteQuery {
+    /** Trimmed original. */
+    raw: string;
+    kind: RuralRouteKind;
+    /** Route number as written. Absent for general delivery, which is never numbered. */
+    number?: string;
+    /** Position within the route, when given. */
+    site?: string;
+    compartment?: string;
+    box?: string;
+    /** The retail outlet the route runs from, e.g. "MAIN" in "STN MAIN". */
+    station?: string;
+    /**
+     * What is left after the delivery terms are removed: normally the community, and the only
+     * part that can actually be geocoded. Empty when the query was delivery terms and nothing
+     * else, which cannot be resolved to anywhere.
+     */
+    remainder: string;
+}
+declare function parseRuralRoute(q: string): RuralRouteQuery | null;
+/**
+ * True when `q` carries Canada Post delivery terms.
+ *
+ * Note this is NOT a routing signal in the way `looksLikeLegalLand` is: a rural-route query is
+ * still answered by civic search, on its remainder. It exists so the caller can strip the terms
+ * and label the result, not so it can pick a different backend.
+ */
+declare function looksLikeRuralRoute(q: string): boolean;
+
+/**
+ * Typed client for the Places API (gateway `/places/*`).
+ *
+ * It lives in `@unmap/geocoding` rather than in a package of its own because places ARE the
+ * geocoding corpus: the same rows, the same container, the same taxonomy. A twelfth npm package
+ * would also mean a twelfth entry in the changesets fixed group and a twelfth trusted publisher
+ * to configure, which is real founder work for no boundary that exists in the code.
+ *
+ * `Geocoder.nearby()` is untouched and still answers in the geocoder's own shape. This is the
+ * Place shape over the same rows.
+ */
+/** A Canadian point of interest, as `/places/*` returns it. */
+interface Place {
+    /** `um:place:<id>`. Opaque: a corpus rebuild may renumber the tail, so do not parse it. */
+    id: string;
+    /** The corpus id, for `POST /places/{id}/feedback`. */
+    source_id: string;
+    name: string;
+    /** Every language and alternate spelling the corpus holds, including syllabics where recorded. */
+    names: Record<string, string>;
+    /** Taxonomy id, e.g. `finance.bank`. */
+    category: string | null;
+    /** The part before the dot, e.g. `finance`. */
+    category_group: string | null;
+    /** `[lng, lat]`, WGS84. */
+    coordinates: [number, number];
+    address: {
+        housenumber?: string;
+        street?: string;
+        city?: string;
+        region?: string;
+        postcode?: string;
+        country?: string;
+    };
+    /** Metres from the anchor. Only on `nearby()`. */
+    distance?: number;
+    /** Registry id of the dataset, for provenance. */
+    source: string;
+}
+/**
+ * The envelope `/places/*` answers in.
+ *
+ * `meta` is deliberately surfaced rather than unwrapped away: a caller that cannot see
+ * `attribution` cannot comply with the licence the data came under, and one that cannot see
+ * `status` cannot tell fresh data from stale.
+ */
+interface PlacesResponse<T> {
+    data: T;
+    meta: {
+        status: "current" | "stale" | "partial" | "unknown";
+        attribution: string;
+        unmap_updated_at: string;
+        source?: string;
+        source_updated_at?: string | null;
+    };
+}
+interface PlacesOptions {
+    key: string;
+    gateway?: string;
+    fetch?: typeof fetch;
+}
+interface PlaceSearchOptions {
+    limit?: number;
+    lang?: string;
+    bbox?: [number, number, number, number];
+    signal?: AbortSignal;
+}
+interface PlaceNearbyOptions {
+    /** `[lng, lat]`. Exactly one of `near` or `bbox`. */
+    near?: [number, number];
+    bbox?: [number, number, number, number];
+    /** Metres, clamped server-side to 50..50000. */
+    radius?: number;
+    limit?: number;
+    lang?: string;
+    signal?: AbortSignal;
+}
+declare class PlacesError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, code?: string | undefined);
+}
+/**
+ * Canadian places.
+ *
+ *   const places = new Places({ key: "um_live_..." });
+ *   const { data } = await places.nearby("bakery", { near: [-114.07, 51.05] });
+ *
+ * ## Fields this does not carry
+ *
+ * No `phone`, `website`, `opening_hours`, `accessibility` or `operator`. The corpus does not hold
+ * them, so they are ABSENT from the response rather than null: an absent key is a statement about
+ * unmap's coverage and is true, while `"phone": null` would be a statement about the place and
+ * usually a false one. The types above reflect that rather than declaring optional fields nothing
+ * ever populates.
+ */
+declare class Places {
+    private readonly key;
+    private readonly base;
+    private readonly fetchImpl;
+    constructor(opts: PlacesOptions);
+    /**
+     * Search places by name.
+     *
+     * Unlike `Geocoder.search()`, which returns whatever best matches and for "Calgary" is the city
+     * itself, this returns places.
+     */
+    search(q: string, opts?: PlaceSearchOptions): Promise<PlacesResponse<Place[]>>;
+    /**
+     * Places of a category near a point.
+     *
+     * `category` takes a taxonomy id (`health.pharmacy`) or a word in English or French
+     * (`pharmacy`, `pharmacie`); the gateway resolves aliases, so `"boulangerie"` works.
+     */
+    nearby(category: string | readonly string[], opts?: PlaceNearbyOptions): Promise<PlacesResponse<Place[]>>;
+    /**
+     * One place by its unmap id.
+     *
+     * Throws `PlacesError` with status 404 when it does not exist. A malformed id is also a 404,
+     * because from a caller's side "does not exist" and "is not a well-formed id" are the same
+     * answer; the gateway's message distinguishes them as far as it honestly can.
+     */
+    get(id: string, opts?: {
+        lang?: string;
+        signal?: AbortSignal;
+    }): Promise<PlacesResponse<Place>>;
+    private request;
+}
+
 interface GeocoderOptions {
     key: string;
     gateway?: string;
     /** Override the fetch implementation (tests, non-global environments). */
     fetch?: typeof fetch;
 }
-type GeocodeLayer = "address" | "street" | "locality" | "region" | "poi";
+type GeocodeLayer = "address" | "street" | "locality" | "region" | "poi" | "legal_land" | "well" | "facility" | "parcel";
+/**
+ * Which dataset the returned record came from. Conflation
+ * (`pipeline/geocoding/conflate.sql`) keeps one survivor per place and deletes the rest, so
+ * this is the SURVIVING record's source, not every dataset that agreed on the place. See
+ * `docs/services/geocoding-sources.md`.
+ */
+type GeocodeSource = "osm" | "openaddresses" | "statcan_nar" | "nrcan_cgndb" | "wof" | "geonames";
+/**
+ * How well the result answers what was asked, as a category — never a probability, and never
+ * derived from `score` (which stays raw BM25 relevance).
+ *
+ * - `exact` — every component the query supplied and the corpus supports was matched.
+ * - `partial` — something supplied did not match, or could not be verified.
+ * - `fallback` — the result is COARSER than the query asked for: a civic number was requested
+ *   and the result carries none. A street or locality standing in for an address is always
+ *   this, never `exact`.
+ * - `unknown` — input-match diagnostics do not apply (reverse, nearby, autocomplete).
+ */
+type GeocodeMatchType = "exact" | "partial" | "fallback" | "unknown";
+/**
+ * Positional resolution the SOURCE supports, separate from how well the input matched.
+ *
+ * `point` means a discrete point record in the source dataset — an address point or a POI. It
+ * is **not** a rooftop-accuracy claim, and it never means interpolated: the engine performs no
+ * interpolation. `locality` and `region` are centroids.
+ */
+type GeocodePrecision = "point" | "street" | "locality" | "region" | "unknown";
+/** Stable reason codes explaining a non-`exact` `match_type`. Additive; never renamed. */
+type GeocodeMatchReason = "housenumber_not_matched" | "housenumber_differs" | "unit_not_verified" | "unit_differs" | "postalcode_not_verified" | "postalcode_differs" | "region_not_verified" | "region_differs" | "terms_unmatched" | "fuzzy_match";
 interface GeocodeResult {
     id: string;
     name: string;
@@ -12,6 +745,16 @@ interface GeocodeResult {
     lng: number;
     lat: number;
     score?: number;
+    /** Originating dataset of the returned record. */
+    source?: GeocodeSource | string;
+    /** That dataset's own identifier for the record, when it published one. */
+    source_id?: string;
+    /** How well the result answers the query. `unknown` where input matching does not apply. */
+    match_type?: GeocodeMatchType;
+    /** Positional resolution the source supports. Not an accuracy figure. */
+    precision?: GeocodePrecision;
+    /** Why `match_type` is not `exact`. Empty or absent when it is. */
+    match_reasons?: GeocodeMatchReason[];
     /** Canonical category id (e.g. "health.pharmacy") when the feature carries one. */
     category?: string;
     /** Spheroidal metres from the query anchor; only `/geocode/nearby` results carry it. */
@@ -24,13 +767,43 @@ interface GeocodeResult {
         region?: string;
         postcode?: string;
         country?: string;
+        /** Unit/suite, where the source published one. Most of the corpus does not. */
+        unit?: string;
+    };
+    /** Structured legal-land parse; only `layer: "legal_land"` results carry it. */
+    legal_land?: LegalLandDetails;
+    /** Well / facility extras; only `layer: "well" | "facility"` results carry them. */
+    uwi?: string;
+    licence?: string;
+    operator?: string;
+    status?: string;
+    /** ParcelMap BC PID; only `layer: "parcel"` results carry it. */
+    pid?: string;
+    /** Survey-cell bounds `[minLng, minLat, maxLng, maxLat]` when the lookup row has a geom. */
+    bbox?: [number, number, number, number];
+    /** Survey polygon when `?geometry=true` and the lookup row has one. */
+    geometry?: {
+        type: "Polygon" | "MultiPolygon";
+        coordinates: number[][][] | number[][][][];
     };
 }
 interface SearchOptions {
     limit?: number;
     lang?: string;
-    /** [minLng, minLat, maxLng, maxLat] bias/filter. */
+    /** [minLng, minLat, maxLng, maxLat] hard filter. Excludes; see `focus` to merely prefer. */
     bbox?: [number, number, number, number];
+    /** [lng, lat] soft proximity preference. Moves ranking toward the point, excludes nothing. */
+    focus?: [number, number];
+    /** Include the survey polygon on a legal-land hit when the table has one. */
+    geometry?: boolean;
+    /**
+     * Which result types may come back. Civic values (`address`, `street`, `locality`, `region`,
+     * `poi`) filter within the civic corpus; energy values (`well`, `facility`) select the energy
+     * corpus instead and need the energy add-on. The two sets cannot be mixed.
+     */
+    layers?: string;
+    /** Province or territory, any accepted spelling. Excludes rows in another province. */
+    region?: string;
     signal?: AbortSignal;
 }
 interface NearbyOptions {
@@ -62,6 +835,15 @@ declare class Geocoder {
     search(q: string, opts?: SearchOptions): Promise<GeocodeResult[]>;
     /** Type-ahead suggestions for partial input. */
     autocomplete(q: string, opts?: SearchOptions): Promise<GeocodeResult[]>;
+    /**
+     * Forward geocoding from address components rather than one string.
+     *
+     * `address` and `city` decide which rows are candidates and which wins. `region` and
+     * `postalcode` narrow: they drop rows that contradict them and keep rows that are silent
+     * about them, which come back with `region_not_verified` / `postalcode_not_verified` in
+     * `match_reasons`. Needs at least one of `address`, `city` or `postalcode`.
+     */
+    structured(opts: StructuredOptions): Promise<GeocodeResult[]>;
     /**
      * Category search: POIs of a kind near a point, sorted by distance (metres, in each
      * result's `distance`). `category` takes canonical taxonomy ids ("health.pharmacy") or
@@ -74,7 +856,23 @@ declare class Geocoder {
         lang?: string;
         signal?: AbortSignal;
     }): Promise<GeocodeResult[]>;
+    /**
+     * Which catalog features contain a point. Default layer is `municipalities`
+     * (core). `survey.dls` / `survey.nts` need the `legal-land` add-on.
+     * `energy.*` need the `energy` add-on. `mining.*` need the `mining` add-on
+     * and identify via Land extra tables. Empty until the matching PostGIS table
+     * is loaded. No mining search grammar — claim numbers stay `energy.mineral-tenure`.
+     */
+    identify(opts: IdentifyOptions): Promise<IdentifyResponse>;
+    /**
+     * Features of one catalog layer that intersect a bbox. Same PostGIS tables as
+     * `identify`. Tile-only catalog ids are a 501. Survey layers need `legal-land`;
+     * `energy.*` need `energy`; `survey.parcels` needs `agriculture`; mining
+     * layers need `mining`. Empty until the matching table is loaded.
+     */
+    queryLayer(opts: QueryOptions): Promise<QueryResponse>;
+    private requestJson;
     private query;
 }
 
-export { type GeocodeLayer, type GeocodeResult, Geocoder, GeocoderError, type GeocoderOptions, type NearbyOptions, type SearchOptions };
+export { AMBIGUOUS_SCORE_RATIO, CIVIC_SEARCH_LAYERS, type CivicSearchLayer, CsvParser, type CsvProblem, type CsvRecord, DEFAULT_IDENTIFY_LAYERS, DEFAULT_QUERY_LIMIT, ENERGY_IDENTIFY_LAYER_IDS, ENERGY_SEARCH_LAYERS, type EnergyDetails, type EnergyQuery, type EnergyQueryKind, type EnergySearchLayer, type FocusParse, type GeocodeLayer, type GeocodeMatchReason, type GeocodeMatchType, type GeocodePrecision, type GeocodeResult, type GeocodeSource, Geocoder, GeocoderError, type GeocoderOptions, IDENTIFY_LAYER_IDS, type IdentifyLayerId, type IdentifyOptions, type IdentifyResponse, type IdentifyResult, LAND_IDENTIFY_LAYER_IDS, type LegalLandComponents, type LegalLandDetails, type LegalLandLayerSystem, type LegalLandParse, type LegalLandSystem, type LegalLandUnit, MAX_QUERY_LIMIT, MINING_IDENTIFY_LAYER_IDS, type NearbyOptions, OUTPUT_COLUMNS, OUTPUT_PREFIX, type OutputColumn, type ParcelQuery, type Place, type PlaceNearbyOptions, type PlaceSearchOptions, Places, PlacesError, type PlacesOptions, type PlacesResponse, QUERY_LAYER_IDS, type QueryBbox, type QueryLayerId, type QueryOptions, type QueryResponse, REGIONS, REGION_CODES, REGION_KEYS, type ReviewReason, type RowStatus, type RuralRouteKind, type RuralRouteQuery, STRUCTURED_FIELDS, type SearchLayersParse, type SearchOptions, type StructuredOptions, type StructuredParseResult, type StructuredQuery, alignRow, classify, encodeField, encodeRow, energySearchRequested, escapeForSpreadsheet, isEnergyIdentifyLayer, isEnergySearchSource, isIdentifyLayer, isLandIdentifyLayer, knownIdentifyLayers, knownQueryLayers, knownSearchLayers, looksLikeEnergyQuery, looksLikeFormula, looksLikeLegalLand, looksLikeParcel, looksLikeRuralRoute, outputValues, parseEnergyQuery, parseEnergySearchLayers, parseFocus, parseIdentifyAt, parseIdentifyLayers, parseLegalLand, parseParcel, parseQueryBbox, parseQueryLayer, parseQueryLimit, parseRegion, parseRuralRoute, parseSearchLayers, parseStructuredQuery, regionForms, resolveOutputHeader, toLegalLandDetails };