Generowanie tras dla dużych pojazdów i szacowanego czasu dotarcia

Dla kogo jest ten przewodnik: przeczytaj ten przewodnik, jeśli jesteś deweloperem tworzącym usługi do planowania i realizacji podróży ciężarówkami lub innymi dużymi pojazdami. Odpowiednie przypadki użycia obejmują obliczanie czasu podróży i odległości, obliczanie szacowanego czasu dotarcia na miejsce lub generowanie tras, które będą używane przez aplikację do nawigacji.

Co zawiera ten przewodnik: ten przewodnik opisuje, jak używać interfejsu Routes API z wyznaczaniem tras dla dużych pojazdów, aby prosić o trasy, odległość, przewidywany czas podróży i szacowany czas dotarcia na miejsce, które uwzględniają określone atrybuty dużego pojazdu, takiego jak ciężarówka komercyjna lub autobus pasażerski.

Informacje o tym, jak wykonywać obliczenia na poziomie floty w przypadku dużych pojazdów za pomocą interfejsu Route Optimization API, znajdziesz w dokumentacji dotyczącej wyznaczania tras dla ciężarówek w Route Optimization API.

Czego się nauczysz

Dowiesz się, jak:

  • Utwórz prawidłowe żądanie routingu.
  • Określ informacje o pojeździe, takie jak wymiary, waga i inne cechy.
  • Zinterpretuj odpowiedź, w tym token trasy i flagi bezpieczeństwa podróży.

Wymagania wstępne

  1. Musisz utworzyć projekt w chmurze Google Cloud i włączyć Routes API.
  2. Twój projekt musi być skonfigurowany pod kątem wyznaczania tras dla dużych pojazdów. Wyznaczanie tras dla dużych pojazdów jest dostępne dla ograniczonej liczby klientów. Skontaktuj się z nami, aby poprosić o dostęp.

Ograniczenia

Zanim zaczniesz, musisz zapoznać się z tymi ograniczeniami i wymaganiami.

  • Dostępność geograficzna: wyznaczanie tras dla dużych pojazdów jest dostępne w 48 stanach kontynentalnych USA (ogólna dostępność) i w Japonii (funkcja eksperymentalna). Nie jest dostępna na Alasce, Hawajach ani na terytoriach zależnych USA.
  • Wskazówki i bezpieczeństwo kierowcy. Kierowcy nie powinni polegać wyłącznie na trasach zwracanych przez ten interfejs API, aby zapewnić bezpieczeństwo lub zgodność z prawem. Nie ma gwarancji, że trasy będą odpowiednie dla pojazdu, a podążanie nimi może narazić kierowców na niebezpieczeństwa, takie jak niskie mosty lub drogi, na których obowiązuje zakaz ruchu dużych pojazdów.
  • Trasy typu „best-effort”. W niektórych przypadkach interfejs API nie może znaleźć trasy, która w pełni spełnia ograniczenia dotyczące podróży. Zamiast tego zwraca trasę „najlepszej obsługi”, która może nadal przebiegać przez obszary z ograniczeniami. Odpowiedź interfejsu Routes API wyraźnie oznacza te trasy w polu routeRestrictionsPartiallyIgnored. W takich przypadkach starannie zaplanuj trasę, najlepiej korzystając z innych źródeł danych. Nie używaj oznaczonej trasy jako jedynego źródła wiarygodnych danych do planowania lub nawigacji.
  • Nieobsługiwane funkcje: wyznaczanie tras dla dużych pojazdów nie obsługuje tych funkcji:
    • Opłaty za przejazd ciężarówek
    • Ograniczenia prędkości
    • Trasa dla materiałów niebezpiecznych radioaktywnych
  • Limity wykorzystania: wszystkie żądania podlegają standardowym limitom zapytań na sekundę (QPS).

Tworzenie żądania trasy dla ciężarówki

Aby uzyskać trasę dla ciężarówki, wyślij żądanie HTTPS do punktu końcowego interfejsu Routes API z określonymi parametrami opisującymi pojazd. Pojęcia opisane w tej sekcji dotyczą zarówno żądań pojedynczej trasy, jak i żądań macierzy tras.

Punkty końcowe

Do wyznaczania tras dla ciężarówek możesz używać 2 punktów końcowych:

  • computeRoutes: oblicza pojedynczą trasę między jednym miejscem początkowym a jednym miejscem docelowym.
  • computeRouteMatrix: oblicza odległość i czas trwania dla macierzy punktów początkowych i docelowych, ale nie zwraca linii łamanej trasy.

Kluczowe parametry żądania

Aby włączyć wyznaczanie tras dla ciężarówek, w treści żądania musisz uwzględnić te parametry:

  • travelMode: ustaw tę wartość na TRUCK.
  • routingPreference: ustaw tę wartość na TRAFFIC_AWARE_OPTIMAL.
  • routeModifiers: ten obiekt zawiera obiekt vehicleInfo, w którym definiujesz atrybuty pojazdu. Obiekt vehicleInfo został szczegółowo opisany poniżej.

Określanie atrybutów pojazdu

Aby wysłać żądanie, musisz podać treść żądania z obiektem vehicleInfo, który opisuje Twój pojazd. Pomyśl o tych informacjach jako o specyfikacji, która odpowiada fizycznym szczegółom Twojego pojazdu w świecie rzeczywistym. Usługa wymaga tych informacji, aby zwracać trasy uwzględniające ograniczenia drogowe na podstawie atrybutów pojazdu.

Pomiary pojazdu

Podaj wagę pojazdu w kilogramach i jego wymiary w milimetrach, zgodnie z nazwami pól. Na przykład całkowitą wysokość należy podać w milimetrach (totalHeightMm). Ponieważ wymiary ciężarówek są często wyrażane w stopach lub metrach, może być konieczne przeliczenie jednostek.

Konwersja z jednostek imperialnych na metryczne

Podczas przeliczania jednostek imperialnych zawsze bierz pod uwagę wymiary swojego pojazdu oraz standardowe limity rozmiarów dróg i przejść podziemnych. Może to być szczególnie ważne w przypadku wartości ułamkowych. W zależności od rzeczywistego rozmiaru pojazdu zaokrąglenie wartości ułamkowej w górę może spowodować, że trasa pojazdu będzie zbyt restrykcyjna.

Na przykład:

  • Szerokość: wiele przyczep w USA ma szerokość 8' 6", co odpowiada 2590,8 mm. Zaokrąglenie do 2591 mm wskazywałoby,że pojazd jest większy niż 8 stóp i 6 cali, co klasyfikowałoby go jako pojazd ponadgabarytowy na drogach w USA. W takim przypadku trasa zostałaby obliczona na podstawie znacznie innych ograniczeń niż zamierzone.
  • Wysokość: trasa prowadząca pod mostem o wysokości 3,3 m nie będzie odpowiednia dla typowego ciągnika siodłowego z naczepą o wysokości 4,1 m. Jednak mniejsze ciężarówki, o wysokości około 3 metrów, mogą przejechać pod wiaduktem. Dlatego ważne jest, aby dokładnie określić atrybuty pojazdu.

Schemat przedstawiający wymiary ciężarówki w porównaniu z wymiarami przejazdu pod wiaduktem

Poniżej znajduje się fragment kodu, który pokazuje przykładowy obiekt vehicleInfo:

"vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }

vehicleInfo pól obiektów

W tabeli poniżej znajdziesz wszystkie definicje pojazdów i ładunków, które możesz wysłać w żądaniu.

Pole Opis Uwagi/wartości
totalHeightMm Maksymalna wysokość pojazdu. W milimetrach, zaokrąglone w dół. Więcej informacji o zaokrąglaniu znajdziesz w artykule Przeliczanie jednostek imperialnych na metryczne.
totalWidthMm Maksymalna szerokość pojazdu. W milimetrach, zaokrąglone w dół.
totalLengthMm Łączna długość pojazdu i przyczep. W milimetrach, zaokrąglone w dół.
totalWeightKg Dopuszczalna masa całkowita pojazdu (w tym przyczep i ładunku). W kilogramach, zaokrąglona w dół.
totalAxleCount Łączna liczba osi pojazdu i przyczep. Dokładne.
trailerInfo (opcjonalnie) Tablica obiektów, po jednym dla każdego zwiastuna. Pomiń w przypadku pojazdu bez przyczepy, np. furgonetki.
hazardousGoodsTypes (opcjonalnie) Tablica określająca materiały niebezpieczne na pokładzie. EXPLOSIVES, GASES, FLAMMABLE, COMBUSTIBLE, ORGANIC, POISON, CORROSIVE, ASPIRATION_HAZARD, ENVIRONMENTAL_HAZARD, OTHER

Używanie masek pól

Aby uzyskać najlepsze wyniki, dodaj do żądania nagłówek X-Goog-FieldMask, aby określić dokładnie te pola, które chcesz otrzymać w odpowiedzi. Maski pól zmniejszają opóźnienie i zapewniają otrzymywanie ważnych pól doradczych. Zawsze uwzględniaj w masce pola co najmniej routes.travelAdvisory.routeRestrictionsPartiallyIgnored, ponieważ wskazuje to, czy trasa ma co najmniej jedno ograniczenie, które dotyczy Twojego pojazdu.

Więcej informacji o maskach pól w interfejsie Routes API znajdziesz w tym artykule.

Opłat

Aby preferować trasy bezpłatne, we właściwości routeModifiers żądania podaj avoidTolls. Więcej informacji o modyfikatorach tras znajdziesz w artykule Określanie cech trasy, których należy unikać.

Określenie avoidTolls nie gwarantuje, że w odpowiedzi zostaną zwrócone trasy bezpłatne. W niektórych przypadkach korzystanie z drogi płatnej jest wymagane do przejazdu między miejscem początkowym a docelowym. Jeśli w masce pola żądania do interfejsu Routes API uwzględnisz routes.warnings, trasy obejmujące drogi płatne będą odpowiednio oznaczone w tym polu.

Inne zachowania związane z routingiem

Gdy ustawisz travelMode na TRUCK, interfejs API automatycznie optymalizuje trasę pod kątem manewrowości dużych pojazdów. Wygenerowane trasy omijają zawracanie i preferują drogi międzystanowe i autostrady zamiast mniejszych dróg. Nie musisz ustawiać żadnych dodatkowych parametrów ani modyfikatorów, aby włączyć te zachowania.

Obliczanie pojedynczej trasy za pomocą computeRoutes

Użyj punktu końcowego computeRoutes, aby obliczyć trasę dla ciężarówki między jednym punktem początkowym a jednym punktem docelowym.

Przykładowe żądanie computeRoutes

Oto pełne żądanie curl dotyczące typowej naczepy. Ten przykład obejmuje punkt końcowy, nagłówki i treść żądania.

curl --location 'https://routes.googleapis.com/directions/v2:computeRoutes' \
--header 'Content-Type: application/json' \
--header 'X-Goog-Api-Key: YOUR_API_KEY' \
--header 'X-Goog-FieldMask: routes.duration,routes.distanceMeters,routes.routeToken,routes.travelAdvisory.routeRestrictionsPartiallyIgnored' \
--data '{
 "origin": {
    "location": {
      "latLng": {
        "latitude": 40.883274,
        "longitude": -74.704574
      }
    }
  },
  "destination": {
    "location": {
      "latLng": {
        "latitude": 40.991920,
        "longitude": -75.183371
      }
    }
  },
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL",
  "routeModifiers": {
    "vehicleInfo": {
      "totalAxleCount": 5,
      "totalHeightMm": 4114,
      "totalLengthMm": 21945,
      "totalWidthMm": 2590,
      "totalWeightKg": 32658,
      "trailerInfo": [{
        "lengthMm": 16154
      }]
    }
  }
}'

Przykładowa odpowiedź computeRoutes

Oto przykładowa odpowiedź na powyższe żądanie. Zwróć uwagę, że w obiekcie travelAdvisory nie ma flagi routeRestrictionsPartiallyIgnored. Oznacza to, że trasa nie jest oznaczona flagą i jest uznawana za w pełni zgodną z atrybutami pojazdu.

{
  "routes": [
    {
      "distanceMeters": 3426,
      "duration": "312s",
      "travelAdvisory": {},
      "routeToken": "CogCCogBChA7b39q54cKGCys_VXaDADjEhgszp8YhZFw0xvzm7SygpvCeIvJ7V0r6XIaJZ6BxNkMa_8HhhqlAci7hYMXi6UCpPgDW-yoAf8gzgHiEYyJAnoiAQU6AQFCB27cD9UCwwdKCMX2Ij7RpxY_eAGqARdUNENZWllLS0tJRGZ2T01QMVptSjRBaxAEGmIKYBIWCAAQAxAGEBMQEhgCQgQaAggFSgIIASIbChdUNENZWmVTc0o0RGZ2T01QMVptSjRBa3ABKAQyJ3RydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnktc29mdCIVAOzExFsGGGfjVIIY7GXjYbPyONS8EiQiInRydWNraW5nOjpzZW1pLXRyYWlsZXItdHJ1Y2staGVhdnk"
    }
  ]
}

Interpretowanie odpowiedzi computeRoutes

Pomyślne żądanie wysłane do punktu końcowego computeRoutes zwraca obiekt odpowiedzi JSON zawierający co najmniej 1 możliwą trasę.

Kluczowe pola odpowiedzi
  • Zakodowana geometria trasy: routes.polyline. Można go użyć do renderowania trasy na mapie.
  • Szacowany czas trwania przejazdu: routes.duration (w sekundach). Czas trwania przejazdu dużego pojazdu jest obliczany na podstawie nowego modelu trenowanego na podstawie obserwowanych prędkości rzeczywistych ciężarówek w sieci dróg. Można go też użyć do obliczenia szacowanego czasu dotarcia na miejsce przez dodanie szacowanego czasu trwania przejazdu do oczekiwanego czasu odjazdu.
  • Całkowita odległość trasy: routes.distanceMeters (w metrach).
  • Token trasy: routes.routeToken. Jest to nieprzezroczysty token, który reprezentuje dokładnie obliczoną trasę. Przekazujesz ten token do pakietu Navigation SDK, aby kierowca widział tę samą trasę dla ciężarówek. Szczegółowe informacje znajdziesz w przewodnikach po pakiecie Navigation SDK na Android i iOS.
Sprawdzanie oznaczeń dotyczących bezpieczeństwa trasy

Gdy otrzymasz odpowiedź, najpierw sprawdź, czy nie ma flag bezpieczeństwa trasy. Jeśli podana trasa zawiera co najmniej jedno ograniczenie, które sprawia, że jest ona nieodpowiednia dla pojazdu, pole travelAdvisory.routeRestrictionsPartiallyIgnored będzie miało wartość true.

To pole działa jako flaga, która odpowiada na pytanie: „Czy ta trasa jest oznaczona jako potencjalny problem?”.

  • false(lub pominięto w odpowiedzi): trasa nie jest oznaczona. System znalazł trasę, która według niego jest w pełni zgodna z parametrami podanymi w żądaniu.
  • true: trasa jest oznaczona flagą. System nie mógł znaleźć w pełni zgodnej trasy i zwrócił trasę „najlepszą z możliwych”, która może nie być bezpieczna lub legalna. Z tej trasy należy korzystać z zachowaniem szczególnej ostrożności.

Obliczanie macierzy tras (computeRouteMatrix)

Użyj punktu końcowego computeRouteMatrix, aby skutecznie porównywać czasy podróży i odległości między wieloma miejscami rozpoczęcia i zakończenia podróży. Możesz na przykład użyć go, aby znaleźć ciężarówkę, która znajduje się najbliżej nowego miejsca odbioru. Gdy określisz miejsce początkowe pojazdu, którego chcesz użyć, możesz wysłać żądanie computeRoutes, aby uzyskać szczegóły trasy i token trasy dla proponowanego pojazdu.

Aby użyć computeRouteMatrix, określ vehicleInfo w każdym obiekcie origin, a nie w głównym żądaniu.

Przykładowe żądanie computeRouteMatrix

{
  "origins": [
    {
      "waypoint": { "location": { "latLng": { "latitude": 32.77, "longitude": -96.85 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    },
    {
      "waypoint": { "location": { "latLng": { "latitude": 33.61, "longitude": -112.11 }}},
      "routeModifiers": { "vehicleInfo": { /* ...vehicle attributes... */ } }
    }
  ],
  "destinations": [
    { "waypoint": { "location": { "latLng": { "latitude": 35.02, "longitude": -106.64 }}}},
    { "waypoint": { "location": { "latLng": { "latitude": 29.77, "longitude": -95.40 }}}}
  ],
  "travelMode": "TRUCK",
  "routingPreference": "TRAFFIC_AWARE_OPTIMAL"
}

Przykładowa odpowiedź computeRouteMatrix

Odpowiedź jest tablicą, w której każdy obiekt zawiera czas trwania i distanceMeters dla jednej pary punktu początkowego i docelowego.

[
  {
    "originIndex": 0,
    "destinationIndex": 1,
    "status": {},
    "distanceMeters": 392372,
    "duration": "14037s",
    "condition": "ROUTE_EXISTS"
  },
  { ... }
]

Dalsze kroki