@tomtom-org/maps-sdk 0.54.0 → 0.56.0

package/services/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ZodError, ZodIssue, ZodObject } from "zod";
-import { AddressProperties, AreaAnalyticsMetricKey, Avoidable, BBox, ChargingPark, ChargingParkWithAvailability, ChargingStation, ChargingStationsAccessType, ChargingStationsAvailability, ChargingStopProps, CommonPlaceProps, Connector, ConnectorType, CurrentType, EVChargingStationWithAvailabilityPlaceProps, EntryPoint, Fuel, GeographyType, GetPositionEntryPointOption, GlobalConfig, HasBBox, HasLngLat, MapcodeType, OpeningHours, OpeningHoursMode, POICategory, Place, PlaceType, Places, PlugType, PolygonFeature, PolygonFeatures, RevGeoAddressProps, RoadShieldReference, Route, RoutePlanningLocation, Routes, SearchPlaceProps, TimeZone, TomTomAPIHeaders, TomTomHeaders, TrafficAreaAnalytics, TrafficIncidentDetails, TrafficIncidentRequestCategory, TrafficIncidentTEC, TrafficIncidentTimeValidity, TravelMode, View, inputSectionTypes } from "@tomtom-org/maps-sdk/core";
+import { AddressProperties, AreaAnalyticsMetricKey, Avoidable, ChargingPark, ChargingParkWithAvailability, ChargingStation, ChargingStationsAccessType, ChargingStationsAvailability, ChargingStopProps, CommonPlaceProps, Connector, ConnectorType, CurrentType, EVChargingStationWithAvailabilityPlaceProps, EntryPoint, Fuel, GeographyType, GetPositionEntryPointOption, GlobalConfig, HasBBox, HasLngLat, MapcodeType, OpeningHours, OpeningHoursMode, POICategory, Place, PlaceType, Places, PlugType, PolygonFeature, PolygonFeatures, RevGeoAddressProps, RoadShieldReference, Route, RoutePlanningLocation, Routes, SearchPlaceProps, TimeZone, TomTomAPIHeaders, TomTomHeaders, TrafficAreaAnalytics, TrafficIncidentDetails, TrafficIncidentRequestCategory, TrafficIncidentTEC, TrafficIncidentTimeValidity, TravelMode, View, inputSectionTypes } from "@tomtom-org/maps-sdk/core";
 //#region src/shared/types/apiResponseErrorTypes.d.ts
 /**
  * @ignore
@@ -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.
-   *
-   * @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
-   *
-   * @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
-   * ```
-   */
-  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.
+   * Where to look: a point with an optional radius, or 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
+   * 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
-   * // 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]
-   *   ]]
-   * }
+   * geoBias: { position: [4.9, 52.3], radiusMeters: 2000 }
+   * geoBias: { boundingBox: [4.8, 52.3, 5.0, 52.4] }
    * ```
    */
-  boundingBox?: HasBBox;
+  geoBias?: GeoBias;
   /**
    * Restrict search to specific countries.
    *
@@ -803,6 +796,10 @@ export type CommonPlacesParams<ApiRequest, ApiResponse> = CommonServiceParams<Ap
    * - `RU`: Russia's perspective
    * - `TR`: Turkey's perspective
    * - `CN`: China's perspective
+   * - `TW`: Taiwan's perspective
+   * - `RS`: Serbia's perspective
+   *
+   * `MA` is accepted by this type but is not supported by the current backend.
    *
    * **Affected Elements:**
    * - Border lines on maps
@@ -1888,9 +1885,11 @@ export type GenericVehicleParams = {
    * Model (static properties) of the vehicle with generic/unspecified engine type.
    *
    * @remarks
-   * Includes dimensions and other characteristics that don't change during travel.
+   * Includes dimensions and other characteristics that don't change during travel. A predefined
+   * `variantId` is not accepted here — only the charging-stops endpoint understands one, and that
+   * endpoint is reached with an electric vehicle carrying charging preferences.
    */
-  model?: VehicleModel;
+  model?: ExplicitVehicleModel<undefined>;
   /**
    * State of the vehicle with generic/unspecified engine type.
    *
@@ -1952,9 +1951,10 @@ export type CombustionVehicleParams = {
    * Model (static properties) specifically for combustion engine vehicles.
    *
    * @remarks
-   * Can include fuel consumption curves and efficiency parameters.
+   * Can include fuel consumption curves and efficiency parameters. A predefined `variantId` is not
+   * accepted here — only the charging-stops endpoint understands one.
    */
-  model?: VehicleModel<'combustion'>;
+  model?: ExplicitVehicleModel<'combustion'>;
   /**
    * State specifically for combustion engine vehicles.
    *
@@ -2060,7 +2060,9 @@ export type ElectricVehicleParams = {
    * Model (static properties) specifically for electric vehicles.
    *
    * @remarks
-   * Should include battery capacity, charging curve, and consumption profiles.
+   * Should include battery capacity, charging curve, and consumption profiles. A predefined
+   * `variantId` is accepted here, but only `calculateRoute` with charging preferences understands
+   * one — a range or a matrix has no charging stops to plan for.
    */
   model?: VehicleModel<'electric'>;
   /**
@@ -2160,6 +2162,23 @@ export type ElectricVehicleParams = {
  * @group Vehicle
  */
 export type VehicleParameters = (GenericVehicleParams | CombustionVehicleParams | ElectricVehicleParams) & VehicleRestrictions;
+/**
+ * An electric vehicle that has asked for charging stops.
+ *
+ * @remarks
+ * Charging preferences are what select the charging-stops endpoint, so `chargingStopsStrategy` —
+ * which no other endpoint accepts — requires this shape rather than plain
+ * {@link ElectricVehicleParams}.
+ *
+ * A predefined `model.variantId` is bound to the same endpoint, but the rule cannot ride on the
+ * vehicle type: `calculateReachableRange` takes the same vehicle and accepts a variant on its own.
+ * `calculateRoute` validates that pairing instead.
+ *
+ * @group Routing
+ */
+export type ElectricVehicleParamsWithChargingStops = ElectricVehicleParams & {
+  preferences: Required<ElectricVehiclePreferences>;
+} & VehicleRestrictions;
 //#endregion
 //#region src/shared/types/commonRoutingParams.d.ts
 /**
@@ -2965,7 +2984,7 @@ type GeoJsonTypes = GeoJSON["type"];
  * Bounding box
  * https://tools.ietf.org/html/rfc7946#section-5
  */
-type BBox$1 = [number, number, number, number] | [number, number, number, number, number, number];
+type BBox = [number, number, number, number] | [number, number, number, number, number, number];
 /**
  * A Position is an array of coordinates.
  * https://tools.ietf.org/html/rfc7946#section-3.1.1
@@ -3032,7 +3051,7 @@ interface GeoJsonObject {
    * The axes order of a bbox follows the axes order of geometries.
    * https://tools.ietf.org/html/rfc7946#section-5
    */
-  bbox?: BBox$1 | undefined;
+  bbox?: BBox | undefined;
 }
 /**
  * Union of GeoJSON objects.
@@ -3527,6 +3546,10 @@ type AlongRouteSearchResponseAPI = {
  * Controls how the returned POIs are ordered relative to the route.
  *
  * @remarks
+ * Pass these to {@link search}, which selects the request variant from the params it is given:
+ * a `route` property dispatches to along-route search, a `geometries` property to geometry search,
+ * and neither to fuzzy search. {@link alongRouteSearch} is also exported directly.
+ *
  * - `detourTime`: Sort by additional travel time required to visit the POI (default)
  * - `detourOffset`: Sort by how far along the route the detour point falls
  *
@@ -4028,28 +4051,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 +4077,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 +4486,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.
    *
@@ -4853,6 +4824,10 @@ type GeometrySearchResponseAPI = {
  * like "restaurants in this neighborhood" or "hotels within these city boundaries".
  *
  * @remarks
+ * Pass these to {@link search}, which selects the request variant from the params it is given:
+ * a `route` property dispatches to along-route search, a `geometries` property to geometry search,
+ * and neither to fuzzy search. There is no separate exported function for geometry search.
+ *
  * **Key Features:**
  * - Search within multiple geometries simultaneously
  * - Supports polygons, multipolygons, and circles
@@ -5248,6 +5223,10 @@ type PlaceByIdOptionalParams = {
    * - `RU`: Russia
    * - `TR`: Turkey
    * - `CN`: China
+   * - `TW`: Taiwan
+   * - `RS`: Serbia
+   *
+   * `MA` is accepted by this type but is not supported by the current backend.
    *
    * @default 'Unified'
    *
@@ -5475,7 +5454,7 @@ type SummaryAPI = {
   arrivalDateTime: string;
   deviationDistanceInMeters?: number;
   deviationDurationInSeconds?: number;
-  deviationPoint?: Point;
+  deviationPoint?: RoutePointAPI$1;
   originalWaypointIndexAtEndOfLeg?: number;
   historicTrafficTravelTimeInSeconds?: number;
   liveTrafficIncidentsTravelTimeInSeconds?: number;
@@ -5592,19 +5571,20 @@ type SectionsAPI = {
   importantRoadStretch?: ImportantRoadStretchSectionAPI[];
 };
 /**
- * Lat/lon point used in guidance instructions (different from the GeoJSON used elsewhere).
+ * Every point in a routing response — `deviationPoint`, a route-path point, an instruction's
+ * `maneuverPoint` — is a two-dimensional GeoJSON `Point`, so its coordinates are already
+ * `[longitude, latitude]` and the parser needs no narrowing of its own.
  * @ignore
  */
-type LatLonPointAPI = {
-  latitude: number;
-  longitude: number;
+type RoutePointAPI$1 = Omit<Point, 'coordinates'> & {
+  coordinates: [number, number];
 };
 /**
  * A point on the route path.
  * @ignore
  */
 type RoutePathPointAPI = {
-  point: LatLonPointAPI;
+  point: RoutePointAPI$1;
   distanceFromRouteStartInMeters: number;
   travelTimeFromRouteStartInSeconds: number;
 };
@@ -5690,7 +5670,7 @@ type SignpostAPI = {
 type InstructionAPI = {
   routeOffsetInMeters: number;
   maneuver?: string;
-  maneuverPoint: LatLonPointAPI;
+  maneuverPoint: RoutePointAPI$1;
   routePath?: RoutePathPointAPI[];
   nextRoadInformation?: InstructionRoadInformationAPI;
   previousRoadInformation?: InstructionRoadInformationAPI;
@@ -5889,18 +5869,23 @@ export type ReachableRangeCostModel = Omit<CostModel, 'avoid' | 'avoidAreas'> &
  * Vehicle parameters accepted by `calculateReachableRange`.
  *
  * @remarks
- * {@link VehicleParameters} without `state.heading`, which this endpoint rejects with
- * *"parameter [vehicleHeading] not supported"*. It stays available on `calculateRoute`, where the
- * routing API takes it as `vehicleHeadingInDegrees`.
+ * {@link VehicleParameters} without the two things this endpoint has no parameter for:
+ *
+ * - `state.heading`, which it rejects with *"parameter [vehicleHeading] not supported"*. The
+ *   routing API takes it as `vehicleHeadingInDegrees`.
+ * - `preferences`, whose only member is `chargingPreferences`. Those belong to the charging-stops
+ *   endpoint, and a range has no stops to plan. A predefined `model.variantId` therefore needs
+ *   nothing beside it here, unlike on `calculateRoute`.
  *
- * Everything else is unchanged, including the engine-specific `state` variants -- an electric
- * vehicle still picks between the percentage and kWh forms.
+ * Both stay available on `calculateRoute`. Everything else is unchanged, including the
+ * engine-specific `state` variants -- an electric vehicle still picks between the percentage and
+ * kWh forms.
  *
  * @group Reachable Range
  */
-export type ReachableRangeVehicleParameters = (Omit<GenericVehicleParams, 'state'> | (Omit<CombustionVehicleParams, 'state'> & {
+export type ReachableRangeVehicleParameters = (Omit<GenericVehicleParams, 'state' | 'preferences'> | (Omit<CombustionVehicleParams, 'state' | 'preferences'> & {
   state?: CombustionVehicleState;
-}) | (Omit<ElectricVehicleParams, 'state'> & {
+}) | (Omit<ElectricVehicleParams, 'state' | 'preferences'> & {
   state?: ElectricVehicleState;
 })) & VehicleRestrictions;
 /**
@@ -6269,6 +6254,8 @@ type ReverseGeocodingOptionalParams = {
    * - `TR` - Turkey
    * - `TW` - Taiwan
    *
+   * `MA` is accepted by this type but is not supported by the current backend.
+   *
    * @defaultValue `"Unified"`
    */
   view?: View;
@@ -6735,7 +6722,28 @@ type MaxNumberOfAlternatives = 0 | 1 | 2 | 3 | 4 | 5;
  *
  * @group Routing
  */
-type CalculateRouteParams = CommonServiceParams<CalculateRouteRequestAPI, CalculateRouteResponseAPI> & CommonRoutingParams & {
+type CalculateRouteParams = ({
+  chargingStopsStrategy?: never;
+} | {
+  /**
+   * How the service should plan charging stops on an electric route.
+   *
+   * Only the charging-stops endpoint understands it, and
+   * `vehicle.preferences.chargingPreferences` is what selects that endpoint — hence the
+   * vehicle this variant requires.
+   *
+   * @default 'automaticFastest' (the service's own default when unset)
+   *
+   * @example
+   * ```typescript
+   * // Plan the fastest journey, choosing charging stops along the way
+   * chargingStopsStrategy: 'automaticFastest'
+   * ```
+   */
+  chargingStopsStrategy: ChargingStopsStrategy;
+  /** An electric vehicle whose charging preferences ask the service to plan stops. */
+  vehicle: ElectricVehicleParamsWithChargingStops;
+}) & CommonServiceParams<CalculateRouteRequestAPI, CalculateRouteResponseAPI> & CommonRoutingParams & {
   /**
    * Ordered list of locations (waypoints) and/or path points for route calculation.
    *
@@ -6833,21 +6841,6 @@ type CalculateRouteParams = CommonServiceParams<CalculateRouteRequestAPI, Calcul
    * ```
    */
   computeTravelTimeFor?: ComputeTravelTimeFor;
-  /**
-   * How the service should plan charging stops on an electric route.
-   *
-   * Only applies to electric routes, so `vehicle.preferences.chargingPreferences` must be set
-   * too — validation says so before the request is sent.
-   *
-   * @default 'automaticFastest' (the service's own default when unset)
-   *
-   * @example
-   * ```typescript
-   * // Plan the fastest journey, choosing charging stops along the way
-   * chargingStopsStrategy: 'automaticFastest'
-   * ```
-   */
-  chargingStopsStrategy?: ChargingStopsStrategy;
   /**
    * Request extended progress information at route polyline points.
    *
@@ -7721,445 +7714,6 @@ export declare function getPlacesWithEVAvailability<P extends CommonPlaceProps =
  */
 export declare const hasChargingAvailability: (chargingPark: ChargingPark | ChargingParkWithAvailability | undefined) => chargingPark is ChargingParkWithAvailability;
 //#endregion
-//#region src/exploration-search/types/areaTags.d.ts
-/**
- * Canonical area-tag vocabulary used by the places-api. Tokens are
- * lowercase `snake_case` and describe the character of the municipality
- * polygon a hit sits in (currently populated for `DE` / `NL` / `FR`).
- *
- * Two groups are exposed below:
- *
- * - **Populated tokens** — the 46 tokens the current pipeline run actually
- *   emits, grouped by classification axis (settlement scale, density,
- *   terrain, tourism, etc.). These are what every live `area_tags` value
- *   will be drawn from today.
- * - **Reserved tokens** — vocabulary tokens that exist canonically but
- *   are not populated by the current pipeline run. They may appear in
- *   future runs without an API change, so callers should treat them as
- *   valid even though no hit returns them today.
- *
- * The schema doc warns the vocabulary may shift between pipeline
- * iterations, so SDK consumers should code defensively. The
- * {@link AreaTag} alias falls back to `string` to keep arbitrary
- * (yet-to-be-added) tokens type-compatible without losing IDE
- * autocompletion on the known set.
- *
- * @ignore
- * @experimental
- */
-export declare const POPULATED_AREA_TAGS: readonly ["village", "small_town", "mid_town", "suburban", "rural", "semi_rural", "residential", "inland", "coastal", "atlantic_coast", "alpine", "mountain", "foothills", "forest", "plains", "farmland", "agricultural", "no_tourism", "low_tourism", "moderate_tourism", "tourism_economy", "eco_tourism", "heritage_tourism", "watersports", "hiking", "cycling", "industrial", "logistics_hub", "retail_hub", "shopping_district", "hospital_town", "dining_scene", "car_oriented", "walkable", "transit_connected", "transit_sparse", "highway_corridor", "commuter_town", "low_traffic", "moderate_traffic", "sparse_commercial", "western_europe", "central_europe", "southern_europe", "north_american", "iberian"];
-/**
- * Vocabulary tokens that exist canonically in the area-tag taxonomy but
- * aren't emitted by the current pipeline run (per the schema doc's
- * "tokens that exist… but are not populated" list). Filtering on these
- * today returns zero hits, but a future pipeline run may activate them
- * without a wire-protocol change.
- *
- * @ignore
- * @experimental
- */
-export declare const RESERVED_AREA_TAGS: readonly ["lakefront", "riverine", "wetland", "marina", "harbor", "beach", "mediterranean", "ski_destination", "beach_destination", "wine_tourism", "vineyard", "university_town", "medieval_old_town", "unesco_site", "midwest_us", "rust_belt"];
-/**
- * Union of every populated area-tag token currently emitted by the
- * places-api pipeline.
- *
- * @ignore
- * @experimental
- */
-type PopulatedAreaTag = (typeof POPULATED_AREA_TAGS)[number];
-/**
- * Union of every canonical (populated + reserved) area-tag token. Reserved
- * tokens may begin appearing as the pipeline evolves.
- *
- * @ignore
- * @experimental
- */
-type CanonicalAreaTag = PopulatedAreaTag | (typeof RESERVED_AREA_TAGS)[number];
-/**
- * Area-tag token accepted by the places-api `area_tags` filter and
- * returned on each hit's `areaTags` property.
- *
- * Resolves to the canonical {@link CanonicalAreaTag} union for editor
- * autocompletion, but tolerates any other string so the SDK doesn't
- * hard-error on tokens added in a future pipeline run. To strictly
- * constrain inputs to the currently-known vocabulary, use
- * {@link CanonicalAreaTag} (or {@link PopulatedAreaTag}) directly.
- *
- * @example
- * ```typescript
- * // Autocomplete on the canonical vocabulary, but new tokens still type-check.
- * const tags: AreaTag[] = ['walkable', 'transit_connected'];
- * ```
- *
- * @ignore
- * @experimental
- */
-type AreaTag = CanonicalAreaTag | string;
-//#endregion
-//#region src/exploration-search/types/explorationSearchRequestAPI.d.ts
-/**
- * @ignore
- */
-type NearAPI = {
-  coordinates: Position;
-  radius_km: number;
-};
-/**
- * @ignore
- */
-type ExplorationSearchPayloadAPI = {
-  q?: string;
-  country?: string;
-  municipalities?: string[];
-  brand?: string;
-  categories?: string[];
-  types?: ExplorationRecordType[];
-  area_id?: string;
-  area_tags?: AreaTag[];
-  near?: NearAPI;
-  bboxes?: BBox[];
-  geometries?: (Polygon | MultiPolygon)[];
-  from?: number;
-  size?: number;
-};
-/**
- * Exploration search request type.
- * @ignore
- */
-type ExplorationSearchRequestAPI = PostObject<ExplorationSearchPayloadAPI>;
-//#endregion
-//#region src/exploration-search/types/explorationSearchResponseAPI.d.ts
-/**
- * @ignore
- */
-type ExplorationClassificationAPI = {
-  code: string;
-  name: string;
-};
-/**
- * @ignore
- */
-type ExplorationBrandAPI = {
-  id?: string;
-  name: string;
-};
-/**
- * @ignore
- * A single open interval inside {@link ExplorationOpeningHoursAPI.intervals}.
- *
- * - `days` — ISO day-of-week numbers `1` (Monday) through `7` (Sunday) the
- *   interval applies to.
- * - `open` / `close` — `HH:MM` strings. `"24:00"` denotes end-of-day so that
- *   round-the-clock intervals can be expressed as `00:00` → `24:00`.
- */
-type ExplorationOpeningIntervalAPI = {
-  days: number[];
-  open: string;
-  close: string;
-};
-/**
- * @ignore
- * Opening-hours payload as returned by the places-api. The compact raw
- * TomTom hours string is parsed upstream into structured `intervals`; the
- * source string is not exposed in the API response.
- */
-type ExplorationOpeningHoursAPI = {
-  is24h?: boolean;
-  intervals?: ExplorationOpeningIntervalAPI[];
-};
-/**
- * @ignore
- */
-type ExplorationChargingParkAPI = {
-  stationId?: string;
-  connectors?: {
-    id: string;
-  }[];
-};
-/**
- * @ignore
- * POI document fields nested under `poi` on each hit. The API strips
- * per-language name maps (`names`, `alternativeNames`) and the street
- * alternative-name map on the way out, so they are not modeled here.
- */
-type ExplorationPOIAPI = {
-  name?: string;
-  phone?: string;
-  url?: string;
-  brands?: ExplorationBrandAPI[];
-  categorySet?: string[];
-  classifications?: ExplorationClassificationAPI[];
-  preferredCategoryId?: string;
-  nearbyCategoryIds?: string[] | null;
-  feature?: string;
-  openingHours?: ExplorationOpeningHoursAPI;
-  accessType?: string | null;
-  outOfBusiness?: string | null;
-  heavyVehicleCategories?: string[];
-  timeZone?: TimeZone;
-};
-/**
- * @ignore
- * Envelope bounding box on Street records — two corner `[lon, lat]` positions.
- */
-type ExplorationViewportAPI = {
-  type: 'envelope';
-  coordinates: [Position, Position];
-};
-/**
- * @ignore
- * Hit shape shared across record types. API metadata (`id`, `score`,
- * `distance_m`, `address`, `position`) sits at the top level; POI document
- * fields are nested under `poi` on `type === 'POI'` hits. Positions are
- * GeoJSON `[lon, lat]` arrays (the API normalizes OpenSearch's `{lat, lon}`
- * storage form on the way out).
- *
- * Field presence by record type:
- * - `poi` — POI records only
- * - `viewport` — Street records only (envelope of the street extent)
- * - `address.entryPoint` — PointAddress records only
- */
-type ExplorationSearchResultAPI = {
-  id: string;
-  score?: number;
-  distance_m?: number;
-  type?: ExplorationRecordType;
-  dataSource?: string;
-  sourceId?: string;
-  country_code?: string;
-  aliasIds?: string[];
-  address?: AddressProperties & {
-    entryPoint?: string;
-  };
-  position: Position;
-  viewport?: ExplorationViewportAPI;
-  vehicleTypes?: string[];
-  chargingPark?: ExplorationChargingParkAPI;
-  placeId?: string;
-  adminChainId?: string;
-  poi?: ExplorationPOIAPI;
-  /** Id of the municipality polygon the hit sits in. Populated for DE / NL / FR only. */
-  area_id?: string;
-  /** ISO2 country of the municipality polygon the hit sits in. Populated for DE / NL / FR only. */
-  area_country?: string;
-  /** Area-character tokens propagated from the hit's municipality polygon. Populated for DE / NL / FR only. */
-  area_tags?: string[];
-};
-/**
- * @ignore
- * Envelope response shape — `total` is capped at 10000 even when more records match.
- */
-type ExplorationSearchResponseAPI = {
-  total: number;
-  hits: ExplorationSearchResultAPI[];
-};
-//#endregion
-//#region src/exploration-search/types/explorationSearchParams.d.ts
-/**
- * Record types the exploration search can return — POIs, standalone point
- * addresses, and street records. Matches the API's `types` filter vocabulary.
- *
- * @ignore
- * @experimental
- */
-type ExplorationRecordType = 'POI' | 'PointAddress' | 'Street';
-/**
- * Parameters for the exploration search service.
- *
- * Mirrors the input surface of the existing {@link search} service, with two
- * extra filters exposed by the exploration places API (`municipalities` and
- * `geometries`).
- *
- * @remarks
- * **Mapping to the places API body:**
- * - `query` → `q`
- * - `countries[0]` → `country`
- * - `poiBrands[0]` → `brand`
- * - `poiCategories` → `categories` (mapped to TomTom numeric category ids)
- * - `position` + `radiusMeters` → `near.coordinates` + `near.radius_km`
- * - `boundingBox` / `boundingBoxes` → `bboxes`
- * - `geometries` → `geometries` (Polygon/MultiPolygon passed through; Circle
- *   buffered to a Polygon; FeatureCollection flattened to its features)
- * - `municipalities` → `municipalities`
- * - `areaId` → `area_id`
- * - `areaTags` → `area_tags`
- * - `offset` → `from`
- * - `limit` → `size`
- *
- * @ignore
- * @experimental
- */
-type ExplorationSearchParams = CommonSearchParams<ExplorationSearchRequestAPI, ExplorationSearchResponseAPI> & CommonGeocodeAndFuzzySearchParams & {
-  /**
-   * 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>`.
-   */
-  position?: HasLngLat;
-  /**
-   * 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.
-   */
-  boundingBoxes?: HasBBox[];
-  /**
-   * Geometries to constrain results to. Accepts the same input shapes as
-   * {@link GeometrySearchParams.geometries} — `Polygon`, `MultiPolygon`,
-   * `Circle`, or `PolygonFeatures`. POIs whose position lies inside any
-   * provided shape are returned.
-   *
-   * Circles are buffered into polygons before being sent to the API.
-   */
-  geometries?: SearchGeometryInput[];
-  /**
-   * Restrict the response to specific record types. Defaults to all types.
-   *
-   * - `'POI'` — points of interest (businesses, landmarks, amenities)
-   * - `'PointAddress'` — standalone street addresses with building numbers
-   * - `'Street'` — street records (no building number)
-   *
-   * Example: `placeTypes: ['POI', 'PointAddress']` to exclude Street records.
-   */
-  placeTypes?: ExplorationRecordType[];
-  /**
-   * Exact id of a municipality polygon — restricts results to places that
-   * sit inside that municipality. Typically populated from the `areaId`
-   * of a previous hit ("what else is in this same area?"). Efficient
-   * terms-only lookup, no spatial query required.
-   */
-  areaId?: string;
-  /**
-   * Area-character tokens describing the surrounding municipality
-   * (`coastal`, `walkable`, `alpine`, `transit_connected`, …). Matches
-   * places in any municipality tagged with ANY of the supplied tokens
-   * (OR semantics). Populated for `DE` / `NL` / `FR` only — supplying
-   * tags in other countries will return zero hits.
-   *
-   * Typed against {@link AreaTag} — autocompletes on the canonical
-   * vocabulary but tolerates new tokens added in a future pipeline
-   * run without a wire-protocol change.
-   */
-  areaTags?: AreaTag[];
-};
-//#endregion
-//#region src/exploration-search/types/explorationSearchResponse.d.ts
-/**
- * Additional properties exposed on each feature in an exploration search
- * response. The places-api propagates "area" metadata from the municipality
- * polygon each hit sits in (currently populated for `DE` / `NL` / `FR`); the
- * SDK surfaces those fields alongside the standard {@link SearchPlaceProps}.
- *
- * The `address` is widened from the SDK's standard {@link AddressProperties}
- * to also expose the optional `entryPoint` string the places-api emits on
- * `PointAddress` records.
- *
- * @ignore
- * @experimental
- */
-type ExplorationPlaceProps = Omit<SearchPlaceProps, 'address'> & {
-  address: AddressProperties & {
-    entryPoint?: string;
-  };
-  /**
-   * Id of the municipality polygon this hit sits inside. Round-trips into
-   * `areaId` on a subsequent request to fetch every other place in the
-   * same municipality.
-   */
-  areaId?: string;
-  /**
-   * ISO 3166-1 alpha-2 country code of the hit's municipality polygon.
-   */
-  areaCountry?: string;
-  /**
-   * Area-character tokens describing the surrounding municipality
-   * (e.g. `coastal`, `walkable`, `transit_connected`).
-   *
-   * Typed against {@link AreaTag} for editor autocompletion on the
-   * canonical vocabulary; arbitrary strings stay compatible to
-   * tolerate future pipeline-run additions.
-   */
-  areaTags?: AreaTag[];
-};
-/**
- * Response from the exploration search service.
- *
- * Matches the shape produced by {@link search} — a `FeatureCollection` of
- * place features with search-specific properties (`score`, `distance`) and a
- * {@link SearchSummary} on the collection — extended with the
- * exploration-specific `areaId` / `areaCountry` / `areaTags` fields on each
- * feature.
- *
- * @ignore
- * @experimental
- */
-type ExplorationSearchResponse = Places<ExplorationPlaceProps, SearchSummary>;
-//#endregion
-//#region src/exploration-search/explorationSearchTemplate.d.ts
-/**
- * Exploration search service template type.
- * @ignore
- */
-type ExplorationSearchTemplate = ServiceTemplate<ExplorationSearchParams, ExplorationSearchRequestAPI, ExplorationSearchResponseAPI, ExplorationSearchResponse>;
-//#endregion
-//#region src/exploration-search/explorationSearch.d.ts
-/**
- * Search for places via the exploration places API.
- *
- * The exploration search service exposes the same input and output surface as
- * the existing {@link search} service, but targets the exploration places API
- * (POST `/places` with a JSON body) instead of the TomTom Search API.
- *
- * @remarks
- * Key features:
- * - **Fuzzy name match** via {@link ExplorationSearchParams.query}
- * - **Near filter** via `position` + `radiusMeters` (mapped to `near.coordinates` + `near.radius_km`)
- * - **Bounding box** via `boundingBox` (mapped to `bboxes`)
- * - **Geometries** via {@link ExplorationSearchParams.geometries} (Polygon,
- *   MultiPolygon, Circle, or FeatureCollection — same shape as {@link geometrySearch})
- * - **Brand / category / country / municipalities** filters
- * - **Pagination** via `offset` / `limit` (mapped to `from` / `size`)
- *
- * @param params Exploration search parameters
- * @param customTemplate Advanced customization for request/response handling
- *
- * @returns Promise resolving to a collection of matching places, with the same
- * {@link SearchPlaceProps} shape used by the existing search service.
- *
- * @example
- * ```typescript
- * // Nearest restaurants to Dam Square
- * const results = await explorationSearch({
- *   position: [4.9003, 52.3791],
- *   radiusMeters: 5000,
- *   poiCategories: ['RESTAURANT'],
- *   limit: 10,
- * });
- *
- * // Inside a GeoJSON polygon
- * const inArea = await explorationSearch({
- *   geometries: [{
- *     type: 'Polygon',
- *     coordinates: [[
- *       [4.878, 52.364], [4.922, 52.364],
- *       [4.922, 52.394], [4.878, 52.394],
- *       [4.878, 52.364],
- *     ]],
- *   }],
- *   poiCategories: ['RESTAURANT'],
- * });
- * ```
- *
- * @ignore
- * @experimental
- */
-export declare const explorationSearch: (params: ExplorationSearchParams, customTemplate?: Partial<ExplorationSearchTemplate>) => Promise<ExplorationSearchResponse>;
-//#endregion
 //#region src/geocode/geocoding.d.ts
 /**
  * Convert addresses into geographic coordinates (geocoding).
@@ -9048,6 +8602,10 @@ type NearbyIntentDetailsAPI = Omit<NearbyIntentDetails, 'position'> & {
  * It's designed to handle typos, abbreviations, and incomplete input gracefully.
  *
  * @remarks
+ * Pass these to {@link search}, which selects the request variant from the params it is given:
+ * a `route` property dispatches to along-route search, a `geometries` property to geometry search,
+ * and neither to fuzzy search. There is no separate exported function for fuzzy search.
+ *
  * **Key Features:**
  * - Tolerates typos and spelling mistakes
  * - Handles partial queries and abbreviations
@@ -9108,30 +8666,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.
@@ -9409,4 +8943,4 @@ export declare const trafficAreaAnalytics: (params: TrafficAreaAnalyticsParams,
  */
 export declare const trafficIncidentDetails: (params: TrafficIncidentDetailsParams, customTemplate?: Partial<TrafficIncidentDetailsTemplate>) => Promise<TrafficIncidentDetails>;
 //#endregion
-export type { AdditionalDataAPI, AlongRouteSearchParams, AlongRouteSearchPayloadAPI, AlongRouteSearchRequestAPI, AlongRouteSearchResponse, AlongRouteSearchResponseAPI, AlongRouteSearchResultAPI, AlongRouteSortBy, AreaAnalyticsDateInput, AreaTag, ArrivalSide, AutocompleteGenericSearchSegment, AutocompleteSearchBrandSegment, AutocompleteSearchCategorySegment, AutocompleteSearchCategorySegmentAPI, AutocompleteSearchContext, AutocompleteSearchContextAPI, AutocompleteSearchMatch, AutocompleteSearchMatches, AutocompleteSearchParams, AutocompleteSearchPlaintextSegment, AutocompleteSearchResponse, AutocompleteSearchResponseAPI, AutocompleteSearchResult, AutocompleteSearchResultAPI, AutocompleteSearchResultGeoBias, AutocompleteSearchResultGeoBiasAPI, AutocompleteSearchSegment, AutocompleteSearchSegmentAPI, AutocompleteSearchSegmentType, BookmarkIntent, BookmarkIntentDetails, CalculateRouteParams, CanonicalAreaTag, ChargingStationsAvailabilityParams, ChargingStopsStrategy, Circle, CircleAPI, CommonServiceParamsWithZoom, ComputeTravelTimeFor, CoordinateIntent, CoordinateIntentAPI, CoordinateIntentDetails, CoordinateIntentDetailsAPI, ExplorationBrandAPI, ExplorationChargingParkAPI, ExplorationClassificationAPI, ExplorationOpeningHoursAPI, ExplorationOpeningIntervalAPI, ExplorationPOIAPI, ExplorationPlaceProps, ExplorationRecordType, ExplorationSearchParams, ExplorationSearchPayloadAPI, ExplorationSearchRequestAPI, ExplorationSearchResponse, ExplorationSearchResponseAPI, ExplorationSearchResultAPI, ExplorationViewportAPI, ExtendedRouteRepresentation, FunctionalRoadClass, FuzzySearchParams, FuzzySearchResponse, FuzzySearchResponseAPI, FuzzySearchResultAPI, GeocodingParams, GeocodingProps, GeocodingResponse, GeometriesInput, GeometryAPI, GeometryDataParams, GeometryDataResponseAPI, GeometryParams, GeometryPlaceParams, GeometrySearchFeatureCollectionProps, GeometrySearchParams, GeometrySearchPayloadAPI, GeometrySearchRequestAPI, GeometrySearchResponse, GeometrySearchResponseAPI, GeometrySearchResultAPI, GuidanceParams, InputSectionType, InputSectionTypes, LegCostModel, MaxNumberOfAlternatives, NearAPI, NearbyIntent, NearbyIntentAPI, NearbyIntentDetails, NearbyIntentDetailsAPI, POICategoriesParams, POICategoriesResponse, POICategoryResult, Phonetics, PlaceByIdMandatoryParams, PlaceByIdOptionalParams, PlaceByIdParams, PlaceByIdResponse, PlaceByIdResponseAPI, PlaceByIdResultAPI, PoiCategoriesResponseAPI, PoiCategoryAPI, PolygonAPI, PopulatedAreaTag, QueryIntent, QueryIntentAPI, ReverseGeocodingMandatoryParams, ReverseGeocodingOptionalParams, ReverseGeocodingParams, RoutePointAPI, RouteStopOptions, SearchGeometryInput, TrafficAreaAnalyticsDateRange, TrafficAreaAnalyticsDays, TrafficAreaAnalyticsParams, TrafficIncidentDetailsByBBoxParams, TrafficIncidentDetailsByIdsParams, TrafficIncidentDetailsParams, W3WIntent, W3WIntentDetails, arrivalSides, chargingStopsStrategies, functionalRoadClasses, metricKeyToApiDataType };
+export type { AdditionalDataAPI, AlongRouteSearchParams, AlongRouteSearchPayloadAPI, AlongRouteSearchRequestAPI, AlongRouteSearchResponse, AlongRouteSearchResponseAPI, AlongRouteSearchResultAPI, AlongRouteSortBy, AreaAnalyticsDateInput, ArrivalSide, AutocompleteGenericSearchSegment, AutocompleteSearchBrandSegment, AutocompleteSearchCategorySegment, AutocompleteSearchCategorySegmentAPI, AutocompleteSearchContext, AutocompleteSearchContextAPI, AutocompleteSearchMatch, AutocompleteSearchMatches, AutocompleteSearchParams, AutocompleteSearchPlaintextSegment, AutocompleteSearchResponse, AutocompleteSearchResponseAPI, AutocompleteSearchResult, AutocompleteSearchResultAPI, AutocompleteSearchResultGeoBias, AutocompleteSearchResultGeoBiasAPI, AutocompleteSearchSegment, AutocompleteSearchSegmentAPI, AutocompleteSearchSegmentType, BookmarkIntent, BookmarkIntentDetails, CalculateRouteParams, ChargingStationsAvailabilityParams, ChargingStopsStrategy, Circle, CircleAPI, CommonServiceParamsWithZoom, ComputeTravelTimeFor, CoordinateIntent, CoordinateIntentAPI, CoordinateIntentDetails, CoordinateIntentDetailsAPI, ExtendedRouteRepresentation, FunctionalRoadClass, FuzzySearchParams, FuzzySearchResponse, FuzzySearchResponseAPI, FuzzySearchResultAPI, GeocodingParams, GeocodingProps, GeocodingResponse, GeometriesInput, GeometryAPI, GeometryDataParams, GeometryDataResponseAPI, GeometryParams, GeometryPlaceParams, GeometrySearchFeatureCollectionProps, GeometrySearchParams, GeometrySearchPayloadAPI, GeometrySearchRequestAPI, GeometrySearchResponse, GeometrySearchResponseAPI, GeometrySearchResultAPI, GuidanceParams, InputSectionType, InputSectionTypes, LegCostModel, MaxNumberOfAlternatives, NearbyIntent, NearbyIntentAPI, NearbyIntentDetails, NearbyIntentDetailsAPI, POICategoriesParams, POICategoriesResponse, POICategoryResult, Phonetics, PlaceByIdMandatoryParams, PlaceByIdOptionalParams, PlaceByIdParams, PlaceByIdResponse, PlaceByIdResponseAPI, PlaceByIdResultAPI, PoiCategoriesResponseAPI, PoiCategoryAPI, PolygonAPI, QueryIntent, QueryIntentAPI, ReverseGeocodingMandatoryParams, ReverseGeocodingOptionalParams, ReverseGeocodingParams, RoutePointAPI, RouteStopOptions, SearchGeometryInput, TrafficAreaAnalyticsDateRange, TrafficAreaAnalyticsDays, TrafficAreaAnalyticsParams, TrafficIncidentDetailsByBBoxParams, TrafficIncidentDetailsByIdsParams, TrafficIncidentDetailsParams, W3WIntent, W3WIntentDetails, arrivalSides, chargingStopsStrategies, functionalRoadClasses, metricKeyToApiDataType };