@tomtom-org/maps-sdk 0.53.0 → 0.55.1

package/core/dist/index.d.ts

@@ -1352,6 +1352,9 @@ export type AddressRanges = {
  * - `main`: Primary entrance (at most one per place)
  * - `minor`: Secondary or alternative entrance (can have multiple)
  *
+ * Absent when the service does not classify its entry points, which is the case for
+ * reverse geocoding.
+ *
  * @group Place
  */
 export type EntryPointType = 'main' | 'minor';
@@ -1384,9 +1387,9 @@ export type EntryPoint = {
    */
   position: Position;
   /**
-   * Type of entry point (main or minor).
+   * Type of entry point (main or minor), when the service classifies it.
    */
-  type: EntryPointType;
+  type?: EntryPointType;
 };
 /**
  * @group Place
@@ -1573,7 +1576,8 @@ export type CommonPlaceProps = {
   /**
    * Physical entry points (entrances) to the place.
    *
-   * Useful for navigation to direct users to the correct entrance.
+   * Useful for navigation to direct users to the correct entrance. Reverse geocoding
+   * returns them unclassified, so their `type` is absent.
    */
   entryPoints?: EntryPoint[];
   /**
@@ -1615,10 +1619,6 @@ export type CommonPlaceProps = {
  * @group Place
  */
 export type RevGeoAddressProps = CommonPlaceProps & {
-  /**
-   * Physical access points (e.g. driveway entrances) for the address, when available.
-   */
-  accessPoints?: Position[];
   /**
    * Original coordinates used in the reverse geocoding query [longitude, latitude].
    */
@@ -2554,6 +2554,20 @@ type Maneuver = 'DEPART' | 'WAYPOINT_LEFT' | 'WAYPOINT_RIGHT' | 'WAYPOINT_REACHE
  * @group Route
  */
 type SideRoadSide = 'LEFT' | 'RIGHT' | 'LEFT_AND_RIGHT';
+/**
+ * A direction relative to the vehicle's approach, used by {@link ManeuverView} to describe the
+ * junction geometry at a maneuver.
+ *
+ * These are relative directions, not angles in degrees — the API reports the road layout as a
+ * small vocabulary of bearings.
+ * @group Route
+ */
+type ManeuverAngle = 'STRAIGHT' | 'SLIGHT_RIGHT' | 'RIGHT' | 'SHARP_RIGHT' | 'SLIGHT_LEFT' | 'LEFT' | 'SHARP_LEFT' | 'BACK';
+/**
+ * The kind of roundabout a roundabout maneuver takes place on.
+ * @group Route
+ */
+type RoundaboutType = 'REGULAR' | 'SMALL';
 /**
  * Available toll payment options.
  * @group Route
@@ -2564,6 +2578,9 @@ type TollPaymentType = 'CASH_COINS_AND_BILLS' | 'CASH_BILLS_ONLY' | 'CASH_COINS_
  * @group Route
  */
 type RoutePathPoint = {
+  /**
+   * The position of this point on the route.
+   */
   point: Position;
   /**
    * Distance (in meters) from the start of the route to this point.
@@ -2655,6 +2672,10 @@ type RoadInformation = {
    * The list can be empty if no road shields are available.
    */
   roadShields?: RoadShield[];
+  /**
+   * The code (ISO 3166-1 alpha-3) of the country this road is in.
+   */
+  countryCode?: string;
 };
 /**
  * Signpost information.
@@ -2690,6 +2711,39 @@ type SideRoad = {
    * The offset is absolute, i.e., it is a positive integer despite that the side road is located before the maneuver on the route.
    */
   offsetFromManeuverInMeters: number;
+  /**
+   * Whether the side road can actually be driven into.
+   *
+   * A non-drivable side road still matters for a junction diagram — the driver can see it — but
+   * cannot be taken by mistake.
+   */
+  isDrivable?: boolean;
+};
+/**
+ * The layout of the junction at a maneuver: which way the route goes, and which other ways lead
+ * off it.
+ *
+ * Useful for drawing a junction diagram — the route's own direction plus the roads it passes up.
+ *
+ * @example
+ * ```typescript
+ * // A right turn at a T-junction where the other arm continues straight
+ * const view: ManeuverView = { onRouteAngle: 'RIGHT', offRouteAngles: ['STRAIGHT'] };
+ * ```
+ *
+ * @group Route
+ */
+type ManeuverView = {
+  /**
+   * The direction the route takes through the junction.
+   */
+  onRouteAngle?: ManeuverAngle;
+  /**
+   * The directions of the other roads at the junction, which the route does not take.
+   *
+   * Empty when the junction has no other arms.
+   */
+  offRouteAngles: ManeuverAngle[];
 };
 /**
  * A set of attributes describing a maneuver, e.g., "Turn right", "Keep left", "Take the ferry", "Take the motorway", "Arrive".
@@ -2713,6 +2767,13 @@ type Instruction = {
    * A code identifying the maneuver (e.g., "Turn right").
    */
   maneuver: Maneuver;
+  /**
+   * The ready-made, human-readable instruction text, e.g. "Turn right onto Damrak".
+   *
+   * Generated and localised by the routing service using the request's language, so it needs no
+   * translation table of your own. Present on every instruction when guidance was requested.
+   */
+  message?: string;
   /**
    * A maneuver can occupy more than one point. For such a maneuver, this field will contain a sequence of all the points it occupies on the map.
    * For maneuvers that only occupy a single point, this field will contain a single array item, with a point value equal to maneuverPoint.
@@ -2836,6 +2897,16 @@ type Instruction = {
    * ROUNDABOUT_BACK
    */
   roundaboutExitNumber?: number;
+  /**
+   * The kind of roundabout this maneuver takes place on.
+   * Included on roundabout maneuvers.
+   */
+  roundaboutType?: RoundaboutType;
+  /**
+   * The layout of the junction at this maneuver — the route's own direction plus the directions
+   * of the roads it does not take.
+   */
+  maneuverView?: ManeuverView;
   /**
    * The name of the tollgate, if available.
    * Included if the maneuver is a tollgate maneuver, i.e., maneuver is TOLLGATE.
@@ -4064,6 +4135,13 @@ export type TrafficSectionProps = SectionProps & {
    * Extra time compared to free-flow conditions. Present when delay can be calculated.
    */
   delayInSeconds?: number;
+  /**
+   * The identifier of the traffic incident behind this section.
+   *
+   * This is the join key back to the full incident: pass it to the traffic incident details
+   * service to get the whole record, rather than re-deriving it from the section's geometry.
+   */
+  eventId?: string;
 };
 /**
  * Route section representing a leg between waypoints.
@@ -4108,6 +4186,25 @@ export type LegSectionProps = Omit<SectionProps, 'startPointIndex' | 'endPointIn
    * Only present if the route polyline geometry is available.
    */
   endPointIndex?: number;
+  /**
+   * Index, in the `locations` the route was requested with, of the waypoint this leg ends at.
+   *
+   * @remarks
+   * A leg does not always end at the location with the same index: on an EV route the service
+   * inserts charging stops of its own, so `legs[i]` is not reliably the leg arriving at
+   * `locations[i + 1]`. This is the index that maps a leg back to the stop the caller passed.
+   *
+   * Absent on the final leg, and on legs that end somewhere the caller did not ask for — an
+   * inserted charging stop, for instance.
+   *
+   * @example
+   * ```typescript
+   * // Which of the stops I passed does this leg arrive at?
+   * const index = leg.originalWaypointIndex;
+   * const stop = index === undefined ? undefined : locations[index];
+   * ```
+   */
+  originalWaypointIndex?: number;
   /**
    * Summary statistics for this leg.
    *
@@ -4210,28 +4307,73 @@ export type RoadShieldSectionProps = SectionProps & {
  * @group Route
  */
 export type SectionsProps = {
+  /** Stretches reserved for carpool (high-occupancy) vehicles. */
   carpool?: SectionProps[];
+  /** Stretches travelled on a car train, where the vehicle is carried by rail. */
   carTrain?: SectionProps[];
+  /** One section per country the route passes through, each naming that country. */
   country?: CountrySectionProps[];
+  /** Stretches travelled by ferry. */
   ferry?: SectionProps[];
+  /** Stretches whose street name or road numbers identify the course of the route. */
   importantRoadStretch?: ImportantRoadStretchProps[];
   /** Lane configuration sections. Guidance-only: present solely when `guidance` was requested. */
   lanes?: LaneSectionProps[];
+  /** One section per leg of the route. Always present: every route has at least one leg. */
   leg: LegSectionProps[];
+  /** Stretches inside a low-emission zone, which a vehicle may need to qualify to enter. */
   lowEmissionZone?: SectionProps[];
+  /** Stretches on a motorway. */
   motorway?: SectionProps[];
+  /** Stretches travelled on foot. */
   pedestrian?: SectionProps[];
+  /** Stretches carrying road shields, for rendering route numbers along the route. */
   roadShields?: RoadShieldSectionProps[];
+  /** Stretches with a known maximum speed limit. */
   speedLimit?: SpeedLimitSectionProps[];
+  /**
+   * Stretches where a per-use road toll is charged — a ticket or barrier motorway, or a
+   * free-flow tolling point.
+   *
+   * @remarks
+   * A subset of {@link SectionsProps.tollRoad | `tollRoad`}: every stretch reported here is also
+   * reported there. Use `toll` for "will this route cost a toll to drive", and `tollRoad` for
+   * "does this route cost anything at all to drive" — the latter also covers vignette-only
+   * motorways and urban charge zones, which carry no per-use toll.
+   *
+   * Requested with `sectionTypes: ['toll']`.
+   */
   toll?: SectionProps[];
+  /**
+   * Stretches that cost money to drive, by any charging scheme: per-use tolls, motorways that
+   * need a vignette, and urban road-charge zones.
+   *
+   * @remarks
+   * A superset of {@link SectionsProps.toll | `toll`}. On a ticket motorway the two report the
+   * same stretches; a vignette-only motorway or a city charge zone appears here and not in
+   * `toll`.
+   *
+   * Included by default: leaving `sectionTypes` unset requests it, and a `sectionTypes` list has
+   * to name `'tollRoad'` to keep it.
+   */
+  tollRoad?: SectionProps[];
+  /**
+   * Stretches needing a vignette, one section per country requiring one.
+   */
   tollVignette?: CountrySectionProps[];
+  /** Stretches affected by a traffic incident, with its delay and cause. */
   traffic?: TrafficSectionProps[];
+  /** Stretches inside a tunnel. */
   tunnel?: SectionProps[];
+  /** Stretches on an unpaved road. */
   unpaved?: SectionProps[];
+  /** Stretches on urban roads. */
   urban?: SectionProps[];
+  /** Stretches the requested vehicle is not permitted to use. */
   vehicleRestricted?: SectionProps[];
 };
 /**
+ * The name of one route section type — a key of {@link SectionsProps}.
  * @group Route
  */
 export type SectionType = keyof SectionsProps;
@@ -5727,4 +5869,4 @@ export declare const mergeFromGlobal: <T extends Partial<GlobalConfig>>(givenCon
  */
 export declare const isProxyCredentialsMode: (config?: Partial<Pick<GlobalConfig, "apiKey" | "commonBaseURL">>) => boolean;
 //#endregion
-export type { Anything, BBox, ChargingAvailabilityDataSource, ChargingPark, ChargingParkWithAvailability, ChargingPointAvailability, ChargingStationsAvailability, CombustionSummary, ConnectorAvailability, ConnectorCount, DrivingSide, EVChargingStationWithAvailabilityPlaceProps, ElectricSummary, FeatureCollectionWithProperties, Fuel, GeometryDataSource, GetPositionEntryPointOption, GetPositionOptions, Guidance, HasBBox, HasConnector, HasCount, HasLngLat, Instruction, Landmark, Language, LegSummary, Maneuver, Moment, OpeningHours, OpeningHoursMode, OptionalBBox, POI, PathLike, PlaceDataSources, PoiDetailsDataSource, PolygonFeature, PolygonFeatures, RelatedPOI, RoadInformation, RoadInformationProperty, RoadShield, RoadShieldReference, RoutePathPoint, RoutePlanningLocation, RoutePlanningLocationType, RouteSummary, SideRoad, SideRoadSide, Signpost, SummaryBase, SummaryWithConsumption, TextWithPhonetics, TimeRange, TimeZone, TollPaymentType, TomTomAPIHeaders, TomTomHeaders, Waypoint, WaypointLike, WaypointProps, Waypoints, languages };
+export type { Anything, BBox, ChargingAvailabilityDataSource, ChargingPark, ChargingParkWithAvailability, ChargingPointAvailability, ChargingStationsAvailability, CombustionSummary, ConnectorAvailability, ConnectorCount, DrivingSide, EVChargingStationWithAvailabilityPlaceProps, ElectricSummary, FeatureCollectionWithProperties, Fuel, GeometryDataSource, GetPositionEntryPointOption, GetPositionOptions, Guidance, HasBBox, HasConnector, HasCount, HasLngLat, Instruction, Landmark, Language, LegSummary, Maneuver, ManeuverAngle, ManeuverView, Moment, OpeningHours, OpeningHoursMode, OptionalBBox, POI, PathLike, PlaceDataSources, PoiDetailsDataSource, PolygonFeature, PolygonFeatures, RelatedPOI, RoadInformation, RoadInformationProperty, RoadShield, RoadShieldReference, RoundaboutType, RoutePathPoint, RoutePlanningLocation, RoutePlanningLocationType, RouteSummary, SideRoad, SideRoadSide, Signpost, SummaryBase, SummaryWithConsumption, TextWithPhonetics, TimeRange, TimeZone, TollPaymentType, TomTomAPIHeaders, TomTomHeaders, Waypoint, WaypointLike, WaypointProps, Waypoints, languages };