@unmap/geocoding 0.0.1 → 0.1.0

package/README.md

@@ -0,0 +1,34 @@
+# @unmap/geocoding
+
+Typed client for the [unmap](https://unmap.dev) geocoding API: full-text search, type-ahead
+autocomplete, category search, and reverse lookup over Canadian addresses and places, with
+English, French, and Indigenous-language names on the same record. No map dependency; works in
+Node and the browser.
+
+```bash
+npm i @unmap/geocoding
+```
+
+```ts
+import { Geocoder } from '@unmap/geocoding'
+
+const geocoder = new Geocoder({ key: 'um_live_...' })
+
+await geocoder.search('Château Frontenac', { lang: 'fr', limit: 5 })
+await geocoder.autocomplete('rue sainte-cath', { lang: 'fr' })
+await geocoder.nearby('pharmacy', { near: [-114.07, 51.05], radius: 2000 })
+await geocoder.reverse(-68.517, 63.749)
+```
+
+Every method resolves to a `GeocodeResult[]`: `id`, `name`, `layer`, `lng`, `lat`, plus `score`
+(search and autocomplete), `distance` in metres and `category` (nearby), `names` when the place
+has names in more than one language, and a structured `address` when one exists.
+
+`search` and `autocomplete` take `{ limit, lang, bbox, signal }`; `nearby` takes exactly one of
+`near: [lng, lat]` or `bbox`, plus `{ radius, limit, lang, signal }`; `reverse` takes
+`{ lang, signal }`. `category` accepts taxonomy ids (`health.pharmacy`) or plain English or
+French words (`pharmacy`, `pharmacie`). A non-2xx response throws a `GeocoderError` carrying the
+HTTP `status`.
+
+Parameters, defaults, the category list, and error bodies are documented at
+[unmap.dev/docs/geocoding-api](https://unmap.dev/docs/geocoding-api).

package/dist/index.d.ts

@@ -12,6 +12,10 @@ interface GeocodeResult {
     lng: number;
     lat: number;
     score?: number;
+    /** 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. */
+    distance?: number;
     names?: Record<string, string>;
     address?: {
         housenumber?: string;
@@ -29,6 +33,17 @@ interface SearchOptions {
     bbox?: [number, number, number, number];
     signal?: AbortSignal;
 }
+interface NearbyOptions {
+    /** [lng, lat] anchor to sort by distance from. Exactly one of `near` or `bbox`. */
+    near?: [number, number];
+    /** [minLng, minLat, maxLng, maxLat]; the API anchors at its centre. */
+    bbox?: [number, number, number, number];
+    /** Search radius in metres (API default 5000, clamped to [50, 50000]). */
+    radius?: number;
+    limit?: number;
+    lang?: string;
+    signal?: AbortSignal;
+}
 declare class GeocoderError extends Error {
     readonly status: number;
     constructor(status: number, message: string);
@@ -43,6 +58,13 @@ declare class Geocoder {
     search(q: string, opts?: SearchOptions): Promise<GeocodeResult[]>;
     /** Type-ahead suggestions for partial input. */
     autocomplete(q: string, opts?: SearchOptions): 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
+     * plain words in English or French ("pharmacy", "pharmacie") — the gateway resolves
+     * aliases, so this client passes the value through untouched.
+     */
+    nearby(category: string | string[], opts?: NearbyOptions): Promise<GeocodeResult[]>;
     /** Reverse geocode a coordinate. */
     reverse(lng: number, lat: number, opts?: {
         lang?: string;
@@ -51,4 +73,4 @@ declare class Geocoder {
     private query;
 }
 
-export { type GeocodeLayer, type GeocodeResult, Geocoder, GeocoderError, type GeocoderOptions, type SearchOptions };
+export { type GeocodeLayer, type GeocodeResult, Geocoder, GeocoderError, type GeocoderOptions, type NearbyOptions, type SearchOptions };

package/dist/index.js

@@ -25,6 +25,26 @@ var Geocoder = class {
   autocomplete(q, opts = {}) {
     return this.query("/geocode/autocomplete", { q, ...toParams(opts) }, 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
+   * plain words in English or French ("pharmacy", "pharmacie") — the gateway resolves
+   * aliases, so this client passes the value through untouched.
+   */
+  nearby(category, opts = {}) {
+    return this.query(
+      "/geocode/nearby",
+      {
+        category: Array.isArray(category) ? category.join(",") : category,
+        near: opts.near ? opts.near.join(",") : void 0,
+        bbox: opts.bbox ? opts.bbox.join(",") : void 0,
+        radius: opts.radius != null ? String(opts.radius) : void 0,
+        limit: opts.limit != null ? String(opts.limit) : void 0,
+        lang: opts.lang
+      },
+      opts.signal
+    );
+  }
   /** Reverse geocode a coordinate. */
   reverse(lng, lat, opts = {}) {
     return this.query(

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { DEFAULT_GATEWAY } from \"@unmap/core\";\n\nexport interface GeocoderOptions {\n  key: string;\n  gateway?: string;\n  /** Override the fetch implementation (tests, non-global environments). */\n  fetch?: typeof fetch;\n}\n\nexport type GeocodeLayer = \"address\" | \"street\" | \"locality\" | \"region\" | \"poi\";\n\nexport interface GeocodeResult {\n  id: string;\n  name: string;\n  layer: GeocodeLayer;\n  lng: number;\n  lat: number;\n  score?: number;\n  names?: Record<string, string>;\n  address?: {\n    housenumber?: string;\n    street?: string;\n    city?: string;\n    region?: string;\n    postcode?: string;\n    country?: string;\n  };\n}\n\nexport interface SearchOptions {\n  limit?: number;\n  lang?: string;\n  /** [minLng, minLat, maxLng, maxLat] bias/filter. */\n  bbox?: [number, number, number, number];\n  signal?: AbortSignal;\n}\n\nexport class GeocoderError extends Error {\n  constructor(\n    public readonly status: number,\n    message: string,\n  ) {\n    super(message);\n    this.name = \"GeocoderError\";\n  }\n}\n\n/** Typed client for the unmap geocoding API (gateway `/geocode/*`). */\nexport class Geocoder {\n  private readonly key: string;\n  private readonly base: string;\n  private readonly fetchImpl: typeof fetch;\n\n  constructor(opts: GeocoderOptions) {\n    this.key = opts.key;\n    this.base = (opts.gateway ?? DEFAULT_GATEWAY).replace(/\\/+$/, \"\");\n    // Bound to globalThis: stored on an instance and called as `this.fetchImpl(...)`, a bare\n    // `fetch` reference is invoked with the Geocoder as its receiver, and browsers reject that\n    // with \"Illegal invocation\". Node is lenient, so this only ever surfaces in the browser.\n    this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);\n  }\n\n  /** Full-text search. */\n  search(q: string, opts: SearchOptions = {}): Promise<GeocodeResult[]> {\n    return this.query(\"/geocode/search\", { q, ...toParams(opts) }, opts.signal);\n  }\n\n  /** Type-ahead suggestions for partial input. */\n  autocomplete(q: string, opts: SearchOptions = {}): Promise<GeocodeResult[]> {\n    return this.query(\"/geocode/autocomplete\", { q, ...toParams(opts) }, opts.signal);\n  }\n\n  /** Reverse geocode a coordinate. */\n  reverse(\n    lng: number,\n    lat: number,\n    opts: { lang?: string; signal?: AbortSignal } = {},\n  ): Promise<GeocodeResult[]> {\n    return this.query(\n      \"/geocode/reverse\",\n      { lon: String(lng), lat: String(lat), lang: opts.lang },\n      opts.signal,\n    );\n  }\n\n  private async query(\n    path: string,\n    params: Record<string, string | undefined>,\n    signal?: AbortSignal,\n  ): Promise<GeocodeResult[]> {\n    const q = new URLSearchParams({ key: this.key });\n    for (const [k, v] of Object.entries(params)) if (v != null && v !== \"\") q.set(k, v);\n    const res = await this.fetchImpl(`${this.base}${path}?${q}`, {\n      signal,\n      headers: { accept: \"application/json\" },\n    });\n    if (!res.ok) throw new GeocoderError(res.status, `geocode ${res.status} on ${path}`);\n    const body = (await res.json()) as { results?: GeocodeResult[] } | GeocodeResult[];\n    return Array.isArray(body) ? body : (body.results ?? []);\n  }\n}\n\nfunction toParams(o: SearchOptions): Record<string, string | undefined> {\n  return {\n    limit: o.limit != null ? String(o.limit) : undefined,\n    lang: o.lang,\n    bbox: o.bbox ? o.bbox.join(\",\") : undefined,\n  };\n}\n"],"mappings":";AAAA,SAAS,uBAAuB;AAqCzB,IAAM,gBAAN,cAA4B,MAAM;AAAA,EACvC,YACkB,QAChB,SACA;AACA,UAAM,OAAO;AAHG;AAIhB,SAAK,OAAO;AAAA,EACd;AAAA,EALkB;AAMpB;AAGO,IAAM,WAAN,MAAe;AAAA,EACH;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,MAAuB;AACjC,SAAK,MAAM,KAAK;AAChB,SAAK,QAAQ,KAAK,WAAW,iBAAiB,QAAQ,QAAQ,EAAE;AAIhE,SAAK,YAAY,KAAK,SAAS,WAAW,MAAM,KAAK,UAAU;AAAA,EACjE;AAAA;AAAA,EAGA,OAAO,GAAW,OAAsB,CAAC,GAA6B;AACpE,WAAO,KAAK,MAAM,mBAAmB,EAAE,GAAG,GAAG,SAAS,IAAI,EAAE,GAAG,KAAK,MAAM;AAAA,EAC5E;AAAA;AAAA,EAGA,aAAa,GAAW,OAAsB,CAAC,GAA6B;AAC1E,WAAO,KAAK,MAAM,yBAAyB,EAAE,GAAG,GAAG,SAAS,IAAI,EAAE,GAAG,KAAK,MAAM;AAAA,EAClF;AAAA;AAAA,EAGA,QACE,KACA,KACA,OAAgD,CAAC,GACvB;AAC1B,WAAO,KAAK;AAAA,MACV;AAAA,MACA,EAAE,KAAK,OAAO,GAAG,GAAG,KAAK,OAAO,GAAG,GAAG,MAAM,KAAK,KAAK;AAAA,MACtD,KAAK;AAAA,IACP;AAAA,EACF;AAAA,EAEA,MAAc,MACZ,MACA,QACA,QAC0B;AAC1B,UAAM,IAAI,IAAI,gBAAgB,EAAE,KAAK,KAAK,IAAI,CAAC;AAC/C,eAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,MAAM,EAAG,KAAI,KAAK,QAAQ,MAAM,GAAI,GAAE,IAAI,GAAG,CAAC;AAClF,UAAM,MAAM,MAAM,KAAK,UAAU,GAAG,KAAK,IAAI,GAAG,IAAI,IAAI,CAAC,IAAI;AAAA,MAC3D;AAAA,MACA,SAAS,EAAE,QAAQ,mBAAmB;AAAA,IACxC,CAAC;AACD,QAAI,CAAC,IAAI,GAAI,OAAM,IAAI,cAAc,IAAI,QAAQ,WAAW,IAAI,MAAM,OAAO,IAAI,EAAE;AACnF,UAAM,OAAQ,MAAM,IAAI,KAAK;AAC7B,WAAO,MAAM,QAAQ,IAAI,IAAI,OAAQ,KAAK,WAAW,CAAC;AAAA,EACxD;AACF;AAEA,SAAS,SAAS,GAAsD;AACtE,SAAO;AAAA,IACL,OAAO,EAAE,SAAS,OAAO,OAAO,EAAE,KAAK,IAAI;AAAA,IAC3C,MAAM,EAAE;AAAA,IACR,MAAM,EAAE,OAAO,EAAE,KAAK,KAAK,GAAG,IAAI;AAAA,EACpC;AACF;","names":[]}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { DEFAULT_GATEWAY } from \"@unmap/core\";\n\nexport interface GeocoderOptions {\n  key: string;\n  gateway?: string;\n  /** Override the fetch implementation (tests, non-global environments). */\n  fetch?: typeof fetch;\n}\n\nexport type GeocodeLayer = \"address\" | \"street\" | \"locality\" | \"region\" | \"poi\";\n\nexport interface GeocodeResult {\n  id: string;\n  name: string;\n  layer: GeocodeLayer;\n  lng: number;\n  lat: number;\n  score?: number;\n  /** Canonical category id (e.g. \"health.pharmacy\") when the feature carries one. */\n  category?: string;\n  /** Spheroidal metres from the query anchor; only `/geocode/nearby` results carry it. */\n  distance?: number;\n  names?: Record<string, string>;\n  address?: {\n    housenumber?: string;\n    street?: string;\n    city?: string;\n    region?: string;\n    postcode?: string;\n    country?: string;\n  };\n}\n\nexport interface SearchOptions {\n  limit?: number;\n  lang?: string;\n  /** [minLng, minLat, maxLng, maxLat] bias/filter. */\n  bbox?: [number, number, number, number];\n  signal?: AbortSignal;\n}\n\nexport interface NearbyOptions {\n  /** [lng, lat] anchor to sort by distance from. Exactly one of `near` or `bbox`. */\n  near?: [number, number];\n  /** [minLng, minLat, maxLng, maxLat]; the API anchors at its centre. */\n  bbox?: [number, number, number, number];\n  /** Search radius in metres (API default 5000, clamped to [50, 50000]). */\n  radius?: number;\n  limit?: number;\n  lang?: string;\n  signal?: AbortSignal;\n}\n\nexport class GeocoderError extends Error {\n  constructor(\n    public readonly status: number,\n    message: string,\n  ) {\n    super(message);\n    this.name = \"GeocoderError\";\n  }\n}\n\n/** Typed client for the unmap geocoding API (gateway `/geocode/*`). */\nexport class Geocoder {\n  private readonly key: string;\n  private readonly base: string;\n  private readonly fetchImpl: typeof fetch;\n\n  constructor(opts: GeocoderOptions) {\n    this.key = opts.key;\n    this.base = (opts.gateway ?? DEFAULT_GATEWAY).replace(/\\/+$/, \"\");\n    // Bound to globalThis: stored on an instance and called as `this.fetchImpl(...)`, a bare\n    // `fetch` reference is invoked with the Geocoder as its receiver, and browsers reject that\n    // with \"Illegal invocation\". Node is lenient, so this only ever surfaces in the browser.\n    this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);\n  }\n\n  /** Full-text search. */\n  search(q: string, opts: SearchOptions = {}): Promise<GeocodeResult[]> {\n    return this.query(\"/geocode/search\", { q, ...toParams(opts) }, opts.signal);\n  }\n\n  /** Type-ahead suggestions for partial input. */\n  autocomplete(q: string, opts: SearchOptions = {}): Promise<GeocodeResult[]> {\n    return this.query(\"/geocode/autocomplete\", { q, ...toParams(opts) }, opts.signal);\n  }\n\n  /**\n   * Category search: POIs of a kind near a point, sorted by distance (metres, in each\n   * result's `distance`). `category` takes canonical taxonomy ids (\"health.pharmacy\") or\n   * plain words in English or French (\"pharmacy\", \"pharmacie\") — the gateway resolves\n   * aliases, so this client passes the value through untouched.\n   */\n  nearby(category: string | string[], opts: NearbyOptions = {}): Promise<GeocodeResult[]> {\n    return this.query(\n      \"/geocode/nearby\",\n      {\n        category: Array.isArray(category) ? category.join(\",\") : category,\n        near: opts.near ? opts.near.join(\",\") : undefined,\n        bbox: opts.bbox ? opts.bbox.join(\",\") : undefined,\n        radius: opts.radius != null ? String(opts.radius) : undefined,\n        limit: opts.limit != null ? String(opts.limit) : undefined,\n        lang: opts.lang,\n      },\n      opts.signal,\n    );\n  }\n\n  /** Reverse geocode a coordinate. */\n  reverse(\n    lng: number,\n    lat: number,\n    opts: { lang?: string; signal?: AbortSignal } = {},\n  ): Promise<GeocodeResult[]> {\n    return this.query(\n      \"/geocode/reverse\",\n      { lon: String(lng), lat: String(lat), lang: opts.lang },\n      opts.signal,\n    );\n  }\n\n  private async query(\n    path: string,\n    params: Record<string, string | undefined>,\n    signal?: AbortSignal,\n  ): Promise<GeocodeResult[]> {\n    const q = new URLSearchParams({ key: this.key });\n    for (const [k, v] of Object.entries(params)) if (v != null && v !== \"\") q.set(k, v);\n    const res = await this.fetchImpl(`${this.base}${path}?${q}`, {\n      signal,\n      headers: { accept: \"application/json\" },\n    });\n    if (!res.ok) throw new GeocoderError(res.status, `geocode ${res.status} on ${path}`);\n    const body = (await res.json()) as { results?: GeocodeResult[] } | GeocodeResult[];\n    return Array.isArray(body) ? body : (body.results ?? []);\n  }\n}\n\nfunction toParams(o: SearchOptions): Record<string, string | undefined> {\n  return {\n    limit: o.limit != null ? String(o.limit) : undefined,\n    lang: o.lang,\n    bbox: o.bbox ? o.bbox.join(\",\") : undefined,\n  };\n}\n"],"mappings":";AAAA,SAAS,uBAAuB;AAqDzB,IAAM,gBAAN,cAA4B,MAAM;AAAA,EACvC,YACkB,QAChB,SACA;AACA,UAAM,OAAO;AAHG;AAIhB,SAAK,OAAO;AAAA,EACd;AAAA,EALkB;AAMpB;AAGO,IAAM,WAAN,MAAe;AAAA,EACH;AAAA,EACA;AAAA,EACA;AAAA,EAEjB,YAAY,MAAuB;AACjC,SAAK,MAAM,KAAK;AAChB,SAAK,QAAQ,KAAK,WAAW,iBAAiB,QAAQ,QAAQ,EAAE;AAIhE,SAAK,YAAY,KAAK,SAAS,WAAW,MAAM,KAAK,UAAU;AAAA,EACjE;AAAA;AAAA,EAGA,OAAO,GAAW,OAAsB,CAAC,GAA6B;AACpE,WAAO,KAAK,MAAM,mBAAmB,EAAE,GAAG,GAAG,SAAS,IAAI,EAAE,GAAG,KAAK,MAAM;AAAA,EAC5E;AAAA;AAAA,EAGA,aAAa,GAAW,OAAsB,CAAC,GAA6B;AAC1E,WAAO,KAAK,MAAM,yBAAyB,EAAE,GAAG,GAAG,SAAS,IAAI,EAAE,GAAG,KAAK,MAAM;AAAA,EAClF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,OAAO,UAA6B,OAAsB,CAAC,GAA6B;AACtF,WAAO,KAAK;AAAA,MACV;AAAA,MACA;AAAA,QACE,UAAU,MAAM,QAAQ,QAAQ,IAAI,SAAS,KAAK,GAAG,IAAI;AAAA,QACzD,MAAM,KAAK,OAAO,KAAK,KAAK,KAAK,GAAG,IAAI;AAAA,QACxC,MAAM,KAAK,OAAO,KAAK,KAAK,KAAK,GAAG,IAAI;AAAA,QACxC,QAAQ,KAAK,UAAU,OAAO,OAAO,KAAK,MAAM,IAAI;AAAA,QACpD,OAAO,KAAK,SAAS,OAAO,OAAO,KAAK,KAAK,IAAI;AAAA,QACjD,MAAM,KAAK;AAAA,MACb;AAAA,MACA,KAAK;AAAA,IACP;AAAA,EACF;AAAA;AAAA,EAGA,QACE,KACA,KACA,OAAgD,CAAC,GACvB;AAC1B,WAAO,KAAK;AAAA,MACV;AAAA,MACA,EAAE,KAAK,OAAO,GAAG,GAAG,KAAK,OAAO,GAAG,GAAG,MAAM,KAAK,KAAK;AAAA,MACtD,KAAK;AAAA,IACP;AAAA,EACF;AAAA,EAEA,MAAc,MACZ,MACA,QACA,QAC0B;AAC1B,UAAM,IAAI,IAAI,gBAAgB,EAAE,KAAK,KAAK,IAAI,CAAC;AAC/C,eAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,MAAM,EAAG,KAAI,KAAK,QAAQ,MAAM,GAAI,GAAE,IAAI,GAAG,CAAC;AAClF,UAAM,MAAM,MAAM,KAAK,UAAU,GAAG,KAAK,IAAI,GAAG,IAAI,IAAI,CAAC,IAAI;AAAA,MAC3D;AAAA,MACA,SAAS,EAAE,QAAQ,mBAAmB;AAAA,IACxC,CAAC;AACD,QAAI,CAAC,IAAI,GAAI,OAAM,IAAI,cAAc,IAAI,QAAQ,WAAW,IAAI,MAAM,OAAO,IAAI,EAAE;AACnF,UAAM,OAAQ,MAAM,IAAI,KAAK;AAC7B,WAAO,MAAM,QAAQ,IAAI,IAAI,OAAQ,KAAK,WAAW,CAAC;AAAA,EACxD;AACF;AAEA,SAAS,SAAS,GAAsD;AACtE,SAAO;AAAA,IACL,OAAO,EAAE,SAAS,OAAO,OAAO,EAAE,KAAK,IAAI;AAAA,IAC3C,MAAM,EAAE;AAAA,IACR,MAAM,EAAE,OAAO,EAAE,KAAK,KAAK,GAAG,IAAI;AAAA,EACpC;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unmap/geocoding",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Typed client for the unmap geocoding API",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,7 +20,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@unmap/core": "0.0.1"
+    "@unmap/core": "0.1.0"
   },
   "devDependencies": {
     "tsup": "^8.3.0",