@tomtom-org/maps-sdk 0.46.2 → 0.46.3

package/package.json

@@ -2,7 +2,7 @@
   "name": "@tomtom-org/maps-sdk",
   "author": "TomTom International B.V.",
   "license": "See in LICENSE.txt",
-  "version": "0.46.2",
+  "version": "0.46.3",
   "description": "TomTom Maps for JavaScript",
   "keywords": [
     "tomtom",
@@ -18,7 +18,7 @@
     "nodejs"
   ],
   "devDependencies": {
-    "@biomejs/biome": "^2.4.6",
+    "@biomejs/biome": "^2.4.7",
     "@size-limit/file": "^11.2.0",
     "@size-limit/preset-app": "^11.2.0",
     "size-limit": "^11.2.0",
@@ -28,7 +28,7 @@
   "peerDependencies": {
     "@turf/turf": "^7.3.4",
     "lodash-es": "^4.17.23",
-    "maplibre-gl": "^5.20.0",
+    "maplibre-gl": "^5.20.1",
     "zod": "^4.3.6"
   },
   "size-limit": [

package/services/dist/index.d.ts

@@ -48,6 +48,7 @@ import { Position } from 'geojson';
 import { PossibleLaneSeparator } from '@tomtom-org/maps-sdk/core';
 import { RevGeoAddressProps } from '@tomtom-org/maps-sdk/core';
 import { RoadShieldReference } from '@tomtom-org/maps-sdk/core';
+import { Route } from '@tomtom-org/maps-sdk/core';
 import { RoutePathPoint } from '@tomtom-org/maps-sdk/core';
 import { RoutePlanningLocation } from '@tomtom-org/maps-sdk/core';
 import { RouteProgressPoint } from '@tomtom-org/maps-sdk/core';
@@ -100,6 +101,200 @@ declare type AddressRangesAPI = {
     to: LatLonAPI;
 };
 
+/**
+ * Search for places along a route, ranked by detour cost.
+ *
+ * Returns POIs reachable within a given detour budget from the provided route geometry.
+ * Results are sorted by detour time (or offset along the route) so the most
+ * accessible stops appear first.
+ *
+ * @remarks
+ * This service is ideal for trip planning use cases:
+ * - Find fuel or EV charging stations along the way
+ * - Locate food stops or rest areas near the route
+ * - Surface services reachable within a time budget
+ *
+ * The `route` is typically sourced from a {@link calculateRoute} result.
+ *
+ * @param params Along-route search parameters including the route geometry and detour budget
+ * @param customTemplate Advanced customization for request/response handling
+ *
+ * @returns Promise resolving to a collection of matching places sorted by detour cost
+ *
+ * @example
+ * ```typescript
+ * // Find coffee shops within a 5-minute detour
+ * const results = await alongRouteSearch({
+ *   route: routeResult.features[0].geometry,
+ *   maxDetourTimeSeconds: 300,
+ *   query: 'coffee',
+ * });
+ *
+ * // EV chargers with a 10-minute budget, sorted by position on route
+ * const chargers = await alongRouteSearch({
+ *   route: routeResult.features[0].geometry,
+ *   maxDetourTimeSeconds: 600,
+ *   poiCategories: ['ELECTRIC_VEHICLE_STATION'],
+ *   sortBy: 'detourOffset',
+ * });
+ * ```
+ *
+ * @see [Along Route Search API Documentation](https://docs.tomtom.com/search-api/documentation/tomtom-orbis-maps/search-service/along-route-search)
+ *
+ * @ignore (exposed via 'search')
+ */
+declare const alongRouteSearch: (params: AlongRouteSearchParams, customTemplate?: Partial<AlongRouteSearchTemplate>) => Promise<AlongRouteSearchResponse>;
+
+/**
+ * Parameters for searching places along a route.
+ *
+ * Along-route search finds POIs near a provided route geometry and ranks them
+ * by the detour cost (time or distance offset) required to visit them.
+ *
+ * @remarks
+ * **Key Features:**
+ * - Search for POIs within a detour budget from the route
+ * - Sort results by detour time or route offset
+ * - Combine with POI category and brand filters
+ * - Use directly with a {@link calculateRoute} result
+ *
+ * **Use Cases:**
+ * - Find fuel stations or EV chargers along a trip
+ * - Locate rest stops or restaurants near a route
+ * - Surface services reachable within a time budget
+ *
+ * @example
+ * ```typescript
+ * // Find coffee shops within a 5-minute detour from a route
+ * const results = await search({
+ *   route: routeResult.features[0],
+ *   maxDetourTimeSeconds: 300,
+ *   query: 'coffee',
+ * });
+ *
+ * // Find EV charging stations using a plain coordinate array
+ * const chargers = await search({
+ *   route: [[4.9, 52.37], [4.95, 52.28], [5.1, 52.09]],
+ *   maxDetourTimeSeconds: 600,
+ *   poiCategories: ['ELECTRIC_VEHICLE_STATION'],
+ *   sortBy: 'detourOffset',
+ * });
+ * ```
+ *
+ * @group Along Route Search
+ */
+export declare type AlongRouteSearchParams = CommonSearchParams<AlongRouteSearchRequestAPI, AlongRouteSearchResponseAPI> & {
+    /**
+     * Route geometry to search along.
+     *
+     * Accepts any of three forms:
+     * - **`Route`** feature as returned by {@link calculateRoute} (most common)
+     * - **`LineString`** GeoJSON geometry object
+     * - **`Position[]`** — a plain array of `[longitude, latitude]` coordinate pairs
+     *
+     * Coordinates must always be in `[longitude, latitude]` order.
+     *
+     * @example
+     * ```typescript
+     * // Route Feature from calculateRoute (most common)
+     * route: routeResult.features[0]
+     *
+     * // GeoJSON LineString geometry
+     * route: routeResult.features[0].geometry
+     *
+     * // Plain coordinate array
+     * route: [[4.9, 52.37], [4.95, 52.28], [5.1, 52.09]]
+     * ```
+     */
+    route: LineString | Route | Position[];
+    /**
+     * Maximum allowed detour time in seconds.
+     *
+     * Only POIs reachable within this additional travel time from the route
+     * will be returned. Controls the width of the search corridor.
+     *
+     * @example
+     * ```typescript
+     * maxDetourTimeSeconds: 300  // 5-minute detour budget
+     * ```
+     */
+    maxDetourTimeSeconds: number;
+    /**
+     * Sort order for the results.
+     *
+     * @default 'detourTime'
+     *
+     * @example
+     * ```typescript
+     * sortBy: 'detourOffset'  // order by position along the route
+     * ```
+     */
+    sortBy?: AlongRouteSortBy;
+};
+
+/**
+ * @ignore
+ */
+export declare type AlongRouteSearchPayloadAPI = {
+    route: {
+        points: RoutePointAPI[];
+    };
+};
+
+/**
+ * Along-route search request type.
+ * @ignore
+ */
+export declare type AlongRouteSearchRequestAPI = PostObject<AlongRouteSearchPayloadAPI>;
+
+/**
+ * Response from an along-route search query.
+ *
+ * Contains places found near the route, sorted by detour time or offset,
+ * along with summary information about the search results.
+ *
+ * @group Along Route Search
+ */
+export declare type AlongRouteSearchResponse = Places<SearchPlaceProps, SearchSummary>;
+
+/**
+ * @ignore
+ */
+export declare type AlongRouteSearchResponseAPI = {
+    /**
+     * Summary information about the search that was performed.
+     */
+    summary: SummaryAPI;
+    /**
+     * The result list, sorted by detour time or offset.
+     */
+    results: AlongRouteSearchResultAPI[];
+};
+
+/**
+ * @ignore
+ */
+export declare type AlongRouteSearchResultAPI = CommonSearchPlaceResultAPI;
+
+/**
+ * Along-route search service template type.
+ * @ignore
+ */
+declare type AlongRouteSearchTemplate = ServiceTemplate<AlongRouteSearchParams, AlongRouteSearchRequestAPI, AlongRouteSearchResponseAPI, AlongRouteSearchResponse>;
+
+/**
+ * Result sorting order for along-route search.
+ *
+ * Controls how the returned POIs are ordered relative to the route.
+ *
+ * @remarks
+ * - `detourTime`: Sort by additional travel time required to visit the POI (default)
+ * - `detourOffset`: Sort by how far along the route the detour point falls
+ *
+ * @group Along Route Search
+ */
+export declare type AlongRouteSortBy = 'detourTime' | 'detourOffset';
+
 /**
  * @ignore
  */
@@ -883,6 +1078,12 @@ export declare type BudgetType = (typeof budgetTypes)[number];
 
 export declare const budgetTypes: readonly ["timeMinutes", "remainingChargeCPT", "spentChargePCT", "spentFuelLiters", "distanceKM"];
 
+/**
+ * Default function for building an along-route search request from {@link AlongRouteSearchParams}.
+ * @param params The along-route search parameters, with global configuration already merged into them.
+ */
+declare const buildAlongRouteSearchRequest: (params: AlongRouteSearchParams) => AlongRouteSearchRequestAPI;
+
 /**
  * Default function for building autocomplete request from {@link AutocompleteSearchParams}
  * @param params The autocomplete parameters, with global configuration already merged into them.
@@ -2143,12 +2344,6 @@ export declare type CommonGeocodeAndFuzzySearchParams = {
  *
  * @example
  * ```typescript
- * // Search with position bias
- * const searchParams: CommonPlacesParams<URL, Response> = {
- *   position: [4.9041, 52.3676],  // Near Amsterdam
- *   limit: 20
- * };
- *
  * // Search with geography type filter
  * const citySearch: CommonPlacesParams<URL, Response> = {
  *   geographyTypes: ['Municipality'],  // Only cities
@@ -2174,34 +2369,6 @@ export declare type CommonGeocodeAndFuzzySearchParams = {
  * @group Search
  */
 export declare type CommonPlacesParams<ApiRequest, ApiResponse> = CommonServiceParams<ApiRequest, ApiResponse> & {
-    /**
-     * Geographic position to bias search results.
-     *
-     * When provided, results closer to this position are ranked higher.
-     * Does not filter results, only influences ranking.
-     *
-     * @remarks
-     * **Coordinates:**
-     * - Longitude: -180 to +180 (East-West)
-     * - Latitude: -90 to +90 (North-South)
-     * - Format: [longitude, latitude]
-     *
-     * **Without Radius:**
-     * Supplying position without a radius parameter biases results toward this area
-     * but doesn't create a hard boundary.
-     *
-     * **Use Cases:**
-     * - "Find pizza near me" - bias toward user's location
-     * - "Main Street" - prioritize Main Streets in the target area
-     * - Local search within a city or region
-     *
-     * @example
-     * ```typescript
-     * position: [4.9041, 52.3676]  // Amsterdam coordinates
-     * position: [-74.0060, 40.7128]  // New York coordinates
-     * ```
-     */
-    position?: HasLngLat;
     /**
      * Maximum number of results to return.
      *
@@ -3239,18 +3406,25 @@ export declare type CostModel = {
 declare type CurrentTypeAPI = 'Direct_Current' | 'Alternating_Current_1_Phase' | 'Alternating_Current_3_Phase';
 
 declare const customize: {
-    buildRevGeoRequest: typeof buildRevGeoRequest;
-    parseRevGeoResponse: typeof parseRevGeoResponse;
-    reverseGeocodingTemplate: ReverseGeocodingTemplate;
+    alongRouteSearch: typeof alongRouteSearch;
+    buildAlongRouteSearchRequest: typeof buildAlongRouteSearchRequest;
+    parseAlongRouteSearchResponse: typeof parseAlongRouteSearchResponse;
+    alongRouteSearchTemplate: AlongRouteSearchTemplate;
 };
 
 declare const customize_10: {
+    buildTrafficIncidentDetailsRequest: typeof buildTrafficIncidentDetailsRequest;
+    parseTrafficIncidentDetailsResponse: typeof parseTrafficIncidentDetailsResponse;
+    trafficIncidentDetailsTemplate: TrafficIncidentDetailsTemplate;
+};
+
+declare const customize_11: {
     buildPlaceByIdRequest: typeof buildPlaceByIdRequest;
     parsePlaceByIdResponse: typeof parsePlaceByIdResponse;
     placeByIdTemplate: PlaceByIdTemplate;
 };
 
-declare const customize_11: {
+declare const customize_12: {
     autocompleteSearch: typeof autocompleteSearch;
     buildAutocompleteSearchRequest: typeof buildAutocompleteSearchRequest;
     parseAutocompleteSearchResponse: typeof parseAutocompleteSearchResponse;
@@ -3258,54 +3432,54 @@ declare const customize_11: {
 };
 
 declare const customize_2: {
+    buildRevGeoRequest: typeof buildRevGeoRequest;
+    parseRevGeoResponse: typeof parseRevGeoResponse;
+    reverseGeocodingTemplate: ReverseGeocodingTemplate;
+};
+
+declare const customize_3: {
     buildGeocodingRequest: typeof buildGeocodingRequest;
     parseGeocodingResponse: typeof parseGeocodingResponse;
     geocodingTemplate: GeocodingTemplate;
 };
 
-declare const customize_3: {
+declare const customize_4: {
     buildGeometryDataRequest: typeof buildGeometryDataRequest;
     parseGeometryDataResponse: typeof parseGeometryDataResponse;
     geometryDataTemplate: GeometryDataTemplate;
 };
 
-declare const customize_4: {
+declare const customize_5: {
     geometrySearch: typeof geometrySearch;
     buildGeometrySearchRequest: typeof buildGeometrySearchRequest;
     parseGeometrySearchResponse: typeof parseGeometrySearchResponse;
     geometrySearchTemplate: GeometrySearchTemplate;
 };
 
-declare const customize_5: {
+declare const customize_6: {
     buildCalculateRouteRequest: typeof buildCalculateRouteRequest;
     parseCalculateRouteResponse: typeof parseCalculateRouteResponse;
     calculateRouteTemplate: CalculateRouteTemplate;
 };
 
-declare const customize_6: {
+declare const customize_7: {
     buildReachableRangeRequest: typeof buildReachableRangeRequest;
     parseReachableRangeResponse: typeof parseReachableRangeResponse;
     reachableRangeTemplate: ReachableRangeTemplate;
 };
 
-declare const customize_7: {
+declare const customize_8: {
     buildEVChargingStationsAvailabilityRequest: typeof buildEVChargingStationsAvailabilityRequest;
     parseEVChargingStationsAvailabilityResponse: typeof parseEVChargingStationsAvailabilityResponse;
     evChargingStationsAvailabilityTemplate: EVChargingStationsAvailabilityTemplate;
 };
 
-declare const customize_8: {
+declare const customize_9: {
     buildTrafficAreaAnalyticsRequest: typeof buildTrafficAreaAnalyticsRequest;
     parseTrafficAreaAnalyticsResponse: typeof parseTrafficAreaAnalyticsResponse;
     trafficAreaAnalyticsTemplate: TrafficAreaAnalyticsTemplate;
 };
 
-declare const customize_9: {
-    buildTrafficIncidentDetailsRequest: typeof buildTrafficIncidentDetailsRequest;
-    parseTrafficIncidentDetailsResponse: typeof parseTrafficIncidentDetailsResponse;
-    trafficIncidentDetailsTemplate: TrafficIncidentDetailsTemplate;
-};
-
 /**
  * Access to service implementation components for advanced customization.
  *
@@ -3349,17 +3523,18 @@ declare const customize_9: {
  * @group Advanced
  */
 export declare const customizeService: {
-    reverseGeocode: typeof customize;
-    geocode: typeof customize_2;
-    geometryData: typeof customize_3;
-    geometrySearch: typeof customize_4;
-    calculateRoute: typeof customize_5;
-    reachableRange: typeof customize_6;
-    evChargingStationsAvailability: typeof customize_7;
-    trafficAreaAnalytics: typeof customize_8;
-    trafficIncidentDetails: typeof customize_9;
-    placeByID: typeof customize_10;
-    autocompleteSearch: typeof customize_11;
+    alongRouteSearch: typeof customize;
+    reverseGeocode: typeof customize_2;
+    geocode: typeof customize_3;
+    geometryData: typeof customize_4;
+    geometrySearch: typeof customize_5;
+    calculateRoute: typeof customize_6;
+    reachableRange: typeof customize_7;
+    evChargingStationsAvailability: typeof customize_8;
+    trafficAreaAnalytics: typeof customize_9;
+    trafficIncidentDetails: typeof customize_10;
+    placeByID: typeof customize_11;
+    autocompleteSearch: typeof customize_12;
 };
 
 /**
@@ -4059,6 +4234,30 @@ export declare type FuzzySearchParams = CommonSearchParams<URL, FuzzySearchRespo
      * minFuzzyLevel: 2  // Require at least moderate similarity
      * ```
      */
+    /**
+     * Geographic position to bias search results toward.
+     *
+     * When provided, results closer to this position are ranked higher.
+     * Does not filter results, only creates a soft bias.
+     *
+     * Accepts any {@link HasLngLat}-compatible value:
+     * - `[longitude, latitude]` coordinate pair
+     * - GeoJSON `Point` geometry
+     * - GeoJSON `Feature<Point>` — pass a {@link Place} directly
+     *
+     * @example
+     * ```typescript
+     * // Coordinate pair
+     * position: [4.9041, 52.3676]
+     *
+     * // Place result from a previous search
+     * position: searchResults.features[0]
+     *
+     * // GeoJSON Point
+     * position: { type: 'Point', coordinates: [4.9041, 52.3676] }
+     * ```
+     */
+    position?: HasLngLat;
     minFuzzyLevel?: number;
     /**
      * Maximum fuzziness level to be used.
@@ -4355,6 +4554,31 @@ export declare type GeocodingParams = Omit<CommonPlacesParams<URL, GeocodingResp
      * ```
      */
     query: string;
+    /**
+     * Geographic position to bias geocoding results toward.
+     *
+     * When provided, results closer to this position are ranked higher.
+     * Useful for resolving ambiguous queries (e.g. "Main Street") to
+     * the right city or region.
+     *
+     * Accepts any {@link HasLngLat}-compatible value:
+     * - `[longitude, latitude]` coordinate pair
+     * - GeoJSON `Point` geometry
+     * - GeoJSON `Feature<Point>` — pass a {@link Place} directly
+     *
+     * @example
+     * ```typescript
+     * // Coordinate pair
+     * position: [4.9041, 52.3676]
+     *
+     * // Place result from a previous search (e.g. user's selected location)
+     * position: selectedPlace
+     *
+     * // GeoJSON Point
+     * position: { type: 'Point', coordinates: [4.9041, 52.3676] }
+     * ```
+     */
+    position?: HasLngLat;
     /**
      * Indexes for which extended postal codes should be included in the results.
      *
@@ -5471,6 +5695,12 @@ declare type OpeningHoursAPI = Omit<OpeningHours, 'alwaysOpenThisPeriod' | 'time
     timeRanges: TimeRangeAPI[];
 };
 
+/**
+ * Default function to parse an along-route search response.
+ * @param apiResponse The API response.
+ */
+declare const parseAlongRouteSearchResponse: (apiResponse: AlongRouteSearchResponseAPI) => AlongRouteSearchResponse;
+
 /**
  * Default function to parse autocomplete response.
  * @param apiResponse The API response.
@@ -6703,6 +6933,14 @@ declare type RoutePathPointAPI = Omit<RoutePathPoint, 'point'> & {
     point: LatitudeLongitudePointAPI;
 };
 
+/**
+ * @ignore
+ */
+export declare type RoutePointAPI = {
+    lat: number;
+    lon: number;
+};
+
 /**
  * Route optimization strategy for route calculation.
  *
@@ -6894,7 +7132,7 @@ export declare class SDKServiceError extends SDKError {
  *
  * @group Search
  */
-export declare const search: (params: GeometrySearchParams | FuzzySearchParams, customTemplate?: Partial<GeometrySearchTemplate | FuzzySearchTemplate>) => Promise<SearchResponse>;
+export declare const search: (params: GeometrySearchParams | FuzzySearchParams | AlongRouteSearchParams, customTemplate?: Partial<GeometrySearchTemplate | FuzzySearchTemplate | AlongRouteSearchTemplate>) => Promise<SearchResponse>;
 
 declare type SearchFeatureCollectionProps = SearchSummary & {
     queryIntent?: QueryIntent[];
@@ -6971,16 +7209,16 @@ export declare type SearchIndexType = 'Geo' | 'PAD' | 'Addr' | 'Str' | 'XStr' |
  * Search for a single place by text query.
  *
  * Convenience function that calls {@link search} and returns the first result.
+ * Throws an error if no results are found.
  *
  * @param query - Search query string
- * @returns Promise resolving to the first matching place, or undefined if no results
+ * @returns Promise resolving to the first matching place
+ * @throws {Error} If no results are found for the query
  *
  * @example
  * ```typescript
  * const place = await searchOne('Vondelpark Amsterdam');
- * if (place) {
- *   console.log(place.properties.name);
- * }
+ * console.log(place.properties.poi?.name);
  * ```
  *
  * @remarks
@@ -6989,7 +7227,7 @@ export declare type SearchIndexType = 'Geo' | 'PAD' | 'Addr' | 'Str' | 'XStr' |
  *
  * @group Search
  */
-export declare const searchOne: (query: string) => Promise<Place<SearchPlaceProps_2> | undefined>;
+export declare const searchOne: (query: string) => Promise<Place<SearchPlaceProps_2>>;
 
 /**
  * Search service response containing places that match the query.