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

package/services/dist/index.d.ts

@@ -1,4 +1,4 @@
-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 { APIErrorDetails, AddressProperties, AreaAnalyticsMetricKey, Avoidable, BBox, ChargingPoint, ChargingStation, CommonPlaceProps, Connector, ConnectorType, CurveDetectionOptions, EntryPoint, Fuel, GeographyType, GeopoliticalView, GetPositionEntryPointOption, GlobalConfig, HasBBox, HasLngLat, MapcodeType, OpeningHours, OpeningHoursMode, POICategory, PathLike, Place, PlaceDataSources, PlaceType, Places, PolygonFeature, PolygonFeatures, PrivatePreviewAccess, ReachableRangeBudget, RevGeoAddressProps, RoadShieldReference, 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
 /**
@@ -210,9 +210,7 @@ interface FeatureCollection<G extends Geometry | null = Geometry, P = GeoJsonPro
 /**
  * @ignore
  */
-declare enum APICode {
-  TOO_MANY_REQUESTS = 429
-}
+type APICode = 429;
 //#endregion
 //#region src/shared/types/fetch.d.ts
 /**
@@ -244,23 +242,6 @@ type FetchInput<PostData = void> = ({
   method: 'POST';
 } & PostObject<PostData>);
 //#endregion
-//#region src/shared/types/privatePreviewAccess.d.ts
-/**
- * The access a Private Preview API needs on the API key, and where to request it.
- *
- * @group Errors
- */
-export type PrivatePreviewAccess = {
-  /**
-   * The API the key needs access to, as TomTom Sales names it, such as `'Calculate Reachable Range'`.
-   */
-  product: string;
-  /**
-   * Where to request that access.
-   */
-  requestAccessURL: string;
-};
-//#endregion
 //#region src/shared/types/servicesTypes.d.ts
 /**
  * The name of a service the SDK calls, as an {@link SDKError}'s `service` reports it.
@@ -294,7 +275,8 @@ type CommonServiceParams<ApiRequest = any, ApiResponse = any> = Partial<Omit<Glo
    * Whether the SDK validates the request parameters against the expected schema before sending them.
    *
    * @remarks
-   * Validation also rejects a parameter the service doesn't know, and names it. To skip validation,
+   * Validation also rejects a parameter the service doesn't know, and names it. Only top-level names
+   * are checked: an unknown key inside an object parameter, such as `filters`, goes unreported. To skip validation,
    * set it to `false`, which then drops an unknown parameter silently. The `commonBaseURL` check
    * (`INSECURE_BASE_URL`) runs either way.
    *
@@ -306,9 +288,6 @@ type CommonServiceParams<ApiRequest = any, ApiResponse = any> = Partial<Omit<Glo
    *
    * @ignore
    *
-   * @remarks
-   * Useful for tracking, logging, or debugging API requests before they are sent to the server.
-   *
    * @param apiRequest - The API request to be sent (usually a URL for GET requests or URL with body for POST requests)
    */
   onAPIRequest?: (apiRequest: ApiRequest) => void;
@@ -320,7 +299,6 @@ type CommonServiceParams<ApiRequest = any, ApiResponse = any> = Partial<Omit<Glo
    * @remarks
    * Called as soon as the API response is received, before parsing.
    * The request object is the same reference as provided to {@link onAPIRequest}.
-   * Useful for tracking, logging, or debugging API request-response pairs.
    *
    * A failed request calls it too, with the error the request threw in place of the body, such as
    * one carrying the HTTP `status`. Check the argument before reading it as a body.
@@ -359,8 +337,8 @@ type CommonServiceParams<ApiRequest = any, ApiResponse = any> = Partial<Omit<Glo
  * The SDK handles two distinct categories of errors:
  * 1. Programming errors are configuration or usage errors in your application,
  *    such as passing incorrect types to parameters or functions.
- * 2. API errors are recoverable errors that occur during SDK operations,
- *    such as network failures or invalid API responses.
+ * 2. API errors occur during SDK operations, such as network failures or invalid API responses.
+ *    `code` says which, and `canRetry` whether the same call is likely to succeed later.
  *
  * 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`.
@@ -432,7 +410,7 @@ export declare const APIErrorCode: { readonly [K in APICode as number]: string;
  *
  * @group Errors
  */
-export declare class SDKServiceError extends SDKError {
+export declare class SDKServiceError extends SDKError implements APIErrorDetails {
   /**
    * HTTP status code of the failed API request.
    *
@@ -444,17 +422,7 @@ export declare class SDKServiceError extends SDKError {
    * - `500`: Internal Server Error
    */
   readonly status?: number;
-  /**
-   * The API's own name for the error, from its `detailedError.code`, when its response carries one.
-   *
-   * On an `INSUFFICIENT_PERMISSIONS` it tells the causes apart: `'Forbidden'` when the API is not enabled for
-   * the key, `'InvalidReferer'` when the key's domain restriction refused the page.
-   */
   readonly apiErrorCode?: string;
-  /**
-   * The access the API key lacks, on an `INSUFFICIENT_PERMISSIONS` from a Private Preview API that did not
-   * name another cause. The message names it too.
-   */
   readonly privatePreviewAccess?: PrivatePreviewAccess;
   /**
    * Creates a new SDKServiceError instance.
@@ -466,10 +434,7 @@ export declare class SDKServiceError extends SDKError {
    * @param service - Name of the service that generated the error.
    * @param status - HTTP status code of the failed request.
    */
-  constructor(message: string, service: ServiceName, status?: number, options?: {
-    apiErrorCode?: string;
-    privatePreviewAccess?: PrivatePreviewAccess;
-  });
+  constructor(message: string, service: ServiceName, status?: number, options?: APIErrorDetails);
 }
 /**
  * Error class for cancelled service calls.
@@ -664,7 +629,7 @@ export type BoundingBoxGeoBias = {
  * const within2km: GeoBias = { position: [4.9, 52.3], radiusMeters: 2000 };
  *
  * // Inside the visible map area
- * const inViewport: GeoBias = { boundingBox: map.getBounds().toArray().flat() as BBox };
+ * const inViewport: GeoBias = { boundingBox: map.getBBox() };
  * ```
  *
  * @group Places Search
@@ -691,43 +656,32 @@ export type GeoBias = (PointGeoBias & {
  * - `XStr`: Cross Streets - Intersections of two streets
  * - `POI`: Points of Interest (businesses, landmarks, facilities)
  *
- * By default, `extendedPostalCodesFor` includes extended postal codes for all indexes except `Geo`.
- * Use this type to request them explicitly for specific indexes.
- *
- * @example
- * ```typescript
- * // Request extended postal codes for addresses and POIs
- * const indexes: SearchIndexType[] = ['PAD', 'Addr', 'POI'];
- * ```
- *
  * @group Places Search
  */
 export type SearchIndexType = 'Geo' | 'PAD' | 'Addr' | 'Str' | 'XStr' | 'POI';
 /**
  * The parameters the places services share.
  *
- * Search, geocoding, and reverse geocoding use them to customise query behaviour, filter results,
+ * Search and geocoding use them to customise query behaviour, filter results,
  * and control response formatting.
  *
- * @typeParam ApiRequest - The API request type (typically URL or FetchInput)
+ * @typeParam ApiRequest - The API request type (`GetObject` or `PostObject`)
  * @typeParam ApiResponse - The API response type
  *
  * @remarks
  * They apply to:
  * - {@link discoverPlaces}
  * - {@link geocode}
- * - {@link reverseGeocode}
  *
  * They cover:
  * - Result limits and pagination
- * - Geographic biasing for location-aware results
  * - Additional data inclusion (mapcodes, extended postal codes)
  * - Geopolitical view context for disputed territories
  *
  * @example
  * ```typescript
  * // Search with mapcodes and specific geopolitical view
- * const detailedSearch: CommonPlacesParams<URL, Response> = {
+ * const detailedSearch: CommonPlacesParams<GetObject, Response> = {
  *   geopoliticalView: 'IN', // India's perspective
  *   mapcodes: ['Local', 'International'],
  *   extendedPostalCodesFor: ['PAD', 'POI'],
@@ -735,7 +689,7 @@ export type SearchIndexType = 'Geo' | 'PAD' | 'Addr' | 'Str' | 'XStr' | 'POI';
  * };
  *
  * // Address search with extended postal codes
- * const addressSearch: CommonPlacesParams<URL, Response> = {
+ * const addressSearch: CommonPlacesParams<GetObject, Response> = {
  *   extendedPostalCodesFor: ['Geo', 'PAD', 'Addr'],
  *   limit: 15
  * };
@@ -775,7 +729,7 @@ export type CommonPlacesParams<ApiRequest, ApiResponse> = CommonServiceParams<Ap
    *
    * A regular postal code is "10001" (basic ZIP code), and an extended one "10001-1234" (ZIP+4 format).
    *
-   * Note that including them for geographies can significantly increase response size.
+   * Including them for geographies can significantly increase response size.
    *
    * @example
    * ```typescript
@@ -1054,10 +1008,7 @@ export type VehicleModel = {
 //#endregion
 //#region src/shared/types/vehicleRestrictionParams.d.ts
 /**
- * Whether the vehicle carries an electronic toll collection transponder.
- *
- * It determines which toll roads the routing engine may use. Some tolls can only be paid by
- * transponder, others only without one.
+ * The values {@link TollTransponder} takes.
  *
  * @group Vehicle
  */
@@ -1080,6 +1031,8 @@ export declare const tollTransponderOptions: readonly ["all", "unknown", "none"]
 export type TollTransponder = (typeof tollTransponderOptions)[number];
 /**
  * The vehicle parameters for the restrictions applied during route planning.
+ *
+ * @group Vehicle
  */
 export type VehicleRestrictions = {
   /**
@@ -1142,7 +1095,7 @@ export type VehicleState = {
    * It improves the initial route calculation by considering the vehicle's current direction of
    * travel.
    *
-   * Allowed values are 0-359.
+   * Allowed values run from 0 up to, but not including, 360.
    *
    * @example
    * ```typescript
@@ -1215,12 +1168,8 @@ export type VehicleParameters = {
 //#endregion
 //#region src/shared/types/commonRoutingParams.d.ts
 /**
- * The available route types, each naming the optimisation that route calculation uses:
- * * `fast` optimises for travel time, while keeping the routes sensible. For example, the calculation may avoid shortcuts along inconvenient side roads or long detours that only save very little time.
- * * `short` finds a good compromise between small travel time and short travel distance.
- * * `efficient` finds a good compromise between small travel time and low fuel or energy consumption.
- * * `thrilling` includes interesting or challenging roads and uses as few motorways as possible.
- * Routes planned with routeType=thrilling are limited to 900km.
+ * The available route types, each naming the optimisation that route calculation uses, as {@link RouteType}
+ * describes.
  *
  * @group Routing
  */
@@ -1242,8 +1191,7 @@ export declare const routeTypes: readonly ["fast", "short", "efficient", "thrill
  *   - May use smaller roads to save distance
  *   - Useful for short trips or when fuel costs matter
  *
- * - `efficient` minimises fuel or energy consumption.
- *   - Optimizes for least energy use
+ * - `efficient` balances travel time against fuel or energy consumption.
  *   - Avoids rapid acceleration/deceleration
  *
  * - `thrilling` plans scenic and engaging routes.
@@ -1380,14 +1328,7 @@ export type CostModel = {
    */
   traffic?: TrafficInput;
   /**
-   * The type of optimisation that route calculation uses.
-   * The values are:
-   *
-   * * `fast` optimises for travel time, while keeping the routes sensible. For example, the calculation may avoid shortcuts along inconvenient side roads or long detours that only save very little time.
-   * * `short` finds a good compromise between small travel time and short travel distance.
-   * * `efficient` finds a good compromise between small travel time and low fuel or energy consumption.
-   * * `thrilling` includes interesting or challenging roads and uses as few motorways as possible.
-   * Routes planned with routeType=thrilling are limited to 900km.
+   * The type of optimisation that route calculation uses, as {@link RouteType} describes.
    * @default fast
    */
   routeType?: RouteType;
@@ -1430,7 +1371,7 @@ export type LocalDateTime = `${number}-${number}-${number}T${number}:${number}:$
  *
  * @example
  * ```typescript
- * // Depart at 08:15 in Tokyo, wherever the code runs
+ * // Depart at 08:15 local time at the origin, wherever the code runs
  * const departParams: DepartArriveParams = {
  *   option: 'departAt',
  *   localDateTime: '2026-10-19T08:15:00'
@@ -1665,13 +1606,10 @@ export type CommonSearchParams<ApiRequest, ApiResponse> = CommonPlacesParams<Api
    * The format and detail level of the POI opening hours data that the response includes.
    *
    * @remarks
-   * Each mode gives a different level of detail about when a POI is open for business.
-   *
    * Use it to:
    * - Display "Open Now" status
    * - Show full weekly schedule
    * - Plan visits during open hours
-   * - Filter to currently open locations
    *
    * @example
    * ```typescript
@@ -1856,18 +1794,12 @@ export type SearchSummary = {
    */
   totalResults?: number;
   /**
-   * The maximum fuzzy matching level used to find results.
+   * The maximum fuzzy level used to find results, one of the levels {@link FuzzyLevel} describes.
    *
    * It shows how much the search relaxed exact matching. Higher values mean more tolerance for
    * typos and variations.
    *
    * @remarks
-   * Fuzzy levels (typically 1-4):
-   * - 1: Single character variation (typo, insertion, deletion)
-   * - 2: Two character variations
-   * - 3: Three character variations
-   * - 4: Four character variations
-   *
    * It is low when exact or near-exact matching finds the results, and increases to find matches
    * when the query has typos.
    *
@@ -1877,7 +1809,7 @@ export type SearchSummary = {
    * @example
    * ```typescript
    * // Query: "amstrdam" (typo)
-   * fuzzyLevel: 2  // Needed 2-character correction to match "amsterdam"
+   * fuzzyLevel: 2  // Needed spell checking to match "amsterdam"
    *
    * // Query: "amsterdam" (correct)
    * fuzzyLevel: 1  // Exact match, no fuzzy matching needed
@@ -2081,11 +2013,17 @@ type CommonSearchPlaceResultAPI = Omit<SearchPlaceProps, 'distance' | 'position'
   dist?: number;
   viewport?: ViewportAPI;
   boundingBox?: BoundingBoxAPI;
+  entityType?: string;
   entryPoints?: EntryPointAPI[];
-  address?: AddressProperties;
+  addressRanges?: AddressRangesAPI;
   poi?: POIAPI;
   chargingStations?: ChargingStationAPI[];
 };
+/**
+ * The fields every places result maps alike, whether a search or a geocoding one.
+ * @ignore
+ */
+type PlaceResultFieldsAPI = Pick<CommonSearchPlaceResultAPI, 'id' | 'position' | 'dist' | 'boundingBox' | 'viewport' | 'entityType' | 'entryPoints' | 'addressRanges'>;
 /**
  * A places response holding only the summary and the results, as geometry search, along-route search and place
  * details answer.
@@ -2214,7 +2152,7 @@ type AlongRouteSearchParams = CommonSearchParams<AlongRouteSearchRequestAPI, Alo
    * route: [[4.9, 52.37], [4.95, 52.28], [5.1, 52.09]]
    * ```
    */
-  route: LineString | Route | Position[];
+  route: LineString | PathLike;
   /**
    * Maximum allowed detour time in seconds, a positive integer up to `3600` (one hour);
    * request validation rejects a larger one.
@@ -2242,6 +2180,15 @@ type AlongRouteSearchParams = CommonSearchParams<AlongRouteSearchRequestAPI, Alo
 };
 //#endregion
 //#region src/fuzzy-search/types/fuzzySearchResponse.d.ts
+/**
+ * Response from the fuzzy search service.
+ *
+ * The places matching the search query, with metadata about the detected query intents
+ * (coordinates, nearby searches, what3words or bookmarks).
+ *
+ * @group Fuzzy Search
+ */
+type FuzzySearchResponse = Places<SearchPlaceProps, FuzzySearchFeatureCollectionProps>;
 /**
  * Additional properties for fuzzy search feature collection.
  *
@@ -2556,7 +2503,7 @@ type FuzzySearchParams = CommonSearchParams<GetObject, FuzzySearchResponseAPI> &
   /**
    * Maximum fuzziness level to use.
    *
-   * It sets the last spell-checking level the search tries, of those `minFuzzyLevel` lists.
+   * It sets the last spell-checking level the search tries, of those {@link FuzzyLevel} lists.
    * Higher values allow more variations but may include irrelevant results.
    *
    * @remarks
@@ -2626,16 +2573,7 @@ type GeocodingResponse = Places<GeocodingProps, SearchSummary>;
 /**
  * @ignore
  */
-type GeocodingResultAPI = Omit<GeocodingProps, 'distance' | 'position' | 'boundingBox' | 'addressRanges' | 'geographyType' | 'entryPoints'> & {
-  id: string;
-  position: LatLonAPI;
-  dist?: number;
-  boundingBox?: BoundingBoxAPI;
-  viewport?: ViewportAPI;
-  entityType?: string;
-  entryPoints?: EntryPointAPI[];
-  addressRanges?: AddressRangesAPI;
-};
+type GeocodingResultAPI = Omit<GeocodingProps, 'distance' | 'position' | 'boundingBox' | 'addressRanges' | 'geographyType' | 'entryPoints'> & PlaceResultFieldsAPI;
 /**
  * @ignore
  */
@@ -2659,12 +2597,7 @@ type GeocodingIndexTypesAbbreviation = Exclude<SearchIndexType, 'POI'>;
  * can place markers on maps or perform spatial operations.
  *
  * @remarks
- * This service is optimized for address lookups and does not return POIs.
- * For POI search, use {@link discoverPlaces} instead.
- *
- * It tolerates typos and incomplete addresses, handles various address formats and supports
- * street addresses, intersections and cross streets. It works with geographies (cities,
- * counties, states, countries) and returns structured address components.
+ * What geocoding finds, and what it tolerates, is on {@link geocode}.
  *
  * @example
  * ```typescript
@@ -2770,21 +2703,18 @@ type GeocodingParams = Omit<CommonPlacesParams<GetObject, GeocodingResponseAPI>
  * higher-level geographies (cities, counties, states, countries) and returns structured address
  * components.
  *
- * @param params - The geocoding parameters, including the address query.
+ * @param queryOrParams - The address or place name to geocode, the same as `{ query }`, or the full
+ * {@link GeocodingParams}. Pass the params form to set any other option, `signal` included.
  *
  * @returns The geocoded locations.
  *
  * @example
  * ```typescript
  * // Geocode a complete address
- * const result = await geocode({
- *   query: '1600 Pennsylvania Avenue NW, Washington, DC'
- * });
+ * const result = await geocode('1600 Pennsylvania Avenue NW, Washington, DC');
  *
- * // Geocode with partial address
- * const partialResult = await geocode({
- *   query: 'Amsterdam, Netherlands'
- * });
+ * // Geocode a partial address, cancellable through an AbortSignal
+ * const partialResult = await geocode({ query: 'Amsterdam, Netherlands', signal });
  *
  * // Geocode with bias towards specific location
  * const biasedResult = await geocode({
@@ -2805,13 +2735,14 @@ type GeocodingParams = Omit<CommonPlacesParams<GetObject, GeocodingResponseAPI>
  *
  * @group Geocoding
  */
-export declare const geocode: (params: GeocodingParams) => Promise<GeocodingResponse>;
+export declare const geocode: (queryOrParams: string | GeocodingParams) => Promise<GeocodingResponse>;
 /**
  * Geocodes a query and returns the single best-matching place.
  *
  * It wraps {@link geocode} and returns the top result directly.
  *
  * @param queryOrParams - The address or place name to geocode, or the full {@link GeocodingParams} without `limit`.
+ * Pass the params form to set any other option, `signal` included.
  * @returns The best-matching place.
  * @throws {SDKError} With the code `NOT_FOUND` and the service `'Geocode'` if no results are found for the query
  *
@@ -2862,7 +2793,7 @@ type GeometryDataResponseAPI = {
  * const ids: GeometriesInput = ['g1234567890', 'g0987654321'];
  * ```
  *
- * @group Geometry
+ * @group Geometry Data
  */
 type GeometriesInput = string[];
 /**
@@ -2870,7 +2801,7 @@ type GeometriesInput = string[];
  *
  * Extended by {@link GeometryDataParams} and {@link GeometryPlaceParams}.
  *
- * @group Geometry
+ * @group Geometry Data
  */
 type CommonServiceParamsWithZoom = CommonServiceParams<GetObject, GeometryDataResponseAPI> & {
   /**
@@ -2913,7 +2844,7 @@ type CommonServiceParamsWithZoom = CommonServiceParams<GetObject, GeometryDataRe
  * };
  * ```
  *
- * @group Geometry
+ * @group Geometry Data
  */
 type GeometryDataParams = CommonServiceParamsWithZoom & {
   /**
@@ -2960,7 +2891,7 @@ type GeometryDataParams = CommonServiceParamsWithZoom & {
  * };
  * ```
  *
- * @group Geometry
+ * @group Geometry Data
  */
 type GeometryPlaceParams = CommonServiceParamsWithZoom & {
   /**
@@ -3005,7 +2936,7 @@ type GeometryPlaceParams = CommonServiceParamsWithZoom & {
  * };
  * ```
  *
- * @group Geometry
+ * @group Geometry Data
  */
 type GeometryParams = GeometryDataParams | GeometryPlaceParams;
 //#endregion
@@ -3017,7 +2948,7 @@ type GeometryParams = GeometryDataParams | GeometryPlaceParams;
  *
  * @typeParam P - The properties of the places passed in.
  *
- * @group Geometry
+ * @group Geometry Data
  */
 type PlaceGeometryProps<P extends CommonPlaceProps = CommonPlaceProps> = P & {
   /**
@@ -3039,21 +2970,17 @@ type PlaceGeometryProps<P extends CommonPlaceProps = CommonPlaceProps> = P & {
  * You can fetch up to 20 geometries in a single call, at scales from countries down to building
  * footprints, as standard GeoJSON Polygon/MultiPolygon features.
  *
- * Use it to display city or country boundaries on maps, show POI building footprints, create
- * geofences for spatial queries, visualise administrative divisions, or calculate areas and
- * spatial relationships.
- *
  * It returns polygons, not places, so pass the result to `GeometriesModule.show()`, not
  * `PlacesModule.show()`. The `geometryId` comes from a prior search result.
  *
  * A `Places` collection gets each polygon its place's properties, as {@link PlaceGeometryProps}.
+ * Places that share a footprint give it the properties of the first of them, the best ranked.
  * A polygon the service returns for no place of the collection has `null` properties. A `Place[]`
- * or geometry IDs return the polygons with the service's own properties.
+ * or geometry IDs return the polygons with the service's own properties. A geometry the service
+ * can't return, such as one with an unknown ID, is left out of the result.
  *
  * @param params - The geometry IDs or places to fetch boundaries for.
  *
- * @returns Polygon features of the area boundaries.
- *
  * @example
  * ```typescript
  * // Fetch geometry by ID
@@ -3079,7 +3006,7 @@ type PlaceGeometryProps<P extends CommonPlaceProps = CommonPlaceProps> = P & {
  * @see [Places Quickstart Guide](https://docs.tomtom.com/maps-sdk-js/guides/services/places/quickstart)
  * @see [Geometry Data Guide](https://docs.tomtom.com/maps-sdk-js/guides/services/places/geometry-data)
  *
- * @group Geometry
+ * @group Geometry Data
  */
 export declare function geometryData<P extends CommonPlaceProps>(params: GeometryPlaceParams & {
   geometries: Places<P>;
@@ -3134,9 +3061,7 @@ type GeometrySearchResponseAPI = SearchResultsResponseAPI;
  * such as "restaurants in this neighborhood" or "hotels within these city boundaries".
  *
  * @remarks
- * Pass these to {@link discoverPlaces}, which picks the request variant from the params you give it.
- * A `route` property selects along-route search, a `geometries` property selects geometry search,
- * and neither selects fuzzy search.
+ * Pass these to {@link discoverPlaces}, which runs a geometry search when given `geometries`.
  *
  * Geometry search searches within multiple geometries at once and supports polygons, multipolygons
  * and circles. It can use geometries from previous search results, and combines with text queries
@@ -3194,7 +3119,7 @@ type GeometrySearchParams = CommonSearchParams<GeometrySearchRequestAPI, Geometr
    * - `PolygonFeatures` - Feature collection with polygon geometries
    *
    * Only a polygon's outer ring is sent, so holes are ignored. The ring is sampled down to 50 vertices,
-   * and a `MultiPolygon` of more than 50 polygons keeps its 50 largest.
+   * and a `MultiPolygon` of more than 50 polygons keeps the 50 with the largest bounding boxes.
    *
    * @example
    * ```typescript
@@ -3291,7 +3216,6 @@ type SearchGeometryInput = Polygon | MultiPolygon | Circle | PolygonFeatures;
 //#endregion
 //#region src/place-details/types/placeDetailsResponseAPI.d.ts
 /**
- * Its results are sorted in descending order by score.
  * @ignore
  */
 type PlaceDetailsResponseAPI = SearchResultsResponseAPI;
@@ -3399,11 +3323,12 @@ type PlaceDetailsResponse = Place<SearchPlaceProps> | undefined;
  *
  * const placeDetails = await getPlaceDetails({
  *   entityId: place.id,
- *   openingHours: 'nextSevenDays'
+ *   openingHours: 'nextSevenDays',
+ *   relatedPois: 'parent'
  * });
  *
  * // Navigate to related POI
- * const relatedPOI = place.properties.relatedPois?.[0];
+ * const relatedPOI = placeDetails?.properties.relatedPois?.[0];
  * if (relatedPOI) {
  *   const parentPlace = await getPlaceDetails({
  *     entityId: relatedPOI.id
@@ -3714,17 +3639,18 @@ export type ReachableRangeOwnParams = {
    * Location where the range calculation starts.
    *
    * @remarks
-   * It is the center point from which reachability is calculated, either:
-   * - An object with `lon` and `lat` properties
-   * - An array `[longitude, latitude]`
+   * It is the center point from which reachability is calculated, as any {@link HasLngLat}:
+   * - A `[longitude, latitude]` position
+   * - A GeoJSON `Point`
+   * - A GeoJSON `Feature` with a `Point` geometry, such as a place from a search
    *
    * @example
    * ```typescript
-   * // Object format
-   * origin: { lon: 4.9, lat: 52.3 }
-   *
-   * // Array format
+   * // Position
    * origin: [4.9, 52.3]
+   *
+   * // A place from a search
+   * origin: await geocodeOne('Amsterdam Centraal')
    * ```
    */
   origin: HasLngLat;
@@ -3767,11 +3693,8 @@ export type ReachableRangeOwnParams = {
    * 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
-   * defaults to departing now.
-   *
-   * Future departure times use predictive traffic, the current time uses live
-   * traffic, and historic times use historical patterns.
+   * Future departure times use predictive traffic, and the current time live traffic. A past date
+   * departs now, as {@link DepartArriveParams} explains.
    *
    * @default Depart now
    *
@@ -3901,10 +3824,6 @@ export declare const calculateReachableRange: (params: ReachableRangeParams) =>
  * @remarks
  * **[Private Preview](https://docs.tomtom.com/legal/private-preview)**. It needs the same API key access as {@link calculateReachableRange}.
  *
- * Use it to compare the service areas of different store locations, create 15/30/45 minute drive
- * time rings from one origin, compare ranges for different vehicle types or times of day, or find
- * optimal facility locations with minimal overlap.
- *
  * Note that ranges are calculated sequentially to avoid rate limiting. For large batches,
  * consider implementing your own parallel processing with appropriate throttling.
  *
@@ -3947,6 +3866,19 @@ export declare const calculateReachableRanges: (paramsArray: ReachableRangeParam
   signal?: AbortSignal;
 }) => Promise<PolygonFeatures<ReachableRangeProperties>>;
 //#endregion
+//#region src/revgeo/requestBuilder.d.ts
+declare const AREA_TYPE_BY_GEOGRAPHY_TYPE: {
+  readonly Country: "country";
+  readonly CountrySubdivision: "countrySubdivision";
+  readonly CountrySecondarySubdivision: "countrySecondarySubdivision";
+  readonly CountryTertiarySubdivision: "countryTertiarySubdivision";
+  readonly Municipality: "municipality";
+  readonly MunicipalitySubdivision: "municipalitySubdivision";
+  readonly MunicipalitySecondarySubdivision: "municipalitySecondarySubdivision";
+  readonly Neighbourhood: "neighborhood";
+  readonly PostalCodeArea: "postalCode";
+};
+//#endregion
 //#region src/revgeo/types/apiTypes.d.ts
 /** Orbis Reverse Geocoding v2 top-level result type.
  * (geocode v2 also has `'intersection'`; reverse geocoding does not.)
@@ -3956,7 +3888,7 @@ type ReverseGeocodingResultTypeAPI = 'address' | 'street' | 'area';
 /** Orbis Reverse Geocoding v2 area sub-type.
  * @ignore
  */
-type ReverseGeocodingAreaTypeAPI = 'country' | 'countrySubdivision' | 'countrySecondarySubdivision' | 'countryTertiarySubdivision' | 'municipality' | 'municipalitySubdivision' | 'municipalitySecondarySubdivision' | 'neighborhood' | 'postalCode';
+type ReverseGeocodingAreaTypeAPI = (typeof AREA_TYPE_BY_GEOGRAPHY_TYPE)[GeographyType];
 /**
  * Address object as returned by the Orbis Reverse Geocoding v2 API.
  * @ignore
@@ -4018,8 +3950,7 @@ type ReverseGeocodingMandatoryParams = {
  * Optional parameters for customizing reverse geocoding requests.
  *
  * @remarks
- * They fine-tune the reverse geocoding behaviour, including filtering,
- * formatting and additional data retrieval.
+ * They set the geography types to return, the heading, the search radius and the geopolitical view.
  *
  * @group Reverse Geocoding
  */
@@ -4047,7 +3978,7 @@ type ReverseGeocodingOptionalParams = {
    *
    * @example
    * ```ts
-   * heading: 90.5  // Traveling east-northeast
+   * heading: 67.5  // Traveling east-northeast
    * ```
    *
    * @minimum -360
@@ -4206,7 +4137,6 @@ type LegRequestAPI = {
  */
 type CalculateRoutePOSTDataAPI = CommonRoutingBodyAPI & CommonVehicleBodyAPI & {
   routePlanningLocations: RoutePlanningLocationsAPI;
-  path?: LineString;
   legs?: LegRequestAPI[];
   maxPathAlternativeRoutes?: number;
   arrivalDateTime?: string;
@@ -4520,28 +4450,7 @@ type InputSectionType = (typeof inputSectionTypesWithGuidance)[number];
  * display additional context like toll roads, ferry crossings or traffic incidents.
  *
  * @remarks
- * Available section types:
- * - `carTrain`: Sections requiring car train transport
- * - `ferry`: Water crossings requiring ferry
- * - `tunnel`: Underground tunnel sections
- * - `motorway`: Highway/freeway sections
- * - `pedestrian`: Pedestrian-only sections
- * - `toll`: Sections requiring toll payment
- * - `tollRoad`: Toll roads
- * - `tollVignette`: Sections requiring toll vignette
- * - `country`: Different countries traversed
- * - `traffic`: Sections with traffic incidents
- * - `vehicleRestricted`: Sections with vehicle restrictions
- * - `carpool`: HOV/carpool lane sections
- * - `urban`: Urban area sections
- * - `unpaved`: Unpaved road sections
- * - `lowEmissionZone`: Low emission zones
- * - `speedLimit`: Speed limit changes
- * - `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
+ * {@link SectionsProps} describes each section type.
  *
  * 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
@@ -4851,15 +4760,12 @@ type CalculateRouteParams = CommonServiceParams<CalculateRouteRequestAPI, Calcul
    */
   guidance?: GuidanceParams;
   /**
-   * Route section types to include in the response.
+   * Route section types to include in the response, as {@link InputSectionTypes} describes.
    *
    * Sections help you display route characteristics like tolls, ferries, or traffic.
    * Leg sections are always included regardless of this parameter, and so are distinct sections
-   * 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`. The SDK finds `curve` and `curvyStretch` in the route's geometry, with
-   * the thresholds of `curveDetection`, and only when the list names them.
+   * when two or more routes come back. 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, core's `defaultSectionTypes`: every type but `curve` and `curvyStretch`.
    *
@@ -4898,7 +4804,6 @@ type CalculateRouteParams = CommonServiceParams<CalculateRouteRequestAPI, Calcul
    * Maximum number of alternative routes to calculate.
    *
    * Alternative routes provide different travel options between the same origin and destination.
-   * Each alternative is optimized differently (e.g., avoiding highways, minimizing tolls).
    *
    * @remarks
    * More alternatives increase response time. Alternatives are returned in order of
@@ -5090,7 +4995,7 @@ export type DiscoverPlacesParams = {
  *
  * @group Places Search
  */
-export type DiscoverPlacesResponse = Places<SearchPlaceProps, FuzzySearchFeatureCollectionProps>;
+export type DiscoverPlacesResponse = FuzzySearchResponse;
 /**
  * Finds places by text query, within geometries or along a route, from one universal function.
  *
@@ -5102,12 +5007,17 @@ export type DiscoverPlacesResponse = Places<SearchPlaceProps, FuzzySearchFeature
  * 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}.
+ * @param queryOrParams - A query string, which runs a fuzzy search the same as `{ query }`, or the
+ * {@link FuzzySearchParams}, {@link GeometrySearchParams} or {@link AlongRouteSearchParams}.
+ * Pass the params form to set any other option, `signal` included.
  *
  * @returns The matching places.
  *
  * @example
  * ```typescript
+ * // Free-text search
+ * const cafes = await discoverPlaces('coffee shop Amsterdam');
+ *
  * // Free-text search near a location
  * const results = await discoverPlaces({
  *   query: 'pizza restaurant',
@@ -5141,22 +5051,23 @@ export type DiscoverPlacesResponse = Places<SearchPlaceProps, FuzzySearchFeature
  *
  * @group Places Search
  */
-export declare function discoverPlaces(params: Extract<DiscoverPlacesParams, {
+export declare function discoverPlaces(queryOrParams: Extract<DiscoverPlacesParams, {
   route: unknown;
 }> & {
   sortBy: 'detourOffset';
 }): Promise<AlongRouteSearchResponse<AlongRoutePlaceProps & Required<Pick<AlongRoutePlaceProps, 'detourOffsetInMeters'>>>>;
-export declare function discoverPlaces(params: Extract<DiscoverPlacesParams, {
+export declare function discoverPlaces(queryOrParams: Extract<DiscoverPlacesParams, {
   route: unknown;
 }>): Promise<AlongRouteSearchResponse>;
-export declare function discoverPlaces(params: DiscoverPlacesParams): Promise<DiscoverPlacesResponse>;
+export declare function discoverPlaces(queryOrParams: string | DiscoverPlacesParams): Promise<DiscoverPlacesResponse>;
 /**
  * Searches for a single place by text query.
  *
- * It calls {@link discoverPlaces} and returns the first result. It throws an error if no
- * results are found.
+ * It runs the fuzzy search {@link discoverPlaces} runs for params without `route` or `geometries`, and returns
+ * the first result. It throws an error if no results are found.
  *
  * @param queryOrParams - The search query, or the full {@link FuzzySearchParams} without `limit`.
+ * Pass the params form to set any other option, `signal` included.
  * @returns The first matching place.
  * @throws {SDKError} With the code `NOT_FOUND` and the service `'FuzzySearch'` if no results are found for the query
  *
@@ -5293,8 +5204,8 @@ type SearchSuggestionsParams = CommonServiceParams & {
   /**
    * Maximum results in the list.
    *
-   * @defaultValue 5
-   * @remarks Capped at 10.
+   * @default 5
+   * @remarks At least 1 and at most 10: a value outside that range is raised or capped to it.
    */
   limit?: number;
   /** What the result set is restricted to. */
@@ -5303,9 +5214,17 @@ type SearchSuggestionsParams = CommonServiceParams & {
     kinds?: SearchSuggestionKind[];
     /** Countries to restrict to, as ISO 3166-1 alpha-2 or alpha-3 codes. */
     countries?: NonNullable<GeographicFilters['countries']>;
-    /** Geography types to restrict `area` results to. */
+    /**
+     * Geography types to restrict `area` results to.
+     *
+     * @remarks Setting it leaves only areas among the search results: no `place`, `address` or `street`.
+     */
     areaTypes?: NonNullable<PlaceFilters['geographyTypes']>;
-    /** POI categories to restrict `place` results to. A parent code also matches its sub-categories. */
+    /**
+     * POI categories to restrict `place` results to. A parent code also matches its sub-categories.
+     *
+     * @remarks Setting it leaves only places among the search results: no `address`, `street` or `area`.
+     */
     poiTypes?: NonNullable<PlaceFilters['poiCategories']>;
     /** Restricts results to a box. How it combines with `geoBias` is on {@link getSearchSuggestions}. */
     boundingBox?: HasBBox;
@@ -5315,7 +5234,8 @@ type SearchSuggestionsParams = CommonServiceParams & {
    *
    * @remarks
    * `position` ranks nearer results higher without excluding anything, and is what `distanceInMeters`
-   * is measured from. It is only a point. `filters.boundingBox` restricts the results.
+   * is measured from. It is only a point. `filters.boundingBox` restricts the results, and with a box
+   * set the position ranks no places, it only measures them.
    */
   geoBias?: Pick<PointGeoBias, 'position'>;
 };
@@ -5465,6 +5385,7 @@ type TrafficAreaAnalyticsDays = {
  * ```typescript
  * // Continuous range
  * const result = await trafficAreaAnalytics({
+ *   apiKey: 'YOUR_MOVE_PORTAL_KEY', // this service only
  *   startDate: '2024-08-01',
  *   endDate: '2024-08-07',
  *   functionalRoadClasses: ['MOTORWAY', 'MAJOR_ROAD', 'OTHER_MAJOR_ROAD', 'SECONDARY_ROAD', 'LOCAL_CONNECTING_ROAD', 'LOCAL_ROAD_HIGH_IMPORTANCE'],
@@ -5481,6 +5402,7 @@ type TrafficAreaAnalyticsDays = {
  * ```typescript
  * // Specific dates
  * const result = await trafficAreaAnalytics({
+ *   apiKey: 'YOUR_MOVE_PORTAL_KEY', // this service only
  *   days: ['2024-08-05', '2024-08-12', '2024-08-19', '2024-08-26'],
  *   functionalRoadClasses: ['MOTORWAY', 'MAJOR_ROAD', 'OTHER_MAJOR_ROAD'],
  *   hours: [8, 9, 17, 18],
@@ -5574,12 +5496,11 @@ type TrafficAreaAnalyticsBaseParams = {
  * - `travelTime`: average travel time per 10 km (minutes)
  * - `networkLength`: total length of road segments with data (meters)
  *
- * @returns Promise resolving to a {@link TrafficAreaAnalytics} FeatureCollection
- *
  * @example
  * ```typescript
  * // Basic speed and congestion analysis for Amsterdam
  * const result = await trafficAreaAnalytics({
+ *   apiKey: 'YOUR_MOVE_PORTAL_KEY', // this service only
  *   days: ['2024-08-06'],
  *   functionalRoadClasses: ['MOTORWAY', 'MAJOR_ROAD', 'OTHER_MAJOR_ROAD', 'SECONDARY_ROAD', 'LOCAL_CONNECTING_ROAD', 'LOCAL_ROAD_HIGH_IMPORTANCE'],
  *   hours: [7, 8, 9, 17, 18],
@@ -5602,6 +5523,7 @@ type TrafficAreaAnalyticsBaseParams = {
  * ```typescript
  * // Full metrics over a multi-day period
  * const result = await trafficAreaAnalytics({
+ *   apiKey: 'YOUR_MOVE_PORTAL_KEY', // this service only
  *   startDate: new Date('2024-08-01'),
  *   endDate: new Date('2024-08-07'),
  *   functionalRoadClasses: 'all',
@@ -5791,10 +5713,6 @@ 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, polygon or ids)
- *
- * @returns Promise resolving to a {@link TrafficIncidentDetails} object containing the matching incidents
- *
  * @example
  * ```typescript
  * // Query by bounding box (Amsterdam area)