calculateRoute

mode=calculateRoute

Tryb pracy iframe pozwalający wyznaczyć trasę.

<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;
}

Parametr alternatives powoduje, że w odpowiedzi o trasie zwracane są także trasy alternatywne. Trasy alternatywne nie są wizualnie przedstawione w iframe’ie.

Waypoints

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

Tylko punkty pośrednie mogą mieć właściwość passThrough: true.

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"
}

Uwaga!

Wybór pojazdu typu car (samochód osobowy) spowoduje przełączenie trybu wyznaczenia trasy z ciężarówek na auta osobowe, co sprawi, że żadne parametry auta podane w VehicleSpec  nie są brane pod uwagę. Jedynie parametry axisNumberTractor, euroClass, truckHeight, truckWeight są używane podczas kalkulacji opłat drogowych. Parametry są opcjonalne, jedyną wartością domyślną jest liczba osi (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
}

Wykluczanie promów lub autostrad może mieć różną wagę:

• STRICT_EXCLUDE – sztywne wykluczanie, trasa nie będzie zawierać ściśle wykluczonych funkcji. Jeżeli warunek nie może być spełniony, trasa nie zostaje zwrócona.
• SOFT_EXCLUDE – lekkie unikania, fragmenty z wykluczonymi funkcjami mają duże kary.
• AVOID – unikanie, fragmenty z wykluczonymi funkcjami mają lekkie kary, trasa zostanie wyznaczona pod wykluczony fragment, jeśli nie uda się znaleźć alternatywy.
• NORMAL – równoznaczne z brakiem tego ustawienia, trasa jest wyznaczana bez wykluczeń.

CalculatorSettings

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

Mode

Parametr mode definiuje, jaka trasa ma zostać zwrócona: najkrótsza, najszybsza, najtańsza, ekologiczna. Domyślną wartością jest trasa najkrótsza.

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

ShowInfo

Parametr warunkujący, czy ma się wyświetlić okno z podsumowaniem wyznaczenia trasy, domyślnie false.

Link

Jako link można podać adres do trasy z aplikacji HOGS, wtedy iframe odtworzy trasę. Jeżeli zostanie podany link, inne parametry definiujące trasę zostaną zignorowane.

Przykłady

Przykład opcji wyznaczenia najtańszej trasy dla ciągnika siodłowego 40 t wraz z omijaniem Szwajcarii, lekkim wykluczeniem autostrad oraz radioaktywną kategorią ADR.

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",
}

Wywołanie iframe’a z wykorzystaniem funkcji encodeURIComponent() tylko dla obiektu z danymi (parametr options):

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}

Należy podać tylko pozyskany w drodze autoryzacji token użytkownika.

Uwaga!

Funkcja interpretująca dane po stronie iframe’a korzysta z metody JSON.parse() na obiekcie options – najmniejszy błąd składni spowoduje błąd.

Zalecamy używać iframe’a z wykorzystaniem mechaniki eventów – nie wymaga każdorazowo przeładowania iframe’a w celu wyznaczanie trasy. Dane (parametr options) do iframe’a są przekazywane jako obiekt, więc odchodzą problemy z poprawnością składni.

Odpowiedź

Odpowiedź o trasie jest emitowana w postaci eventu calculationSuccess

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 };
}

Uwaga!

Wartości dystansu, czasu są odpowiednio podane w metrach i sekundach. W podsumowaniu na kraje kilometry wykonane na promach nie są odliczane!

W odpowiedzi, w manewrach (Maneuver), są zawarte notatki (Note) – w nich są np. informacje o naruszonym zakazie drogowym (type: violation, text: truckRestriction).

Parametry, które nie są wspierane przez aplikację HOGS (app.hogs.live), tzn. wygenerowany link w odpowiedzi o trasie, nie odtworzy trasy w aplikacji:

• avoidFerries z CustomRouteSettings
• avoidMotorways z CustomRouteSettings
• auto osobowe jako rodzaj pojazdu (VehicleType .car)

Odcinki dróg płatnych TollSection

W obiekcie odpowiedzi opłat drogowych zawarte są pola tollPoints i tollSection. Pole tollPoints zawiera informację o punkcie początku i końca danego odcinka. Pole tollSection definuje całe odcinki płatne. Jeżeli w obiekcie tollSection jest zdefiniowane pole sections, oznacza to, że dana opłata dotyczny kilku odcinków, niekoniecznie połączonych ze sobą (np. winieta czasowa w Holandii).

Pola legTollPoints i legTollSections zawierają te same punkty i odcinki, ale zgrupowane wg odcinków trasy(Leg). Pole shapeIndex dotyczy indexu kształtu trasy we właściwym obiekcie leg. To samo dotyczy informacji na temat odcinków określających naruszenie zakazów, pola: legTruckRestrictionViolationSections i truckRestrictionViolationSections.