@unmap/geocoding 0.27.0 → 0.28.0

package/dist/index.d.ts

@@ -916,8 +916,10 @@ interface Place {
         postcode?: string;
         country?: string;
     };
-    /** Metres from the anchor. Only on `nearby()`. */
+    /** Metres from the anchor on `nearby()`; metres off the route on `along()`. */
     distance?: number;
+    /** Metres from the start of the route to the nearest point on it. Only on `along()`. */
+    along?: number;
     /** Registry id of the dataset, for provenance. */
     source: string;
 }
@@ -973,6 +975,19 @@ interface PlaceNearbyOptions {
     lang?: string;
     signal?: AbortSignal;
 }
+interface PlaceAlongOptions {
+    /** Metres either side of the route, clamped server-side to 10..500. Default 50. */
+    radius?: number;
+    /** 1..200, default 50. Out of range is status 400. */
+    limit?: number;
+    lang?: string;
+    signal?: AbortSignal;
+}
+/** A GeoJSON LineString, the shape `/route` returns as `geometry`. */
+interface RouteLine {
+    type: "LineString";
+    coordinates: number[][];
+}
 /**
  * A places failure.
  *
@@ -1020,6 +1035,18 @@ declare class Places {
      * outside WGS84, including a bbox corner, rejects with status 400 and code `bad_request`.
      */
     nearby(category: string | readonly string[], opts?: PlaceNearbyOptions): Promise<PlacesResponse<Place[]>>;
+    /**
+     * Places of a category along a route, in the order the route reaches them.
+     *
+     * Pass the `geometry` a route response carries; each place comes back with `distance` (metres
+     * off the route) and `along` (metres from the start), sorted by `along`. The line is capped at
+     * 2,000 coordinates and 100 km (status 400 beyond either), and every coordinate must be in
+     * Canada (status 422, code `outside_coverage`). `category` resolves aliases as `nearby()` does.
+     *
+     *   const route = await router.route(from, to, { mode: "pedestrian" });
+     *   const { data } = await places.along(route.geometry, "cafe");
+     */
+    along(route: RouteLine, category: string | readonly string[], opts?: PlaceAlongOptions): Promise<PlacesResponse<Place[]>>;
     /**
      * One place by its unmap id.
      *
@@ -1101,8 +1128,10 @@ interface GeocodeResult {
     match_reasons?: GeocodeMatchReason[];
     /** Canonical category id (e.g. "health.pharmacy") when the feature carries one. */
     category?: string;
-    /** Spheroidal metres from the query anchor; only `/geocode/nearby` results carry it. */
+    /** Spheroidal metres from the query anchor (`/geocode/nearby`), or off the route (`/places/along`). */
     distance?: number;
+    /** Metres from the start of the route; only the geocode container's `/along` sets it. */
+    along?: number;
     names?: Record<string, string>;
     address?: {
         housenumber?: string;
@@ -1254,4 +1283,4 @@ declare class Geocoder {
     private query;
 }
 
-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 };
+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 PlaceAlongOptions, 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 RouteLine, 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 };

package/dist/index.js

@@ -1222,6 +1222,27 @@ var Places = class {
       lang: opts.lang
     }, opts.signal);
   }
+  /**
+   * Places of a category along a route, in the order the route reaches them.
+   *
+   * Pass the `geometry` a route response carries; each place comes back with `distance` (metres
+   * off the route) and `along` (metres from the start), sorted by `along`. The line is capped at
+   * 2,000 coordinates and 100 km (status 400 beyond either), and every coordinate must be in
+   * Canada (status 422, code `outside_coverage`). `category` resolves aliases as `nearby()` does.
+   *
+   *   const route = await router.route(from, to, { mode: "pedestrian" });
+   *   const { data } = await places.along(route.geometry, "cafe");
+   */
+  along(route, category, opts = {}) {
+    const body = {
+      route,
+      category: Array.isArray(category) ? category.join(",") : String(category),
+      ...opts.radius != null ? { radius: opts.radius } : {},
+      ...opts.limit != null ? { limit: opts.limit } : {},
+      ...opts.lang ? { lang: opts.lang } : {}
+    };
+    return this.request("/places/along", {}, opts.signal, body);
+  }
   /**
    * One place by its unmap id.
    *
@@ -1232,15 +1253,11 @@ var Places = class {
   get(id, opts = {}) {
     return this.request(`/places/${encodeURIComponent(id)}`, { lang: opts.lang }, opts.signal);
   }
-  async request(path, params, signal) {
+  async request(path, params, signal, body) {
     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 fetchWithRetry(
-      this.fetchImpl,
-      `${this.base}${path}?${q}`,
-      { signal, headers: { accept: "application/json" } },
-      this.retry
-    );
+    const init = body === void 0 ? { signal, headers: { accept: "application/json" } } : { method: "POST", signal, headers: { accept: "application/json", "content-type": "application/json" }, body: JSON.stringify(body) };
+    const res = await fetchWithRetry(this.fetchImpl, `${this.base}${path}?${q}`, init, this.retry);
     if (!res.ok) throw await errorFrom(res, path);
     return await res.json();
   }