@tomtom-org/maps-sdk 0.58.0 → 0.59.0

package/services/dist/index.d.ts

@@ -1,4 +1,4 @@
-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";
+import { AddressProperties, AreaAnalyticsMetricKey, Avoidable, ChargingPark, ChargingParkWithAvailability, ChargingPoint, 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, StaticChargingPoint, TimeZone, TomTomAPIHeaders, TomTomHeaders, TrafficAreaAnalytics, TrafficIncidentDetails, TrafficIncidentRequestCategory, TrafficIncidentTEC, TrafficIncidentTimeValidity, TravelMode, View, inputSectionTypes } from "@tomtom-org/maps-sdk/core";
 import { ZodError, ZodIssue, ZodObject } from "zod";
 //#region ../node_modules/.pnpm/@types+geojson@7946.0.16/node_modules/@types/geojson/index.d.ts
 /**
@@ -285,7 +285,7 @@ type RequestValidationConfig<Params = any> = {
  *
  * @remarks
  * This type extends the global configuration and provides additional service-specific options
- * such as custom base URLs, request validation, and lifecycle event listeners.
+ * such as request validation, cancellation, and lifecycle event listeners.
  *
  * @typeParam ApiRequest - The type of the API request object
  * @typeParam ApiResponse - The type of the API response object
@@ -293,20 +293,6 @@ type RequestValidationConfig<Params = any> = {
  * @group Shared
  */
 export type CommonServiceParams<ApiRequest = any, ApiResponse = any> = Partial<GlobalConfig> & {
-  /**
-   * Custom base URL for the service endpoint.
-   *
-   * @remarks
-   * Should contain the URL up to the part that changes per service call.
-   *
-   * @example
-   * ```ts
-   * customServiceBaseURL: 'https://api.tomtom.com/search/10/reverseGeocode/'
-   * ```
-   *
-   * @defaultValue `undefined` (uses default service URL)
-   */
-  customServiceBaseURL?: string;
   /**
    * Controls whether input request schema validation is performed.
    *
@@ -349,20 +335,11 @@ export type CommonServiceParams<ApiRequest = any, ApiResponse = any> = Partial<G
    * Compose signals to add a deadline: `AbortSignal.any([mine, AbortSignal.timeout(5000)])`.
    *
    * @example
-   * Cancel the previous search whenever a new one starts:
+   * Keep only the latest search with {@link createLatestRequest}:
    * ```ts
-   * let controller: AbortController | undefined;
-   *
-   * const searchForQuery = async (query: string) => {
-   *     controller?.abort();
-   *     controller = new AbortController();
-   *     try {
-   *         return await discoverPlaces({ query, signal: controller.signal });
-   *     } catch (error) {
-   *         if (error instanceof SDKAbortError) return;
-   *         throw error;
-   *     }
-   * };
+   * const latestSearch = createLatestRequest();
+   * const search = await latestSearch.run((signal) => discoverPlaces({ query, signal }));
+   * if (search.current) showResults(search.value);
    * ```
    *
    * @defaultValue `undefined` (the request cannot be cancelled)
@@ -412,16 +389,11 @@ export type ServiceTemplate<Params extends CommonServiceParams<ApiRequest, ApiRe
    */
   buildRequest: (params: Params) => ApiRequest;
   /**
-   * Determines the API version to use for the service call.
-   *
-   * @remarks
-   * Useful for services that require a specific API version different from the global configuration.
-   * If not provided, the API version from the global or provided configuration will be used.
+   * The API version the service calls. Callers cannot override it.
    *
-   * @param params - Input parameters that may influence the API version selection
-   * @returns The API version number
+   * @defaultValue 1
    */
-  getAPIVersion?: (params?: Params) => number;
+  apiVersion?: number;
   /**
    * Sends the constructed request to the API server.
    *
@@ -558,12 +530,15 @@ export declare class SDKServiceError extends SDKError {
  * the convention used by `fetch`, and the original abort reason — including a custom
  * value passed to `AbortController.abort(reason)` — is available on `cause`.
  *
+ * To drop a call a newer one supersedes without catching this error, run it through
+ * {@link createLatestRequest}.
+ *
  * @example
  * ```typescript
  * try {
- *   await discoverPlaces({ query: 'cafe', signal: controller.signal });
+ *   await discoverPlaces({ query: 'cafe', signal: AbortSignal.timeout(5000) });
  * } catch (error) {
- *   if (error instanceof SDKAbortError) return; // superseded by a newer search
+ *   if (error instanceof SDKAbortError) return showMessage('Search timed out');
  *   throw error;
  * }
  * ```
@@ -601,6 +576,78 @@ export declare const buildResponseError: (error: unknown, serviceName: ServiceNa
  */
 export declare const buildValidationError: (error: ValidationError, serviceName: ServiceName) => SDKError;
 //#endregion
+//#region src/shared/types/latestRequest.d.ts
+/**
+ * What {@link LatestRequest.run} resolves to.
+ *
+ * `current: false` means a newer `run` or a `cancel` retired the request, so its value — or its
+ * error — is stale and must not be shown.
+ *
+ * @group Shared
+ */
+export type LatestRequestResult<T> = {
+  current: true;
+  value: T;
+} | {
+  current: false;
+};
+/**
+ * One in-flight request slot, where each new request retires the one before it.
+ *
+ * @see {@link createLatestRequest}
+ *
+ * @group Shared
+ */
+export type LatestRequest = {
+  /**
+   * Aborts the request in flight, if any, then starts this one.
+   *
+   * @remarks
+   * `request` is called synchronously with a fresh signal, which it passes to every service
+   * call it makes. A rejection is rethrown only while the request is still current, so a
+   * deadline of your own composed onto the signal still surfaces as an {@link SDKAbortError}.
+   *
+   * @param request - The work to run, typically one or more service calls sharing the signal
+   */
+  run: <T>(request: (signal: AbortSignal) => Promise<T>) => Promise<LatestRequestResult<T>>;
+  /**
+   * Aborts the request in flight without starting another, so it resolves `{ current: false }`.
+   */
+  cancel: () => void;
+  /**
+   * Whether a request is in flight and not yet retired.
+   */
+  isRunning: () => boolean;
+};
+//#endregion
+//#region src/shared/latestRequest.d.ts
+/**
+ * Creates a slot that keeps only the latest request: starting one aborts its predecessor, and an
+ * answer that arrives after a newer request or a `cancel` is dropped rather than returned.
+ *
+ * @remarks
+ * Use one per thing that can be superseded — a click lookup, a search box, a refetch on map move.
+ * Aborting stops the network work; checking again once the answer is in also catches a `cancel`
+ * that arrives after the response but before the caller paints it.
+ *
+ * @example
+ * ```ts
+ * const lookup = createLatestRequest();
+ *
+ * map.mapLibreMap.on('click', async (event) => {
+ *     const result = await lookup.run((signal) => reverseGeocode({ position: event.lngLat.toArray(), signal }));
+ *     if (!result.current) return;
+ *     showAddress(result.value);
+ * });
+ * clearButton.addEventListener('click', lookup.cancel);
+ * ```
+ *
+ * @see [Keeping only the latest request](https://docs.tomtom.com/maps-sdk-js/guides/services/request-options-and-errors#keeping-only-the-latest-request)
+ *
+ * @group Shared
+ */
+export declare const createLatestRequest: () => LatestRequest;
+//#endregion
 //#region src/shared/types/geoBias.d.ts
 /**
  * A point to search around, optionally bounded by a radius.
@@ -661,135 +708,6 @@ export type GeoBias = (PointGeoBias & {
   radiusMeters?: never;
 });
 //#endregion
-//#region src/shared/types/commonGeocodeAndFuzzySearchParams.d.ts
-/**
- * Common parameters shared between fuzzy search and geocoding services.
- *
- * These parameters control search behavior that applies to both fuzzy search
- * and geocoding operations, including autocomplete mode, pagination, and geographic filtering.
- *
- * @remarks
- * Used by:
- * - {@link fuzzySearch}
- * - {@link geocode}
- *
- * @group Places Search
- */
-export type CommonGeocodeAndFuzzySearchParams = {
-  /**
-   * Enable predictive/autocomplete mode for partial input queries.
-   *
-   * When true, the query is treated as incomplete text being typed by a user,
-   * and the search returns suggestions that match the partial input.
-   *
-   * @remarks
-   * **Autocomplete Behavior:**
-   * - Optimized for real-time search-as-you-type
-   * - Returns results that start with or contain the query
-   * - Better for interactive search boxes
-   * - Lower result quality thresholds to show more options
-   *
-   * **Regular Search (false):**
-   * - Treats query as complete input
-   * - Higher quality thresholds
-   * - Better for final search submission
-   *
-   * @default false
-   *
-   * @example
-   * ```typescript
-   * // Autocomplete mode for "Amst" input
-   * typeahead: true   // Returns: Amsterdam, Amstelveen, etc.
-   *
-   * // Regular search mode
-   * typeahead: false  // Expects complete query
-   * ```
-   */
-  typeahead?: boolean;
-  /**
-   * Starting position within the complete result set for pagination.
-   *
-   * Use with `limit` to implement pagination through large result sets.
-   * Zero-based index indicating which result to start from.
-   *
-   * @remarks
-   * **Pagination Pattern:**
-   * - Page 1: `offset: 0, limit: 10` (results 0-9)
-   * - Page 2: `offset: 10, limit: 10` (results 10-19)
-   * - Page 3: `offset: 20, limit: 10` (results 20-29)
-   *
-   * **Performance Note:**
-   * Very high offset values may have slower performance.
-   *
-   * @default 0
-   *
-   * @example
-   * ```typescript
-   * // First page
-   * offset: 0
-   *
-   * // Second page (assuming limit: 10)
-   * offset: 10
-   *
-   * // Third page
-   * offset: 20
-   * ```
-   */
-  offset?: number;
-  /**
-   * Where to look: a point with an optional radius, or a bounding box.
-   *
-   * @remarks
-   * 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
-   * geoBias: { position: [4.9, 52.3], radiusMeters: 2000 }
-   * geoBias: { boundingBox: [4.8, 52.3, 5.0, 52.4] }
-   * ```
-   */
-  geoBias?: GeoBias;
-  /**
-   * Restrict search to specific countries.
-   *
-   * Limits results to locations within the specified countries only.
-   * Useful for country-specific searches or compliance requirements.
-   *
-   * @remarks
-   * **Country Code Formats:**
-   * - ISO 3166-1 alpha-2: Two-letter codes (e.g., "US", "FR", "DE")
-   * - ISO 3166-1 alpha-3: Three-letter codes (e.g., "USA", "FRA", "DEU")
-   * - Can mix formats: `["US", "FRA", "DE"]`
-   *
-   * **Behavior:**
-   * - Multiple countries create OR condition (results from any listed country)
-   * - Case-insensitive
-   * - The `view` parameter may affect available countries
-   *
-   * **Use Cases:**
-   * - Regional applications (EU-only, North America-only)
-   * - Compliance with data sovereignty rules
-   * - Simplifying results for specific markets
-   *
-   * @example
-   * ```typescript
-   * // Single country (United States)
-   * countries: ['US']
-   *
-   * // Multiple countries (Europe)
-   * countries: ['FR', 'DE', 'NL', 'BE']
-   *
-   * // Mixed formats
-   * countries: ['US', 'GBR', 'CA']
-   *
-   * // North America
-   * countries: ['USA', 'CAN', 'MEX']
-   * ```
-   */
-  countries?: string[];
-};
-//#endregion
 //#region src/shared/types/commonPlacesParams.d.ts
 /**
  * Index representing the type of place data to search.
@@ -838,18 +756,11 @@ export type SearchIndexType = 'Geo' | 'PAD' | 'Addr' | 'Str' | 'XStr' | 'POI';
  * **Key Features:**
  * - Result limits and pagination
  * - Geographic biasing for location-aware results
- * - Result type filtering (addresses, POIs, geographies)
  * - Additional data inclusion (mapcodes, extended postal codes)
  * - Geopolitical view context for disputed territories
  *
  * @example
  * ```typescript
- * // Search with geography type filter
- * const citySearch: CommonPlacesParams<URL, Response> = {
- *   geographyTypes: ['Municipality'],  // Only cities
- *   limit: 10
- * };
- *
  * // Search with mapcodes and specific geopolitical view
  * const detailedSearch: CommonPlacesParams<URL, Response> = {
  *   view: 'IN',  // India's perspective
@@ -860,7 +771,6 @@ export type SearchIndexType = 'Geo' | 'PAD' | 'Addr' | 'Str' | 'XStr' | 'POI';
  *
  * // Address search with extended postal codes
  * const addressSearch: CommonPlacesParams<URL, Response> = {
- *   geographyTypes: ['Country', 'Municipality'],
  *   extendedPostalCodesFor: ['Geo', 'PAD', 'Addr'],
  *   limit: 15
  * };
@@ -873,7 +783,7 @@ export type CommonPlacesParams<ApiRequest, ApiResponse> = CommonServiceParams<Ap
    * Maximum number of results to return.
    *
    * Controls pagination by limiting the number of results in a single response.
-   * Use with `offset` (in specific service params) for pagination.
+   * Fuzzy search and geocoding page with `cursor`; see {@link CommonGeocodeAndFuzzySearchParams.cursor}.
    *
    * @remarks
    * **Range:** 1 to 100
@@ -996,54 +906,154 @@ export type CommonPlacesParams<ApiRequest, ApiResponse> = CommonServiceParams<Ap
    * ```
    */
   view?: View;
+};
+//#endregion
+//#region src/shared/types/searchFilters.d.ts
+/**
+ * Which countries results may come from. Everything here **excludes** results.
+ *
+ * @remarks
+ * Separate from {@link PlaceFilters} because geometry and along-route search take no country
+ * restriction. Where to look is {@link GeoBias}, not a filter.
+ *
+ * @group Places Search
+ */
+export type GeographicFilters = {
+  /** Countries to restrict to, as ISO 3166-1 alpha-2 or alpha-3 codes. */
+  countries?: string[];
+};
+/**
+ * What kind of places may come back. Everything here **excludes** results: a place that does not
+ * match is dropped, not ranked lower.
+ *
+ * @remarks
+ * Values within one member are OR'd: `poiBrands: ['Shell', 'BP']` keeps a place of either brand.
+ * Members are AND'd with each other.
+ *
+ * Fuzzy search intersects it with {@link GeographicFilters} as {@link SearchFilters}, so one
+ * `filters` object carries the country and the attribute restrictions together.
+ *
+ * @example
+ * ```typescript
+ * filters: { poiCategories: ['RESTAURANT', 'CAFE'] }
+ * filters: { poiBrands: ['Shell', 'BP'], fuelTypes: ['Diesel'] }
+ * filters: { connectors: ['IEC62196Type2CCS'], minPowerKW: 50, maxPowerKW: 150 }
+ * ```
+ *
+ * @group Places Search
+ */
+export type PlaceFilters = {
+  /** POI categories to restrict to. */
+  poiCategories?: POICategory[];
+  /** POI brands to restrict to, by name. Case-sensitive; quote a name containing a comma: `'"A,B"'`. */
+  poiBrands?: string[];
+  /** Which kinds of place data to search. Defaults to all. */
+  indexes?: SearchIndexType[];
+  /** Geography types to restrict `Geography` results to. */
+  geographyTypes?: GeographyType[];
+  /** EV connector types to restrict charging results to. */
+  connectors?: ConnectorType[];
+  /** Fuel types to restrict fuel station results to. */
+  fuelTypes?: Fuel[];
+  /** Minimum EV charging power, in kilowatts. */
+  minPowerKW?: number;
+  /** Maximum EV charging power, in kilowatts. */
+  maxPowerKW?: number;
+};
+/**
+ * Both halves of `filters` in one object: what fuzzy search takes.
+ *
+ * @group Places Search
+ */
+export type SearchFilters = PlaceFilters & GeographicFilters;
+//#endregion
+//#region src/shared/types/commonGeocodeAndFuzzySearchParams.d.ts
+/**
+ * Common parameters shared between fuzzy search and geocoding services.
+ *
+ * These parameters control search behavior that applies to both fuzzy search
+ * and geocoding operations, including autocomplete mode, pagination, and geographic filtering.
+ *
+ * @remarks
+ * Used by:
+ * - {@link fuzzySearch}
+ * - {@link geocode}
+ *
+ * @group Places Search
+ */
+export type CommonGeocodeAndFuzzySearchParams = {
   /**
-   * Filter results to specific geography types.
+   * Enable predictive/autocomplete mode for partial input queries.
    *
-   * Restricts results to only geographic entities of the specified types,
-   * filtering out other result types like POIs or addresses.
+   * When true, the query is treated as incomplete text being typed by a user,
+   * and the search returns suggestions that match the partial input.
    *
    * @remarks
-   * **Geography Hierarchy (largest to smallest):**
-   * - `Country`: Sovereign nations
-   * - `CountrySubdivision`: States, provinces, regions
-   * - `CountrySecondarySubdivision`: Counties, districts
-   * - `CountryTertiarySubdivision`: Sub-districts
-   * - `Municipality`: Cities, towns
-   * - `MunicipalitySubdivision`: City districts
-   * - `Neighbourhood`: Neighborhoods, quarters
-   * - `PostalCodeArea`: Areas defined by postal codes
-   *
-   * **Filtering Behavior:**
-   * When specified, only Geography results with matching entity types
-   * are returned. POIs, addresses, and other result types are excluded.
+   * **Autocomplete Behavior:**
+   * - Optimized for real-time search-as-you-type
+   * - Returns results that start with or contain the query
+   * - Better for interactive search boxes
+   * - Lower result quality thresholds to show more options
    *
-   * **Use Cases:**
-   * - City/country search for travel apps
-   * - Administrative boundary lookups
-   * - Filtering out POI noise in geographic searches
-   * - Hierarchical location pickers
+   * **Regular Search (false):**
+   * - Treats query as complete input
+   * - Higher quality thresholds
+   * - Better for final search submission
+   *
+   * @default false
    *
    * @example
    * ```typescript
-   * // Search only for cities
-   * geographyTypes: ['Municipality']
-   *
-   * // Search for countries and cities
-   * geographyTypes: ['Country', 'Municipality']
-   *
-   * // Search for all administrative levels
-   * geographyTypes: [
-   *   'Country',
-   *   'CountrySubdivision',
-   *   'CountrySecondarySubdivision',
-   *   'Municipality'
-   * ]
+   * // Autocomplete mode for "Amst" input
+   * typeahead: true   // Returns: Amsterdam, Amstelveen, etc.
    *
-   * // Search for postal code areas only
-   * geographyTypes: ['PostalCodeArea']
+   * // Regular search mode
+   * typeahead: false  // Expects complete query
    * ```
    */
-  geographyTypes?: GeographyType[];
+  typeahead?: boolean;
+  /**
+   * Continues a previous search: its response's `nextCursor`, passed back unchanged alongside the
+   * same parameters. Leave it out for the first page.
+   *
+   * @remarks
+   * The value is **opaque**: the SDK mints it and only the SDK reads it, which lets the pagination
+   * mechanism change without breaking callers. Passing a value this SDK did not produce throws.
+   *
+   * @example
+   * ```typescript
+   * let response = await discoverPlaces({ query: 'cafe', limit: 20 });
+   *
+   * while (response.properties?.nextCursor) {
+   *   response = await discoverPlaces({ query: 'cafe', limit: 20, cursor: response.properties?.nextCursor });
+   * }
+   * ```
+   */
+  cursor?: string;
+  /**
+   * Where to look: a point with an optional radius, or a bounding box.
+   *
+   * @remarks
+   * 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
+   * geoBias: { position: [4.9, 52.3], radiusMeters: 2000 }
+   * geoBias: { boundingBox: [4.8, 52.3, 5.0, 52.4] }
+   * ```
+   */
+  geoBias?: GeoBias;
+  /**
+   * Which countries results may come from: see {@link GeographicFilters}. Fuzzy search's `filters`
+   * also carries {@link PlaceFilters}; geocoding's also carries `geographyTypes`.
+   *
+   * @example
+   * ```typescript
+   * filters: { countries: ['NL', 'BE'] }
+   * ```
+   */
+  filters?: GeographicFilters;
 };
 //#endregion
 //#region src/shared/types/vehicleEngineParams.d.ts
@@ -1374,6 +1384,9 @@ type PredefinedVehicleModel = {
  * Physical properties of the vehicle.
  *
  * @remarks
+ * Weight is the only dimension routing takes: there are no height, width, length or axle-weight
+ * restrictions. `TravelMode` lists the modes routing offers.
+ *
  * The vehicle weight is used to:
  * - Check road weight restrictions
  * - Calculate toll costs (weight-based pricing)
@@ -2628,7 +2641,7 @@ export type DepartArriveParams<Option extends DepartArriveOption = DepartArriveO
  *       },
  *       engine: {
  *         consumption: {
- *           speedToConsumption: [
+ *           speedsToConsumptionsKWH: [
  *             { speedKMH: 50, consumptionUnitsPer100KM: 15 },
  *             { speedKMH: 90, consumptionUnitsPer100KM: 18 },
  *             { speedKMH: 120, consumptionUnitsPer100KM: 22 }
@@ -2642,13 +2655,12 @@ export type DepartArriveParams<Option extends DepartArriveOption = DepartArriveO
  *   }
  * };
  *
- * // Truck route with restrictions
- * const truckParams: CommonRoutingParams = {
+ * // Heavy, speed-limited vehicle, described by weight alone (see `VehicleDimensions`)
+ * const heavyVehicleParams: CommonRoutingParams = {
  *   costModel: {
  *     routeType: 'short',
  *     avoid: ['tollRoads', 'ferries']
  *   },
- *   travelMode: 'truck',
  *   vehicle: {
  *     model: {
  *       dimensions: {
@@ -2751,8 +2763,8 @@ export type TimeZoneRequest = 'iana';
 /**
  * Common parameters for search services with POI filtering capabilities.
  *
- * Extends basic places parameters with advanced search features including
- * category filtering, brand filtering, and EV charging station specifics.
+ * Extends basic places parameters with the POI attribute filters — categories, brands, EV
+ * charging specifics — grouped under `filters`.
  *
  * @typeParam ApiRequest - The API request type
  * @typeParam ApiResponse - The API response type
@@ -2763,10 +2775,8 @@ export type TimeZoneRequest = 'iana';
  * - {@link fuzzySearch}
  * - {@link geometrySearch}
  *
- * Provides extensive filtering options for:
- * - POI categories and brands
- * - EV charging station specifications
- * - Fuel type availability
+ * Provides:
+ * - POI category, brand, EV charging and fuel type filters (`filters`)
  * - Opening hours and timezone data
  * - Related POI relationships
  *
@@ -2779,8 +2789,8 @@ export type CommonSearchParams<ApiRequest, ApiResponse> = CommonPlacesParams<Api
    * Search query string.
    *
    * The text to search for — can be a place name, POI, address, or any free-form location query.
-   * When omitted, results are driven entirely by other filters such as {@link poiCategories},
-   * {@link poiBrands}, {@link fuelTypes}, or {@link geometries}.
+   * When omitted, results are driven entirely by `filters` — a category, a brand, a fuel type —
+   * or by `geometries` on geometry search.
    *
    * @remarks
    * **Query Examples:**
@@ -2796,173 +2806,12 @@ export type CommonSearchParams<ApiRequest, ApiResponse> = CommonPlacesParams<Api
    * query: 'coffee shop'
    *
    * // Omit query to search purely by category
-   * poiCategories: ['CHARGING_LOCATION']
+   * filters: { poiCategories: ['CHARGING_LOCATION'] }
    * ```
    */
   query?: string;
-  /**
-   * Specify which search indexes to query.
-   *
-   * Fine-tunes search by selecting specific data categories to include.
-   * By default, all indexes are searched.
-   *
-   * @remarks
-   * **Available Indexes:**
-   * - `Geo`: Geographic entities (countries, cities, etc.)
-   * - `PAD`: Point addresses with building numbers
-   * - `Addr`: Address ranges on streets
-   * - `Str`: Street names
-   * - `XStr`: Cross streets (intersections)
-   * - `POI`: Points of interest
-   *
-   * **Use Cases:**
-   * - POI-only search: `['POI']`
-   * - Address-only search: `['PAD', 'Addr']`
-   * - Exclude geographies: `['PAD', 'Addr', 'Str', 'POI']`
-   *
-   * @example
-   * ```typescript
-   * // Search only POIs
-   * indexes: ['POI']
-   *
-   * // Search addresses and streets only
-   * indexes: ['PAD', 'Addr', 'Str']
-   * ```
-   */
-  indexes?: SearchIndexType[];
-  /**
-   * Filter results to specific POI categories.
-   *
-   * Restricts results to Points of Interest belonging to the specified
-   * categories. Use values from the {@link POICategory} type.
-   *
-   * @remarks
-   * **Multiple Categories:**
-   * Results include POIs matching ANY of the specified categories (OR logic).
-   *
-   * **Discovering Categories:**
-   * Use the {@link getPOICategories} service to search and browse available
-   * categories by name or synonym, then pass the resulting `code` values here.
-   *
-   * @example
-   * ```typescript
-   * // Filter to specific categories
-   * poiCategories: ['RESTAURANT', 'CAFE']
-   *
-   * // Category-only search (no query)
-   * poiCategories: ['CHARGING_LOCATION']
-   *
-   * // Discovered via getPOICategories() service
-   * import { getPOICategoryCodes } from '@tomtom-org/maps-sdk/services';
-   * const codes = await getPOICategoryCodes({ filters: ['italian'] });
-   * const results = await discoverPlaces({ poiCategories: codes, position });
-   * ```
-   */
-  poiCategories?: POICategory[];
-  /**
-   * Filter results to specific POI brands.
-   *
-   * Restricts results to Points of Interest belonging to the specified
-   * brand names. Useful for finding specific chain locations.
-   *
-   * @remarks
-   * **Brand Names:**
-   * - Case-sensitive
-   * - Exact match required
-   * - Brands with commas must be quoted: `"A,B,C"`
-   *
-   * **Multiple Brands:**
-   * Results include POIs matching ANY of the specified brands (OR logic).
-   *
-   * **Use Cases:**
-   * - Find specific chain stores: "Starbucks", "McDonald's"
-   * - Compare competing brands
-   * - Brand-specific navigation
-   *
-   * @example
-   * ```typescript
-   * // Single brand
-   * poiBrands: ['Starbucks']
-   *
-   * // Multiple brands
-   * poiBrands: ['Shell', 'BP', 'Chevron']
-   *
-   * // Brand with comma in name
-   * poiBrands: ['"A,B,C"']
-   * ```
-   */
-  poiBrands?: string[];
-  /**
-   * Filter EV charging stations by connector types.
-   *
-   * Restricts results to EV charging stations that support at least one
-   * of the specified connector types. Essential for EV drivers to find
-   * compatible charging infrastructure.
-   *
-   * @remarks
-   * **Common Connector Types:**
-   * - `IEC62196Type2CableAttached`: Type 2 / Mennekes (Europe)
-   * - `IEC62196Type2CCS`: CCS Combo 2 (Europe)
-   * - `IEC62196Type1CCS`: CCS Combo 1 (North America)
-   * - `Chademo`: CHAdeMO (Japan)
-   * - `Tesla`: Tesla proprietary
-   *
-   * **Multiple Connectors:**
-   * Results include stations with ANY of the specified connectors (OR logic).
-   *
-   * **Use Cases:**
-   * - Find compatible chargers for specific EV model
-   * - Route planning for long-distance EV travel
-   * - Filter by fast charging capability
-   *
-   * @example
-   * ```typescript
-   * // CCS Combo 2 (common in Europe)
-   * connectors: ['IEC62196Type2CCS']
-   *
-   * // Multiple connector types
-   * connectors: ['IEC62196Type2CCS', 'Chademo']
-   *
-   * // Tesla or CCS
-   * connectors: ['Tesla', 'IEC62196Type2CCS']
-   * ```
-   */
-  connectors?: ConnectorType[];
-  /**
-   * Filter fuel stations by available fuel types.
-   *
-   * Restricts results to fuel stations that offer the specified fuel types.
-   * Can be used with empty query to find any station with specific fuel.
-   *
-   * @remarks
-   * **Common Fuel Types:**
-   * - Petrol/Gasoline
-   * - Diesel
-   * - LPG (Liquefied Petroleum Gas)
-   * - CNG (Compressed Natural Gas)
-   * - E85 (Ethanol blend)
-   * - AdBlue (Diesel exhaust fluid)
-   *
-   * **Multiple Fuel Types:**
-   * Results include stations offering ANY of the specified fuels (OR logic).
-   *
-   * **Empty Query:**
-   * When `fuelTypes` is specified, the query parameter can be empty,
-   * and all POIs with matching fuel types will be returned.
-   *
-   * @example
-   * ```typescript
-   * // Diesel stations only
-   * fuelTypes: ['Diesel']
-   *
-   * // Alternative fuels
-   * fuelTypes: ['CNG', 'LPG', 'E85']
-   *
-   * // Standard fuels
-   * fuelTypes: ['Petrol', 'Diesel']
-   * ```
-   */
-  fuelTypes?: Fuel[];
+  /** What kind of places may come back: see {@link PlaceFilters}. */
+  filters?: PlaceFilters;
   /**
    * Request opening hours information for POIs.
    *
@@ -3044,67 +2893,6 @@ export type CommonSearchParams<ApiRequest, ApiResponse> = CommonPlacesParams<Api
    * ```
    */
   relatedPois?: RelatedPoisRequest;
-  /**
-   * Minimum charging power for EV stations (in kilowatts).
-   *
-   * Filters EV charging stations to those supporting at least one
-   * connector with the specified minimum power output. Useful for
-   * finding fast charging capabilities.
-   *
-   * @remarks
-   * **Power Levels:**
-   * - 3-7 kW: Level 2 AC (slow charging)
-   * - 7-22 kW: Level 2 AC (moderate charging)
-   * - 50+ kW: DC fast charging
-   * - 150+ kW: Ultra-fast charging
-   * - 350 kW: Maximum current technology
-   *
-   * **Closed Interval:**
-   * Includes stations with exactly this power value.
-   *
-   * @example
-   * ```typescript
-   * // Fast charging (50kW+)
-   * minPowerKW: 50
-   *
-   * // Ultra-fast charging (150kW+)
-   * minPowerKW: 150
-   *
-   * // Combined with max power
-   * minPowerKW: 50,
-   * maxPowerKW: 150  // 50-150 kW range
-   * ```
-   */
-  minPowerKW?: number;
-  /**
-   * Maximum charging power for EV stations (in kilowatts).
-   *
-   * Filters EV charging stations to those with at least one connector
-   * not exceeding the specified maximum power output.
-   *
-   * @remarks
-   * **Use Cases:**
-   * - Find charging compatible with vehicle's maximum charge rate
-   * - Exclude ultra-fast chargers when not needed
-   * - Filter by infrastructure capability
-   *
-   * **Closed Interval:**
-   * Includes stations with exactly this power value.
-   *
-   * @example
-   * ```typescript
-   * // Level 2 charging only (up to 22kW)
-   * maxPowerKW: 22
-   *
-   * // Moderate fast charging (up to 50kW)
-   * maxPowerKW: 50
-   *
-   * // Power range 50-150 kW
-   * minPowerKW: 50,
-   * maxPowerKW: 150
-   * ```
-   */
-  maxPowerKW?: number;
 };
 //#endregion
 //#region src/shared/types/searchSummary.d.ts
@@ -3123,29 +2911,29 @@ type SummaryQueryType = 'NEARBY' | 'NON_NEAR';
 /**
  * Metadata summary for search API responses.
  *
- * Provides information about the search query execution, result counts,
- * and pagination details. This metadata helps understand how the search
- * was processed and manage result navigation.
+ * Provides information about the search query execution, result counts, and the cursor that
+ * continues the search. This metadata helps understand how the search was processed and page
+ * through results.
  *
  * @remarks
  * This summary is included in responses from:
  * - {@link discoverPlaces}
  * - {@link fuzzySearch}
  * - {@link geometrySearch}
+ * - {@link geocode}
  *
  * @example
  * ```typescript
  * const results = await discoverPlaces({
- *   key: 'your-api-key',
  *   query: 'pizza',
- *   at: [4.9, 52.3]
+ *   geoBias: { position: [4.9, 52.3] }
  * });
  *
- * const summary = results.summary;
- * console.log(`Found ${summary.totalResults ?? 'an unknown number of'} total results`);
- * console.log(`Showing ${summary.numResults} results`);
- * console.log(`Query type: ${summary.queryType}`); // 'NEARBY'
- * console.log(`Search took ${summary.queryTime}ms`);
+ * const summary = results.properties;
+ * console.log(`Found ${summary?.totalResults ?? 'an unknown number of'} total results`);
+ * console.log(`Showing ${summary?.numResults} results`);
+ * console.log(`Query type: ${summary?.queryType}`); // 'NEARBY'
+ * console.log(`Search took ${summary?.queryTime}ms`);
  * ```
  *
  * @group Places Search
@@ -3204,27 +2992,14 @@ export type SearchSummary = {
    */
   numResults: number;
   /**
-   * Starting position of these results within the complete result set.
-   *
-   * Zero-based index indicating where this page of results begins.
-   * Used for pagination to retrieve subsequent pages.
+   * The opaque cursor that continues this search: pass it back as the request's `cursor`, see
+   * {@link CommonGeocodeAndFuzzySearchParams.cursor}. Only fuzzy search and geocoding page this way.
    *
    * @remarks
-   * Set using the `offset` parameter in the search request.
-   *
-   * @example
-   * ```typescript
-   * // First page (results 0-9)
-   * offset: 0, numResults: 10
-   *
-   * // Second page (results 10-19)
-   * offset: 10, numResults: 10
-   *
-   * // Third page (results 20-29)
-   * offset: 20, numResults: 10
-   * ```
+   * Absent means pagination has ended: the result set is exhausted, this page came back empty, or
+   * the next page would start past result 1900, the furthest the backend serves.
    */
-  offset: number;
+  nextCursor?: string;
   /**
    * Total number of matching results found by the search.
    *
@@ -3232,19 +3007,16 @@ export type SearchSummary = {
    * regardless of pagination limits.
    *
    * @remarks
-   * Optional — a total is not guaranteed, so guard it rather than assuming a number. Where it
-   * is present, use it with `offset` and `numResults` to paginate:
-   * - Current page: `offset / limit + 1`
-   * - Total pages: `totalResults === undefined ? undefined : Math.ceil(totalResults / limit)`
-   * - Has more results: `totalResults !== undefined && offset + numResults < totalResults`
+   * Optional — a total is not guaranteed, so guard it rather than assuming a number. Use it to
+   * size a progress indicator, such as a page count of `Math.ceil(totalResults / limit)`, not to
+   * drive pagination: `nextCursor` decides whether a further page exists.
    *
    * @example
    * ```typescript
    * totalResults: 50  // 50 total matches found
    * numResults: 10    // Showing first 10
-   * offset: 0         // Starting from beginning
    *
-   * // Can fetch more with offset: 10, 20, 30, 40
+   * // Fetch the rest by passing `nextCursor` back as `cursor`
    * ```
    */
   totalResults?: number;
@@ -3405,10 +3177,14 @@ type AddressRangesAPI = {
  * we call always send them, and this type is what asserts that. Relaxing it would let a parser
  * silently stop populating them.
  *
+ * The wire pages by `offset`; `nextCursor` is the SDK's own, minted from it by the parser.
+ *
  * @ignore
  */
-type SummaryAPI$1 = Omit<SearchSummary, 'geoBias'> & Required<Pick<SearchSummary, 'totalResults' | 'fuzzyLevel'>> & {
+type SummaryAPI$1 = Omit<SearchSummary, 'geoBias' | 'nextCursor'> & Required<Pick<SearchSummary, 'totalResults' | 'fuzzyLevel'>> & {
   geoBias?: LatLonAPI;
+  /** Where this page starts in the full result set, zero-based. */
+  offset: number;
 };
 /**
  * @ignore
@@ -3463,17 +3239,22 @@ type POIAPI = {
   timeZone?: TimeZone;
 };
 /**
+ * A connector as the places APIs return it: `chargingSpeed` is derived by the SDK.
  * @ignore
  */
-type ConnectorAPI = Omit<Connector, 'type' | 'chargingSpeed'> & {
-  connectorType: ConnectorType;
-};
+type ConnectorAPI = Omit<Connector, 'chargingSpeed'>;
 /**
+ * A charging point as the places APIs return it: `ev/id` omits empty `capabilities` and `restrictions`.
  * @ignore
  */
-type ChargingParkAPI = {
-  connectors: ConnectorAPI[];
+type ChargingPointAPI = Omit<StaticChargingPoint, 'capabilities' | 'restrictions' | 'connectors'> & Partial<Pick<StaticChargingPoint, 'capabilities' | 'restrictions'>> & {
+  connectors?: ConnectorAPI[];
 };
+/**
+ * @typeParam Status - `Pick<ChargingPoint, 'status'>` from `ev/id`; nothing from the search services.
+ * @ignore
+ */
+type ChargingStationAPI<Status extends object = object> = ChargingStation<ChargingPointAPI & Status>;
 /**
  * @ignore
  */
@@ -3486,7 +3267,7 @@ type CommonSearchPlaceResultAPI = Omit<SearchPlaceProps, 'distance' | 'position'
   entryPoints?: EntryPointAPI[];
   address?: AddressProperties;
   poi?: POIAPI;
-  chargingPark?: ChargingParkAPI;
+  chargingStations?: ChargingStationAPI[];
 };
 //#endregion
 //#region src/along-route-search/types/alongRouteSearchResponseAPI.d.ts
@@ -3556,7 +3337,7 @@ type AlongRouteSortBy = 'detourTime' | 'detourOffset';
  * const chargers = await discoverPlaces({
  *   route: [[4.9, 52.37], [4.95, 52.28], [5.1, 52.09]],
  *   maxDetourTimeSeconds: 600,
- *   poiCategories: ['CHARGING_LOCATION'],
+ *   filters: { poiCategories: ['CHARGING_LOCATION'] },
  *   sortBy: 'detourOffset',
  * });
  * ```
@@ -3656,7 +3437,7 @@ type AlongRouteSearchResponse = Places<SearchPlaceProps, SearchSummary>;
  * const chargers = await alongRouteSearch({
  *   route: routeResult.features[0].geometry,
  *   maxDetourTimeSeconds: 600,
- *   poiCategories: ['CHARGING_LOCATION'],
+ *   filters: { poiCategories: ['CHARGING_LOCATION'] },
  *   sortBy: 'detourOffset',
  * });
  * ```
@@ -3678,7 +3459,7 @@ type EVChargingStationResultAPI = {
   openingHours: OpeningHoursAPI;
   timeZone: TimeZone;
   accessType: ChargingStationsAccessType;
-  chargingStations: ChargingStation[];
+  chargingStations: ChargingStationAPI<Pick<ChargingPoint, 'status'>>[];
 };
 /**
  * @ignore
@@ -3770,6 +3551,9 @@ type ChargingStationsAvailabilityParams = CommonServiceParams<URL, ChargingStati
  * - **Access information**: Public, private, or restricted access
  * - **Opening hours**: When the charging facility is accessible
  *
+ * Returns availability records, not places. To show stations with their availability, pass the
+ * places to {@link getPlacesWithEVAvailability} instead, and its result to `PlacesModule.show()`.
+ *
  * @param params - Charging availability parameters with station ID
  *
  * @returns Promise resolving to charging station availability information
@@ -3778,17 +3562,17 @@ type ChargingStationsAvailabilityParams = CommonServiceParams<URL, ChargingStati
  * ```typescript
  * // Get availability for a specific charging park
  * const availability = await evChargingStationsAvailability({
- *   key: 'your-api-key',
+ *   apiKey: 'YOUR_API_KEY',
  *   id: 'charging-park-id-123'
  * });
  *
  * // Check how many chargers are available
- * const availableCount = availability.chargingPointAvailability.statusCounts.Available;
+ * const availableCount = availability?.chargingPointAvailability.statusCounts.Available ?? 0;
  * console.log(`${availableCount} chargers available`);
  *
- * // Find available CCS connectors
- * const ccsConnectors = availability.connectorAvailabilities.find(
- *   ca => ca.connector.type === 'IEC62196Type2CCS'
+ * // CCS connectors, one entry per power level
+ * const ccsConnectors = availability?.connectorAvailabilities.filter(
+ *   ({ connector }) => connector.type === 'IEC62196Type2CCS'
  * );
  * ```
  *
@@ -3807,13 +3591,15 @@ export declare const evChargingStationsAvailability: (params: ChargingStationsAv
  *
  * @remarks
  * Needs the same API key access as {@link evChargingStationsAvailability}. A failed request,
- * including one from a key without that access, is logged and resolves to `undefined`.
+ * including one from a key without that access, is logged and resolves to `undefined`. A
+ * cancellation is the caller's own decision rather than a data gap, so it rejects the call instead.
  *
  * @param place - The place to enhance with availability data
- * @param commonParams - Common service parameters (e.g. `key`, `customServiceBaseURL`, `onAPIRequest`) forwarded to the availability request
+ * @param commonParams - Common service parameters (e.g. `apiKey`, `onAPIRequest`, `signal`) forwarded to the availability request
  *
  * @returns Promise resolving to the place with merged availability information
  * @returns undefined if no availability data is present for the `place` input parameter.
+ * @throws {@link SDKAbortError} when `commonParams.signal` is aborted
  *
  * @example
  * ```typescript
@@ -3822,10 +3608,9 @@ export declare const evChargingStationsAvailability: (params: ChargingStationsAv
  * const place = searchResult.features[0];
  *
  * const enhancedPlace = await getPlaceWithEVAvailability(place);
- * const availability = enhancedPlace.properties.chargingPark?.availability;
- *
- * if (availability) {
- *   console.log('Available chargers:', availability.chargingPointAvailability.count);
+ * if (enhancedPlace) {
+ *   const { count, statusCounts } = enhancedPlace.properties.chargingPark.availability.chargingPointAvailability;
+ *   console.log(`${statusCounts.Available ?? 0} of ${count} chargers available`);
  * }
  * ```
  *
@@ -3841,13 +3626,14 @@ export declare const getPlaceWithEVAvailability: <P extends CommonPlaceProps = C
  * @remarks
  * **Important**: Availability requests are made sequentially to avoid exceeding
  * API rate limits (QPS - Queries Per Second). For large result sets, this may
- * take some time.
+ * take some time. Pass a `signal` to stop early: aborting it cancels the in-flight
+ * request, skips the remaining ones and rejects with {@link SDKAbortError}.
  *
  * Needs the same API key access as {@link evChargingStationsAvailability}. A place whose request
  * fails, including for a key without that access, counts as having unknown availability.
  *
  * @param places - Collection of places to enhance
- * @param options - Configuration options, including common service parameters (e.g. `key`, `customServiceBaseURL`, `onAPIRequest`) forwarded to each availability request
+ * @param options - Configuration options, including common service parameters (e.g. `apiKey`, `onAPIRequest`, `signal`) forwarded to each availability request
  *
  * @returns Promise resolving to places collection with merged availability
  *
@@ -3856,8 +3642,7 @@ export declare const getPlaceWithEVAvailability: <P extends CommonPlaceProps = C
  * // Search for charging stations and add availability
  * const results = await discoverPlaces({
  *   query: 'EV charging',
- *   at: [4.9, 52.3],
- *   radius: 5000
+ *   geoBias: { position: [4.9, 52.3], radiusMeters: 5000 }
  * });
  *
  * const withAvailability = await getPlacesWithEVAvailability(results, {
@@ -3866,8 +3651,8 @@ export declare const getPlaceWithEVAvailability: <P extends CommonPlaceProps = C
  *
  * // Display only stations with known availability
  * withAvailability.features.forEach(place => {
- *   const available = place.properties.chargingPark?.availability?.chargingPointAvailability.count;
- *   console.log(`${place.properties.poi?.name}: ${available} chargers`);
+ *   const { count, statusCounts } = place.properties.chargingPark.availability.chargingPointAvailability;
+ *   console.log(`${place.properties.poi?.name}: ${statusCounts.Available ?? 0} of ${count} chargers available`);
  * });
  * ```
  *
@@ -3933,11 +3718,11 @@ type GeocodingProps = Omit<SearchPlaceProps, 'info'> & {
  * Response from the geocoding service.
  *
  * Collection of places matching the geocoding query, each with address information
- * and match confidence scoring.
+ * and match confidence scoring. Its {@link SearchSummary} carries the `nextCursor` for the next page.
  *
  * @group Geocoding
  */
-type GeocodingResponse = Places<GeocodingProps>;
+type GeocodingResponse = Places<GeocodingProps, SearchSummary>;
 //#endregion
 //#region src/geocode/types/apiTypes.d.ts
 /**
@@ -4006,6 +3791,19 @@ type GeocodingIndexTypesAbbreviation = Exclude<SearchIndexType, 'POI'>;
  * @group Geocoding
  */
 type GeocodingParams = Omit<CommonPlacesParams<GetObject, GeocodingResponseAPI> & CommonGeocodeAndFuzzySearchParams, 'extendedPostalCodesFor'> & {
+  /**
+   * Where results may come from. Everything here **excludes** results.
+   *
+   * @remarks
+   * {@link GeographicFilters} plus `geographyTypes`, which restricts the kinds of geography that
+   * come back. Geocoding has no POI notion, so the rest of {@link PlaceFilters} does not apply.
+   *
+   * @example
+   * ```typescript
+   * filters: { countries: ['NL'], geographyTypes: ['Municipality'] }
+   * ```
+   */
+  filters?: GeographicFilters & Pick<PlaceFilters, 'geographyTypes'>;
   /**
    * Address or location query to geocode.
    *
@@ -4019,7 +3817,7 @@ type GeocodingParams = Omit<CommonPlacesParams<GetObject, GeocodingResponseAPI>
    * - City name: "Amsterdam"
    * - Intersection: "Broadway & 42nd St, New York"
    * - Landmark: "Eiffel Tower, Paris"
-   * - Partial address: "Dam Square" (city context resolved via `position` or `countries`)
+   * - Partial address: "Dam Square" (city context resolved via `geoBias` or `filters.countries`)
    *
    * @example
    * ```typescript
@@ -4355,6 +4153,9 @@ type GeometryParams = GeometryDataParams | GeometryPlaceParams;
  * - Visualize administrative divisions
  * - Calculate areas and spatial relationships
  *
+ * Returns polygons, not places. Pass the result to `GeometriesModule.show()`,
+ * not `PlacesModule.show()`. The `geometryId` comes from a prior search result.
+ *
  * @param params - Geometry parameters with IDs or places to fetch boundaries for
  *
  * @returns Promise resolving to polygon features representing area boundaries
@@ -5013,7 +4814,7 @@ type POICategoryResult = {
   /**
    * The standardized enum value identifying this category.
    *
-   * Use this value in search `poiCategories` parameters to filter results by category,
+   * Use this value in a search's `filters.poiCategories` to filter results by category,
    * or to cross-reference with `Place.properties.poi.categories` on search results.
    */
   code: POICategory;
@@ -5024,7 +4825,7 @@ type POICategoryResult = {
    * possible sub-categories — so you can understand the category hierarchy without
    * additional lookups.
    *
-   * Use these values directly in search `poiCategories` parameters.
+   * Use these values directly in a search's `filters.poiCategories`.
    */
   childCategoryCodes: POICategory[];
   /**
@@ -5050,7 +4851,7 @@ type POICategoriesResponse = {
  * Retrieve the list of POI category types supported by the TomTom Search API.
  *
  * The returned `code` values (`POICategory`) serve two purposes:
- * - Pass to `discoverPlaces({ poiCategories })` to filter search results by category.
+ * - Pass to `discoverPlaces({ filters: { poiCategories } })` to filter search results by category.
  * - Pass to `POIsModule.filterCategories()` to filter the map's built-in POI icons.
  *   Generic parent codes (e.g. `'RESTAURANT'`) are supported there; overly specific child
  *   codes (e.g. `'ITALIAN_RESTAURANT'`) are not — use a parent or a `POICategoryGroup` instead.
@@ -5077,7 +4878,7 @@ export declare const getPOICategories: (params?: POICategoriesParams) => Promise
  * Convenience wrapper around {@link getPOICategories} that returns a flat array of `POICategory` codes.
  *
  * The returned codes serve two purposes:
- * - Pass to `discoverPlaces({ poiCategories })` to filter search results by category.
+ * - Pass to `discoverPlaces({ filters: { poiCategories } })` to filter search results by category.
  * - Pass to `POIsModule.filterCategories()` to filter the map's built-in POI icons.
  *   Generic parent codes (e.g. `'RESTAURANT'`) are supported there; overly specific child
  *   codes (e.g. `'ITALIAN_RESTAURANT'`) are not — use a parent or a `POICategoryGroup` instead.
@@ -7108,7 +6909,7 @@ type NearbyIntentDetailsAPI = Omit<NearbyIntentDetails, 'position'> & {
  * const params: FuzzySearchParams = {
  *   key: 'your-api-key',
  *   query: 'pizz',  // Will find "pizza" restaurants
- *   position: [4.9041, 52.3676]
+ *   geoBias: { position: [4.9041, 52.3676] }
  * };
  *
  * // Fuzzy search with custom fuzziness
@@ -7124,6 +6925,8 @@ type NearbyIntentDetailsAPI = Omit<NearbyIntentDetails, 'position'> & {
  * @group Places Search
  */
 type FuzzySearchParams = CommonSearchParams<GetObject, FuzzySearchResponseAPI> & CommonGeocodeAndFuzzySearchParams & {
+  /** What may come back: the country and the POI-attribute restrictions together. */
+  filters?: SearchFilters;
   /**
    * Minimum fuzziness level to be used.
    *
@@ -7180,6 +6983,24 @@ type FuzzySearchParams = CommonSearchParams<GetObject, FuzzySearchResponseAPI> &
 type SearchFeatureCollectionProps = SearchSummary & {
   queryIntent?: QueryIntent[];
 };
+/** The keys of `Params` that `Base` lacks, each forbidden. */
+type Without<Params, Base> = { [Key in Exclude<keyof Params, keyof Base>]?: never; };
+/**
+ * What {@link discoverPlaces} takes: one search variant's params, with the other variants' own
+ * options forbidden. So `{ geometries, cursor }` is a compile error rather than a cursor silently
+ * dropped, as it would be with a plain union.
+ *
+ * @group Places Search
+ */
+export type DiscoverPlacesParams = (FuzzySearchParams & Without<GeometrySearchParams, FuzzySearchParams> & Without<AlongRouteSearchParams, FuzzySearchParams>) | (GeometrySearchParams & Without<FuzzySearchParams, GeometrySearchParams> & Without<AlongRouteSearchParams, GeometrySearchParams> & {
+  filters?: {
+    countries?: never;
+  };
+}) | (AlongRouteSearchParams & Without<FuzzySearchParams, AlongRouteSearchParams> & Without<GeometrySearchParams, AlongRouteSearchParams> & {
+  filters?: {
+    countries?: never;
+  };
+});
 /**
  * Search service response containing places that match the query.
  *
@@ -7205,7 +7026,7 @@ export type DiscoverPlacesResponse = Places<SearchPlaceProps, SearchFeatureColle
  *
  * Results are ranked by relevance with scores and optional distances.
  *
- * @param params - Search parameters (either GeometrySearchParams or FuzzySearchParams)
+ * @param params - Search parameters: {@link FuzzySearchParams}, {@link GeometrySearchParams} or {@link AlongRouteSearchParams}
  *
  * @returns Promise resolving to a collection of matching places
  *
@@ -7227,7 +7048,7 @@ export type DiscoverPlacesResponse = Places<SearchPlaceProps, SearchFeatureColle
  *
  * // Category search
  * const restaurants = await discoverPlaces({
- *   poiCategories: ['ITALIAN_RESTAURANT'],
+ *   filters: { poiCategories: ['ITALIAN_RESTAURANT'] },
  *   geoBias: { position: [4.9041, 52.3676], radiusMeters: 5000 }  // Within 5km
  * });
  * ```
@@ -7238,7 +7059,7 @@ export type DiscoverPlacesResponse = Places<SearchPlaceProps, SearchFeatureColle
  *
  * @group Places Search
  */
-export declare const discoverPlaces: (params: GeometrySearchParams | FuzzySearchParams | AlongRouteSearchParams) => Promise<DiscoverPlacesResponse>;
+export declare const discoverPlaces: (params: DiscoverPlacesParams) => Promise<DiscoverPlacesResponse>;
 /**
  * Search for a single place by text query.
  *
@@ -7369,11 +7190,9 @@ type SearchSuggestion = PlaceSuggestion | RefinementSuggestion;
  * Shaped after Places Search v3's `suggest` body: `filters` for what narrows the result set, and
  * `origin` for the point to search around.
  *
- * No `customServiceBaseURL`: the call spans two endpoints, and one URL cannot stand for both.
- *
  * @group Places Search
  */
-type SearchSuggestionsParams = Omit<CommonServiceParams, 'customServiceBaseURL'> & {
+type SearchSuggestionsParams = CommonServiceParams & {
   /** What the user typed. A partial query is fine; so is a complete one. */
   query: string;
   /**
@@ -7795,6 +7614,34 @@ type TrafficIncidentDetailsByBBoxParams = TrafficIncidentDetailsBaseParams & {
    * ```
    */
   bbox: HasBBox;
+  polygon?: never;
+  ids?: never;
+};
+/**
+ * Parameters for fetching incidents within a polygon, such as a city boundary.
+ *
+ * @remarks
+ * The API only accepts a bounding box, so the request is sent with the polygon's bounding box and the
+ * response is then trimmed to the incidents that intersect the polygon. A `LineString` incident that
+ * crosses the boundary is kept. The 10,000 km² limit applies to that bounding box.
+ *
+ * @example
+ * ```typescript
+ * const place = await geocodeOne('Amsterdam');
+ * const params: TrafficIncidentDetailsByPolygonParams = {
+ *   polygon: await geometryData({ geometries: [place] })
+ * };
+ * ```
+ *
+ * @group Traffic
+ */
+type TrafficIncidentDetailsByPolygonParams = TrafficIncidentDetailsBaseParams & {
+  /**
+   * Area to query: a `Polygon` or `MultiPolygon`, a `Feature` wrapping one, or a `FeatureCollection` of
+   * them, such as the {@link PolygonFeatures} that {@link geometryData} returns.
+   */
+  polygon: Polygon | MultiPolygon | Feature<Polygon | MultiPolygon> | FeatureCollection<Polygon | MultiPolygon>;
+  bbox?: never;
   ids?: never;
 };
 /**
@@ -7826,30 +7673,33 @@ type TrafficIncidentDetailsByIdsParams = TrafficIncidentDetailsBaseParams & {
    */
   ids: string[];
   bbox?: never;
+  polygon?: never;
 };
 /**
  * Parameters for the Traffic Incident Details service.
  *
- * Provide either a `bbox` to search within an area, or a list of `ids` to
- * look up specific incidents.
+ * Provide one of a `bbox` or a `polygon` to search within an area, or a list of `ids` to look up
+ * specific incidents.
  *
  * @group Traffic
  */
-type TrafficIncidentDetailsParams = TrafficIncidentDetailsByBBoxParams | TrafficIncidentDetailsByIdsParams;
+type TrafficIncidentDetailsParams = TrafficIncidentDetailsByBBoxParams | TrafficIncidentDetailsByPolygonParams | TrafficIncidentDetailsByIdsParams;
 //#endregion
 //#region src/traffic-incident-details/trafficIncidentDetails.d.ts
 /**
  * Fetch detailed information about traffic incidents.
  *
- * Query incidents either by a geographic bounding box or by a list of incident IDs.
+ * Query incidents by a geographic bounding box, by a polygon, or by a list of incident IDs.
  * Results are GeoJSON Features whose geometry is a `Point` (localised incidents) or
  * a `LineString` (incidents spanning a stretch of road).
  *
  * @remarks
- * **Two query modes:**
+ * **Three query modes:**
  *
  * - **Bounding box** (`bbox`): Returns all incidents within the given area.
  *   Maximum area is 10,000 km².
+ * - **Polygon** (`polygon`): Returns the incidents that intersect a polygon, such as a city boundary.
+ *   The request covers the polygon's bounding box, and the response is trimmed to the polygon.
  * - **By IDs** (`ids`): Returns the specified incidents directly.
  *   GET is used automatically for up to 5 IDs; POST for up to 100 IDs.
  *
@@ -7860,7 +7710,7 @@ type TrafficIncidentDetailsParams = TrafficIncidentDetailsByBBoxParams | Traffic
  * - Time information: start/end times and whether the incident is `present` or `future`
  * - Events: one or more detailed event descriptions
  *
- * @param params - Traffic Incident Details parameters (bbox or ids)
+ * @param params - Traffic Incident Details parameters (bbox, polygon or ids)
  *
  * @returns Promise resolving to a {@link TrafficIncidentDetails} object containing the matching incidents
  *
@@ -7880,6 +7730,15 @@ type TrafficIncidentDetailsParams = TrafficIncidentDetailsByBBoxParams | Traffic
  *
  * @example
  * ```typescript
+ * // Query within a city boundary rather than its bounding box
+ * const place = await geocodeOne('Amsterdam');
+ * const result = await trafficIncidentDetails({
+ *   polygon: await geometryData({ geometries: [place] })
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
  * // Query up to 5 specific incidents by ID (GET)
  * const result = await trafficIncidentDetails({
  *   ids: ['incident-id-1', 'incident-id-2']
@@ -7911,4 +7770,4 @@ type TrafficIncidentDetailsParams = TrafficIncidentDetailsByBBoxParams | Traffic
  */
 export declare const trafficIncidentDetails: (params: TrafficIncidentDetailsParams) => Promise<TrafficIncidentDetails>;
 //#endregion
-export type { AdditionalDataAPI, AlongRouteSearchParams, AlongRouteSearchPayloadAPI, AlongRouteSearchRequestAPI, AlongRouteSearchResponse, AlongRouteSearchResponseAPI, AlongRouteSearchResultAPI, AlongRouteSortBy, AreaAnalyticsDateInput, ArrivalSide, BookmarkIntent, BookmarkIntentDetails, BrandSuggestion, CalculateRouteParams, CategorySuggestion, 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, PlaceDetailsMandatoryParams, PlaceDetailsOptionalParams, PlaceDetailsParams, PlaceDetailsResponse, PlaceDetailsResponseAPI, PlaceDetailsResultAPI, PlaceSuggestion, PoiCategoriesResponseAPI, PoiCategoryAPI, PolygonAPI, QueryIntent, QueryIntentAPI, RefinementSuggestion, ReverseGeocodingMandatoryParams, ReverseGeocodingOptionalParams, ReverseGeocodingParams, RoutePointAPI, RouteStopOptions, SearchGeometryInput, SearchSuggestion, SearchSuggestionKind, SearchSuggestionsParams, SearchSuggestionsResponse, TrafficAreaAnalyticsDateRange, TrafficAreaAnalyticsDays, TrafficAreaAnalyticsParams, TrafficIncidentDetailsByBBoxParams, TrafficIncidentDetailsByIdsParams, TrafficIncidentDetailsParams, W3WIntent, W3WIntentDetails, arrivalSides, chargingStopsStrategies, functionalRoadClasses };
+export type { AdditionalDataAPI, AlongRouteSearchParams, AlongRouteSearchPayloadAPI, AlongRouteSearchRequestAPI, AlongRouteSearchResponse, AlongRouteSearchResponseAPI, AlongRouteSearchResultAPI, AlongRouteSortBy, AreaAnalyticsDateInput, ArrivalSide, BookmarkIntent, BookmarkIntentDetails, BrandSuggestion, CalculateRouteParams, CategorySuggestion, 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, PlaceDetailsMandatoryParams, PlaceDetailsOptionalParams, PlaceDetailsParams, PlaceDetailsResponse, PlaceDetailsResponseAPI, PlaceDetailsResultAPI, PlaceSuggestion, PoiCategoriesResponseAPI, PoiCategoryAPI, PolygonAPI, QueryIntent, QueryIntentAPI, RefinementSuggestion, ReverseGeocodingMandatoryParams, ReverseGeocodingOptionalParams, ReverseGeocodingParams, RoutePointAPI, RouteStopOptions, SearchGeometryInput, SearchSuggestion, SearchSuggestionKind, SearchSuggestionsParams, SearchSuggestionsResponse, TrafficAreaAnalyticsDateRange, TrafficAreaAnalyticsDays, TrafficAreaAnalyticsParams, TrafficIncidentDetailsByBBoxParams, TrafficIncidentDetailsByIdsParams, TrafficIncidentDetailsByPolygonParams, TrafficIncidentDetailsParams, W3WIntent, W3WIntentDetails, arrivalSides, chargingStopsStrategies, functionalRoadClasses };