@unmap/geocoding 0.10.0 → 0.13.0

package/dist/index.js

@@ -1,5 +1,951 @@
 // src/index.ts
+import { DEFAULT_GATEWAY as DEFAULT_GATEWAY2 } from "@unmap/core";
+
+// src/legal-land.ts
+var SEP = String.raw`(?:\s*-\s*|\s+)`;
+var SEP_OPT = String.raw`(?:\s*-\s*|\s+)?`;
+var LSD_N = String.raw`(?<lsd>0?[1-9]|1[0-6])`;
+var SEC_N = String.raw`(?<section>(?:0?[1-9]|[1-2][0-9]|3[0-6])a?)`;
+var TWP_N = String.raw`(?<township>(?:(?:00|0)?[1-9]|0?[1-9][0-9]|1[0-2][0-9])a?)`;
+var RGE_N = String.raw`(?<range>(?:0?[1-9]|[1-8][0-9]|9[0-3])a?)`;
+var MER_N = String.raw`(?<meridian>[Ww][1-6]|[Ee][1-2])[Mm]?`;
+var DLS_LSD = new RegExp(`^${LSD_N}${SEP}${SEC_N}${SEP}${TWP_N}${SEP}${RGE_N}${SEP_OPT}${MER_N}$`, "i");
+var DLS_SEC = new RegExp(`^${SEC_N}${SEP}${TWP_N}${SEP}${RGE_N}${SEP_OPT}${MER_N}$`, "i");
+var DLS_TWP = new RegExp(`^${TWP_N}${SEP}${RGE_N}${SEP_OPT}${MER_N}$`, "i");
+var DLS_QTR_MATCH = new RegExp(`^([ns][ew])(1/4)?(?:\\s*-\\s*|\\s+).*$`, "i");
+var DLS_QTR = new RegExp(
+  `^(?<quarter>[ns][ew])(?:[\\s-]*1/4)?${SEP_OPT}${SEC_N}${SEP}${TWP_N}${SEP}${RGE_N}${SEP_OPT}${MER_N}$`,
+  "i"
+);
+var DLS_HALF_MATCH = new RegExp(`^([nsew])(1/2)?(?:\\s*-\\s*|\\s+).*$`, "i");
+var DLS_HALF = new RegExp(
+  `^(?<half>[nsew])(?:[\\s-]*1/2)?${SEP_OPT}${SEC_N}${SEP}${TWP_N}${SEP}${RGE_N}${SEP_OPT}${MER_N}$`,
+  "i"
+);
+var NTS = new RegExp(
+  `^(?<quarterUnit>[abcd])${SEP_OPT}(?<ntsUnit>(?:00|0)?[1-9]|0?[1-9][0-9]|100)${SEP_OPT}(?<block>[a-l])\\s*/?\\s*(?<series>0?8[2-9]|0?9[0-9]|10[0-9]|11[0-4])${SEP_OPT}(?<mapArea>[a-p])${SEP_OPT}(?<mapSheet>0?[1-9]|1[0-6])$`,
+  "i"
+);
+var NTS_SHEET = new RegExp(
+  `^(?<series>0?8[2-9]|0?9[0-9]|10[0-9]|11[0-4])(?<mapArea>[a-p])\\s*/?\\s*(?<mapSheet>0?[1-9]|1[0-6])$`,
+  "i"
+);
+var FPS_UNIT = /^([a-p])\s+(\d{1,2})\s+(\d{2})-(\d{2})\s+n\s+(\d{1,3})-(\d{1,3})\s+w$/i;
+var FPS_SECTION = /^(\d{1,2})\s+(\d{2})-(\d{2})\s+n\s+(\d{1,3})-(\d{1,3})\s+w$/i;
+var FPS_GRID = /^(\d{2})-(\d{2})\s+n\s+(\d{1,3})-(\d{1,3})\s+w$/i;
+var ON_LOT = /^lot\s+(\d+)(?:\s+(.*))?$/i;
+var ON_CON = /^(?:con|concession)\s+(\d+)\s+([\w ]+)$/i;
+var ON_CON_IN_REST = /^(?:con|concession)\s+(\d+)\s*(.*)$/i;
+var ON_LOT_IN_REST = /^lot\s+(\d+)\s*(.*)$/i;
+var RIVER = /^(pl|rl|wl|lx|sl|ot)(?:[\s-]+[a-z0-9]+)+$/i;
+function sanitize(q) {
+  return q.trim().replace(/['"]/g, "").replace(/[;\\]/g, "");
+}
+function insertDirectionSeparator(q) {
+  return q.replace(/^([NS][EW]|[NSEW])(?!1\/[24]\b)(\d)/i, "$1-$2");
+}
+function cleanPart(value) {
+  return value.replace(/^0+(?=\d)/, "").replace(/\/0+/, "/").toUpperCase();
+}
+function dlsProvince(meridian) {
+  const m = meridian.toUpperCase();
+  if (m === "W5") return "AB";
+  if (m === "W1" || m === "E1" || m === "E2") return "MB";
+  return void 0;
+}
+function titleCase(value) {
+  return value.replace(/\w\S*/g, (word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase());
+}
+function groups(re, q) {
+  const match = re.exec(q);
+  if (!match?.groups) return null;
+  const out = {};
+  for (const [key, value] of Object.entries(match.groups)) {
+    if (value === void 0 || value === "") continue;
+    out[key] = cleanPart(value);
+  }
+  return out;
+}
+function dlsFrom(unit, g) {
+  const meridian = g.meridian;
+  const components = { meridian, range: g.range, township: g.township };
+  const pieces = [];
+  if (unit === "lsd") {
+    components.lsd = g.lsd;
+    components.section = g.section;
+    pieces.push(g.lsd, g.section);
+  } else if (unit === "qtr") {
+    components.quarter = g.quarter;
+    components.section = g.section;
+    pieces.push(g.quarter, g.section);
+  } else if (unit === "half") {
+    components.half = g.half;
+    components.section = g.section;
+    pieces.push(g.half, g.section);
+  } else if (unit === "sec") {
+    components.section = g.section;
+    pieces.push(g.section);
+  }
+  pieces.push(g.township, g.range, meridian);
+  const parsed = {
+    system: "DLS",
+    canonical: pieces.join("-"),
+    unit,
+    components
+  };
+  const province = dlsProvince(meridian);
+  if (province) parsed.province = province;
+  return parsed;
+}
+function parseDls(q) {
+  const candidate = insertDirectionSeparator(q);
+  const lsd = groups(DLS_LSD, candidate);
+  if (lsd) return dlsFrom("lsd", lsd);
+  if (DLS_QTR_MATCH.test(candidate)) {
+    const qtr = groups(DLS_QTR, candidate);
+    if (qtr) return dlsFrom("qtr", qtr);
+  }
+  if (DLS_HALF_MATCH.test(candidate)) {
+    const half = groups(DLS_HALF, candidate);
+    if (half) return dlsFrom("half", half);
+  }
+  const sec = groups(DLS_SEC, candidate);
+  if (sec) return dlsFrom("sec", sec);
+  const twp = groups(DLS_TWP, candidate);
+  if (twp) return dlsFrom("twp", twp);
+  return null;
+}
+function parseNts(q) {
+  const full = groups(NTS, q);
+  if (full) {
+    return {
+      system: "NTS",
+      canonical: `${full.quarterUnit}-${full.ntsUnit}-${full.block}/${full.series}-${full.mapArea}-${full.mapSheet}`,
+      unit: "nts",
+      components: {
+        quarterUnit: full.quarterUnit,
+        ntsUnit: full.ntsUnit,
+        block: full.block,
+        series: full.series,
+        mapArea: full.mapArea,
+        mapSheet: full.mapSheet
+      }
+    };
+  }
+  const sheet = groups(NTS_SHEET, q);
+  if (!sheet) return null;
+  return {
+    system: "NTS",
+    canonical: `${sheet.series}${sheet.mapArea}/${sheet.mapSheet}`,
+    unit: "nts_sheet",
+    components: {
+      series: sheet.series,
+      mapArea: sheet.mapArea,
+      mapSheet: sheet.mapSheet
+    }
+  };
+}
+function parseFps(q) {
+  const unit = FPS_UNIT.exec(q);
+  if (unit) {
+    const components2 = {
+      fpsUnit: unit[1].toUpperCase(),
+      fpsSection: unit[2],
+      latDeg: unit[3],
+      latMin: unit[4],
+      lonDeg: unit[5],
+      lonMin: unit[6]
+    };
+    return {
+      system: "FPS",
+      canonical: `${components2.fpsUnit} ${components2.fpsSection} ${components2.latDeg}-${components2.latMin} N ${components2.lonDeg}-${components2.lonMin} W`,
+      unit: "unit",
+      components: components2
+    };
+  }
+  const section = FPS_SECTION.exec(q);
+  if (section) {
+    const components2 = {
+      fpsSection: section[1],
+      latDeg: section[2],
+      latMin: section[3],
+      lonDeg: section[4],
+      lonMin: section[5]
+    };
+    return {
+      system: "FPS",
+      canonical: `${components2.fpsSection} ${components2.latDeg}-${components2.latMin} N ${components2.lonDeg}-${components2.lonMin} W`,
+      unit: "section",
+      components: components2
+    };
+  }
+  const grid = FPS_GRID.exec(q);
+  if (!grid) return null;
+  const components = {
+    latDeg: grid[1],
+    latMin: grid[2],
+    lonDeg: grid[3],
+    lonMin: grid[4]
+  };
+  return {
+    system: "FPS",
+    canonical: `${components.latDeg}-${components.latMin} N ${components.lonDeg}-${components.lonMin} W`,
+    unit: "grid",
+    components
+  };
+}
+function parseGts(q) {
+  const lot = ON_LOT.exec(q);
+  if (lot) {
+    const components2 = { lot: cleanPart(lot[1]) };
+    const rest2 = (lot[2] ?? "").trim();
+    const con2 = ON_CON_IN_REST.exec(rest2);
+    const nameBits = [];
+    if (con2) {
+      components2.concession = cleanPart(con2[1]);
+      const after = (con2[2] ?? "").trim();
+      if (after) components2.townshipName = titleCase(after);
+      nameBits.push(`Con ${components2.concession}`);
+      if (components2.townshipName) nameBits.push(components2.townshipName);
+    } else if (rest2) {
+      components2.townshipName = titleCase(rest2);
+      nameBits.push(components2.townshipName);
+    }
+    return {
+      system: "GTS",
+      canonical: [`Lot ${components2.lot}`, ...nameBits].join(" "),
+      unit: "lot",
+      components: components2,
+      province: "ON"
+    };
+  }
+  const con = ON_CON.exec(q);
+  if (!con) return null;
+  const components = { concession: cleanPart(con[1]) };
+  const rest = con[2].trim();
+  const nestedLot = ON_LOT_IN_REST.exec(rest);
+  if (nestedLot) {
+    components.lot = cleanPart(nestedLot[1]);
+    const after = (nestedLot[2] ?? "").trim();
+    if (after) components.townshipName = titleCase(after);
+  } else {
+    components.townshipName = titleCase(rest);
+  }
+  const tail = [
+    components.lot ? `Lot ${components.lot}` : "",
+    components.townshipName ?? ""
+  ].filter(Boolean).join(" ");
+  return {
+    system: "GTS",
+    canonical: [`Con ${components.concession}`, tail].filter(Boolean).join(" "),
+    unit: components.lot ? "lot" : "con",
+    components,
+    province: "ON"
+  };
+}
+function parseRiverLot(q) {
+  if (!RIVER.test(q)) return null;
+  const tokens = q.split(/[\s-]+/).filter(Boolean).map((t) => t.toUpperCase());
+  const kind = tokens[0];
+  const parts = tokens.slice(1);
+  return {
+    system: "RIVER_LOT",
+    canonical: tokens.join("-"),
+    unit: "river_lot",
+    components: { kind, parts },
+    province: "MB"
+  };
+}
+function parseLegalLand(q) {
+  if (typeof q !== "string") return null;
+  const raw = sanitize(q);
+  if (!raw) return null;
+  return parseFps(raw) ?? parseGts(raw) ?? parseRiverLot(raw) ?? parseDls(raw) ?? parseNts(raw);
+}
+var LAYER_SYSTEM = {
+  DLS: "dls",
+  NTS: "nts",
+  GTS: "on",
+  FPS: "fps",
+  RIVER_LOT: "river_lot"
+};
+function looksLikeLegalLand(q) {
+  return parseLegalLand(q) != null;
+}
+function toLegalLandDetails(parsed) {
+  return {
+    system: LAYER_SYSTEM[parsed.system],
+    ...parsed.province ? { province: parsed.province } : {},
+    canonical: parsed.canonical,
+    unit: parsed.unit,
+    components: parsed.components
+  };
+}
+
+// src/energy.ts
+var ENERGY_SEARCH_LAYERS = ["well", "facility"];
+var DLS_UWI = /^\s*(?:[A-Z0-9]{2}|\d{3})\/(1[0-6]|0?[1-9])-(3[0-6]|[12][0-9]|0?[1-9])-(1[0-2][0-9]|0?[1-9][0-9]|00[1-9])-(([1-8][0-9]|9[0-3]|0?[1-9])\s*(w[1-6]|e[1-2]|[1-6]))\s*m?\/?(\w{1,2})?\s*$/i;
+var BC_UWI = /^\s*\d{3}\/(a|b|c|d)(\s*-\s*|\s+)?((00|0)?[1-9]|0?[1-9][0-9]|100)(\s*-\s*|\s+)?(a|b|c|d|e|f|g|h|i|j|k|l)\s*?\/\s*(0?8[2-9]|0?9[0-9]|10[0-9]|11[0-4])(\s*-\s*|\s+)?(a|b|c|d|e|f|g|h|i|j|k|l|m|n|o|p)(\s*-\s*|\s+)?(1[0-6]|0?[1-9])\/\d{1,2}\s*$/i;
+var WELL_LICENCE = /^\s*(?:w|wl|lic(?:\.|ence|ense)?)\s*[-#]?\s*(\d{5,7})\s*$/i;
+function parseEnergyQuery(q) {
+  if (typeof q !== "string") return null;
+  const raw = q.trim();
+  if (!raw) return null;
+  if (BC_UWI.test(raw) || DLS_UWI.test(raw)) {
+    return { kind: "uwi", raw, key: raw.replace(/\s+/g, "").toUpperCase() };
+  }
+  const licence = WELL_LICENCE.exec(raw);
+  if (licence?.[1]) {
+    return { kind: "licence", raw, key: licence[1] };
+  }
+  return null;
+}
+function looksLikeEnergyQuery(q) {
+  return parseEnergyQuery(q) != null;
+}
+function parseEnergySearchLayers(raw) {
+  if (!raw) return [];
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const token of raw.split(",")) {
+    const id = token.trim();
+    if (id === "well" || id === "facility") {
+      if (!seen.has(id)) {
+        seen.add(id);
+        out.push(id);
+      }
+    }
+  }
+  return out;
+}
+function isEnergySearchSource(raw) {
+  return raw?.trim() === "energy";
+}
+function energySearchRequested(q, opts = {}) {
+  if (looksLikeEnergyQuery(q)) return true;
+  if (parseEnergySearchLayers(opts.layers).length > 0) return true;
+  return isEnergySearchSource(opts.profile) || isEnergySearchSource(opts.source);
+}
+
+// src/identify.ts
+var LAND_IDENTIFY_LAYER_IDS = [
+  "municipalities",
+  "survey.dls",
+  "survey.nts",
+  "survey.parcels"
+];
+var ENERGY_IDENTIFY_LAYER_IDS = [
+  "energy.wells",
+  "energy.pipelines",
+  "energy.facilities"
+];
+var MINING_IDENTIFY_LAYER_IDS = [
+  "mining.occurrences",
+  "mining.prospectivity",
+  "mining.sk-potential"
+];
+var IDENTIFY_LAYER_IDS = [
+  ...LAND_IDENTIFY_LAYER_IDS,
+  ...ENERGY_IDENTIFY_LAYER_IDS,
+  "energy.fields",
+  "energy.petroleum-tenure",
+  "energy.mineral-tenure",
+  ...MINING_IDENTIFY_LAYER_IDS
+];
+var DEFAULT_IDENTIFY_LAYERS = ["municipalities"];
+function isIdentifyLayer(id) {
+  return IDENTIFY_LAYER_IDS.includes(id);
+}
+function isLandIdentifyLayer(id) {
+  return LAND_IDENTIFY_LAYER_IDS.includes(id) || MINING_IDENTIFY_LAYER_IDS.includes(id);
+}
+function isEnergyIdentifyLayer(id) {
+  return id.startsWith("energy.");
+}
+function knownIdentifyLayers() {
+  return IDENTIFY_LAYER_IDS.join(", ");
+}
+function parseIdentifyLayers(raw) {
+  const ids = (raw ?? "").split(",").map((id) => id.trim()).filter((id) => id.length > 0);
+  if (ids.length === 0) {
+    return { layers: [...DEFAULT_IDENTIFY_LAYERS] };
+  }
+  const layers = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const id of ids) {
+    if (!isIdentifyLayer(id)) {
+      return { error: `unknown identify layer "${id}". known: ${knownIdentifyLayers()}` };
+    }
+    if (!seen.has(id)) {
+      seen.add(id);
+      layers.push(id);
+    }
+  }
+  return { layers };
+}
+function parseIdentifyAt(at, lon, lat) {
+  const rawAt = at?.trim();
+  if (rawAt) {
+    const pieces = rawAt.split(",");
+    if (pieces.length !== 2 || pieces.some((p) => p.trim() === "")) {
+      return { error: "at must be lng,lat" };
+    }
+    const lng = Number(pieces[0]);
+    const latN = Number(pieces[1]);
+    if (!Number.isFinite(lng) || !Number.isFinite(latN)) {
+      return { error: "at must be lng,lat" };
+    }
+    return { at: [lng, latN] };
+  }
+  if (lon != null && lon !== "" && lat != null && lat !== "") {
+    const lng = Number(lon);
+    const latN = Number(lat);
+    if (!Number.isFinite(lng) || !Number.isFinite(latN)) {
+      return { error: "lon and lat must be numbers" };
+    }
+    return { at: [lng, latN] };
+  }
+  return { error: "at (lng,lat) or lon and lat required" };
+}
+
+// src/batch/csv.ts
+var QUOTE = 34;
+var COMMA = 44;
+var CR = 13;
+var LF = 10;
+var CsvParser = class {
+  field = "";
+  row = [];
+  inQuotes = false;
+  /** A quote seen inside a quoted field: either an escape or the close. */
+  pendingQuote = false;
+  /** A CR seen outside quotes: end of record, and a following LF is part of the same break. */
+  pendingCr = false;
+  started = false;
+  rowHasContent = false;
+  /**
+   * 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) {
+    const out = [];
+    if (!this.started) {
+      this.started = true;
+      if (chunk.charCodeAt(0) === 65279) chunk = chunk.slice(1);
+    }
+    for (let i = 0; i < chunk.length; i++) {
+      const ch = chunk.charCodeAt(i);
+      if (this.pendingCr) {
+        this.pendingCr = false;
+        if (ch === LF) continue;
+      }
+      if (this.inQuotes) {
+        if (this.pendingQuote) {
+          this.pendingQuote = false;
+          if (ch === QUOTE) {
+            this.field += '"';
+            continue;
+          }
+          this.inQuotes = false;
+        } else if (ch === QUOTE) {
+          this.pendingQuote = true;
+          continue;
+        } else {
+          this.field += chunk[i];
+          continue;
+        }
+      }
+      if (ch === QUOTE && this.field === "") {
+        this.inQuotes = true;
+        this.rowHasContent = true;
+        continue;
+      }
+      if (ch === COMMA) {
+        this.row.push(this.field);
+        this.field = "";
+        this.rowHasContent = true;
+        continue;
+      }
+      if (ch === CR) {
+        this.pendingCr = true;
+        out.push(this.finishRow());
+        continue;
+      }
+      if (ch === LF) {
+        out.push(this.finishRow());
+        continue;
+      }
+      this.field += chunk[i];
+      this.rowHasContent = true;
+    }
+    return out.filter((r) => r !== EMPTY);
+  }
+  /** Flush a final record with no trailing newline. */
+  end() {
+    if (this.inQuotes && this.pendingQuote) this.inQuotes = false;
+    if (this.field !== "" || this.row.length > 0 || this.rowHasContent) {
+      const row = this.finishRow();
+      return row === EMPTY ? [] : [row];
+    }
+    return [];
+  }
+  /** True when the stream ended inside an unterminated quoted field. */
+  get unterminated() {
+    return this.inQuotes && !this.pendingQuote;
+  }
+  finishRow() {
+    this.row.push(this.field);
+    const row = this.row;
+    this.field = "";
+    this.row = [];
+    const hadContent = this.rowHasContent;
+    this.rowHasContent = false;
+    if (!hadContent && row.length === 1 && row[0] === "") return EMPTY;
+    return row;
+  }
+};
+var EMPTY = [];
+function alignRow(header, values, index) {
+  if (values.length === header.length) return { record: { index, values: [...values] } };
+  if (values.length < header.length) {
+    return {
+      record: { index, values: [...values, ...Array(header.length - values.length).fill("")] },
+      problem: {
+        index,
+        code: "too_few_fields",
+        message: `row ${index} has ${values.length} fields, header has ${header.length}`
+      }
+    };
+  }
+  return {
+    record: { index, values: [...values] },
+    problem: {
+      index,
+      code: "too_many_fields",
+      message: `row ${index} has ${values.length} fields, header has ${header.length}`
+    }
+  };
+}
+function encodeField(value) {
+  if (value === "") return "";
+  if (/[",\r\n\t]/.test(value)) return `"${value.replace(/"/g, '""')}"`;
+  return value;
+}
+function looksLikeFormula(value) {
+  return /^[=+\-@\t\r]/.test(value);
+}
+function escapeForSpreadsheet(value) {
+  return looksLikeFormula(value) ? `	${value}` : value;
+}
+function encodeRow(values, opts = {}) {
+  const prepared = opts.spreadsheetSafe ? values.map(escapeForSpreadsheet) : values;
+  return prepared.map(encodeField).join(",") + "\r\n";
+}
+
+// src/batch/output.ts
+var OUTPUT_PREFIX = "unmap_";
+var OUTPUT_COLUMNS = [
+  "unmap_status",
+  "unmap_id",
+  "unmap_name",
+  "unmap_lng",
+  "unmap_lat",
+  "unmap_layer",
+  "unmap_source",
+  "unmap_match_type",
+  "unmap_precision",
+  "unmap_review"
+];
+function resolveOutputHeader(inputHeader) {
+  const taken = new Set(inputHeader.map((h) => h.trim().toLowerCase()));
+  const renamed = [];
+  const header = [...inputHeader];
+  for (const column of OUTPUT_COLUMNS) {
+    let name = column;
+    if (taken.has(name.toLowerCase())) {
+      let n = 2;
+      while (taken.has(`${column}_${n}`.toLowerCase())) n++;
+      name = `${column}_${n}`;
+      renamed.push({ column, to: name });
+    }
+    taken.add(name.toLowerCase());
+    header.push(name);
+  }
+  return { header, renamed };
+}
+var AMBIGUOUS_SCORE_RATIO = 0.95;
+function classify(results) {
+  if (results.length === 0) return { status: "no_match", reasons: ["no_match"] };
+  const [top, second] = results;
+  const reasons = [];
+  if (top.match_type === "fallback") reasons.push("fallback_match");
+  for (const r of top.match_reasons ?? []) reasons.push(r);
+  if (second && typeof top.score === "number" && typeof second.score === "number" && top.score > 0 && second.score / top.score >= AMBIGUOUS_SCORE_RATIO) {
+    reasons.push("ambiguous");
+  }
+  return { status: reasons.length ? "review" : "matched", reasons };
+}
+function outputValues(status, reasons, top) {
+  return [
+    status,
+    top?.id ?? "",
+    top?.name ?? "",
+    // Fixed precision rather than the float's own repr: a CSV of coordinates is read by humans
+    // and by spreadsheets, and 51.04000000000001 is neither. 7 dp is ~1 cm, well beyond what any
+    // source in the corpus actually resolves.
+    top ? trimCoordinate(top.lng) : "",
+    top ? trimCoordinate(top.lat) : "",
+    top?.layer ?? "",
+    top?.source ?? "",
+    top?.match_type ?? "",
+    top?.precision ?? "",
+    reasons.join(" ")
+  ];
+}
+function trimCoordinate(n) {
+  return n.toFixed(7).replace(/\.?0+$/, "");
+}
+
+// src/search-layers.ts
+var CIVIC_SEARCH_LAYERS = ["address", "street", "locality", "region", "poi"];
+var CIVIC = new Set(CIVIC_SEARCH_LAYERS);
+var ENERGY = new Set(ENERGY_SEARCH_LAYERS);
+function knownSearchLayers() {
+  return [...CIVIC_SEARCH_LAYERS, ...ENERGY_SEARCH_LAYERS].join(", ");
+}
+function parseSearchLayers(raw) {
+  if (raw == null || raw.trim() === "") return { kind: "none" };
+  const civic = [];
+  const energy = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const token of raw.split(",")) {
+    const id = token.trim();
+    if (id === "") continue;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    if (CIVIC.has(id)) civic.push(id);
+    else if (ENERGY.has(id)) energy.push(id);
+    else return { error: `unknown layer "${id}". Known layers: ${knownSearchLayers()}` };
+  }
+  if (civic.length && energy.length) {
+    return {
+      error: `layers cannot mix civic and energy values: ${civic.join(", ")} filter results within the civic corpus, while ${energy.join(", ")} select the energy corpus instead. Ask for one or the other.`
+    };
+  }
+  if (energy.length) return { kind: "energy", layers: energy };
+  if (civic.length) return { kind: "civic", layers: civic };
+  return { kind: "none" };
+}
+function parseFocus(raw) {
+  if (raw == null || raw.trim() === "") return void 0;
+  const pieces = raw.split(",").map((s) => s.trim());
+  const parts = pieces.map((s) => s === "" ? Number.NaN : Number(s));
+  if (parts.length !== 2 || !parts.every(Number.isFinite)) {
+    return { error: "focus must be lng,lat with two finite numbers" };
+  }
+  const [lng, lat] = parts;
+  if (lng < -180 || lng > 180) return { error: `focus longitude ${lng} is outside [-180, 180]` };
+  if (lat < -90 || lat > 90) return { error: `focus latitude ${lat} is outside [-90, 90]` };
+  return { focus: [lng, lat] };
+}
+
+// src/regions.ts
+var BASE = {
+  ab: "AB",
+  alberta: "AB",
+  alta: "AB",
+  bc: "BC",
+  "british columbia": "BC",
+  "colombie-britannique": "BC",
+  mb: "MB",
+  manitoba: "MB",
+  nb: "NB",
+  "new brunswick": "NB",
+  "nouveau-brunswick": "NB",
+  nl: "NL",
+  "newfoundland and labrador": "NL",
+  newfoundland: "NL",
+  "terre-neuve-et-labrador": "NL",
+  nfld: "NL",
+  ns: "NS",
+  "nova scotia": "NS",
+  "nouvelle-\xE9cosse": "NS",
+  "nouvelle-ecosse": "NS",
+  nt: "NT",
+  "northwest territories": "NT",
+  "territoires du nord-ouest": "NT",
+  nwt: "NT",
+  nu: "NU",
+  nunavut: "NU",
+  on: "ON",
+  ontario: "ON",
+  ont: "ON",
+  pe: "PE",
+  pei: "PE",
+  "prince edward island": "PE",
+  "\xEEle-du-prince-\xE9douard": "PE",
+  qc: "QC",
+  pq: "QC",
+  quebec: "QC",
+  qu\u00E9bec: "QC",
+  "que.": "QC",
+  "qu\xE9.": "QC",
+  sk: "SK",
+  saskatchewan: "SK",
+  sask: "SK",
+  yt: "YT",
+  yukon: "YT"
+};
+for (const [k, v] of Object.entries(BASE)) {
+  if (/^[a-z]{2}$/.test(k)) BASE[k[0] + "." + k[1] + "."] = v;
+  else if (k === "nwt" || k === "pei") BASE[k.split("").join(".") + "."] = v;
+  else if (/^[a-z]{3,4}$/.test(k)) BASE[k + "."] = v;
+}
+var REGIONS = BASE;
+var REGION_KEYS = Object.keys(BASE).sort((a, b) => b.length - a.length);
+var REGION_CODES = [...new Set(Object.values(BASE))].sort();
+function parseRegion(raw) {
+  if (!raw) return void 0;
+  const key = raw.trim().toLowerCase();
+  if (REGIONS[key]) return REGIONS[key];
+  const unaccented = key.normalize("NFD").replace(/\p{M}/gu, "");
+  for (const [k, v] of Object.entries(REGIONS)) {
+    if (k.normalize("NFD").replace(/\p{M}/gu, "") === unaccented) return v;
+  }
+  return void 0;
+}
+function regionForms(code) {
+  const forms = /* @__PURE__ */ new Set([code.toUpperCase()]);
+  for (const [k, v] of Object.entries(REGIONS)) if (v === code) forms.add(k.toUpperCase());
+  return [...forms];
+}
+
+// src/structured.ts
+var STRUCTURED_FIELDS = ["address", "city", "region", "postalcode", "country"];
+var ANCHOR_FIELDS = ["address", "city", "postalcode"];
+var POSTCODE = /^[A-Z]\d[A-Z]\d[A-Z]\d$/;
+function parseStructuredQuery(raw) {
+  const trim = (v) => {
+    const t = (v ?? "").trim();
+    return t === "" ? void 0 : t;
+  };
+  const country = trim(raw.country);
+  if (country && !/^(ca|can|canada)$/i.test(country)) {
+    return { error: `country must be CA: unmap covers Canada only (got "${country}")` };
+  }
+  let region;
+  const rawRegion = trim(raw.region);
+  if (rawRegion) {
+    region = parseRegion(rawRegion);
+    if (!region) {
+      return { error: `unknown region "${rawRegion}". Use a province or territory code: ${REGION_CODES.join(", ")}` };
+    }
+  }
+  let postalcode;
+  const rawPostal = trim(raw.postalcode);
+  if (rawPostal) {
+    postalcode = rawPostal.replace(/\s+/g, "").toUpperCase();
+    if (!POSTCODE.test(postalcode)) {
+      return { error: `postalcode must be a Canadian postal code such as M5H 2N2 (got "${rawPostal}")` };
+    }
+  }
+  const query = {
+    ...trim(raw.address) ? { address: trim(raw.address) } : {},
+    ...trim(raw.city) ? { city: trim(raw.city) } : {},
+    ...region ? { region } : {},
+    ...postalcode ? { postalcode } : {},
+    country: "CA"
+  };
+  if (!ANCHOR_FIELDS.some((f) => query[f] != null)) {
+    return {
+      error: `structured search needs at least one of ${ANCHOR_FIELDS.join(", ")}. region and country narrow a search; they cannot be one on their own.`
+    };
+  }
+  return { query };
+}
+
+// src/parcel.ts
+var PID = /^\d{3}-?\d{3}-?\d{3}$/;
+function parseParcel(q) {
+  if (typeof q !== "string") return null;
+  const raw = q.trim();
+  if (!PID.test(raw)) return null;
+  const digits = raw.replace(/-/g, "");
+  return {
+    raw,
+    pid: `${digits.slice(0, 3)}-${digits.slice(3, 6)}-${digits.slice(6)}`
+  };
+}
+function looksLikeParcel(q) {
+  return parseParcel(q) != null;
+}
+
+// src/query.ts
+var QUERY_LAYER_IDS = IDENTIFY_LAYER_IDS;
+var DEFAULT_QUERY_LIMIT = 50;
+var MAX_QUERY_LIMIT = 50;
+function knownQueryLayers() {
+  return knownIdentifyLayers();
+}
+function parseQueryLayer(raw) {
+  const id = (raw ?? "").trim();
+  if (!id) return { error: "layer required" };
+  if (isIdentifyLayer(id)) return { layer: id };
+  return {
+    unknown: id,
+    error: `unknown query layer "${id}". queryable: ${knownQueryLayers()}`
+  };
+}
+function parseQueryBbox(raw) {
+  const value = raw?.trim();
+  if (!value) return { error: "bbox (minlng,minlat,maxlng,maxlat) required" };
+  const pieces = value.split(",");
+  if (pieces.length !== 4 || pieces.some((piece) => piece.trim() === "")) {
+    return { error: "bbox must be minlng,minlat,maxlng,maxlat" };
+  }
+  const nums = pieces.map(Number);
+  if (nums.some((n) => !Number.isFinite(n))) {
+    return { error: "bbox must be minlng,minlat,maxlng,maxlat" };
+  }
+  const [minLng, minLat, maxLng, maxLat] = nums;
+  if (minLng >= maxLng || minLat >= maxLat) {
+    return { error: "bbox must be minlng,minlat,maxlng,maxlat" };
+  }
+  return { bbox: [minLng, minLat, maxLng, maxLat] };
+}
+function parseQueryLimit(raw) {
+  if (raw == null || raw === "") return DEFAULT_QUERY_LIMIT;
+  const n = Number(raw);
+  return Number.isFinite(n) ? Math.min(Math.max(Math.trunc(n), 1), MAX_QUERY_LIMIT) : DEFAULT_QUERY_LIMIT;
+}
+
+// src/rural-route.ts
+var KINDS = [
+  { pattern: /\b(?:R\.?\s?R\.?|RURAL\s+ROUTE)\s*#?\s*(\d{1,3})\b/i, kind: "rural-route", numbered: true },
+  { pattern: /\b(?:S\.?\s?S\.?|SUBURBAN\s+SERVICE)\s*#?\s*(\d{1,3})\b/i, kind: "suburban-service", numbered: true },
+  { pattern: /\b(?:M\.?\s?R\.?|MOBILE\s+ROUTE)\s*#?\s*(\d{1,3})\b/i, kind: "mobile-route", numbered: true },
+  { pattern: /\b(?:G\.?\s?D\.?|GENERAL\s+DELIVERY)\b/i, kind: "general-delivery", numbered: false }
+];
+var PARTS = [
+  { pattern: /\bSITE\s*#?\s*([A-Z0-9-]{1,8})\b/i, field: "site" },
+  { pattern: /\bCOMP(?:ARTMENT)?\s*#?\s*([A-Z0-9-]{1,8})\b/i, field: "compartment" },
+  { pattern: /\b(?:PO\s*)?BOX\s*#?\s*([A-Z0-9-]{1,8})\b/i, field: "box" },
+  // One word only. Canada Post does publish two-word station names ("STN ST LAURENT"), but
+  // "STN MAIN BRANDON" is ambiguous between a two-word station and a station plus a community,
+  // and guessing wrong swallows the only part that can be geocoded. Missing the second word of
+  // a rare station name costs a label; stealing the town costs the answer.
+  { pattern: /\b(?:STN|STATION|RPO|LCD)\s+([A-Z][A-Z0-9'-]*)\b/i, field: "station" }
+];
+function parseRuralRoute(q) {
+  if (typeof q !== "string") return null;
+  const raw = q.trim();
+  if (raw === "") return null;
+  const matched = KINDS.map((k) => ({ ...k, match: k.pattern.exec(raw) })).find((k) => k.match !== null);
+  if (!matched?.match) return null;
+  let rest = raw.replace(matched.pattern, " ");
+  const parsed = { raw, kind: matched.kind, remainder: "" };
+  if (matched.numbered) parsed.number = String(Number(matched.match[1]));
+  for (const part of PARTS) {
+    const hit = part.pattern.exec(rest);
+    if (!hit) continue;
+    parsed[part.field] = hit[1].trim().toUpperCase();
+    rest = rest.replace(part.pattern, " ");
+  }
+  parsed.remainder = rest.replace(/[,;]+/g, " ").replace(/\s+/g, " ").replace(/^[-\s]+|[-\s]+$/g, "");
+  return parsed;
+}
+function looksLikeRuralRoute(q) {
+  return parseRuralRoute(q) != null;
+}
+
+// src/places.ts
 import { DEFAULT_GATEWAY } from "@unmap/core";
+var PlacesError = class extends Error {
+  constructor(status, message, code) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "PlacesError";
+  }
+  status;
+  code;
+};
+async function errorFrom(res, path) {
+  const fallback = `places ${res.status} on ${path}`;
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    body = void 0;
+  }
+  const reason = typeof body?.error === "string" ? body.error : void 0;
+  const code = typeof body?.code === "string" ? body.code : void 0;
+  return new PlacesError(res.status, reason ? `${reason} (${fallback})` : fallback, code);
+}
+var Places = class {
+  key;
+  base;
+  fetchImpl;
+  constructor(opts) {
+    this.key = opts.key;
+    this.base = (opts.gateway ?? DEFAULT_GATEWAY).replace(/\/+$/, "");
+    this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+  /**
+   * Search places by name.
+   *
+   * Unlike `Geocoder.search()`, which returns whatever best matches and for "Calgary" is the city
+   * itself, this returns places.
+   */
+  search(q, opts = {}) {
+    return this.request("/places/search", {
+      q,
+      limit: opts.limit != null ? String(opts.limit) : void 0,
+      lang: opts.lang,
+      bbox: opts.bbox?.join(",")
+    }, opts.signal);
+  }
+  /**
+   * 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, opts = {}) {
+    return this.request("/places/nearby", {
+      category: Array.isArray(category) ? category.join(",") : String(category),
+      near: opts.near?.join(","),
+      bbox: opts.bbox?.join(","),
+      radius: opts.radius != null ? String(opts.radius) : void 0,
+      limit: opts.limit != null ? String(opts.limit) : void 0,
+      lang: opts.lang
+    }, opts.signal);
+  }
+  /**
+   * 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, opts = {}) {
+    return this.request(`/places/${encodeURIComponent(id)}`, { lang: opts.lang }, opts.signal);
+  }
+  async request(path, params, signal) {
+    const q = new URLSearchParams({ key: this.key });
+    for (const [k, v] of Object.entries(params)) if (v != null && v !== "") q.set(k, v);
+    const res = await this.fetchImpl(`${this.base}${path}?${q}`, {
+      signal,
+      headers: { accept: "application/json" }
+    });
+    if (!res.ok) throw await errorFrom(res, path);
+    return await res.json();
+  }
+};
+
+// src/index.ts
 var GeocoderError = class extends Error {
   constructor(status, message, code) {
     super(message);
@@ -10,7 +956,7 @@ var GeocoderError = class extends Error {
   status;
   code;
 };
-async function errorFrom(res, path) {
+async function errorFrom2(res, path) {
   const fallback = `geocode ${res.status} on ${path}`;
   let body;
   try {
@@ -28,7 +974,7 @@ var Geocoder = class {
   fetchImpl;
   constructor(opts) {
     this.key = opts.key;
-    this.base = (opts.gateway ?? DEFAULT_GATEWAY).replace(/\/+$/, "");
+    this.base = (opts.gateway ?? DEFAULT_GATEWAY2).replace(/\/+$/, "");
     this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
   }
   /** Full-text search. */
@@ -39,6 +985,32 @@ var Geocoder = class {
   autocomplete(q, opts = {}) {
     return this.query("/geocode/autocomplete", { q, ...toParams(opts) }, opts.signal);
   }
+  /**
+   * 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) {
+    return this.query(
+      "/geocode/structured",
+      {
+        address: opts.address,
+        city: opts.city,
+        region: opts.region,
+        postalcode: opts.postalcode,
+        country: opts.country,
+        limit: opts.limit != null ? String(opts.limit) : void 0,
+        lang: opts.lang,
+        bbox: opts.bbox ? opts.bbox.join(",") : void 0,
+        focus: opts.focus ? opts.focus.join(",") : void 0,
+        layers: opts.layers
+      },
+      opts.signal
+    );
+  }
   /**
    * 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
@@ -67,15 +1039,54 @@ var Geocoder = class {
       opts.signal
     );
   }
-  async query(path, params, signal) {
+  /**
+   * 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) {
+    return this.requestJson(
+      "/identify",
+      {
+        at: opts.at.join(","),
+        layers: opts.layers?.length ? opts.layers.join(",") : void 0,
+        geometry: opts.geometry ? "true" : void 0
+      },
+      opts.signal
+    );
+  }
+  /**
+   * 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) {
+    return this.requestJson(
+      "/data/query",
+      {
+        layer: opts.layer,
+        bbox: opts.bbox.join(","),
+        limit: opts.limit != null ? String(opts.limit) : void 0,
+        geometry: opts.geometry ? "true" : void 0
+      },
+      opts.signal
+    );
+  }
+  async requestJson(path, params, signal) {
     const q = new URLSearchParams({ key: this.key });
     for (const [k, v] of Object.entries(params)) if (v != null && v !== "") q.set(k, v);
     const res = await this.fetchImpl(`${this.base}${path}?${q}`, {
       signal,
       headers: { accept: "application/json" }
     });
-    if (!res.ok) throw await errorFrom(res, path);
-    const body = await res.json();
+    if (!res.ok) throw await errorFrom2(res, path);
+    return res.json();
+  }
+  async query(path, params, signal) {
+    const body = await this.requestJson(path, params, signal);
     return Array.isArray(body) ? body : body.results ?? [];
   }
 };
@@ -83,11 +1094,71 @@ function toParams(o) {
   return {
     limit: o.limit != null ? String(o.limit) : void 0,
     lang: o.lang,
-    bbox: o.bbox ? o.bbox.join(",") : void 0
+    bbox: o.bbox ? o.bbox.join(",") : void 0,
+    focus: o.focus ? o.focus.join(",") : void 0,
+    region: o.region,
+    geometry: o.geometry ? "true" : void 0,
+    layers: o.layers
   };
 }
 export {
+  AMBIGUOUS_SCORE_RATIO,
+  CIVIC_SEARCH_LAYERS,
+  CsvParser,
+  DEFAULT_IDENTIFY_LAYERS,
+  DEFAULT_QUERY_LIMIT,
+  ENERGY_IDENTIFY_LAYER_IDS,
+  ENERGY_SEARCH_LAYERS,
   Geocoder,
-  GeocoderError
+  GeocoderError,
+  IDENTIFY_LAYER_IDS,
+  LAND_IDENTIFY_LAYER_IDS,
+  MAX_QUERY_LIMIT,
+  MINING_IDENTIFY_LAYER_IDS,
+  OUTPUT_COLUMNS,
+  OUTPUT_PREFIX,
+  Places,
+  PlacesError,
+  QUERY_LAYER_IDS,
+  REGIONS,
+  REGION_CODES,
+  REGION_KEYS,
+  STRUCTURED_FIELDS,
+  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
 };
 //# sourceMappingURL=index.js.map