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

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

Zakres tego przewodnika: ten przewodnik zawiera informacje o tym, jak używać interfejsu Routes API z funkcją routingu dla dużych pojazdów, aby wysyłać żądania dotyczące tras, odległości do pokonania, przewidywanego czasu podróży i szacowanego czasu przybycia, które uwzględniają konkretne atrybuty dużego pojazdu, takiego jak ciężarówka 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 interfejsie Route Optimization API.

Czego się nauczysz

Dowiesz się, jak:

  • Utwórz prawidłowe żądanie routingu.
  • Określ profil pojazdu dla rzeczywistego pojazdu, podając jego wymiary, wagę i inne cechy.
  • Interpretuj 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ć w nim Routes API.
  2. Twój projekt musi być skonfigurowany pod kątem wyznaczania tras dla pojazdów wielkogabarytowych. Aby to zrobić, skontaktuj się z przedstawicielem Google.

Ograniczenia

Zanim zaczniesz, zapoznaj się z tymi ograniczeniami i wymaganiami.

  • Dostępność geograficzna: wyznaczanie tras dla dużych pojazdów jest dostępne tylko w 48 stanach kontynentalnych Stanów Zjednoczonych.
  • Wyznaczanie tras dla dużych pojazdów jest dostępne w wersji podglądowej. Kierowcy nie mogą polegać wyłącznie na trasach zwracanych przez ten interfejs API, aby zapewnić bezpieczeństwo i zgodność z przepisami. Trasy nie są dostosowane do pojazdu, a podążanie nimi 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 o najwyższym priorytecie. W niektórych przypadkach interfejs API nie może znaleźć trasy, która w pełni spełnia wymagania dotyczące ograniczeń w podróżowaniu. Zamiast tego zwraca „najlepszą możliwą” trasę, która może 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 oflagowanej trasy jako jedynego źródła informacji do planowania ani nawigacji.
  • Nieobsługiwane funkcje: pracujemy nad dodaniem do tego oferowanego rozwiązania większej liczby funkcji, ale obecnie wyznaczanie tras dla dużych pojazdów nie obsługuje tych funkcji:
    • Opłaty za przejazd dla ciężarówek
    • Ograniczenia prędkości
    • Wyznaczanie tras dla radioaktywnych materiałów niebezpiecznych
  • 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 Routes API z określonymi parametrami opisującymi Twój pojazd.

Punkty końcowe

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

  • computeRoutes: oblicza pojedynczą trasę między jednym punktem początkowym a jednym punktem 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

W treści żądania musisz podać te informacje:

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

Określanie profilu pojazdu

Aby wysłać żądanie, musisz podać treść żądania z obiektem vehicleInfo, który opisuje Twój pojazd. Te informacje to specyfikacja odpowiadająca 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 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, więc może być konieczne przeliczenie jednostek.

Konwersja z jednostek imperialnych na metryczne

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

Na przykład:

  • Szerokość: wiele przyczep w Stanach Zjednoczonych ma szerokość 8 stóp i 6 cali, czyli 2590,8 mm. Zaokrąglenie do 2591 mm oznaczałoby, że pojazd ma ponad 2,59 m długości, co w Stanach Zjednoczonych kwalifikuje go jako pojazd ponadgabarytowy. W takim przypadku trasa zostałaby obliczona na podstawie innych ograniczeń niż zamierzone.
  • Wysokość: trasa prowadząca pod mostem o wysokości 3,35 m nie będzie odpowiednia dla typowego ciągnika siodłowego z przyczepą o wysokości 4,11 m. Jednak mniejsze furgony o długości około 3 m mogą przejechać pod wiaduktem. Dlatego tak ważne jest dokładne określenie atrybutów pojazdu.

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

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 pola obiektu

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

Pole Opis Notatki / 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 wszystkich przyczep. W milimetrach, zaokrąglone w dół.
totalWeightKg Masa całkowita pojazdu (wraz z przyczepami i ładunkiem). W kilogramach, zaokrąglona w dół.
totalAxleCount Łączna liczba osi pojazdu i przyczep. Dokładnie.
trailerInfo (opcjonalnie) Tablica obiektów, po jednym dla każdej przyczepy. Pomiń w przypadku pojazdu bez przyczep, np. furgonetki.
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 umieść nagłówek X-Goog-FieldMask, aby dokładnie określić pola, które mają się znaleźć w odpowiedzi. Maski pól zmniejszają opóźnienie i zapewniają otrzymywanie ważnych pól doradczych. W masce pola zawsze uwzględniaj co najmniej routes.travelAdvisory.routeRestrictionsPartiallyIgnored, ponieważ wskazuje ona, czy na trasie występują ograniczenia, które mają zastosowanie do Twojego pojazdu.

Więcej informacji o maskach FieldMask w interfejsie Routes API znajdziesz w tym artykule.

Opłat

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

Określenie wartości avoidTolls nie gwarantuje, że w odpowiedzi zostaną uwzględnione trasy bezpłatne. W niektórych przypadkach dojazd z miejsca początkowego do docelowego wymaga przejazdu drogą płatną. Jeśli w parametrze fieldmask żądania do interfejsu Routes API uwzględnisz routes.warnings, trasy zawierające drogi płatne będą odpowiednio oznaczone w tym polu.

Pełny przykład żądania curl

Oto pełne żądanie cURL dotyczące typowej naczepy. 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
      }]
    }
  }
}'

Interpretowanie odpowiedzi computeRoutes

Pomyślne żądanie do interfejsu Routes API zwraca obiekt odpowiedzi JSON zawierający co najmniej jedną możliwą trasę.

Kluczowe pola odpowiedzi

  • Zakodowana geometria trasy: routes.polyline. Można go użyć do wyrenderowania trasy na mapie.
  • Szacowany czas trwania podróży: routes.duration (w sekundach). Czas trwania podróży w przypadku wyznaczania tras dla dużych pojazdów jest obliczany na podstawie nowego modelu wytrenowanego na podstawie zaobserwowanych prędkości rzeczywistych ciężarówek w sieci dróg. Można go też używać do obliczania szacowanego czasu dotarcia na miejsce, dodając szacowany czas trwania podróży do przewidywanego czasu odjazdu.
  • Całkowita odległość trasy: routes.distanceMeters (w metrach).
  • Token trasy: routes.routeToken. Jest to nieprzezroczysty token, który reprezentuje dokładną obliczoną trasę. Przekazujesz ten token do pakietu SDK Navigation, aby kierowca widział tę samą trasę dostosowaną do ciężarówki. Więcej informacji o tym, jak to zrobić, znajdziesz w przewodniku Udostępnianie nawigacji krok po kroku.

Sprawdzanie flag bezpieczeństwa trasy

Gdy otrzymasz odpowiedź, w pierwszej kolejności sprawdź flagi bezpieczeństwa trasy. Jeśli podana trasa zawiera co najmniej jedno ograniczenie, które sprawia, że nie nadaje się ona dla danego pojazdu, pole travelAdvisory.routeRestrictionsPartiallyIgnored będzie miało wartość true.

To pole służy jako flaga, która odpowiada na pytanie: „Czy ta trasa jest oznaczona jako potencjalnie problematyczna?”.

  • false(lub pominięta w odpowiedzi): trasa nie jest oznaczona. System znalazł trasę, która prawdopodobnie 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ę „najlepszą z możliwych”, która może nie być bezpieczna ani zgodna z przepisami. Z tej trasy należy korzystać z zachowaniem najwyższej ostrożności.

Przykład: odpowiedź computeRoutes

Oto 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 jest uważana za w pełni zgodną z profilem pojazdu.

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

Pobieranie macierzy tras dla samochodów ciężarowych

Aby obliczyć czas podróży dla wielu potencjalnych wycieczek jednocześnie, użyj punktu końcowego computeRouteMatrix do planowania na wysokim poziomie, aby skutecznie porównywać czas podróży i odległości między wieloma punktami początkowymi i docelowymi. Możesz na przykład użyć tej funkcji, aby znaleźć najbliższą ciężarówkę w nowym punkcie odbioru. Po określeniu pochodzenia pojazdu, które chcesz wykorzystać, możesz wysłać computeRoutesżądanie, aby uzyskać szczegóły trasy i token trasy dla proponowanego pojazdu.

Aby użyć computeRouteMatrix, musisz określić vehicleInfo w każdym obiekcie źródłowym.

Przykładowe żądanie

{
  "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ź

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

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

Dalsze kroki