@tomtom-org/maps-sdk 0.30.2 → 0.31.1

package/map/package.json

@@ -14,14 +14,6 @@
     "clean:dist": "rimraf ./dist"
   },
   "types": "./dist/index.d.ts",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/tomtom-international/maps-sdk-js.git"
-  },
-  "bugs": {
-    "url": "https://github.com/tomtom-international/maps-sdk-js/issues"
-  },
-  "homepage": "https://github.com/tomtom-international/maps-sdk-js#readme",
   "devDependencies": {
     "@microsoft/api-extractor": "catalog:",
     "@rollup/plugin-terser": "catalog:",

package/package.json

@@ -2,12 +2,8 @@
   "name": "@tomtom-org/maps-sdk",
   "author": "TomTom International B.V.",
   "license": "See in LICENSE.txt",
-  "version": "0.30.2",
-  "description": "JavaScript library for TomTom maps and location services",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/tomtom-international/maps-sdk-js.git"
-  },
+  "version": "0.31.1",
+  "description": "TomTom Maps for JavaScript",
   "keywords": [
     "tomtom",
     "sdk",
@@ -21,12 +17,8 @@
     "web",
     "nodejs"
   ],
-  "bugs": {
-    "url": "https://github.com/tomtom-international/maps-sdk-js/issues"
-  },
-  "homepage": "https://github.com/tomtom-international/maps-sdk-js#readme",
   "devDependencies": {
-    "@biomejs/biome": "^2.3.3",
+    "@biomejs/biome": "^2.3.4",
     "@size-limit/file": "^11.2.0",
     "@size-limit/preset-app": "^11.2.0",
     "size-limit": "^11.2.0",
@@ -60,8 +52,6 @@
     "services/package.json",
     "package.json",
     "README.md",
-    "sdk-examples-collage.png",
-    "tomtom-logo-big.svg",
     "CHANGELOG.md",
     "LICENSE.txt"
   ],

package/services/dist/index.d.ts

@@ -665,7 +665,7 @@ declare type BatteryCurve = {
  *
  * @group Fuzzy Search
  */
-declare type BookmarkIntent = {
+export declare type BookmarkIntent = {
     /**
      * Query type identifier.
      *
@@ -685,7 +685,7 @@ declare type BookmarkIntent = {
  *
  * @group Fuzzy Search
  */
-declare type BookmarkIntentDetails = {
+export declare type BookmarkIntentDetails = {
     /**
      * The detected bookmark keyword.
      *
@@ -834,86 +834,13 @@ export declare const buildResponseError: (error: unknown, serviceName: ServiceNa
 export declare const buildValidationError: (error: ValidationError, serviceName: ServiceName) => SDKError;
 
 /**
- * Calculate optimal routes between locations with comprehensive routing options.
+ * Calculates a route between an origin and destination, optionally passing through extra waypoints.
  *
- * The Calculate Route service computes the best path between an origin and destination,
- * optionally passing through intermediate waypoints. Routes account for real-time traffic,
- * vehicle characteristics, and user preferences.
+ * @param params - Route calculation parameters including locations, travel mode, and other options
+ * @param customTemplate - Optional template customization for request/response handling
+ * @returns Promise resolving to calculated route(s) with geometry, distance, and travel time
  *
- * @remarks
- * This service provides:
- * - **Traffic-aware routing**: Uses current traffic and typical road speeds
- * - **Turn-by-turn guidance**: Optional navigation instructions
- * - **Alternative routes**: Multiple route options with different characteristics
- * - **EV routing**: Long-distance electric vehicle routing with charging stops
- * - **Consumption estimates**: Fuel or battery consumption calculations
- * - **Route sections**: Detailed breakdowns (tolls, ferries, traffic, countries)
- *
- * Route calculations consider:
- * - Current and historic traffic patterns
- * - Road types and speeds
- * - Vehicle specifications (dimensions, weight, engine type)
- * - User preferences (avoid tolls, motorways, ferries, etc.)
- * - Departure/arrival time
- *
- * @param params - Routing parameters including waypoints and options
- * @param customTemplate - Advanced customization for request/response handling
- *
- * @returns Promise resolving to calculated route(s) with geometry and metadata
- *
- * @example
- * ```typescript
- * // Basic route calculation
- * const route = await calculateRoute({
- *   key: 'your-api-key',
- *   locations: [
- *     [4.9041, 52.3676],  // Amsterdam
- *     [4.4777, 51.9244]   // Rotterdam
- *   ]
- * });
- *
- * // Route with guidance and alternatives
- * const guidedRoute = await calculateRoute({
- *   key: 'your-api-key',
- *   locations: [[4.9, 52.3], [4.5, 51.9]],
- *   guidance: { type: 'coded', phonetics: 'IPA' },
- *   maxAlternatives: 2,
- *   routeType: 'fastest',
- *   avoid: ['tollRoads'],
- *   departAt: new Date('2025-10-20T08:00:00Z')
- * });
- *
- * // Electric vehicle route with charging
- * const evRoute = await calculateRoute({
- *   key: 'your-api-key',
- *   locations: [[4.9, 52.3], [8.5, 50.1]],  // Long distance
- *   vehicleEngineType: 'electric',
- *   currentChargeInkWh: 50,
- *   maxChargeInkWh: 85,
- *   constantSpeedConsumptionInkWhPerHundredkm: [[50, 8], [80, 12], [120, 18]]
- * });
- *
- * // Multi-stop delivery route
- * const deliveryRoute = await calculateRoute({
- *   key: 'your-api-key',
- *   locations: [
- *     [4.9, 52.3],   // Warehouse
- *     [4.85, 52.32], // Stop 1
- *     [4.88, 52.35], // Stop 2
- *     [4.92, 52.38]  // Stop 3
- *   ],
- *   vehicleCommercial: true,
- *   vehicleLoadType: ['otherHazmatGeneral']
- * });
- * ```
- *
- * @see [Calculate Route API Documentation](https://docs.tomtom.com/routing-api/documentation/routing/calculate-route)
- * @see [Routing Quickstart Guide](https://docs.tomtom.com/maps-sdk-js/guides/services/routing/quickstart)
- * @see [Planning a Route Guide](https://docs.tomtom.com/maps-sdk-js/guides/services/routing/planning-a-route)
- * @see [Waypoints and Custom Routes Guide](https://docs.tomtom.com/maps-sdk-js/guides/services/routing/waypoints-and-custom-routes)
- * @see [Planning Criteria Guide](https://docs.tomtom.com/maps-sdk-js/guides/services/routing/planning-criteria)
- * @see [Route Sections Guide](https://docs.tomtom.com/maps-sdk-js/guides/services/routing/route-sections)
- * @see [Long Distance EV Routing Guide](https://docs.tomtom.com/maps-sdk-js/guides/services/routing/long-distance-ev-routing)
+ * @see [Calculate Route API Documentation](https://docs.tomtom.com/routing-api/documentation/tomtom-maps/calculate-route)
  *
  * @group Routing
  */
@@ -929,7 +856,7 @@ export declare const calculateRoute: (params: CalculateRouteParams, customTempla
  * ```typescript
  * // Basic route from A to B
  * const params: CalculateRouteParams = {
- *   key: 'your-api-key',
+ *   apiKey: 'your-api-key',
  *   locations: [
  *     [4.9041, 52.3676],  // Amsterdam
  *     [4.4777, 51.9244]   // Rotterdam
@@ -938,23 +865,40 @@ export declare const calculateRoute: (params: CalculateRouteParams, customTempla
  *
  * // Route with guidance and alternatives
  * const advancedParams: CalculateRouteParams = {
- *   key: 'your-api-key',
+ *   apiKey: 'your-api-key',
  *   locations: [[4.9041, 52.3676], [4.4777, 51.9244]],
  *   guidance: { type: 'coded', phonetics: 'IPA' },
  *   maxAlternatives: 2,
- *   routeType: 'fastest',
- *   avoid: ['tollRoads', 'motorways'],
- *   departAt: new Date('2025-10-20T08:00:00Z')
+ *   costModel: {
+ *     routeType: 'fast',
+ *     avoid: ['tollRoads', 'motorways']
+ *   },
+ *   when: {
+ *     option: 'departAt',
+ *     date: new Date('2025-10-20T08:00:00Z')
+ *   }
  * };
  *
  * // Electric vehicle route with charging
  * const evParams: CalculateRouteParams = {
- *   key: 'your-api-key',
+ *   apiKey: 'your-api-key',
  *   locations: [[4.9, 52.3], [8.5, 50.1]],
- *   vehicleEngineType: 'electric',
- *   currentChargeInkWh: 50,
- *   maxChargeInkWh: 85,
- *   constantSpeedConsumptionInkWhPerHundredkm: [[50, 8], [80, 12], [120, 18]]
+ *   vehicle: {
+ *     engineType: 'electric',
+ *     model: {
+ *       engine: {
+ *         consumption: {
+ *           charging: { maxChargeKWH: 85 },
+ *           speedToConsumption: [
+ *             { speedKMH: 50, consumptionUnitsPer100KM: 8 },
+ *             { speedKMH: 80, consumptionUnitsPer100KM: 12 },
+ *             { speedKMH: 120, consumptionUnitsPer100KM: 18 }
+ *           ]
+ *         }
+ *       }
+ *     },
+ *     state: { currentChargeInkWh: 50 }
+ *   }
  * };
  * ```
  *
@@ -2864,7 +2808,7 @@ declare type ConsumptionModelEfficiency = {
  *
  * @group Fuzzy Search
  */
-declare type CoordinateIntent = {
+export declare type CoordinateIntent = {
     /**
      * Query type identifier.
      *
@@ -2880,7 +2824,7 @@ declare type CoordinateIntent = {
 /**
  * @ignore
  */
-declare type CoordinateIntentAPI = {
+export declare type CoordinateIntentAPI = {
     /**
      * the query is a coordinate in one of the supported formats (e.g., "48.858380, 2.294440").
      */
@@ -2895,7 +2839,7 @@ declare type CoordinateIntentAPI = {
  *
  * @group Fuzzy Search
  */
-declare type CoordinateIntentDetails = {
+export declare type CoordinateIntentDetails = {
     /**
      * Position of the parsed coordinate from user input.
      *
@@ -2909,7 +2853,7 @@ declare type CoordinateIntentDetails = {
 /**
  * @ignore
  */
-declare type CoordinateIntentDetailsAPI = {
+export declare type CoordinateIntentDetailsAPI = {
     /**
      * Latitude of the (parsed) user input coordinate. See LatLon. The results will be places nearby this coordinate.
      * If lat and lon parameters are specified, the dist field will have the distance between the geoBias and the searched coordinate.
@@ -3630,6 +3574,75 @@ export declare type FetchInput<PostData = void> = {
     method: 'POST';
 } & PostObject<PostData>);
 
+/**
+ * Search for places using free-text queries with fuzzy matching.
+ *
+ * The Fuzzy Search service provides a flexible search that handles typos, abbreviations,
+ * and incomplete addresses. It searches across POIs (Points of Interest), addresses,
+ * and geographic areas to find the best matches for your query.
+ *
+ * @remarks
+ * Key features:
+ * - **Typo tolerance**: Handles misspellings and typing errors
+ * - **Partial matching**: Works with incomplete queries
+ * - **Multi-category search**: Searches POIs, addresses, and places simultaneously
+ * - **Position bias**: Prioritizes results near a given location
+ * - **Flexible input**: Accepts natural language queries
+ *
+ * The service is ideal for:
+ * - User-facing search boxes where typos are common
+ * - Location lookup without knowing exact names
+ * - General "find anything" search functionality
+ * - Autocomplete with final selection
+ *
+ * @param params Fuzzy search parameters including the search query
+ * @param customTemplate Advanced customization for request/response handling
+ *
+ * @returns Promise resolving to a collection of matching places
+ *
+ * @example
+ * ```typescript
+ * // Basic search with typo tolerance
+ * const results = await fuzzySearch({
+ *   key: 'your-api-key',
+ *   query: 'amstrdam'  // Typo: missing 'e'
+ * });
+ * // Still finds "Amsterdam"
+ *
+ * // Search near a specific location
+ * const nearby = await fuzzySearch({
+ *   key: 'your-api-key',
+ *   query: 'pizza',
+ *   at: [4.9041, 52.3676],  // Amsterdam
+ *   radius: 2000,  // Within 2km
+ *   limit: 10
+ * });
+ *
+ * // Search with category filter
+ * const restaurants = await fuzzySearch({
+ *   key: 'your-api-key',
+ *   query: 'italian',
+ *   categorySet: [7315],  // Restaurant category
+ *   at: [4.9041, 52.3676]
+ * });
+ *
+ * // Partial address search
+ * const addresses = await fuzzySearch({
+ *   key: 'your-api-key',
+ *   query: '123 main st',
+ *   countrySet: ['US'],
+ *   limit: 5
+ * });
+ * ```
+ *
+ * @see [Fuzzy Search API Documentation](https://docs.tomtom.com/search-api/documentation/search-service/fuzzy-search)
+ * @see [Places Quickstart Guide](https://docs.tomtom.com/maps-sdk-js/guides/services/places/quickstart)
+ * @see [Search Guide](https://docs.tomtom.com/maps-sdk-js/guides/services/places/search)
+ *
+ * @group Search
+ */
+export declare const fuzzySearch: (params: FuzzySearchParams, customTemplate?: Partial<FuzzySearchTemplate>) => Promise<FuzzySearchResponse>;
+
 /**
  * Additional properties for fuzzy search feature collection.
  *
@@ -3689,7 +3702,7 @@ declare type FuzzySearchFeatureCollectionProps = SearchSummary & {
  *
  * @group Search
  */
-declare type FuzzySearchParams = CommonSearchParams<URL, FuzzySearchResponseAPI> & CommonGeocodeAndFuzzySearchParams & {
+export declare type FuzzySearchParams = CommonSearchParams<URL, FuzzySearchResponseAPI> & CommonGeocodeAndFuzzySearchParams & {
     /**
      * Minimum fuzziness level to be used.
      *
@@ -3750,12 +3763,12 @@ declare type FuzzySearchParams = CommonSearchParams<URL, FuzzySearchResponseAPI>
  *
  * @group Fuzzy Search
  */
-declare type FuzzySearchResponse = Places<SearchPlaceProps, FuzzySearchFeatureCollectionProps>;
+export declare type FuzzySearchResponse = Places<SearchPlaceProps, FuzzySearchFeatureCollectionProps>;
 
 /**
  * @ignore
  */
-declare type FuzzySearchResponseAPI = {
+export declare type FuzzySearchResponseAPI = {
     /**
      * Summary information about the search that was performed.
      */
@@ -3771,7 +3784,7 @@ declare type FuzzySearchResponseAPI = {
 /**
  * @ignore
  */
-declare type FuzzySearchResultAPI = CommonSearchPlaceResultAPI;
+export declare type FuzzySearchResultAPI = CommonSearchPlaceResultAPI;
 
 /**
  * Fuzzy search service template type.
@@ -4722,7 +4735,7 @@ declare type MomentAPI = {
  *
  * @group Fuzzy Search
  */
-declare type NearbyIntent = {
+export declare type NearbyIntent = {
     /**
      * Query type identifier.
      *
@@ -4738,7 +4751,7 @@ declare type NearbyIntent = {
 /**
  * @ignore
  */
-declare type NearbyIntentAPI = {
+export declare type NearbyIntentAPI = {
     /**
      * the query asks for some entity in the proximity of another entity (e.g., "hotel near Lyon").
      */
@@ -4754,7 +4767,7 @@ declare type NearbyIntentAPI = {
  *
  * @group Fuzzy Search
  */
-declare type NearbyIntentDetails = {
+export declare type NearbyIntentDetails = {
     /**
      * Position of the reference location in the nearby search.
      *
@@ -4783,7 +4796,7 @@ declare type NearbyIntentDetails = {
 /**
  * @ignore
  */
-declare type NearbyIntentDetailsAPI = Omit<NearbyIntentDetails, 'position'> & {
+export declare type NearbyIntentDetailsAPI = Omit<NearbyIntentDetails, 'position'> & {
     /**
      * Latitude of the place, near which the user searches for something.
      * For example, for the input restaurant near Berlin central station this is the position of "Berlin Central Station".
@@ -5192,12 +5205,12 @@ declare type PredefinedVehicleModel = {
  *
  * @group Fuzzy Search
  */
-declare type QueryIntent = CoordinateIntent | NearbyIntent | W3WIntent | BookmarkIntent;
+export declare type QueryIntent = CoordinateIntent | NearbyIntent | W3WIntent | BookmarkIntent;
 
 /**
  * @ignore
  */
-declare type QueryIntentAPI = CoordinateIntentAPI | NearbyIntentAPI | W3WIntent | BookmarkIntent;
+export declare type QueryIntentAPI = CoordinateIntentAPI | NearbyIntentAPI | W3WIntent | BookmarkIntent;
 
 /**
  * Budget constraint for reachable range calculation.
@@ -6951,7 +6964,7 @@ declare type ViewportAPI = {
  *
  * @group Fuzzy Search
  */
-declare type W3WIntent = {
+export declare type W3WIntent = {
     /**
      * Query type identifier.
      *
@@ -6971,7 +6984,7 @@ declare type W3WIntent = {
  *
  * @group Fuzzy Search
  */
-declare type W3WIntentDetails = {
+export declare type W3WIntentDetails = {
     /**
      * The detected what3words address.
      *

package/services/dist/services.cjs.js

@@ -4670,11 +4670,60 @@ const toCountrySectionProps = (apiSection) => ({
   countryCodeISO3: apiSection.countryCode
 });
 const toVehicleRestrictedSectionProps = (apiSection) => apiSection.travelMode === "other" ? toSectionProps(apiSection) : null;
+const calculateTrafficCategory = (tecMainCauseCode) => {
+  switch (tecMainCauseCode) {
+    case 1:
+      return "jam";
+    case 2:
+      return "accident";
+    case 3:
+      return "roadworks";
+    case 4:
+      return "narrow-lanes";
+    case 5:
+      return "road-closed";
+    case 9:
+      return "danger";
+    case 11:
+      return "animals-on-road";
+    case 13:
+      return "broken-down-vehicle";
+    case 16:
+      return "lane-closed";
+    case 17:
+      return "wind";
+    case 18:
+      return "fog";
+    case 19:
+      return "rain";
+    case 22:
+      return "frost";
+    case 23:
+      return "flooding";
+    default:
+      return "other";
+  }
+};
+const toTrafficCategories = (apiSection) => {
+  if (apiSection.tec?.causes?.length) {
+    return apiSection.tec.causes.map((cause) => calculateTrafficCategory(cause.mainCauseCode));
+  }
+  switch (apiSection.simpleCategory) {
+    case "JAM":
+      return ["jam"];
+    case "ROAD_WORK":
+      return ["roadworks"];
+    case "ROAD_CLOSURE":
+      return ["road-closed"];
+    default:
+      return ["other"];
+  }
+};
 const toTrafficSectionProps = (apiSection) => ({
   ...toSectionProps(apiSection),
   delayInSeconds: apiSection.delayInSeconds,
   effectiveSpeedInKmh: apiSection.effectiveSpeedInKmh,
-  simpleCategory: apiSection.simpleCategory.toLowerCase(),
+  categories: toTrafficCategories(apiSection),
   magnitudeOfDelay: core.indexedMagnitudes[apiSection.magnitudeOfDelay],
   tec: apiSection.tec
 });
@@ -4999,6 +5048,7 @@ exports.buildValidationError = buildValidationError;
 exports.calculateRoute = calculateRoute;
 exports.customizeService = customizeService;
 exports.evChargingStationsAvailability = evChargingStationsAvailability;
+exports.fuzzySearch = fuzzySearch;
 exports.geocode = geocode;
 exports.geocodeOne = geocodeOne;
 exports.geometryData = geometryData;