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

Dla kogo jest ten przewodnik: jeśli jesteś deweloperem, który tworzy usługi do planowania i realizacji podróży z wykorzystaniem ciężarówek lub innych dużych pojazdów, przeczytaj ten przewodnik. Odpowiednie przypadki użycia obejmują obliczanie czasu podróży i odległości, szacowanie czasu przybycia lub generowanie tras, które będą używane przez aplikację do nawigacji.

Czego dowiesz się z tego przewodnika: z tego przewodnika dowiesz się, jak używać interfejsu Routes API z wyznaczaniem tras dla dużych pojazdów, aby wysyłać żądania dotyczące tras, odległości podróży, przewidywanego czasu podróży i szacowanego czasu przybycia, które uwzględniają konkretne atrybuty dużego pojazdu, takie jak ciężarówka lub autobus.

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 interfejsie Route Optimization API.

Czego się nauczysz

Dowiesz się, jak:

  • utworzyć prawidłowe żądanie wyznaczenia trasy;
  • określić informacje o pojeździe, w tym jego wymiary, wagę i inne cechy;
  • interpretować 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ć przygotowany do wyznaczania tras dla dużych pojazdów. Wyznaczanie tras dla dużych pojazdów jest dostępne tylko dla niektórych 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 sąsiadujących ze sobą stanach USA (dostępność ogólna) i Japonii (wersja eksperymentalna). Nie jest dostępne na Alasce, Hawajach ani na terytoriach USA.
  • Porady i bezpieczeństwo kierowcy. Kierowcy nie mogą polegać wyłącznie na trasach zwracanych przez ten interfejs API, aby zapewnić bezpieczeństwo lub zgodność z przepisami. Nie ma gwarancji, że trasy będą odpowiednie dla pojazdu, a ich pokonywanie może narażać kierowców na niebezpieczeństwa, takie jak niskie mosty lub drogi, na których obowiązuje zakaz wjazdu dla dużych pojazdów.
  • Trasy w trybie możliwie najlepszej obsługi. 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ę w trybie „możliwie najlepszej obsługi”, która może przebiegać przez obszary objęte ograniczeniami. Odpowiedź Routes API wyraźnie oznacza te trasy w polu routeRestrictionsPartiallyIgnored. W takich przypadkach dokładnie zaplanuj trasę, najlepiej korzystając z innych danych źródłowych. Nie używaj oznaczonej trasy jako jedynego źródła informacji na potrzeby planowania lub nawigacji.
  • Nieobsługiwane funkcje: wyznaczanie tras dla dużych pojazdów nie obsługuje tych funkcji:
    • ceny za przejazd ciężarówką;
    • ograniczenia prędkości;
    • wyznaczanie tras dla radioaktywnych materiałów niebezpiecznych.
  • Limity użycia: 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 Routes API z określonymi parametrami opisującymi Twój pojazd. Koncepcje 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 1 miejscem początkowym a 1 miejscem docelowym.
  • computeRouteMatrix: oblicza odległość i czas trwania dla macierzy miejsc 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 jest 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. Te informacje są specyfikacją, która odpowiada fizycznym szczegółom Twojego pojazdu. Usługa wymaga tych informacji, aby zwracać trasy, które uwzględniają ograniczenia drogowe na podstawie atrybutów pojazdu.

Wymiary pojazdu

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

Konwersja z jednostek imperialnych na metryczne

Podczas konwersji z jednostek imperialnych zawsze uwzględniaj konkretne wymiary pojazdu oraz standardowe limity rozmiarów dróg i przejazdów podziemnych. Może to być szczególnie ważne w przypadku wartości ułamkowych. W zależności od rozmiaru rzeczywistego pojazdu zaokrąglenie wartości ułamkowej w górę może spowodować zbyt restrykcyjne wyznaczanie trasy dla pojazdu.

Na przykład:

  • Szerokość: wiele przyczep w USA ma szerokość 8 stóp i 6 cali, co odpowiada 2590,8 mm. Zaokrąglenie do 2591 mm oznaczałoby,że pojazd ma więcej niż 8 stóp i 6 cali, co w USA kwalifikowałoby go jako pojazd ponadgabarytowy. Spowodowałoby to obliczenie trasy zgodnie z istotnie różnymi ograniczeniami niż zamierzone.
  • Wysokość: trasa prowadząca pod mostem o wysokości 11 stóp nie byłaby odpowiednia dla typowego ciągnika siodłowego o wysokości 13,5 stopy. Jednak mniejsze ciężarówki o wysokości około 10 stóp mogłyby przejechać pod mostem. Dlatego ważne jest, aby dokładnie określić atrybuty pojazdu.

Diagram ilustrujący wymiary ciężarówki na tle wymiarów przejazdu podziemnego

Poniżej znajdziesz fragment kodu, który pokazuje przykład obiektu vehicleInfo:

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

Pola obiektu vehicleInfo

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ąglona w dół. Więcej informacji o zaokrąglaniu znajdziesz w sekcji Konwersja z jednostek imperialnych na metryczne.
totalWidthMm Maksymalna szerokość pojazdu. W milimetrach, zaokrąglona w dół.
totalLengthMm Łączna długość pojazdu i wszystkich przyczep. W milimetrach, zaokrąglona w dół.
totalWeightKg Masa całkowita pojazdu (w tym przyczepy i ładunek). W kilogramach, zaokrąglona w dół.
totalAxleCount Łączna liczba osi w pojeździe i wszystkich przyczepach. Dokładna.
trailerInfo (opcjonalnie) Tablica obiektów, po jednym dla każdej przyczepy. Pomiń w przypadku pojazdu bez przyczep, np. ciężarówki.
hazardousGoodsTypes (opcjonalnie) Tablica określająca wszelkie 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, w żądaniu uwzględnij nagłówek X-Goog-FieldMask, aby określić dokładnie te pola, które chcesz uwzględnić w odpowiedzi. Maski pól zmniejszają opóźnienie i zapewniają otrzymywanie ważnych pól z poradami. Zawsze uwzględniaj w masce pola co najmniej routes.travelAdvisory.routeRestrictionsPartiallyIgnored, ponieważ wskazuje ona, czy trasa ma co najmniej 1 ograniczenie, które dotyczy Twojego pojazdu.

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

Opłat

Aby preferować trasy bezpłatne, w żądaniu określ avoidTolls we właściwości routeModifiers. Więcej informacji o modyfikatorach trasy, zobacz Określanie funkcji trasy, których należy unikać.

Określenie avoidTolls nie gwarantuje, że w odpowiedzi znajdą się trasy bezpłatne. W niektórych przypadkach dojazd z miejsca początkowego do docelowego wymaga skorzystania z drogi płatnej. Jeśli w masce pola żądania do interfejsu API Routes uwzględnisz routes.warnings, trasy zawierające drogi płatne zostaną odpowiednio oznaczone w tym polu.

Inne zachowania związane z wyznaczaniem tras

Gdy ustawisz travelMode na TRUCK, interfejs API automatycznie zoptymalizuje trasę pod kątem zwrotności dużych pojazdów. Wygenerowane trasy unikają zawracania i zdecydowanie preferują autostrady ponad mniejsze drogi. Aby włączyć te zachowania, nie musisz ustawiać żadnych dodatkowych parametrów ani modyfikatorów.

Obliczanie pojedynczej trasy za pomocą computeRoutes

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

Przykład żądania computeRoutes

Oto pełne żądanie curl dla typowej ciężarówki z naczepą. Ten przykład zawiera 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ład odpowiedzi computeRoutes

To jest przykładowa odpowiedź na żądanie pokazane powyżej. Zwróć uwagę, że w obiekcie travelAdvisory nie ma flagi routeRestrictionsPartiallyIgnored. Oznacza to, że trasa nie jest oznaczona i uważa się, że jest w pełni zgodna z atrybutami pojazdu.

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

Interpretowanie odpowiedzi computeRoutes

Pomyślne żądanie 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 jej użyć do renderowania trasy na mapie.
  • Szacowany czas trwania przejazdu: routes.duration (w sekundach). Czas trwania podróży w przypadku wyznaczania tras dla dużych pojazdów korzysta z nowego modelu wytrenowanego na podstawie obserwowanych prędkości podróży rzeczywistych ciężarówek w sieci dróg. Można go też używać do obliczania szacowanego czasu przybycia, dodając szacowany czas trwania podróży do przewidywanego czasu wyjazdu.
  • Całkowita odległość trasy: routes.distanceMeters (w metrach).
  • Token trasy: routes.routeToken. Jest to nieprzezroczysty token, który reprezentuje dokładnie obliczoną trasę. Przekaż ten token do Navigation SDK, aby kierowca widział tę samą trasę dla ciężarówki. Więcej informacji znajdziesz w przewodnikach Navigation SDK na Android lub iOS.
Sprawdzanie flag bezpieczeństwa trasy

Gdy otrzymasz odpowiedź, najpierw sprawdź flagi bezpieczeństwa trasy. Jeśli podana trasa zawiera co najmniej 1 ograniczenie, które sprawia, że nie nadaje się ona 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ęte w odpowiedzi): trasa nie jest oznaczona. System znalazł trasę, która jest w pełni zgodna z parametrami podanymi w żądaniu.
  • true: trasa jest oznaczona. System nie mógł znaleźć w pełni zgodnej trasy i zwrócił trasę w trybie „możliwie najlepszej obsługi”, która może nie być bezpieczna lub zgodna z przepisami. Z tej trasy należy korzystać z dużą 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 początkowymi i docelowymi. Możesz na przykład użyć go do znalezienia najbliższej ciężarówki w nowym miejscu 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 u głównego poziomu żądania.

Przykład żądania 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ład odpowiedzi computeRouteMatrix

Odpowiedź to tablica, w której każdy obiekt zawiera czas trwania i distanceMeters dla 1 pary miejsc początkowych i docelowych.

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

Dalsze kroki