@unmap/elevation 0.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maps & Apps Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,16 @@
+# @unmap/elevation
+
+Ground elevation anywhere in Canada, from NRCan's national 30 m DEM.
+
+```ts
+import { Elevation } from "@unmap/elevation";
+
+const elevation = new Elevation({ key: "um_live_..." });
+const [metres] = await elevation.get([-114.0719, 51.0447]);
+```
+
+Heights are metres above the CGVD2013 geoid. `null` means the dataset covers nothing there; it
+never means sea level.
+
+`@unmap/sdk` exposes the same object as `unmap.elevation`. Full documentation:
+<https://unmap.dev/docs/elevation-api>.

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+/** [longitude, latitude]. Longitude first, everywhere in unmap. Not exported: `@unmap/routing`
+ *  already exports a `LngLat` of the same shape, and both packages land in `@unmap/sdk`'s star
+ *  exports, where two same-named exports would be a type error. */
+type LngLat = [number, number];
+interface ElevationOptions {
+    key: string;
+    gateway?: string;
+    fetch?: typeof fetch;
+}
+/** The gateway's own cap. Checked here so an over-long batch fails without spending a call. */
+declare const MAX_ELEVATION_POINTS = 1000;
+/**
+ * Cloudflare refuses a request URL longer than this at the edge, before the Worker runs.
+ *
+ * It bites well before `MAX_ELEVATION_POINTS` does. `URLSearchParams` percent-encodes both of
+ * the batch separators (`,` becomes `%2C`, `|` becomes `%7C`), so a coordinate costs about six
+ * bytes more than it reads, and a thousand six-decimal points is roughly 22 KB of URL. Past the
+ * limit the request never reaches the gateway: the caller gets an edge 414 with no error
+ * envelope to explain it, which is the least legible failure in the system. So the check is
+ * here, against the real encoded URL, and the message says what actually fits.
+ */
+declare const MAX_REQUEST_URL_BYTES = 16384;
+declare class ElevationError extends Error {
+    readonly status: number;
+    /** The gateway's machine-readable `code`, when the response carried one. */
+    readonly code?: string | undefined;
+    constructor(status: number, message: string, 
+    /** The gateway's machine-readable `code`, when the response carried one. */
+    code?: string | undefined);
+}
+/**
+ * Typed client for the unmap elevation API (gateway `/elevation`).
+ *
+ * Heights are metres above CGVD2013. `null` means the dataset covers nothing at that coordinate;
+ * it never means sea level, and the client does not substitute a number for it.
+ */
+declare class Elevation {
+    private readonly key;
+    private readonly base;
+    private readonly fetchImpl;
+    constructor(opts: ElevationOptions);
+    /**
+     * Ground elevation in metres, one entry per coordinate, in the order asked.
+     *
+     * Always an array, whether you passed one coordinate or a thousand, so the single and batch
+     * cases are the same call:
+     *
+     *   const [metres] = await unmap.elevation.get([-114.0719, 51.0447]);
+     */
+    get(points: LngLat | LngLat[], opts?: {
+        signal?: AbortSignal;
+    }): Promise<(number | null)[]>;
+}
+
+export { Elevation, ElevationError, type ElevationOptions, MAX_ELEVATION_POINTS, MAX_REQUEST_URL_BYTES };

package/dist/index.js

@@ -0,0 +1,87 @@
+// src/index.ts
+import { DEFAULT_GATEWAY } from "@unmap/core";
+var MAX_ELEVATION_POINTS = 1e3;
+var MAX_REQUEST_URL_BYTES = 16384;
+var URL_HEADROOM_BYTES = 256;
+var ElevationError = class extends Error {
+  constructor(status, message, code) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "ElevationError";
+  }
+  status;
+  code;
+};
+var Elevation = 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);
+  }
+  /**
+   * Ground elevation in metres, one entry per coordinate, in the order asked.
+   *
+   * Always an array, whether you passed one coordinate or a thousand, so the single and batch
+   * cases are the same call:
+   *
+   *   const [metres] = await unmap.elevation.get([-114.0719, 51.0447]);
+   */
+  async get(points, opts = {}) {
+    const list = isSingle(points) ? [points] : points;
+    if (list.length === 0) return [];
+    if (list.length > MAX_ELEVATION_POINTS) {
+      throw new ElevationError(400, `elevation.get takes at most ${MAX_ELEVATION_POINTS} coordinates`);
+    }
+    const q = new URLSearchParams({ key: this.key });
+    if (list.length === 1) {
+      const [lon, lat] = list[0];
+      q.set("lon", String(lon));
+      q.set("lat", String(lat));
+    } else {
+      q.set("points", list.map(([lng, lat]) => `${lng},${lat}`).join("|"));
+    }
+    const target = `${this.base}/elevation?${q}`;
+    const bytes = new TextEncoder().encode(target).length;
+    const budget = MAX_REQUEST_URL_BYTES - URL_HEADROOM_BYTES;
+    if (bytes > budget) {
+      const fits = Math.max(1, Math.floor(list.length * budget / bytes));
+      throw new ElevationError(
+        414,
+        `elevation.get built a ${bytes} byte request URL; this client sends at most ${budget} bytes, keeping headroom under the edge's ${MAX_REQUEST_URL_BYTES} byte limit. Send at most about ${fits} of these coordinates per request (roughly 700 at six decimal places).`
+      );
+    }
+    const res = await this.fetchImpl(target, {
+      signal: opts.signal,
+      headers: { accept: "application/json" }
+    });
+    if (!res.ok) throw await errorFrom(res);
+    const body = await res.json();
+    return body.elevations;
+  }
+};
+function isSingle(points) {
+  return typeof points[0] === "number";
+}
+async function errorFrom(res) {
+  const fallback = `elevation ${res.status}`;
+  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 ElevationError(res.status, reason ? `${reason} (${fallback})` : fallback, code);
+}
+export {
+  Elevation,
+  ElevationError,
+  MAX_ELEVATION_POINTS,
+  MAX_REQUEST_URL_BYTES
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { DEFAULT_GATEWAY } from \"@unmap/core\";\n\n/** [longitude, latitude]. Longitude first, everywhere in unmap. Not exported: `@unmap/routing`\n *  already exports a `LngLat` of the same shape, and both packages land in `@unmap/sdk`'s star\n *  exports, where two same-named exports would be a type error. */\ntype LngLat = [number, number];\n\nexport interface ElevationOptions {\n  key: string;\n  gateway?: string;\n  fetch?: typeof fetch;\n}\n\n/** The gateway's own cap. Checked here so an over-long batch fails without spending a call. */\nexport const MAX_ELEVATION_POINTS = 1000;\n\n/**\n * Cloudflare refuses a request URL longer than this at the edge, before the Worker runs.\n *\n * It bites well before `MAX_ELEVATION_POINTS` does. `URLSearchParams` percent-encodes both of\n * the batch separators (`,` becomes `%2C`, `|` becomes `%7C`), so a coordinate costs about six\n * bytes more than it reads, and a thousand six-decimal points is roughly 22 KB of URL. Past the\n * limit the request never reaches the gateway: the caller gets an edge 414 with no error\n * envelope to explain it, which is the least legible failure in the system. So the check is\n * here, against the real encoded URL, and the message says what actually fits.\n */\nexport const MAX_REQUEST_URL_BYTES = 16384;\n\n/** Headroom under the edge limit, so a proxy that appends a parameter cannot tip a request over. */\nconst URL_HEADROOM_BYTES = 256;\n\nexport class ElevationError extends Error {\n  constructor(\n    public readonly status: number,\n    message: string,\n    /** The gateway's machine-readable `code`, when the response carried one. */\n    public readonly code?: string,\n  ) {\n    super(message);\n    this.name = \"ElevationError\";\n  }\n}\n\ninterface ElevationResponse {\n  elevations: (number | null)[];\n  units: \"m\";\n  datum: string;\n  resolution: number;\n}\n\n/**\n * Typed client for the unmap elevation API (gateway `/elevation`).\n *\n * Heights are metres above CGVD2013. `null` means the dataset covers nothing at that coordinate;\n * it never means sea level, and the client does not substitute a number for it.\n */\nexport class Elevation {\n  private readonly key: string;\n  private readonly base: string;\n  private readonly fetchImpl: typeof fetch;\n\n  constructor(opts: ElevationOptions) {\n    this.key = opts.key;\n    this.base = (opts.gateway ?? DEFAULT_GATEWAY).replace(/\\/+$/, \"\");\n    // Bound to globalThis for the same reason Router does it: a bare `fetch` stored on an\n    // instance is invoked with that instance as its receiver, which browsers reject.\n    this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);\n  }\n\n  /**\n   * Ground elevation in metres, one entry per coordinate, in the order asked.\n   *\n   * Always an array, whether you passed one coordinate or a thousand, so the single and batch\n   * cases are the same call:\n   *\n   *   const [metres] = await unmap.elevation.get([-114.0719, 51.0447]);\n   */\n  async get(\n    points: LngLat | LngLat[],\n    opts: { signal?: AbortSignal } = {},\n  ): Promise<(number | null)[]> {\n    const list: LngLat[] = isSingle(points) ? [points] : points;\n    if (list.length === 0) return [];\n    if (list.length > MAX_ELEVATION_POINTS) {\n      throw new ElevationError(400, `elevation.get takes at most ${MAX_ELEVATION_POINTS} coordinates`);\n    }\n\n    const q = new URLSearchParams({ key: this.key });\n    if (list.length === 1) {\n      // Safe: the length check above guarantees index 0 exists.\n      const [lon, lat] = list[0]!;\n      q.set(\"lon\", String(lon));\n      q.set(\"lat\", String(lat));\n    } else {\n      q.set(\"points\", list.map(([lng, lat]) => `${lng},${lat}`).join(\"|\"));\n    }\n\n    const target = `${this.base}/elevation?${q}`;\n    const bytes = new TextEncoder().encode(target).length;\n    const budget = MAX_REQUEST_URL_BYTES - URL_HEADROOM_BYTES;\n    if (bytes > budget) {\n      // Scaled from the URL actually built, so the number quoted reflects this caller's own\n      // coordinate precision rather than an average of somebody else's.\n      const fits = Math.max(1, Math.floor((list.length * budget) / bytes));\n      throw new ElevationError(\n        414,\n        `elevation.get built a ${bytes} byte request URL; this client sends at most ${budget} ` +\n          `bytes, keeping headroom under the edge's ${MAX_REQUEST_URL_BYTES} byte limit. Send ` +\n          `at most about ${fits} of these coordinates per request (roughly 700 at six decimal ` +\n          `places).`,\n      );\n    }\n\n    const res = await this.fetchImpl(target, {\n      signal: opts.signal,\n      headers: { accept: \"application/json\" },\n    });\n    if (!res.ok) throw await errorFrom(res);\n    const body = (await res.json()) as ElevationResponse;\n    return body.elevations;\n  }\n}\n\n/** `[number, number]` is a coordinate; `[[number, number], ...]` is a list of them. */\nfunction isSingle(points: LngLat | LngLat[]): points is LngLat {\n  return typeof points[0] === \"number\";\n}\n\nasync function errorFrom(res: { status: number; json(): Promise<unknown> }): Promise<ElevationError> {\n  const fallback = `elevation ${res.status}`;\n  let body: { error?: unknown; code?: unknown } | undefined;\n  try {\n    body = (await res.json()) as { error?: unknown; code?: unknown };\n  } catch {\n    body = undefined;\n  }\n  const reason = typeof body?.error === \"string\" ? body.error : undefined;\n  const code = typeof body?.code === \"string\" ? body.code : undefined;\n  return new ElevationError(res.status, reason ? `${reason} (${fallback})` : fallback, code);\n}\n"],"mappings":";AAAA,SAAS,uBAAuB;AAczB,IAAM,uBAAuB;AAY7B,IAAM,wBAAwB;AAGrC,IAAM,qBAAqB;AAEpB,IAAM,iBAAN,cAA6B,MAAM;AAAA,EACxC,YACkB,QAChB,SAEgB,MAChB;AACA,UAAM,OAAO;AALG;AAGA;AAGhB,SAAK,OAAO;AAAA,EACd;AAAA,EAPkB;AAAA,EAGA;AAKpB;AAeO,IAAM,YAAN,MAAgB;AAAA,EACJ;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,MAAwB;AAClC,SAAK,MAAM,KAAK;AAChB,SAAK,QAAQ,KAAK,WAAW,iBAAiB,QAAQ,QAAQ,EAAE;AAGhE,SAAK,YAAY,KAAK,SAAS,WAAW,MAAM,KAAK,UAAU;AAAA,EACjE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,MAAM,IACJ,QACA,OAAiC,CAAC,GACN;AAC5B,UAAM,OAAiB,SAAS,MAAM,IAAI,CAAC,MAAM,IAAI;AACrD,QAAI,KAAK,WAAW,EAAG,QAAO,CAAC;AAC/B,QAAI,KAAK,SAAS,sBAAsB;AACtC,YAAM,IAAI,eAAe,KAAK,+BAA+B,oBAAoB,cAAc;AAAA,IACjG;AAEA,UAAM,IAAI,IAAI,gBAAgB,EAAE,KAAK,KAAK,IAAI,CAAC;AAC/C,QAAI,KAAK,WAAW,GAAG;AAErB,YAAM,CAAC,KAAK,GAAG,IAAI,KAAK,CAAC;AACzB,QAAE,IAAI,OAAO,OAAO,GAAG,CAAC;AACxB,QAAE,IAAI,OAAO,OAAO,GAAG,CAAC;AAAA,IAC1B,OAAO;AACL,QAAE,IAAI,UAAU,KAAK,IAAI,CAAC,CAAC,KAAK,GAAG,MAAM,GAAG,GAAG,IAAI,GAAG,EAAE,EAAE,KAAK,GAAG,CAAC;AAAA,IACrE;AAEA,UAAM,SAAS,GAAG,KAAK,IAAI,cAAc,CAAC;AAC1C,UAAM,QAAQ,IAAI,YAAY,EAAE,OAAO,MAAM,EAAE;AAC/C,UAAM,SAAS,wBAAwB;AACvC,QAAI,QAAQ,QAAQ;AAGlB,YAAM,OAAO,KAAK,IAAI,GAAG,KAAK,MAAO,KAAK,SAAS,SAAU,KAAK,CAAC;AACnE,YAAM,IAAI;AAAA,QACR;AAAA,QACA,yBAAyB,KAAK,gDAAgD,MAAM,6CACtC,qBAAqB,mCAChD,IAAI;AAAA,MAEzB;AAAA,IACF;AAEA,UAAM,MAAM,MAAM,KAAK,UAAU,QAAQ;AAAA,MACvC,QAAQ,KAAK;AAAA,MACb,SAAS,EAAE,QAAQ,mBAAmB;AAAA,IACxC,CAAC;AACD,QAAI,CAAC,IAAI,GAAI,OAAM,MAAM,UAAU,GAAG;AACtC,UAAM,OAAQ,MAAM,IAAI,KAAK;AAC7B,WAAO,KAAK;AAAA,EACd;AACF;AAGA,SAAS,SAAS,QAA6C;AAC7D,SAAO,OAAO,OAAO,CAAC,MAAM;AAC9B;AAEA,eAAe,UAAU,KAA4E;AACnG,QAAM,WAAW,aAAa,IAAI,MAAM;AACxC,MAAI;AACJ,MAAI;AACF,WAAQ,MAAM,IAAI,KAAK;AAAA,EACzB,QAAQ;AACN,WAAO;AAAA,EACT;AACA,QAAM,SAAS,OAAO,MAAM,UAAU,WAAW,KAAK,QAAQ;AAC9D,QAAM,OAAO,OAAO,MAAM,SAAS,WAAW,KAAK,OAAO;AAC1D,SAAO,IAAI,eAAe,IAAI,QAAQ,SAAS,GAAG,MAAM,KAAK,QAAQ,MAAM,UAAU,IAAI;AAC3F;","names":[]}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@unmap/elevation",
+  "version": "0.12.0",
+  "description": "Typed client for the unmap elevation API (Canadian ground elevation)",
+  "license": "MIT",
+  "keywords": [
+    "unmap",
+    "elevation",
+    "dem",
+    "terrain",
+    "canada"
+  ],
+  "homepage": "https://unmap.dev/docs/elevation-api",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unmap-dev/unmap.git",
+    "directory": "packages/elevation"
+  },
+  "bugs": {
+    "url": "https://github.com/unmap-dev/unmap/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@unmap/core": "0.12.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}