calculateRoute

mode=calculateRoute

Iframe mode that allows route plotting.

<iframe src="https://iframe.hogs.live?authToken=<authToken>&mode=calculateRoute&options=<options>"></iframe>

Options

interface CalculateRouteOptions {
  waypoints: Waypoint[];
  vehicleSpec: VehicleSpec;
  routeSettings: CustomRouteSettings;
  calculatorSettings: CalculatorSettings;
  mode: RouteKind;
  alternatives?: boolean;
  showInfo?: boolean;
  link?: string;
}

Alternatives parameter causes the route querry to return with alternative routes. Alternative routes are not visually represented in the iframe.

Waypoints

interface Waypoint {
  lat: string;
  lat: string;
  passThrough?: boolean;
}

Only intermediary points can have passThrough: true value.

VehicleSpec

interface VehicleSpec {
  truckHeight: string;
  truckWidth: string;
  truckLength: string;
  truckWeight: string;
  axisNumberTractor: string;
  euroClass: EuroClass;
  heightAboveFirstAxle: string;
  vehicleType: VehicleType;
  weightPerAxle: string;
  trailerHeight: string;
  axisNumberTrailer: string;
}

enum EuroClass {
  EURO_I = "1",
  EURO_II = "2",
  EURO_III = "3",
  EURO_IV = "4",
  EURO_V = "5",
  EURO_VI = "6",
  EURO_EEV = "7",
  Electric_Vehicles = "8"
}

enum VehicleType {
  truckTractor = "truckTractor",
  tandem = "tandem",
  solo = "solo",
  bus = "bus"
  car = "car"
}

Attention!

Choosing car (passenger car) type will switch from articulated vehicle route plotting to passener car plotting and all parameters provided in VehicleSpec will not be considered. Only axisNumberTractor, euroClass, truckHeight, truckWeight parameters are usig when calculating road toll. Parameters are optional and the only default value is the number of axis (axisNumberTractor) – 2.

CustomRouteSettings

interface CustomRouteSettings {
  departure?: string;
  avoidPayments?: boolean;
  avoidCountries?: string;
  shippedHazardousGoods?: ShippedHazardousGoods;
  avoidFerries?: RouteFeatureWeight;
  avoidMotorways?: RouteFeatureWeight;
  currency?: string;
}

enum ShippedHazardousGoods {
  explosive = "explosive",
  gas = "gas",
  flammable = "flammable",
  combustible = "combustible",
  organic = "organic",
  poison = "poison",
  radioActive = "radioActive",
  corrosive = "corrosive",
  poisonousInhalation = "poisonousInhalation",
  harmfulToWater = "harmfulToWater",
  other = "other"
}

enum RouteFeatureWeight {
  STRICT_EXCLUDE = -3,
  SOFT_EXCLUDE = -2,
  AVOID = -1,
  NORMAL = 0
}

Excluding ferries or highways may have different weight:

• STRICT_EXCLUDE - static exclusion, route will not contain static exclusion functions. If the condition cannot be met, the route will not be plotted.
• SOFT_EXCLUDE - soft exclusion, fragments with excluded functions have high penalties.
• AVOID - avoiding, soft exclusion, fragments with excluded functions have low penalties, the route will be plotted for the excluded fragment if the there are no alternatives.
• NORMAL - without this setting the route will be plotted without exclusions.

CalculatorSettings

interface CalculatorSettings {
  averageConsumption: number;
  fuelPrice: number;
  othersCosts: number;
}

Mode

Mode parameter defines what route will be returned: shorters, fastest, cheapers, ecological. Shortest route is default value.

enum Mode {
  shortest = "shortest",
  fastest = "fastest",
  eko = "eko",
  cheapest = "cheapest"
}

ShowInfo

Parameter that conditions whether a window with the summary of a plotted route will be displayed, false by default.

Link

You can link the Hogs application route and the iframe will open the route. When the link is provided other parameters defining the route will be ignored.

Examples

An example showing cheapers route plotting for a 40t tractor, avoiding Switzerland, soft highway exclusion and ADR radioactive cathegory.

const options = {
  waypoints: [
    {
      lng: "14.110965",
      lat: "52.264435"
    },
    {
      lng: "2.348631",
      lat: "50.600393"
    },
  ],
  vehicleSpec: {
    "truckLength": "16.5",
    "truckHeight": "4.00",
    "truckWidth": "2.6",
    "truckWeight": "40.00",
    "axisNumberTrailer": "4",
    "axisNumberTractor": "3",
    "euroClass": "5",
    "vehicleType": "truckTractor",
    "heightAboveFirstAxle": "3.2",
    "trailerHeight": "4.2",
    "weightPerAxle": "10",
  },
  routeSettings: {
    "avoidPayments": false,
    "avoidCountries": "CHE",
    "avoidMotorways": "SOFT_EXCLUDE",
    "shippedHazardousGoods": "radioActive",
  },
  calculatorSettings: {
    averageConsumption: 30,
    fuelPrice: 1.15,
    othersCosts: 0,
  },
  mode: "cheapest",
}

Iframe calling while using encodeURIComponent() function only for the object with data (options parameter):

https://iframe.hogs.live/?authToken=&mode=calculateRoute&options={%22showInfo%22:true,%22waypoints%22:[{%22lng%22:%2214.110965%22,%22lat%22:%2252.264435%22},{%22lng%22:%222.348631%22,%22lat%22:%2250.600393%22}],%22vehicleSpec%22:{%22truckLength%22:%2216.5%22,%22truckHeight%22:%224.00%22,%22truckWidth%22:%222.6%22,%22truckWeight%22:%2240.00%22,%22axisNumberTrailer%22:%224%22,%22axisNumberTractor%22:%223%22,%22euroClass%22:%225%22,%22vehicleType%22:%22truckTractor%22,%22vehicleWeight%22:%2240%22,%22heightAboveFirstAxle%22:%223.2%22,%22trailerHeight%22:%224.2%22,%22weightPerAxle%22:%2210%22},%22routeSettings%22:{%22avoidPayments%22:%22false%22,%22avoidCountries%22:%22CHE%22,%22shippedHazardousGoods%22:%22radioActive%22,%22avoidMotorways%22:%22SOFT_EXCLUDE%22},%22calculatorSettings%22:{%22averageConsumption%22:30,%22fuelPrice%22:1.15,%22othersCosts%22:0},%22mode%22:%22cheapest%22}

Provide the user token acquired during authorisation.

Attention!

Iframe data interpreting function uses the JSON.parse() method on the options object - smallest syntax mistake will result in error.

We recommed to use the iframe with event mechanics - does not require to reload the iframe each time to plot a route. Iframe data (optioms parameter) are transmited as object so correct syntax problem is avoided.

Answer

Answer about route is emited as calculationSuccess event

interface Response {
  type: string;
  data: Data;
}

interface Data {
  route: string;
  link: string;
  ferryConnections: FerryConnections[];
  toll: Toll;
  legs: Leg[];
  legTruckRestrictionViolationSections: TruckRestrictionViolationSection[][]
  truckRestrictionViolationSections: TruckRestrictionViolationSection[];
  totalCost: number
  summaryByCountry: SummaryByCountry[];
  details: Details;
}

interface Details {
  distance: number;
  travelTime: number;
  trafficTime: number;
  co2Emission: number;
}

interface SummaryByCountry {
  distance: number;
  trafficTime: number;
  baseTime: number;
  travelTime: number;
  co2Emission: number;
  country: string;
  tollRoadDistance: number;
}

interface Toll {
  costsByCountry: CostsByCountry[];
  costsByTollSystem: CostsByTollSystem[];
  tollPoints: TollPointData[];
  tollCost: number;
  tollSection: TollSection[];
  legTollPoints: TollPointData[][];
  legTollSection: TollSection[][];
  routeId: string;
}

interface TollPointData {
  country: string;
  tollSystemName: string;
  distance: number;
  costInTargetCurrency: number;
  shapeIndex: number;
  tollPointType: 'START_TOLL_ROAD' | 'END_TOLL_ROAD';
  position: { lat: number, lng: number }
}

interface TollSection {
  startShapeIndex: number;
  endShapeIndex: number;
  startCoordinate: { lat: string, lng: string };
  endCoordinate: { lat: string, lng: string };
  distance: number;
  costInTargetCurrency: number;
  tollSystemName: string;
  country: string;
  sections?: TollSection[];
}

interface CostsByCountry {
  amount: number;
  country: string;
}

interface CostsByTollSystem {
  amount: number;
  country: string;
}

interface FerryConnections {
  fromCity: string;
  toCity: string;
  through?: string;
}

interface Leg {
  shape: number[];
  maneuver: Maneuver[];
  link: Link[];
  length: number;
  travelTime: number;
  waypoint: MappedWaypoint[];
}

interface Maneuver {
  position: { latitude: number, longitude: number };
  action: string;
  instruction: string;
  note: Note[];
  roadNumber: string;
  toLink: string;
  travelTime: number;
}

interface Link {
  linkId: string;
  shape: number[];
}

interface Note {
  code: string,
  type: string
  text?: string,
  countryChangeDetails?: { toCountry: string }
}

interface MappedWaypoint {
  linkId: string;
  mappedPosition: { latitude: number, longitude: number }
  originalPosition: { latitude: number, longitude: number }
  shapeIndex: number;
  type: string;
}

interface TruckRestrictionViolationSection {
  startIndexShape: number;
  endIndexShape: number;
  startCoordinate: { lat: string, lng: string };
  endCoordinate: { lat: string, lng: string };
  shape: number[];
  distance: number;
  violation: { [key: string]: any };
}

Attention!

Distance and time values are provided in meters and seconds. Kilometers done via ferry are not subtracted in the country summary.

Notes (note) are included in the maneuver (Maneuver) element in the querry answer - notes contain such information as ex. road bat violation (type: violation, tex: truckRestriction).

Parameters now supported by HOGS application (app.hogs.live) such as link generated in the route answer will not open the route in the application:

• avoidFerries from CustomRouteSettings
• avoidMotorways from CustomRouteSettings
• passenger car as type of vehicle (VehicleType .car)

Road toll sections TollSection

tollPoints and tollSection fields are contained within the road toll answer object. tollPoints field contains informaton about start and end point of the section. tollSection field defines whole paid sections. If a sections field is defines within the tollSection object it means that the cost involved several fragments that do not have to be connected together (ex. time vignette in Holand).

The legTollPoints and legTollSections fields contain the same points and sections but grouped by route fragments(Leg). The shapeIndex field is connected to the route shape index in the correct leg object. Simular situation applies to the information about sections describing describing restrictions violation such as legTruckRestrictionViolationSections and truckRestrictionViolationSections.