@unmap/geocoding 0.12.0 → 0.14.0

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { RetryPolicy, UnmapError } from '@unmap/core';
+export { RetryPolicy, UnmapError, parseRetryAfter } from '@unmap/core';
+
 /**
  * Framework-free port of Township Canada's legal-land regex grammar
  * (`api/packages/shared/regex_rules.js` + `helpers.processInput`).
@@ -211,6 +214,126 @@ type StructuredParseResult = {
 /** Normalise and validate raw structured input. Returns the cleaned query or one error string. */
 declare function parseStructuredQuery(raw: Partial<Record<string, string | undefined>>): StructuredParseResult;
 
+/**
+ * Treaty context: `include=treaties` on `/geocode/search` and `/geocode/reverse`.
+ *
+ * The contract is frozen in `docs/indigenous-context/contract.md`; the decision behind its shape
+ * is `docs/decisions/2026-09-22-treaty-context-on-geocode.md`. These types and parsers are shared
+ * by the gateway, the civic geocode container and the SDK, like every other request parser here.
+ *
+ * What the data is, so nothing downstream overstates it: two CIRNAC datasets of the Crown's
+ * published treaty representations. A match is a spatial match to a representation, not a
+ * determination of rights, title or territory, and `ok` with no matches means "no record in this
+ * dataset", never "unceded" and never "no Indigenous rights".
+ */
+declare const INCLUDE_VALUES: readonly ["treaties"];
+type IncludeValue = (typeof INCLUDE_VALUES)[number];
+/**
+ * Release C values (docs/indigenous-context/community-pilot.md). Refused unless the deployment has
+ * switched community context on, which it must not do before a community source is admitted under
+ * an agreement with human review (CLAUDE.md rule 6).
+ */
+declare const COMMUNITY_INCLUDE_VALUES: readonly ["territories", "acknowledgements"];
+type CommunityIncludeValue = (typeof COMMUNITY_INCLUDE_VALUES)[number];
+interface IncludeParse {
+    treaties: boolean;
+    territories: boolean;
+    acknowledgements: boolean;
+}
+type TreatyPointBasis = "result_point" | "input_point";
+type TreatyCategory = "historic" | "modern";
+type TreatyGeographyKind = "treaty_area" | "overall_treaty_area" | "settlement_land" | "rights_area" | "other" | "unspecified";
+type TreatyRepresentation = "approximate" | "illustrative" | "unspecified";
+type TreatyLang = "en" | "fr";
+interface TreatyMatch {
+    /** `<source_id>:<source_record_id>`, stable across refreshes. */
+    id: string;
+    /** Registry id of the publishing dataset, e.g. `treaties.cirnac-historic`. */
+    source_id: string;
+    /** The publisher's own key (CIRNAC `TAG_ID`). */
+    source_record_id: string;
+    category: TreatyCategory;
+    /** In the requested language when the source has it; `name_lang` says which it is. */
+    name: string;
+    name_lang: TreatyLang;
+    names: {
+        en?: string;
+        fr?: string;
+    };
+    /** The publisher's subtype label ("Numbered Treaty"), same language rule as `name`. */
+    subtype?: string;
+    subtypes?: {
+        en?: string;
+        fr?: string;
+    };
+    geography_kind: TreatyGeographyKind;
+    representation: TreatyRepresentation;
+    /** Publisher dataset page. Always http(s). */
+    source_url: string;
+}
+interface TreatyContext {
+    schema_version: 1;
+    /** Null only when no version could be resolved; never null when `status` is `ok`. */
+    dataset_version: string | null;
+    status: "ok" | "unavailable";
+    point: {
+        lng: number;
+        lat: number;
+        basis: TreatyPointBasis;
+    };
+    coverage: {
+        scope: "Canada";
+        completeness: "partial";
+    };
+    /** Always empty when `status` is `unavailable`. */
+    matches: TreatyMatch[];
+    notice_code: "source_limitations_apply";
+}
+/** `include=` on the two endpoints that accept it. Absent or empty means nothing extra. */
+declare function parseInclude(raw: string | undefined, options?: {
+    community?: boolean;
+}): IncludeParse | {
+    error: string;
+};
+/**
+ * `YYYY-MM-DD.` plus twelve lowercase hex characters, with a date that exists. Checked before a
+ * version reaches SQL or an R2 key, so `../` and friends never get that far.
+ */
+declare function isTreatiesVersion(value: string): boolean;
+declare function parseTreatiesVersion(raw: string | undefined, treatiesIncluded: boolean): {
+    version: string | undefined;
+} | {
+    error: string;
+};
+/**
+ * The label to show for `lang`, and the language it is actually in. `fr` (and `fr-CA`) prefers
+ * French; everything else prefers English. The other language is a fallback that is reported,
+ * never presented as a translation. No label at all is `undefined`: nothing is invented.
+ */
+declare function pickTreatyLabel(labels: {
+    en?: string;
+    fr?: string;
+}, lang: string): {
+    text: string;
+    lang: TreatyLang;
+} | undefined;
+/** Historic before modern, then by id; a record delivered twice appears once. */
+declare function orderTreatyMatches(matches: readonly TreatyMatch[]): TreatyMatch[];
+/**
+ * Runtime check of a `treaties` object, including the two invariants the type cannot express:
+ * `ok` carries a version, and `unavailable` carries no matches. Throws a TypeError otherwise.
+ */
+declare function parseTreatyContext(value: unknown): TreatyContext;
+/**
+ * The `treaties` object for a lookup that could not run. Shared so the container and the
+ * gateway (which enriches legal-land and energy results) produce byte-identical failures.
+ */
+declare function unavailableTreatyContext(point: {
+    lng: number;
+    lat: number;
+    basis: TreatyPointBasis;
+}): TreatyContext;
+
 /**
  * Energy-query detect for wells / facilities.
  *
@@ -485,6 +608,192 @@ type FocusParse = {
 } | undefined;
 declare function parseFocus(raw: string | undefined): FocusParse;
 
+/**
+ * Release C: territories and acknowledgement resources (docs/indigenous-context/community-pilot.md,
+ * community-review-packet.md). Built and tested on synthetic data only. No community source is
+ * admitted, so a deployment answers `not_enabled` at best, and refuses these include values
+ * unless community context has been switched on.
+ *
+ * The semantics carried here are the review packet's: a territory match is a source-defined
+ * record, never an inference from proximity; `community_ids` are relationships the source states;
+ * an acknowledgement resource applies only through a reviewed relationship to a matched territory,
+ * never by city name or nearest reserve; exact text appears only where republication is permitted,
+ * and is never generated or machine-translated.
+ */
+/** `not_enabled`: nothing admitted for this collection. Not a successful empty lookup. */
+type CommunityStatus = "ok" | "not_enabled" | "unavailable";
+interface TerritoryMatch {
+    /** `<source_id>:<source_record_id>`. */
+    id: string;
+    source_id: string;
+    source_record_id: string;
+    name: string;
+    /** Language tag of `name` as the source supplied it. */
+    name_lang: string;
+    /** Only the names and language tags the source supplied. */
+    names: Record<string, string>;
+    /** Communities the source relates to this record. Never inferred. */
+    community_ids: string[];
+    representation: "approximate" | "illustrative" | "source_defined";
+    source_url: string;
+    attribution: string;
+}
+interface TerritoryContext {
+    schema_version: 1;
+    dataset_version: string | null;
+    status: CommunityStatus;
+    point: {
+        lng: number;
+        lat: number;
+        basis: TreatyPointBasis;
+    };
+    coverage: {
+        scope: "source_defined";
+        completeness: "partial";
+    };
+    matches: TerritoryMatch[];
+    notice_code: "source_limitations_apply";
+}
+interface AcknowledgementResource {
+    id: string;
+    source_id: string;
+    title: string;
+    /** The approved original. Always present, so a client can link when it cannot show text. */
+    url: string;
+    /** Language of the resource as approved. Resources are not translated. */
+    language: string;
+    attribution: string;
+    /** The reviewed explanation of where and how the resource applies. */
+    applicability: string;
+    /** Territory ids the partner linked this resource to. The only way a resource is matched. */
+    applies_to: string[];
+    reviewed_at: string;
+    content_version: string;
+    /** Exact approved wording, only where the agreement permits republication. */
+    text?: string;
+}
+interface AcknowledgementContext {
+    schema_version: 1;
+    dataset_version: string | null;
+    status: CommunityStatus;
+    point: {
+        lng: number;
+        lat: number;
+        basis: TreatyPointBasis;
+    };
+    resources: AcknowledgementResource[];
+    notice_code: "source_limitations_apply";
+}
+/**
+ * The name to show for `lang`: the requested primary language when supplied, otherwise the
+ * source's own default. Nothing is translated or invented; `undefined` if neither exists.
+ */
+declare function pickCommunityName(names: Record<string, string>, lang: string, defaultLang: string): {
+    text: string;
+    lang: string;
+} | undefined;
+declare function emptyTerritoryContext(p: {
+    lng: number;
+    lat: number;
+    basis: TreatyPointBasis;
+}, status: Exclude<CommunityStatus, "ok">): TerritoryContext;
+declare function emptyAcknowledgementContext(p: {
+    lng: number;
+    lat: number;
+    basis: TreatyPointBasis;
+}, status: Exclude<CommunityStatus, "ok">): AcknowledgementContext;
+declare function parseTerritoryContext(value: unknown): TerritoryContext;
+declare function parseAcknowledgementContext(value: unknown): AcknowledgementContext;
+
+/**
+ * Treaty overlay controller (docs/indigenous-context/contract.md, "Tiles").
+ *
+ * Drawing is the style's job: `overlays: ["treaties"]` composes the catalog layer, in the style's
+ * own colours. This helper does the rest: shows or hides historic and modern, and answers "which
+ * treaties are here" for a clicked point or a point a keyboard user supplied. The answer comes
+ * from the geocoder's full-resolution lookup, never from the tile features, because a tile may
+ * have simplified away a small record; the clicked features only say which dataset version is on
+ * screen, and every lookup is pinned to it.
+ *
+ * Each lookup is one reverse geocode call. Creating the controller, toggling and restyling make
+ * no requests.
+ */
+/** The layer ids `overlays: ["treaties"]` composes (apps/gateway/src/overlays.ts). */
+declare function treatyLayerIds(category: TreatyCategory): [fill: string, line: string];
+/** The slice of a MapLibre map this controller uses. */
+interface TreatyMapLike {
+    on(type: "click", listener: (e: {
+        lngLat: {
+            lng: number;
+            lat: number;
+        };
+        point: unknown;
+    }) => void): unknown;
+    on(type: "styledata", listener: () => void): unknown;
+    off(type: "click", listener: (e: {
+        lngLat: {
+            lng: number;
+            lat: number;
+        };
+        point: unknown;
+    }) => void): unknown;
+    off(type: "styledata", listener: () => void): unknown;
+    getLayer(id: string): unknown;
+    setLayoutProperty(id: string, name: "visibility", value: "visible" | "none"): unknown;
+    queryRenderedFeatures(point: unknown, options: {
+        layers: string[];
+    }): Array<{
+        properties?: Record<string, unknown> | null;
+    }>;
+}
+/** Anything with the geocoder's `reverse`: `unmap.geocoder`, or a `Geocoder`. */
+interface TreatyLookupClient {
+    reverse(lng: number, lat: number, opts?: ReverseOptions): Promise<GeocodeResult[]>;
+}
+interface TreatySelection {
+    /** Treaty context for the point, from the full-resolution lookup. */
+    context: TreatyContext;
+    /** Record ids drawn under the point on screen, deduplicated across tile fragments. */
+    drawn: string[];
+    /** Categories currently hidden on the map. Their matches are still in `context`. */
+    hidden: TreatyCategory[];
+}
+interface TreatyOverlayOptions {
+    historic?: boolean;
+    modern?: boolean;
+    lang?: "en" | "fr";
+    /** Answer map clicks. Default true; false leaves lookups to `lookupAt`. */
+    interactive?: boolean;
+    /** The latest selection. A superseded or destroyed lookup never calls this. */
+    onSelect?(selection: TreatySelection): void;
+    /**
+     * A lookup failed. `code: "treaties_version_not_found"` means the drawn version has been
+     * retired: show it as unavailable and offer to reload the map, never newer details.
+     */
+    onError?(error: Error & {
+        code?: string;
+    }): void;
+}
+interface TreatyOverlayController {
+    setVisibility(value: {
+        historic?: boolean;
+        modern?: boolean;
+    }): void;
+    readonly visibility: {
+        historic: boolean;
+        modern: boolean;
+    };
+    setLanguage(lang: "en" | "fr"): void;
+    /**
+     * Treaty context for a point: the non-canvas path (a geocoder result, typed coordinates).
+     * `datasetVersion` pins it; omitted, it pins to whatever the map last showed at a click, or the
+     * current release when nothing has been clicked.
+     */
+    lookupAt(point: [number, number], datasetVersion?: string): Promise<TreatySelection | undefined>;
+    destroy(): void;
+}
+declare function createTreatyOverlay(map: TreatyMapLike, client: TreatyLookupClient, options?: TreatyOverlayOptions): TreatyOverlayController;
+
 /** Every recognised spelling, lowercase, mapped to its two-letter code. */
 declare const REGIONS: Readonly<Record<string, string>>;
 /**
@@ -573,11 +882,175 @@ declare function parseRuralRoute(q: string): RuralRouteQuery | null;
  */
 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;
+    /**
+     * Retry policy for `429`, `502`, `503` and transport failures. `false` disables it.
+     *
+     * On by default. `Retry-After` is on a `429` other than `billing_required`, and on a container
+     * `503`. A `502` has none: routing uses `routing_failed`, and `/elevation` uses
+     * `upstream_error`. With no header the client backs off itself. A wait longer than
+     * `maxDelayMs` (10 s) is not slept through; the error carries `retryAfterSeconds` instead.
+     * See `RetryPolicy` in `@unmap/core`.
+     */
+    retry?: RetryPolicy | false;
+}
+interface PlaceSearchOptions {
+    limit?: number;
+    lang?: string;
+    /**
+     * [minLng, minLat, maxLng, maxLat] hard filter. Excludes; name the city in the query to merely prefer.
+     * A corner outside WGS84 is status 400, code `bad_request`. A box outside Canada stays a filter.
+     */
+    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;
+}
+/**
+ * A places failure.
+ *
+ * Extends `UnmapError`, so `catch (e) { if (e instanceof UnmapError) }` catches this alongside
+ * every other unmap client's errors. `instanceof PlacesError` keeps working, and `status` and `code`
+ * are still where they were; `retryAfterSeconds` is new and comes from the header.
+ */
+declare class PlacesError extends UnmapError {
+    constructor(status: number, message: string, code?: string, retryAfterSeconds?: number);
+}
+/**
+ * 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;
+    private readonly retry;
+    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. A missing query is 400 `bad_request` (`q is required`). A bbox
+     * corner outside WGS84 is the same status and code. A box outside Canada stays a filter.
+     */
+    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. An anchor
+     * outside Canada rejects with status 422 and code `outside_coverage`. A longitude or latitude
+     * outside WGS84, including a bbox corner, rejects with status 400 and code `bad_request`.
+     */
+    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;
+}
+
+/** Largest `queries` array `POST /geocode/batch` accepts. Payload size, not pool size. */
+declare const GEOCODE_BATCH_MAX = 100;
 interface GeocoderOptions {
     key: string;
     gateway?: string;
     /** Override the fetch implementation (tests, non-global environments). */
     fetch?: typeof fetch;
+    /**
+     * Retry policy for `429`, `502`, `503` and transport failures. `false` disables it.
+     *
+     * On by default. `Retry-After` is on a `429` other than `billing_required`, and on a container
+     * `503`. A `502` has none. The client that reads the header is better placed to honour it than
+     * every caller re-deriving the same loop, and it backs off itself when the header is absent.
+     * A wait longer than `maxDelayMs` (10 s) is not slept through; the error carries
+     * `retryAfterSeconds` instead. See `RetryPolicy` in `@unmap/core`.
+     */
+    retry?: RetryPolicy | false;
 }
 type GeocodeLayer = "address" | "street" | "locality" | "region" | "poi" | "legal_land" | "well" | "facility" | "parcel";
 /**
@@ -657,11 +1130,19 @@ interface GeocodeResult {
         type: "Polygon" | "MultiPolygon";
         coordinates: number[][][] | number[][][][];
     };
+    /**
+     * Treaty context for this result, only with `include=treaties`. On search it describes the
+     * result's own point; on reverse, the coordinate that was sent.
+     */
+    treaties?: TreatyContext;
 }
 interface SearchOptions {
     limit?: number;
     lang?: string;
-    /** [minLng, minLat, maxLng, maxLat] hard filter. Excludes; see `focus` to merely prefer. */
+    /**
+     * [minLng, minLat, maxLng, maxLat] hard filter. Excludes; see `focus` to merely prefer.
+     * A corner outside WGS84 is status 400, code `bad_request`. A box outside Canada stays a filter.
+     */
     bbox?: [number, number, number, number];
     /** [lng, lat] soft proximity preference. Moves ranking toward the point, excludes nothing. */
     focus?: [number, number];
@@ -677,6 +1158,21 @@ interface SearchOptions {
     region?: string;
     signal?: AbortSignal;
 }
+/**
+ * Treaty context (`include=treaties`), on `search` and `reverse` only. See TreatyContext: a match
+ * is to the Crown's published representation, and an empty `ok` is not a statement about rights.
+ */
+interface TreatyOptions {
+    /** `["treaties"]` adds `treaties` to every result. Omitted, responses are unchanged. */
+    include?: IncludeValue[];
+    /** Pin the treaty dataset version (e.g. the one a map overlay feature carries). */
+    treatiesVersion?: string;
+}
+interface ReverseOptions extends TreatyOptions {
+    lang?: string;
+    limit?: number;
+    signal?: AbortSignal;
+}
 interface NearbyOptions {
     /** [lng, lat] anchor to sort by distance from. Exactly one of `near` or `bbox`. */
     near?: [number, number];
@@ -688,22 +1184,30 @@ interface NearbyOptions {
     lang?: string;
     signal?: AbortSignal;
 }
-declare class GeocoderError extends Error {
-    readonly status: number;
-    /** The gateway's machine-readable `code`, when the response carried one (e.g. `unauthorized`). */
-    readonly code?: string | undefined;
-    constructor(status: number, message: string, 
-    /** The gateway's machine-readable `code`, when the response carried one (e.g. `unauthorized`). */
-    code?: string | undefined);
+/**
+ * A geocoding failure.
+ *
+ * Extends `UnmapError`, so `catch (e) { if (e instanceof UnmapError) }` catches this alongside
+ * every other unmap client's errors. `instanceof GeocoderError` keeps working, and `status` and
+ * `code` are still where they were; `retryAfterSeconds` is new and comes from the header.
+ */
+declare class GeocoderError extends UnmapError {
+    constructor(status: number, message: string, code?: string, retryAfterSeconds?: number);
 }
 /** Typed client for the unmap geocoding API (gateway `/geocode/*`). */
 declare class Geocoder {
     private readonly key;
     private readonly base;
     private readonly fetchImpl;
+    private readonly retry;
     constructor(opts: GeocoderOptions);
     /** Full-text search. */
-    search(q: string, opts?: SearchOptions): Promise<GeocodeResult[]>;
+    search(q: string, opts?: SearchOptions & TreatyOptions): Promise<GeocodeResult[]>;
+    /**
+     * Many searches in one or more `POST /geocode/batch` calls, chunked at
+     * {@link GEOCODE_BATCH_MAX}. Results stay aligned to `queries`.
+     */
+    batch(queries: string[], opts?: SearchOptions): Promise<GeocodeResult[][]>;
     /** Type-ahead suggestions for partial input. */
     autocomplete(q: string, opts?: SearchOptions): Promise<GeocodeResult[]>;
     /**
@@ -719,14 +1223,17 @@ declare class Geocoder {
      * 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
      * plain words in English or French ("pharmacy", "pharmacie") — the gateway resolves
-     * aliases, so this client passes the value through untouched.
+     * aliases, so this client passes the value through untouched. An anchor outside Canada rejects
+     * with status 422 and code `outside_coverage`; the corpus is not queried. A longitude or
+     * latitude outside WGS84, including a bbox corner, rejects with status 400 and code `bad_request`.
      */
     nearby(category: string | string[], opts?: NearbyOptions): Promise<GeocodeResult[]>;
-    /** Reverse geocode a coordinate. */
-    reverse(lng: number, lat: number, opts?: {
-        lang?: string;
-        signal?: AbortSignal;
-    }): Promise<GeocodeResult[]>;
+    /**
+     * Reverse geocode a coordinate. A point outside Canada rejects with status 422 and code
+     * `outside_coverage`. A longitude or latitude outside WGS84 rejects with status 400 and code
+     * `bad_request`.
+     */
+    reverse(lng: number, lat: number, opts?: ReverseOptions): Promise<GeocodeResult[]>;
     /**
      * Which catalog features contain a point. Default layer is `municipalities`
      * (core). `survey.dls` / `survey.nts` need the `legal-land` add-on.
@@ -742,8 +1249,9 @@ declare class Geocoder {
      * layers need `mining`. Empty until the matching table is loaded.
      */
     queryLayer(opts: QueryOptions): Promise<QueryResponse>;
+    private postJson;
     private requestJson;
     private query;
 }
 
-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, 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 };
+export { AMBIGUOUS_SCORE_RATIO, type AcknowledgementContext, type AcknowledgementResource, CIVIC_SEARCH_LAYERS, COMMUNITY_INCLUDE_VALUES, type CivicSearchLayer, type CommunityIncludeValue, type CommunityStatus, 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, GEOCODE_BATCH_MAX, type GeocodeLayer, type GeocodeMatchReason, type GeocodeMatchType, type GeocodePrecision, type GeocodeResult, type GeocodeSource, Geocoder, GeocoderError, type GeocoderOptions, IDENTIFY_LAYER_IDS, INCLUDE_VALUES, type IdentifyLayerId, type IdentifyOptions, type IdentifyResponse, type IdentifyResult, type IncludeParse, type IncludeValue, 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 ReverseOptions, type ReviewReason, type RowStatus, type RuralRouteKind, type RuralRouteQuery, STRUCTURED_FIELDS, type SearchLayersParse, type SearchOptions, type StructuredOptions, type StructuredParseResult, type StructuredQuery, type TerritoryContext, type TerritoryMatch, type TreatyCategory, type TreatyContext, type TreatyGeographyKind, type TreatyLang, type TreatyLookupClient, type TreatyMapLike, type TreatyMatch, type TreatyOptions, type TreatyOverlayController, type TreatyOverlayOptions, type TreatyPointBasis, type TreatyRepresentation, type TreatySelection, alignRow, classify, createTreatyOverlay, emptyAcknowledgementContext, emptyTerritoryContext, encodeField, encodeRow, energySearchRequested, escapeForSpreadsheet, isEnergyIdentifyLayer, isEnergySearchSource, isIdentifyLayer, isLandIdentifyLayer, isTreatiesVersion, knownIdentifyLayers, knownQueryLayers, knownSearchLayers, looksLikeEnergyQuery, looksLikeFormula, looksLikeLegalLand, looksLikeParcel, looksLikeRuralRoute, orderTreatyMatches, outputValues, parseAcknowledgementContext, parseEnergyQuery, parseEnergySearchLayers, parseFocus, parseIdentifyAt, parseIdentifyLayers, parseInclude, parseLegalLand, parseParcel, parseQueryBbox, parseQueryLayer, parseQueryLimit, parseRegion, parseRuralRoute, parseSearchLayers, parseStructuredQuery, parseTerritoryContext, parseTreatiesVersion, parseTreatyContext, pickCommunityName, pickTreatyLabel, regionForms, resolveOutputHeader, toLegalLandDetails, treatyLayerIds, unavailableTreatyContext };