@tomtom-org/maps-sdk 0.54.0 → 0.55.1

package/map/package.json

@@ -17,6 +17,7 @@
     "build:watch": "vite build --watch",
     "build:full": "pnpm type-check && pnpm build",
     "type-check": "tsc --noEmit",
+    "refresh-style-fixture": "node scripts/refresh-style-fixture.mjs",
     "clean:dist": "rimraf ./dist"
   },
   "devDependencies": {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@tomtom-org/maps-sdk",
   "author": "TomTom International B.V.",
   "license": "See in LICENSE.txt",
-  "version": "0.54.0",
+  "version": "0.55.1",
   "description": "TomTom maps, search, geocoding, routing, isochrones, EV and traffic for JavaScript — typed GeoJSON services and a MapLibre GL JS map.",
   "homepage": "https://docs.tomtom.com/maps-sdk-js/introduction/overview",
   "repository": {

package/services/dist/index.d.ts

@@ -425,6 +425,66 @@ export declare const buildResponseError: (error: unknown, serviceName: ServiceNa
  */
 export declare const buildValidationError: (error: ValidationError, serviceName: ServiceName) => SDKError;
 //#endregion
+//#region src/shared/types/geoBias.d.ts
+/**
+ * A point to search around, optionally bounded by a radius.
+ *
+ * @remarks
+ * Without `radiusMeters` the point biases the ranking without restricting results; with it, results
+ * are confined to that circle.
+ *
+ * @group Search
+ */
+export type PointGeoBias = {
+  /**
+   * The point to search around, as `[longitude, latitude]` or any GeoJSON form carrying one.
+   */
+  position: HasLngLat;
+  /**
+   * Radius around `position`, in metres. Values of zero or less are ignored by the API.
+   */
+  radiusMeters?: number;
+};
+/**
+ * A rectangle to confine results to.
+ *
+ * @group Search
+ */
+export type BoundingBoxGeoBias = {
+  /**
+   * The rectangle, as `[minLongitude, minLatitude, maxLongitude, maxLatitude]` or any GeoJSON
+   * value a bounding box can be derived from — a `bbox` property, a Feature, or a geometry.
+   */
+  boundingBox: HasBBox;
+};
+/**
+ * Where to look: a point with an optional radius, or a bounding box — one or the other.
+ *
+ * @remarks
+ * The two cannot be combined, which is why they are a union rather than separate options: an
+ * endpoint applies exactly one geographic bias per request.
+ *
+ * @example
+ * ```typescript
+ * // Around a point, ranking bias only
+ * const nearAmsterdam: GeoBias = { position: [4.9, 52.3] };
+ *
+ * // Around a point, confined to 2 km
+ * const within2km: GeoBias = { position: [4.9, 52.3], radiusMeters: 2000 };
+ *
+ * // Inside the visible map area
+ * const inViewport: GeoBias = { boundingBox: map.getBounds().toArray().flat() as BBox };
+ * ```
+ *
+ * @group Search
+ */
+export type GeoBias = (PointGeoBias & {
+  boundingBox?: never;
+}) | (BoundingBoxGeoBias & {
+  position?: never;
+  radiusMeters?: never;
+});
+//#endregion
 //#region src/shared/types/commonGeocodeAndFuzzySearchParams.d.ts
 /**
  * Common parameters shared between fuzzy search and geocoding services.
@@ -501,86 +561,19 @@ export type CommonGeocodeAndFuzzySearchParams = {
    */
   offset?: number;
   /**
-   * Search radius in meters around the specified position.
-   *
-   * When used with `position`, constrains results to locations within
-   * this distance from the position. Creates a circular search area.
+   * Where to look: a point with an optional radius, or a bounding box.
    *
    * @remarks
-   * **Behavior:**
-   * - Must be used with `position` parameter
-   * - Values ≤ 0 are ignored (parameter has no effect)
-   * - Mutually exclusive with `boundingBox` (radius takes precedence)
-   *
-   * **Typical Values:**
-   * - 500m: Immediate vicinity (walking distance)
-   * - 2000m: Neighborhood area
-   * - 5000m: City district
-   * - 10000m: Greater city area
+   * A point without `radiusMeters` biases the ranking; with one, or with a `boundingBox`, results
+   * are confined to that area. Leave it out to search without a geographic bias.
    *
    * @example
    * ```typescript
-   * // Search within 1km radius
-   * radiusMeters: 1000
-   *
-   * // Search within 5km radius
-   * radiusMeters: 5000
-   *
-   * // Combined with position
-   * position: [4.9, 52.3],
-   * radiusMeters: 2000  // Within 2km of Amsterdam center
+   * geoBias: { position: [4.9, 52.3], radiusMeters: 2000 }
+   * geoBias: { boundingBox: [4.8, 52.3, 5.0, 52.4] }
    * ```
    */
-  radiusMeters?: number;
-  /**
-   * Bounding box to constrain search results to a rectangular area.
-   *
-   * Filters results to only include locations within the specified bounding box.
-   * Accepts various GeoJSON formats that contain or can derive a bounding box.
-   *
-   * @remarks
-   * **Accepted Formats:**
-   * - Direct BBox array: `[minLng, minLat, maxLng, maxLat]`
-   * - GeoJSON Feature/FeatureCollection with bbox property
-   * - Any GeoJSON geometry (bbox calculated automatically)
-   *
-   * **Important:**
-   * - Mutually exclusive with Point-Radius parameters
-   * - Point-Radius (`position` + `radiusMeters`) takes precedence if both provided
-   * - Useful for map viewport filtering
-   *
-   * **Use Cases:**
-   * - "Search in visible map area"
-   * - City/region boundary filtering
-   * - Custom geographic restrictions
-   *
-   * @example
-   * ```typescript
-   * // Direct bounding box (Amsterdam area)
-   * boundingBox: [4.8, 52.3, 5.0, 52.4]
-   *
-   * // From GeoJSON Feature
-   * boundingBox: {
-   *   type: 'Feature',
-   *   bbox: [4.8, 52.3, 5.0, 52.4],
-   *   geometry: { ... },
-   *   properties: {}
-   * }
-   *
-   * // From Polygon (bbox calculated)
-   * boundingBox: {
-   *   type: 'Polygon',
-   *   coordinates: [[
-   *     [4.8, 52.3],
-   *     [5.0, 52.3],
-   *     [5.0, 52.4],
-   *     [4.8, 52.4],
-   *     [4.8, 52.3]
-   *   ]]
-   * }
-   * ```
-   */
-  boundingBox?: HasBBox;
+  geoBias?: GeoBias;
   /**
    * Restrict search to specific countries.
    *
@@ -4028,28 +4021,19 @@ type AutocompleteSearchParams = CommonServiceParams<URL, AutocompleteSearchRespo
    */
   query: string;
   /**
-   * Position to bias results towards.
-   *
-   * Results closer to this location will be ranked higher in suggestions.
+   * The point to bias suggestions towards, and how far around it to look.
    *
    * @remarks
-   * Can be provided as:
-   * - Object with `lon` and `lat` properties
-   * - Array `[longitude, latitude]`
-   *
-   * When used without `radiusMeters`, biases results but doesn't restrict them.
-   * When used with `radiusMeters`, constrains results to that area.
+   * This endpoint biases by point only — it takes no bounding box. Without `radiusMeters` the
+   * point ranks nearer suggestions higher without restricting them.
    *
    * @example
    * ```typescript
-   * // Object format
-   * position: { lon: 4.9041, lat: 52.3676 }
-   *
-   * // Array format
-   * position: [4.9041, 52.3676]
+   * geoBias: { position: [4.9041, 52.3676] }
+   * geoBias: { position: [4.9041, 52.3676], radiusMeters: 5000 }
    * ```
    */
-  position?: HasLngLat;
+  geoBias?: PointGeoBias;
   /**
    * Maximum number of suggestions to return.
    *
@@ -4063,24 +4047,6 @@ type AutocompleteSearchParams = CommonServiceParams<URL, AutocompleteSearchRespo
    * ```
    */
   limit?: number;
-  /**
-   * Search radius in meters from the position.
-   *
-   * When combined with `position`, restricts results to within this radius.
-   * Without `position`, this parameter is ignored.
-   *
-   * @remarks
-   * Only results within this distance from `position` will be returned.
-   * Values ≤ 0 are ignored.
-   *
-   * @example
-   * ```typescript
-   * // Search within 5km of position
-   * position: [4.9, 52.3],
-   * radiusMeters: 5000
-   * ```
-   */
-  radiusMeters?: number;
   /**
    * Restrict results to specific countries.
    *
@@ -4490,31 +4456,6 @@ type GeocodingParams = Omit<CommonPlacesParams<URL, GeocodingResponseAPI> & Comm
    * ```
    */
   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.
    *
@@ -7976,8 +7917,8 @@ type ExplorationRecordType = 'POI' | 'PointAddress' | 'Street';
  * - `countries[0]` → `country`
  * - `poiBrands[0]` → `brand`
  * - `poiCategories` → `categories` (mapped to TomTom numeric category ids)
- * - `position` + `radiusMeters` → `near.coordinates` + `near.radius_km`
- * - `boundingBox` / `boundingBoxes` → `bboxes`
+ * - `geoBias` → `near.coordinates` + `near.radius_km`
+ * - `boundingBoxes` → `bboxes`
  * - `geometries` → `geometries` (Polygon/MultiPolygon passed through; Circle
  *   buffered to a Polygon; FeatureCollection flattened to its features)
  * - `municipalities` → `municipalities`
@@ -7989,23 +7930,18 @@ type ExplorationRecordType = 'POI' | 'PointAddress' | 'Street';
  * @ignore
  * @experimental
  */
-type ExplorationSearchParams = CommonSearchParams<ExplorationSearchRequestAPI, ExplorationSearchResponseAPI> & CommonGeocodeAndFuzzySearchParams & {
+type ExplorationSearchParams = CommonSearchParams<ExplorationSearchRequestAPI, ExplorationSearchResponseAPI> & Omit<CommonGeocodeAndFuzzySearchParams, 'geoBias'> & {
   /**
-   * Geographic position to restrict results around.
-   *
-   * Combined with {@link radiusMeters} this maps to the API's `near` filter.
-   * Accepts any {@link HasLngLat}-compatible value — a `[lon, lat]` tuple,
-   * a GeoJSON `Point`, or a `Feature<Point>`.
+   * The point to search around, and how far. Unlike the other search services, this endpoint
+   * takes a point and {@link boundingBoxes} as separate filters, so both may be given.
    */
-  position?: HasLngLat;
+  geoBias?: PointGeoBias;
   /**
    * Exact, case-sensitive municipality/city filters (e.g. `['Amsterdam', 'Utrecht']`).
    */
   municipalities?: string[];
   /**
-   * Additional bounding boxes to restrict results to.
-   *
-   * Merged with {@link boundingBox} and sent as the API's `bboxes` array.
+   * Bounding boxes to restrict results to, sent as the API's `bboxes` array.
    */
   boundingBoxes?: HasBBox[];
   /**
@@ -9108,30 +9044,6 @@ type FuzzySearchParams = CommonSearchParams<URL, FuzzySearchResponseAPI> & Commo
    * 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.