@tomtom-org/maps-sdk 1.0.0-rc.3 → 1.0.0-rc.4

package/services/dist/index.d.ts

@@ -1,5 +1,35 @@
-import { AddressProperties, AreaAnalyticsMetricKey, Avoidable, BBox, ChargingPoint, ChargingStation, CommonPlaceProps, Connector, ConnectorType, EntryPoint, Fuel, GeographyType, GeopoliticalView, GetPositionEntryPointOption, GlobalConfig, HasBBox, HasLngLat, MapcodeType, OpeningHours, OpeningHoursMode, POICategory, Place, PlaceDataSources, PlaceType, Places, PolygonFeature, PolygonFeatures, ReachableRangeBudget, RevGeoAddressProps, RoadShieldReference, Route, RoutePlanningLocation, Routes, SDKErrorCode, SearchPlaceProps, TimeZone, TomTomAPIHeaders, TrafficAreaAnalytics, TrafficIncidentDetails, TrafficIncidentRequestCategory, TrafficIncidentTEC, TrafficIncidentTimeValidity, TravelMode, inputSectionTypesWithGuidance } from "@tomtom-org/maps-sdk/core";
+import { AddressProperties, AreaAnalyticsMetricKey, Avoidable, BBox, ChargingPoint, ChargingStation, CommonPlaceProps, Connector, ConnectorType, CurveDetectionOptions, EntryPoint, Fuel, GeographyType, GeopoliticalView, GetPositionEntryPointOption, GlobalConfig, HasBBox, HasLngLat, MapcodeType, OpeningHours, OpeningHoursMode, POICategory, Place, PlaceDataSources, PlaceType, Places, PolygonFeature, PolygonFeatures, ReachableRangeBudget, RevGeoAddressProps, RoadShieldReference, Route, RoutePlanningLocation, Routes, SDKErrorCode, SearchPlaceProps, TimeZone, TomTomAPIHeaders, TrafficAreaAnalytics, TrafficIncidentDetails, TrafficIncidentRequestCategory, TrafficIncidentTEC, TrafficIncidentTimeValidity, TravelMode, inputSectionTypesWithGuidance } from "@tomtom-org/maps-sdk/core";
 import { core } from "zod";
+//#region src/along-route-search/types/alongRoutePlaceProps.d.ts
+/**
+ * The properties of a place that {@link discoverPlaces} finds along a route: the search properties
+ * plus the detour a stop at the place costs.
+ *
+ * @remarks
+ * A detour is measured against the original route, so either figure can be negative.
+ *
+ * @example
+ * ```typescript
+ * const cafes = await discoverPlaces({ route, maxDetourTimeSeconds: 600, query: 'cafe' });
+ * const minutes = Math.round(cafes.features[0].properties.detourTimeInSeconds / 60);
+ * ```
+ *
+ * @group Along Route Search
+ */
+type AlongRoutePlaceProps = SearchPlaceProps & {
+  /** Seconds a stop at the place adds to the route, negative when the route through it is faster. */
+  detourTimeInSeconds: number;
+  /** Meters a stop at the place adds to the route, negative when the route through it is shorter. */
+  detourDistanceInMeters: number;
+  /**
+   * Meters from the start of the route to where the detour to the place leaves it.
+   *
+   * @remarks
+   * It is present only when you sort by `'detourOffset'`, which types it as required.
+   */
+  detourOffsetInMeters?: number;
+};
+//#endregion
 //#region ../node_modules/.pnpm/@types+geojson@7946.0.16/node_modules/@types/geojson/index.d.ts
 /**
  * The value values for the "type" property of GeoJSON Objects.
@@ -264,8 +294,9 @@ type CommonServiceParams<ApiRequest = any, ApiResponse = any> = Partial<Omit<Glo
    * Whether the SDK validates the request parameters against the expected schema before sending them.
    *
    * @remarks
-   * To skip validation, set it to `false`. The `commonBaseURL` check (`INSECURE_BASE_URL`) runs
-   * either way.
+   * Validation also rejects a parameter the service doesn't know, and names it. To skip validation,
+   * set it to `false`, which then drops an unknown parameter silently. The `commonBaseURL` check
+   * (`INSECURE_BASE_URL`) runs either way.
    *
    * @defaultValue `true`
    */
@@ -331,9 +362,9 @@ type CommonServiceParams<ApiRequest = any, ApiResponse = any> = Partial<Omit<Glo
  * 2. API errors are recoverable errors that occur during SDK operations,
  *    such as network failures or invalid API responses.
  *
- * A service call rejects with one, except for a request it cannot build at all, such as one with a geometry type
- * that geometry search does not support sent with `validateRequest: false`, and for `geocodeOne` or `discoverOnePlace` finding nothing. Those reject
- * with a plain `Error`. An `onAPIRequest` or `onAPIResponse` hook that throws rejects the call with its own error.
+ * A service call rejects with one, even for a request it cannot build at all, such as one with a geometry type
+ * that geometry search does not support sent with `validateRequest: false`. That one is an `INVALID_REQUEST`.
+ * An `onAPIRequest` or `onAPIResponse` hook that throws rejects the call with its own error.
  *
  * @example
  * ```typescript
@@ -477,8 +508,8 @@ export declare class SDKAbortError extends SDKError {
 /**
  * What {@link LatestRequest.run} resolves to.
  *
- * `current: false` means a newer `run` or a `cancel` retired the request, so its value or error is
- * stale and must not be shown.
+ * `current: false` means a newer request or a `cancel` retired the request, so its value or error
+ * is stale and must not be shown.
  *
  * @group Shared
  */
@@ -489,7 +520,32 @@ export type LatestRequestResult<T> = {
   current: false;
 };
 /**
- * One in-flight request slot, where each new request retires the one before it.
+ * When a newer request retires the ones started before it.
+ *
+ * - `'on-start'`: as it starts, so only one request is ever in flight.
+ * - `'on-answer'`: as its answer arrives, so the older ones keep running and each answer that
+ *   lands first is still shown. Use it when requests start faster than they answer, such as a
+ *   route re-planned during a drag, where `'on-start'` would show nothing until the drag pauses.
+ *
+ * @group Shared
+ */
+export type LatestRequestSupersede = 'on-start' | 'on-answer';
+/**
+ * Options for {@link createLatestRequest}.
+ *
+ * @group Shared
+ */
+export type LatestRequestOptions = {
+  /**
+   * When a newer request retires the ones started before it.
+   *
+   * @defaultValue `'on-start'`
+   */
+  supersede?: LatestRequestSupersede;
+};
+/**
+ * A request slot that keeps only the latest answer, where each request retires the ones started
+ * before it, as {@link LatestRequestOptions.supersede} sets.
  *
  * @see {@link createLatestRequest}
  *
@@ -497,18 +553,19 @@ export type LatestRequestResult<T> = {
  */
 export type LatestRequest = {
   /**
-   * Aborts the request in flight, if any, then starts this one.
+   * Starts this request, and retires the ones started before it when it starts or when it answers.
    *
    * @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}.
+   * call it makes. Retiring a request aborts its signal. 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 }`.
+   * Aborts every request in flight without starting another, so each resolves `{ current: false }`.
    */
   cancel: () => void;
   /**
@@ -521,14 +578,18 @@ export type LatestRequest = {
 /**
  * Creates a slot that keeps only the latest request.
  *
- * Starting one aborts its predecessor, and an answer arriving after a newer request or a `cancel` is
- * dropped rather than returned.
+ * A newer request aborts the ones started before it, and an answer arriving after a newer one or a
+ * `cancel` is dropped rather than returned.
  *
  * @remarks
  * Use one per thing that can be superseded, like a click lookup, a search box or 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.
  *
+ * By default a request retires the older ones as it starts. With `supersede: 'on-answer'` they keep
+ * running until a newer answer arrives, so a stream of requests faster than their answers still
+ * shows each answer in order.
+ *
  * @example
  * ```ts
  * const lookup = createLatestRequest();
@@ -541,11 +602,19 @@ export type LatestRequest = {
  * clearButton.addEventListener('click', lookup.cancel);
  * ```
  *
+ * @example
+ * Show each route re-planned during a drag as it arrives, never an older one after a newer one:
+ * ```ts
+ * const latestRoute = createLatestRequest({ supersede: 'on-answer' });
+ * const result = await latestRoute.run((signal) => calculateRoute({ locations, signal }));
+ * if (result.current) await routingModule.showRoutes(result.value);
+ * ```
+ *
  * @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;
+export declare const createLatestRequest: (options?: LatestRequestOptions) => LatestRequest;
 //#endregion
 //#region src/shared/types/geoBias.d.ts
 /**
@@ -574,8 +643,8 @@ export type PointGeoBias = {
  */
 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).
+   * The rectangle, as a {@link BBox} `[west, south, east, north]` (west > east across the antimeridian),
+   * or any GeoJSON value a bounding box can be derived from (a `bbox` property, a Feature, or a geometry).
    */
   boundingBox: HasBBox;
 };
@@ -864,8 +933,12 @@ export type CommonGeocodeAndFuzzySearchParams = {
    * the same parameters. Leave it out for the first page.
    *
    * @remarks
-   * The value is **opaque**. Only the SDK mints and reads it, so the pagination mechanism can
-   * change without breaking callers. Passing a value this SDK did not produce throws.
+   * The value is **opaque**. Its format isn't part of the contract, so the pagination mechanism
+   * can change without breaking callers. A value the SDK can't read as a cursor throws an `SDKError`.
+   *
+   * The cursor isn't tied to the search that minted it. If you pass it with another `query` or
+   * other `filters`, that search starts at the same position and skips its first pages. Leave
+   * `cursor` out to start a new search.
    *
    * @example
    * ```typescript
@@ -1320,12 +1393,27 @@ export type CostModel = {
   routeType?: RouteType;
 };
 type DepartArriveOption = 'departAt' | 'arriveBy';
+/**
+ * A wall-clock date and time without a UTC offset, as `YYYY-MM-DDTHH:mm:ss`, such as
+ * `'2026-10-19T08:15:00'`.
+ *
+ * @remarks
+ * Seconds are required, and an offset, a trailing `Z` or a date that doesn't exist, such as
+ * `2026-02-30`, is rejected. Each field takes two digits, which the type can't check, so pad what
+ * you build at runtime and cast it with `as LocalDateTime`. Request validation checks the rest.
+ *
+ * @group Routing
+ */
+export type LocalDateTime = `${number}-${number}-${number}T${number}:${number}:${number}`;
 /**
  * The departure or arrival time for route planning.
  *
  * It sets either when to depart from the origin or when to arrive at the destination. The routing
  * engine then optimises the route for that time window, considering traffic patterns for that time of day.
  *
+ * Pass exactly one of `date`, an instant, and `localDateTime`, a wall-clock time the routing API
+ * reads in the local time zone of the place it applies to.
+ *
  * @typeParam Option - Whether this specifies departure or arrival time
  *
  * @remarks
@@ -1342,23 +1430,17 @@ type DepartArriveOption = 'departAt' | 'arriveBy';
  *
  * @example
  * ```typescript
- * // Depart at specific time (morning commute)
+ * // Depart at 08:15 in Tokyo, wherever the code runs
  * const departParams: DepartArriveParams = {
  *   option: 'departAt',
- *   date: new Date('2025-10-20T08:00:00+02:00')
+ *   localDateTime: '2026-10-19T08:15:00'
  * };
  *
- * // Arrive by specific time (catch a flight)
+ * // Arrive by an instant (catch a flight)
  * const arriveParams: DepartArriveParams = {
  *   option: 'arriveBy',
  *   date: new Date('2025-10-20T14:00:00+02:00')
  * };
- *
- * // Plan route avoiding rush hour
- * const offPeakDepart: DepartArriveParams = {
- *   option: 'departAt',
- *   date: new Date('2025-10-20T10:30:00+02:00')  // After morning rush
- * };
  * ```
  *
  * @group Routing
@@ -1372,18 +1454,32 @@ export type DepartArriveParams<Option extends DepartArriveOption = DepartArriveO
    * - `arriveBy` calculates the route backward to arrive by this time.
    */
   option: Option;
+} & ({
   /**
-   * The date and time to depart or arrive.
+   * The instant to depart or arrive.
    *
    * @remarks
    * If you pass a past date, or one that is impossible to achieve (such as an imminent arrival
    * date for a very long route), the route defaults to departing immediately.
    *
-   * The date is an instant, sent in UTC. For a wall-clock time at the origin, build the `Date`
-   * with the origin's UTC offset.
+   * The date is sent in UTC. For a wall-clock time at the origin, use `localDateTime` instead.
    */
   date: Date;
-};
+  localDateTime?: never;
+} | {
+  /**
+   * The wall-clock time to depart or arrive, without a UTC offset.
+   *
+   * @remarks
+   * `localDateTime` is a wall-clock time without an offset, read in the origin's time zone.
+   * With `arriveBy`, it is read in the time zone of the route's final destination instead.
+   *
+   * The response's `summary.departureTime` and `summary.arrivalTime` carry the instants it
+   * resolved to. A past or unreachable time defaults to departing immediately, as with `date`.
+   */
+  localDateTime: LocalDateTime;
+  date?: never;
+});
 /**
  * The parameters every routing service request shares.
  *
@@ -1413,7 +1509,7 @@ export type DepartArriveParams<Option extends DepartArriveOption = DepartArriveO
  *   travelMode: 'car',
  *   when: {
  *     option: 'departAt',
- *     date: new Date('2025-10-20T08:00:00+02:00')
+ *     localDateTime: '2026-10-19T08:00:00'
  *   }
  * };
  *
@@ -1436,7 +1532,7 @@ export type DepartArriveParams<Option extends DepartArriveOption = DepartArriveO
  * };
  * ```
  *
- * @see [Common Routing Parameters Documentation](https://docs.tomtom.com/routing-api/documentation/routing/common-routing-parameters)
+ * @see [Calculate Route POST data parameters](https://docs.tomtom.com/routing-api/documentation/tomtom-orbis-maps/v3/calculate-route#post-data-parameters)
  *
  * @group Routing
  */
@@ -1448,15 +1544,16 @@ export type CommonRoutingParams = {
   /**
    * The travel mode for the requested route, which is the primary means of transport while routing.
    *
-   * Note that the requested travelMode may not be available for the entire route. Where it is not
-   * available for a particular section, the response element for that section is 'other'.
-   * @default None
+   * Only `'car'` is supported, which is also the routing service's default.
+   * For `calculateRoute`, the parts of the route a car may not use come back as its
+   * `vehicleRestricted` sections, unless `sectionTypes` leaves them out.
+   * @default 'car'
    */
   travelMode?: TravelMode;
   /**
-   * When to depart or arrive.
-   * If you pass a past date, or one that is impossible to achieve (such as an imminent arrival
-   * date for a long route), it defaults to departing now.
+   * When to depart or arrive, as an instant or a wall-clock time.
+   * If you pass a past time, or one that is impossible to achieve (such as an imminent arrival
+   * for a long route), it defaults to departing now.
    * @default depart now
    */
   when?: DepartArriveParams;
@@ -1669,7 +1766,6 @@ type SummaryQueryType = 'NEARBY' | 'NON_NEAR';
  * });
  *
  * 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`);
@@ -1721,9 +1817,8 @@ export type SearchSummary = {
    *
    * @example
    * ```typescript
-   * // If limit=10 and totalResults=50
+   * // If limit=10 and more results exist
    * numResults: 10  // Only 10 results in this response
-   * totalResults: 50  // 50 total matches exist
    * ```
    */
   numResults: number;
@@ -1733,24 +1828,30 @@ export type SearchSummary = {
    * @remarks
    * See {@link CommonGeocodeAndFuzzySearchParams.cursor}. Only fuzzy search and geocoding page this way.
    *
-   * If it is absent, pagination has ended. Either the result set is exhausted, this page came back
-   * empty, or the next page would start past result 1900, the furthest the backend serves.
+   * If it is absent, pagination has ended. Either the next page would start at `totalResults`, this
+   * page came back empty, or the next page would start past result 1900, the furthest the backend
+   * serves. Fuzzy search's `totalResults` is at most 100 and can be lower at a larger `limit`, so its
+   * pagination ends there.
    */
   nextCursor?: string;
   /**
-   * The total number of results that match the query, regardless of pagination limits.
+   * The number of results the search API reports for the query.
    *
    * @remarks
-   * A total is not guaranteed, so guard it rather than assume a number. Use it to size a progress
-   * indicator, such as a page count of `Math.ceil(totalResults / limit)`, but not to drive
-   * pagination. `nextCursor` decides whether a further page exists.
+   * It is not guaranteed, so guard it rather than assume a number. For geocoding, it counts matches
+   * beyond the page returned. Fuzzy and geometry search report at most 100, the most one search
+   * returns, and fuzzy search's number can drop as `limit` grows. Along-route search reports the
+   * page's own length. So don't show it as a total except for geocoding.
+   *
+   * Don't drive pagination with it either. `nextCursor` decides whether a further page exists.
    *
    * @example
    * ```typescript
-   * totalResults: 50  // 50 total matches found
-   * numResults: 10    // Showing first 10
+   * // geocode({ query: 'Main Street' })
+   * totalResults: 58090  // Matches counted, this page included
+   * numResults: 10       // Showing the first 10
    *
-   * // Fetch the rest by passing `nextCursor` back as `cursor`
+   * // Fetch more by passing `nextCursor` back as `cursor`
    * ```
    */
   totalResults?: number;
@@ -2017,11 +2118,24 @@ type AlongRouteSearchPayloadAPI = {
 type AlongRouteSearchRequestAPI = PostObject<AlongRouteSearchPayloadAPI>;
 //#endregion
 //#region src/along-route-search/types/alongRouteSearchResponseAPI.d.ts
+/**
+ * @ignore
+ */
+type AlongRouteSearchResultAPI = CommonSearchPlaceResultAPI & {
+  /** In seconds. */
+  detourTime: number;
+  /** In meters. */
+  detourDistance: number;
+  /** In meters, sent only when sorting by `detourOffset`. */
+  detourOffset?: number;
+};
 /**
  * Its results are sorted by detour time or offset.
  * @ignore
  */
-type AlongRouteSearchResponseAPI = SearchResultsResponseAPI;
+type AlongRouteSearchResponseAPI = Omit<SearchResultsResponseAPI, 'results'> & {
+  results: AlongRouteSearchResultAPI[];
+};
 //#endregion
 //#region src/along-route-search/types/alongRouteSearchParams.d.ts
 /**
@@ -2030,8 +2144,11 @@ type AlongRouteSearchResponseAPI = SearchResultsResponseAPI;
  * Controls how the returned POIs are ordered relative to the route.
  *
  * @remarks
- * - `detourTime`: Sort by additional travel time required to visit the POI (default)
- * - `detourOffset`: Sort by how far along the route the detour point falls
+ * - `detourTime`: Sort by the detour time, the travel time a stop at the POI adds (default). It is
+ *   negative when the route through the POI is faster than the original one, so those POIs come first.
+ *   Each result carries it as `detourTimeInSeconds`, in {@link AlongRoutePlaceProps}.
+ * - `detourOffset`: Sort by how far along the route the detour point falls. Each result then carries it
+ *   as `detourOffsetInMeters`, in {@link AlongRoutePlaceProps}.
  *
  * @group Along Route Search
  */
@@ -2040,7 +2157,7 @@ type AlongRouteSortBy = 'detourTime' | 'detourOffset';
  * Parameters for searching places along a route.
  *
  * Along-route search finds POIs near a provided route geometry and ranks them
- * by the detour cost (time or distance offset) required to visit them.
+ * by the detour time a stop adds, or by the detour point's offset along the route.
  *
  * @remarks
  * **Key Features:**
@@ -2099,7 +2216,8 @@ type AlongRouteSearchParams = CommonSearchParams<AlongRouteSearchRequestAPI, Alo
    */
   route: LineString | Route | Position[];
   /**
-   * Maximum allowed detour time in seconds.
+   * Maximum allowed detour time in seconds, a positive integer up to `3600` (one hour);
+   * request validation rejects a larger one.
    *
    * Only POIs reachable within this additional travel time from the route
    * are returned. It controls the width of the search corridor.
@@ -2583,7 +2701,7 @@ type GeocodingParams = Omit<CommonPlacesParams<GetObject, GeocodingResponseAPI>
    * Address or location query to geocode.
    *
    * The text to convert into geographic coordinates, typically a street address,
-   * intersection, city name or landmark. The service tolerates typos and incomplete
+   * intersection or city name. The service tolerates typos and incomplete
    * inputs. Pass it as plain text. The SDK encodes it for the request path, so a value
    * you already encoded is encoded again and can resolve to a different place.
    *
@@ -2592,14 +2710,16 @@ type GeocodingParams = Omit<CommonPlacesParams<GetObject, GeocodingResponseAPI>
    * - Full street address: "1600 Pennsylvania Avenue NW, Washington, DC"
    * - City name: "Amsterdam"
    * - Intersection: "Broadway & 42nd St, New York"
-   * - Landmark: "Eiffel Tower, Paris"
    * - Partial address: "Dam Square" (city context resolved via `geoBias` or `filters.countries`)
    *
+   * A landmark such as "Eiffel Tower, Paris" is a POI, which geocoding never returns: find it
+   * with {@link discoverPlaces}.
+   *
    * @example
    * ```typescript
    * query: '1600 Pennsylvania Avenue NW, Washington, DC'
    * query: 'Museumplein, Amsterdam'
-   * query: 'Buckingham Palace, London'
+   * query: 'Broadway & 42nd St, New York'
    * ```
    */
   query: string;
@@ -2693,7 +2813,7 @@ export declare const geocode: (params: GeocodingParams) => Promise<GeocodingResp
  *
  * @param queryOrParams - The address or place name to geocode, or the full {@link GeocodingParams} without `limit`.
  * @returns The best-matching place.
- * @throws {Error} If no results are found for the query
+ * @throws {SDKError} With the code `NOT_FOUND` and the service `'Geocode'` if no results are found for the query
  *
  * @remarks
  * To handle finding no results without throwing, use {@link geocode} with a `limit`
@@ -3194,8 +3314,7 @@ type PlaceDetailsMandatoryParams = {
    *
    * @remarks
    * You can get this ID from:
-   * - Previous search results (place.id)
-   * - POI details data source (place.properties.dataSources.poiDetails.id)
+   * - Previous search results (place.id, on the feature rather than in its properties)
    * - Related POIs (place.properties.relatedPois[].id)
    *
    * @example
@@ -3255,8 +3374,8 @@ type PlaceDetailsResponse = Place<SearchPlaceProps> | undefined;
  * Retrieves detailed information about a place using its unique identifier.
  *
  * The place details service fetches comprehensive data for a specific place when you
- * have its ID from a previous search or from a place's dataSources. Use it to get
- * additional details or refresh information about a known location.
+ * have its ID from a previous search. Use it to get additional details or refresh
+ * information about a known location.
  *
  * @remarks
  * Use it to fetch a POI's opening hours, related POIs and EV charging hardware, update
@@ -3264,8 +3383,7 @@ type PlaceDetailsResponse = Place<SearchPlaceProps> | undefined;
  * deep links, or explore parent/child relationships between related POIs.
  *
  * You can get the ID from:
- * - Previous search results (place.id)
- * - POI details data source (place.properties.dataSources.poiDetails.id)
+ * - Previous search results (place.id, on the feature rather than in its properties)
  * - Related POIs (place.properties.relatedPois[].id)
  * - Deep links or bookmarks
  *
@@ -3277,23 +3395,13 @@ type PlaceDetailsResponse = Place<SearchPlaceProps> | undefined;
  * ```typescript
  * // Get a search result's full details
  * const searchResult = await discoverPlaces({ query: 'Eiffel Tower' });
- * const placeId = searchResult.features[0].id;
+ * const place = searchResult.features[0];
  *
  * const placeDetails = await getPlaceDetails({
- *   entityId: placeId
+ *   entityId: place.id,
+ *   openingHours: 'nextSevenDays'
  * });
  *
- * // Get extended POI details
- * const place = searchResult.features[0];
- * const poiDetailsId = place.properties.dataSources?.poiDetails?.id;
- *
- * if (poiDetailsId) {
- *   const detailedPOI = await getPlaceDetails({
- *     entityId: poiDetailsId,
- *     openingHours: 'nextSevenDays'
- *   });
- * }
- *
  * // Navigate to related POI
  * const relatedPOI = place.properties.relatedPois?.[0];
  * if (relatedPOI) {
@@ -3656,7 +3764,7 @@ export type ReachableRangeOwnParams = {
    */
   smoothing?: 'none' | 'weak' | 'strong';
   /**
-   * When to depart.
+   * When to depart, as an instant (`date`) or a wall-clock time at the origin (`localDateTime`).
    *
    * @remarks
    * If you supply past dates or dates that are impossible to achieve, it
@@ -3669,7 +3777,7 @@ export type ReachableRangeOwnParams = {
    *
    * @example
    * ```typescript
-   * when: { option: 'departAt', date: new Date('2025-10-20T08:00:00+02:00') }
+   * when: { option: 'departAt', localDateTime: '2026-10-19T08:00:00' }
    * ```
    */
   when?: DepartArriveParams<'departAt'>;
@@ -3773,7 +3881,7 @@ export type ReachableRangeProperties = Omit<ReachableRangeParams, keyof CommonSe
  * const morningRange = await calculateReachableRange({
  *   origin: [4.9041, 52.3676],
  *   budget: { type: 'timeMinutes', value: 45 },
- *   when: { option: 'departAt', date: new Date('2025-10-20T08:00:00+02:00') }  // Rush hour
+ *   when: { option: 'departAt', localDateTime: '2026-10-19T08:00:00' }  // Rush hour in Amsterdam
  * });
  * ```
  *
@@ -4432,6 +4540,8 @@ type InputSectionType = (typeof inputSectionTypesWithGuidance)[number];
  * - `roadShields`: Road shield information
  * - `importantRoadStretch`: Named important road stretches along the route
  * - `lanes`: Lane guidance
+ * - `curve`: Curves, with their heading change and radius, which the SDK finds in the route's geometry
+ * - `curvyStretch`: Stretches where curves follow one another closely, which the SDK groups the curves into
  *
  * A requested section type is only present in the response if the route actually traverses it
  * (e.g. `ferry` is omitted on a route with no water crossing). The `lanes` section is returned only
@@ -4443,14 +4553,14 @@ type InputSectionType = (typeof inputSectionTypesWithGuidance)[number];
  * // Request toll, ferry, and traffic sections
  * const sectionTypes: InputSectionTypes = ['toll', 'ferry', 'traffic'];
  *
- * // Request all available sections
- * const sectionTypes: InputSectionTypes = inputSectionTypesWithGuidance;
+ * // The default sections, and the curves
+ * const sectionTypes: InputSectionTypes = [...defaultSectionTypes, 'curve', 'curvyStretch'];
  *
  * // Request no optional sections (leg sections still included)
  * const sectionTypes: InputSectionTypes = [];
  * ```
  *
- * @default When omitted, all section types are requested (equivalent to `inputSectionTypesWithGuidance`).
+ * @default When omitted, core's `defaultSectionTypes`: every type but `curve` and `curvyStretch`.
  *
  * @group Routing
  */
@@ -4588,7 +4698,7 @@ type MaxNumberOfAlternatives = 0 | 1 | 2 | 3 | 4 | 5;
  *   },
  *   when: {
  *     option: 'departAt',
- *     date: new Date('2025-10-20T08:00:00+02:00')
+ *     localDateTime: '2026-10-19T08:00:00'
  *   }
  * };
  *
@@ -4624,8 +4734,8 @@ type CalculateRouteParams = CommonServiceParams<CalculateRouteRequestAPI, Calcul
    * pins the geometry the route must follow, but its endpoints go out as waypoints as well,
    * so it shapes the route without shortening the list of legs.
    *
-   * @see [POST data parameters](https://docs.tomtom.com/routing-api/documentation/tomtom-maps/calculate-route#post-data-parameters)
-   * @see [Response structure](https://docs.tomtom.com/routing-api/documentation/tomtom-maps/calculate-route#structure-of-a-successful-response)
+   * @see [POST data parameters](https://docs.tomtom.com/routing-api/documentation/tomtom-orbis-maps/v3/calculate-route#post-data-parameters)
+   * @see [Response structure](https://docs.tomtom.com/routing-api/documentation/tomtom-orbis-maps/v3/calculate-route#structure-of-a-successful-response)
    *
    * @example
    * ```typescript
@@ -4653,7 +4763,8 @@ type CalculateRouteParams = CommonServiceParams<CalculateRouteRequestAPI, Calcul
    * They improve routing accuracy by directing to the correct entrance.
    *
    * @remarks
-   * - `main-when-available`: Use main entry point if available, otherwise use place center (recommended for routing)
+   * - `main-when-available`: Use the entry point {@link GetPositionEntryPointOption} picks, otherwise the
+   *   place center (recommended for routing)
    * - `ignore`: Always use place center position
    *
    * @default 'ignore' (a place's geometry is used)
@@ -4747,20 +4858,42 @@ type CalculateRouteParams = CommonServiceParams<CalculateRouteRequestAPI, Calcul
    * when two or more routes come back. A section type is only present in the response if the
    * route actually traverses it. The `lanes` section is returned only when
    * {@link GuidanceParams | `guidance`} is also requested, and, when a list is given, only if it
-   * includes `lanes`.
+   * includes `lanes`. The SDK finds `curve` and `curvyStretch` in the route's geometry, with
+   * the thresholds of `curveDetection`, and only when the list names them.
    *
-   * @default When omitted, all section types are requested.
+   * @default When omitted, core's `defaultSectionTypes`: every type but `curve` and `curvyStretch`.
    *
    * @example
    * ```typescript
    * // Request specific sections (any combination of available section types)
    * sectionTypes: ['toll', 'ferry', 'traffic', 'country', 'roadShields']
    *
+   * // The default sections, and the curves
+   * sectionTypes: [...defaultSectionTypes, 'curve', 'curvyStretch']
+   *
    * // Request no optional sections
    * sectionTypes: []
    * ```
    */
   sectionTypes?: InputSectionTypes;
+  /**
+   * The thresholds the SDK finds the `curve` and `curvyStretch` sections with, when
+   * `sectionTypes` names them.
+   *
+   * @remarks
+   * The SDK finds them in the route's geometry once it comes back, so they change nothing the
+   * routing API returns. To find them again with other thresholds, with no new request, pass
+   * the route to core's `withCurveSections`.
+   *
+   * @default The defaults of core's `getCurveSections` and `getCurvyStretchSections`.
+   *
+   * @example
+   * ```typescript
+   * // Only the hard curves, and the stretches of five or more of them
+   * curveDetection: { curve: { maxRadiusInMeters: 100 }, curvyStretch: { minCurveCount: 5 } }
+   * ```
+   */
+  curveDetection?: CurveDetectionOptions;
   /**
    * Maximum number of alternative routes to calculate.
    *
@@ -4789,7 +4922,7 @@ type CalculateRouteParams = CommonServiceParams<CalculateRouteRequestAPI, Calcul
  * @param params - The locations, travel mode and other route calculation options.
  * @returns The calculated routes, with their geometry, distance and travel time.
  *
- * @see [Calculate Route API Documentation](https://docs.tomtom.com/routing-api/documentation/tomtom-maps/calculate-route)
+ * @see [Calculate Route API Documentation](https://docs.tomtom.com/routing-api/documentation/tomtom-orbis-maps/v3/calculate-route)
  *
  * @group Routing
  */
@@ -4890,6 +5023,17 @@ type RouteStopOptions = {
   legCostModel?: LegCostModel;
 };
 //#endregion
+//#region src/along-route-search/types/alongRouteSearchResponse.d.ts
+/**
+ * Response from an along-route search query: the places found near the route, sorted by detour
+ * time or offset, with the search summary.
+ *
+ * @typeParam P - The place properties, which carry `detourOffsetInMeters` when sorted by offset.
+ *
+ * @ignore
+ */
+type AlongRouteSearchResponse<P extends AlongRoutePlaceProps = AlongRoutePlaceProps> = Places<P, SearchSummary>;
+//#endregion
 //#region src/search/discoverPlaces.d.ts
 /** The keys of `Params` that `Base` lacks, each forbidden. */
 type Without<Params, Base> = { [Key in Exclude<keyof Params, keyof Base>]?: never; };
@@ -4955,6 +5099,9 @@ export type DiscoverPlacesResponse = Places<SearchPlaceProps, FuzzySearchFeature
  * - Geometry search when `geometries` is given, for places inside those areas.
  * - Fuzzy search otherwise, for free text, optionally biased by `geoBias`.
  *
+ * With a `route`, each result's properties are {@link AlongRoutePlaceProps}, which add the detour a stop
+ * at the place costs.
+ *
  * @param params - The {@link FuzzySearchParams}, {@link GeometrySearchParams} or {@link AlongRouteSearchParams}.
  *
  * @returns The matching places.
@@ -4994,7 +5141,15 @@ export type DiscoverPlacesResponse = Places<SearchPlaceProps, FuzzySearchFeature
  *
  * @group Places Search
  */
-export declare const discoverPlaces: (params: DiscoverPlacesParams) => Promise<DiscoverPlacesResponse>;
+export declare function discoverPlaces(params: Extract<DiscoverPlacesParams, {
+  route: unknown;
+}> & {
+  sortBy: 'detourOffset';
+}): Promise<AlongRouteSearchResponse<AlongRoutePlaceProps & Required<Pick<AlongRoutePlaceProps, 'detourOffsetInMeters'>>>>;
+export declare function discoverPlaces(params: Extract<DiscoverPlacesParams, {
+  route: unknown;
+}>): Promise<AlongRouteSearchResponse>;
+export declare function discoverPlaces(params: DiscoverPlacesParams): Promise<DiscoverPlacesResponse>;
 /**
  * Searches for a single place by text query.
  *
@@ -5003,7 +5158,7 @@ export declare const discoverPlaces: (params: DiscoverPlacesParams) => Promise<D
  *
  * @param queryOrParams - The search query, or the full {@link FuzzySearchParams} without `limit`.
  * @returns The first matching place.
- * @throws {Error} If no results are found for the query
+ * @throws {SDKError} With the code `NOT_FOUND` and the service `'FuzzySearch'` if no results are found for the query
  *
  * @example
  * ```typescript
@@ -5050,7 +5205,13 @@ type PlaceSuggestion = SuggestionBase & {
   kind: 'place' | 'address' | 'street' | 'area';
   /** The place id, as {@link getPlaceDetails} takes it. */
   id: string;
-  /** Lines under the title that tell similar results apart, such as the address. */
+  /**
+   * Lines under the title that tell similar results apart, such as the address.
+   *
+   * The last one is the country, unless it's the home country: that of the place nearest
+   * `geoBias.position`, or, without `geoBias`, the country most places are in. Both are judged over
+   * the up to 10 places the search fetches, not only the suggestions returned.
+   */
   subtitles: string[];
   /** Distance from `geoBias.position`, when one was given. */
   distanceInMeters?: number;
@@ -5525,8 +5686,8 @@ type TrafficIncidentDetailsByBBoxParams = TrafficIncidentDetailsBaseParams & {
   /**
    * The bounding box to query for incidents.
    *
-   * It accepts a raw `[minLon, minLat, maxLon, maxLat]` tuple, any GeoJSON object
-   * (Feature, FeatureCollection, Geometry, …), or an array of GeoJSON objects. For a GeoJSON
+   * It accepts a {@link BBox} `[west, south, east, north]` (west > east across the antimeridian), any
+   * GeoJSON object (Feature, FeatureCollection, Geometry, …), or an array of GeoJSON objects. For a GeoJSON
    * value, its bounding box is calculated automatically with {@link bboxFromGeoJSON}.
    *
    * It covers at most 10,000 km².
@@ -5682,4 +5843,4 @@ type TrafficIncidentDetailsParams = TrafficIncidentDetailsByBBoxParams | Traffic
  */
 export declare const trafficIncidentDetails: (params: TrafficIncidentDetailsParams) => Promise<TrafficIncidentDetails>;
 //#endregion
-export type { AlongRouteSearchParams, AlongRouteSortBy, AreaAnalyticsDateInput, ArrivalSide, BookmarkIntent, BookmarkIntentDetails, BrandSuggestion, CalculateRouteParams, CategorySuggestion, Circle, CommonServiceParams, CommonServiceParamsWithZoom, ComputeTravelTimeFor, CoordinateIntent, CoordinateIntentDetails, ExtendedRouteRepresentation, FetchInput, FunctionalRoadClass, FuzzyLevel, FuzzySearchParams, GeocodingParams, GeocodingProps, GeocodingResponse, GeometriesInput, GeometryDataParams, GeometryParams, GeometryPlaceParams, GeometrySearchParams, GetObject, GuidanceParams, InputSectionType, InputSectionTypes, LegCostModel, MaxNumberOfAlternatives, NearbyIntent, NearbyIntentDetails, POICategoriesParams, POICategoriesResponse, POICategoryResult, PlaceDetailsMandatoryParams, PlaceDetailsOptionalParams, PlaceDetailsParams, PlaceDetailsResponse, PlaceGeometryProps, PlaceSuggestion, PostObject, QueryIntent, RefinementSuggestion, ResolvePOICategoriesParams, ResolvedPOICategories, ReverseGeocodingMandatoryParams, ReverseGeocodingOptionalParams, ReverseGeocodingParams, ReverseGeocodingResponse, RouteStopOptions, SearchGeometryInput, SearchSuggestion, SearchSuggestionKind, SearchSuggestionsParams, SearchSuggestionsResponse, TrafficAreaAnalyticsDateRange, TrafficAreaAnalyticsDays, TrafficAreaAnalyticsParams, TrafficIncidentDetailsByBBoxParams, TrafficIncidentDetailsByIdsParams, TrafficIncidentDetailsByPolygonParams, TrafficIncidentDetailsParams, W3WIntent, W3WIntentDetails };
+export type { AlongRoutePlaceProps, AlongRouteSearchParams, AlongRouteSortBy, AreaAnalyticsDateInput, ArrivalSide, BookmarkIntent, BookmarkIntentDetails, BrandSuggestion, CalculateRouteParams, CategorySuggestion, Circle, CommonServiceParams, CommonServiceParamsWithZoom, ComputeTravelTimeFor, CoordinateIntent, CoordinateIntentDetails, ExtendedRouteRepresentation, FetchInput, FunctionalRoadClass, FuzzyLevel, FuzzySearchParams, GeocodingParams, GeocodingProps, GeocodingResponse, GeometriesInput, GeometryDataParams, GeometryParams, GeometryPlaceParams, GeometrySearchParams, GetObject, GuidanceParams, InputSectionType, InputSectionTypes, LegCostModel, MaxNumberOfAlternatives, NearbyIntent, NearbyIntentDetails, POICategoriesParams, POICategoriesResponse, POICategoryResult, PlaceDetailsMandatoryParams, PlaceDetailsOptionalParams, PlaceDetailsParams, PlaceDetailsResponse, PlaceGeometryProps, PlaceSuggestion, PostObject, QueryIntent, RefinementSuggestion, ResolvePOICategoriesParams, ResolvedPOICategories, ReverseGeocodingMandatoryParams, ReverseGeocodingOptionalParams, ReverseGeocodingParams, ReverseGeocodingResponse, RouteStopOptions, SearchGeometryInput, SearchSuggestion, SearchSuggestionKind, SearchSuggestionsParams, SearchSuggestionsResponse, TrafficAreaAnalyticsDateRange, TrafficAreaAnalyticsDays, TrafficAreaAnalyticsParams, TrafficIncidentDetailsByBBoxParams, TrafficIncidentDetailsByIdsParams, TrafficIncidentDetailsByPolygonParams, TrafficIncidentDetailsParams, W3WIntent, W3WIntentDetails };