Table of Contents

TMS FNC Toll Cost — Guides

Service backends

Set Service to choose the toll data provider: tcsHere (the default) or tcsPTVxServer. Coverage and pricing models vary by region and provider. HERE authenticates with APIKey; the PTV xServer backend uses UserName, Token, and ServiceEndpoint.

HERE Routing API

The HERE backend calls the HERE Routing API v8 (router.hereapi.com/v8/routes), which replaced the retired Fleet Telematics toll-cost service. Two consequences for calling code:

  • A single HERE APIKey, provisioned for the Routing API, is all the authentication needed.
  • The vehicle description is only forwarded for the travel modes that carry one. ttCustom sends the Options.TravelInfo axle count, height, and weight; ttDeliveryVan, ttLightTruck, and ttHeavyTruck substitute their own fixed profile; ttCar sends no vehicle description at all. Use ttCustom whenever the values you set in Options.TravelInfo must actually reach the service.
uses
  FMX.TMSFNCTollCost, FMX.TMSFNCMapsCommonTypes;

procedure TForm1.FormCreate(Sender: TObject);
begin
  // The HERE backend now calls the HERE Routing API (router.hereapi.com/v8),
  // which replaced the retired Fleet Telematics toll-cost service. A single
  // HERE APIKey is all it needs - UserName and Token apply to tcsPTVxServer.
  TMSFNCTollCost1.Service := tcsHere;
  TMSFNCTollCost1.APIKey := MyHereApiKey;

  TMSFNCTollCost1.OnGetTollCostResult := TMSFNCTollCost1GetTollCostResult;
end;

procedure TForm1.RequestTollCostButtonClick(Sender: TObject);
begin
  // Only ttCustom forwards the Options.TravelInfo axle count, height and
  // weight to the service; ttDeliveryVan, ttLightTruck and ttHeavyTruck send
  // their own fixed vehicle profile instead, and ttCar sends no vehicle
  // description at all.
  TMSFNCTollCost1.Options.TravelInfo.VehicleAxles := 5;
  TMSFNCTollCost1.Options.TravelInfo.VehicleWeight := 12000;
  TMSFNCTollCost1.Options.TravelInfo.VehicleHeight := 400;

  // The CO2 class is only sent when an emission type is set as well, so set
  // both or neither.
  TMSFNCTollCost1.Options.TravelInfo.VehicleEmissionType := etEuro6;
  TMSFNCTollCost1.Options.TravelInfo.VehicleCO2Class := co2Class1;

  TMSFNCTollCost1.GetTollCostResult(
    CreateCoordinate(51.2213, 4.4051),   { origin: Antwerp }
    CreateCoordinate(48.8566, 2.3522),   { destination: Paris }
    nil,                                 { no inline callback }
    'antwerp-paris',                     { request ID }
    nil,                                 { no data pointer }
    ttCustom,                            { forward the travel info above }
    nil,                                 { no waypoints }
    tcEUR);
end;

procedure TForm1.TMSFNCTollCost1GetTollCostResult(Sender: TObject;
  const AResult: TTMSFNCTollCostRequest);
var
  I, J: Integer;
  LItem: TTMSFNCTollCostItem;
  LSystem: TTMSFNCTollCostSystem;
begin
  if AResult.ErrorMessage <> '' then
  begin
    Memo1.Lines.Add('Request ' + AResult.ID + ' failed: ' + AResult.ErrorMessage);
    Exit;
  end;

  for I := 0 to AResult.Items.Count - 1 do
  begin
    LItem := AResult.Items[I];

    // TotalCost and Currency carry the route total the Routing API reports
    // through its toll summary.
    Memo1.Lines.Add(Format('Route %d: %.2f %s over %.1f km',
      [I, LItem.TotalCost, LItem.Currency, LItem.Distance / 1000]));

    // The individual charges are on TollSystems; Steps holds the route legs
    // (location, distance, duration, instructions), not per-leg amounts.
    for J := 0 to LItem.TollSystems.Count - 1 do
    begin
      LSystem := LItem.TollSystems[J];
      Memo1.Lines.Add(Format('  %s: %.2f %s (%s)',
        [LSystem.SystemID, LSystem.Cost, LSystem.Currency, LSystem.Summary]));
    end;
  end;
end;

Configuring vehicle travel info

Toll tariffs for trucks and commercial vehicles typically vary by axle count, weight, height, and emission class — a light passenger car and a heavy truck can be charged very differently for the same route. Use Options.TravelInfo (TTMSFNCTollCostTravelInfo) to describe the vehicle before calling GetTollCost or GetTollCostResult:

  • VehicleAxles — number of axles on the vehicle (default 2).
  • VehicleWeight — vehicle weight in kilograms (default 3499).
  • VehicleHeight — vehicle height in centimeters (default 199).
  • VehicleEmissionType — Euro emission standard (etUnknown through etEuroEev).
  • VehicleCO2Class — CO2 emission class (co2Unknown through co2Class5). Only sent when VehicleEmissionType is also set, so set both or neither.

Pair the travel info with a TravelMode that actually forwards it — see HERE Routing API above:

procedure TForm1.ConfigureTruckTravelInfo;
begin
  { Describe the vehicle so the toll cost service can apply truck-specific tariffs. }
  TMSFNCTollCost1.Options.TravelInfo.VehicleAxles := 5;
  TMSFNCTollCost1.Options.TravelInfo.VehicleWeight := 12000;
  TMSFNCTollCost1.Options.TravelInfo.VehicleHeight := 400;
  TMSFNCTollCost1.Options.TravelInfo.VehicleEmissionType := etEuro6;
  TMSFNCTollCost1.Options.TravelInfo.VehicleCO2Class := co2Class1;

  { ttCustom is the travel mode that forwards the values above. The named truck
    modes (ttDeliveryVan, ttLightTruck, ttHeavyTruck) substitute their own fixed
    axle count, height, and weight instead, and ttCar sends none at all. }
  TMSFNCTollCost1.GetTollCost(
    CreateCoordinate(51.2213, 4.4051),
    CreateCoordinate(50.8503, 4.3517),
    nil, 'route-1', nil, ttCustom);
end;

Result handling

Both entry points are asynchronous. GetTollCostResult reports the parsed result through OnGetTollCostResult; GetTollCost reports the raw request outcome through OnGetTollCost. Either way the parsed data lands on the TTMSFNCTollCostRequest, which carries ID, TravelMode, Status, ErrorMessage, and an Items collection of TTMSFNCTollCostItem.

Each TTMSFNCTollCostItem describes one route:

  • TotalCost and Currency — the toll total reported for the route.
  • Distance and Duration — route length in meters and duration in seconds.
  • TollSystems — the individual charges (TTMSFNCTollCostSystem: SystemID, Summary, Cost, Currency).
  • Steps — the route legs (TTMSFNCTollCostStep: Location, Distance, Duration, Instructions). Steps carry no amounts; the charges are on TollSystems.
  • Coordinates and Bounds — the route geometry and its bounding box, ready to draw on a map.

Currency is chosen per request through the ACurrency parameter of GetTollCost / GetTollCostResult, not through Options.

See also