Генерация маршрутов и расчетного времени прибытия для крупногабаритных транспортных средств

Who this guide is for: Read this guide if you are a developer building services for trip planning and execution using trucks or other large vehicles. Relevant use cases include calculating travel times and distances, computing ETAs, or generating routes that will be used by a navigation application.

What this guide covers: This guide covers how to use the Routes API with Large Vehicle Routing to request routes, travel distance, predicted travel time, and ETAs that account for the specific attributes of a large vehicle, such as a commercial truck or a passenger bus.

Для получения информации о том, как выполнять вычисления на уровне автопарка для крупногабаритных транспортных средств с использованием API оптимизации маршрутов, см. документацию по оптимизации маршрутов для грузовых автомобилей .

Что вы узнаете

Вы научитесь делать следующее:

• Сформируйте действительный запрос маршрутизации.
• Укажите информацию о вашем реальном автомобиле, используя габариты, вес и другие характеристики.
• Проанализируйте полученный ответ, включая номер маршрутного жетона и флажки безопасности поездки.

Предварительные требования

1. Необходимо создать проект Google Cloud и включить API маршрутизации .
2. Для вашего проекта необходимо предусмотреть возможность организации маршрутов для крупногабаритных транспортных средств . Доступ к таким маршрутам предоставляется ограниченному кругу клиентов; свяжитесь с нами, чтобы запросить доступ.

Ограничения

Прежде чем начать, необходимо ознакомиться со следующими ограничениями и требованиями.

• Географическая доступность : Маршрутизация для крупногабаритных транспортных средств доступна на территории 48 континентальных штатов США (общедоступно) и Японии (экспериментально). Она недоступна на Аляске, Гавайях и территориях США.
• Driver advisory and safety . Drivers must not rely solely on routes returned by this API to be safe or legal. Routes are not guaranteed to be appropriate for the vehicle, and following them may expose drivers to hazards such as low bridges or roads where large vehicles are prohibited.
• Маршруты, соответствующие ограничениям . В некоторых случаях API не может найти маршрут, полностью соответствующий ограничениям на передвижение. Вместо этого он возвращает маршрут, соответствующий ограничениям, который может проходить через зоны с ограничениями. Ответ API Routes четко помечает такие маршруты в поле routeRestrictionsPartiallyIgnored . В таких случаях тщательно планируйте свой маршрут, в идеале используя другие исходные данные. Не используйте помеченный маршрут в качестве единственного источника достоверной информации для планирования или навигации.
• Неподдерживаемые функции : Маршрутизация крупногабаритных транспортных средств не поддерживает следующие функции:
  • цены на проезд по платным дорогам для грузовиков
  • Ограничения скорости
  • Маршрутизация радиоактивных опасных материалов
• Ограничения на использование: Все запросы подлежат стандартным ограничениям по количеству запросов в секунду (QPS) .

Создать запрос на маршрут для грузовика

To get a truck route, you send an HTTPS request to a Routes API endpoint with specific parameters that describe your vehicle. The concepts in this section apply to both single route and route matrix requests.

Конечные точки

Для маршрутизации грузовиков можно использовать две конечные точки:

• computeRoutes : Вычисляет единый маршрут между одной точкой отправления и одной точкой назначения.
• computeRouteMatrix : Вычисляет расстояние и продолжительность для матрицы пунктов отправления и назначения, но не возвращает полилинию маршрута.

Ключевые параметры запроса

Для включения маршрутизации грузовых автомобилей в тексте запроса необходимо указать следующие параметры:

• travelMode : Установите это значение на TRUCK .
• routingPreference : Установите это значение равным TRAFFIC_AWARE_OPTIMAL .
• routeModifiers : Этот объект содержит объект vehicleInfo , в котором вы определяете атрибуты вашего транспортного средства. Объект vehicleInfo подробно описан ниже.

Укажите характеристики транспортного средства.

In order to send a request, you must supply a request body with a vehicleInfo object that describes your vehicle. Think of this information as a specification that matches the physical details of your real-world vehicle. The service requires these details in order to return routes that take into account road restrictions based on your vehicle's attributes.

Измерения транспортного средства

Provide vehicle weight in kilograms and vehicle dimensions in millimeters, as indicated by the field names. For example, total height should be supplied in millimeters ( totalHeightMm ). Since truck dimensions are often expressed in feet or meters, this may require a unit conversion.

Перевод из имперской системы мер в метрическую.

When converting from imperial units, always consider your specific vehicle dimensions alongside standard road and underpass size limits. This can be especially important with fractional values. Depending on the size of the actual vehicle, rounding up a fractional value can result in overly restrictive routing for the vehicle.

Например:

• Width : Many US trailers have a width of 8' 6", which converts to 2,590.8mm. Rounding up to 2,591mm would indicate the vehicle is greater than 8' 6", which would classify it as an oversize vehicle on US roads. This would then result in a route that was computed according to meaningfully different constraints than intended.
• Height : A route leading under an 11' bridge wouldn't be suitable for a typical tractor-trailer with a height of 13.5'. However, smaller box trucks around 10' would be able to navigate the underpass. Accordingly, it's critical to specify your vehicle attributes accurately.

Ниже приведён фрагмент кода, демонстрирующий пример объекта vehicleInfo :

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

поля объекта vehicleInfo

В таблице ниже приведены все определения транспортных средств и грузов, которые вы можете отправить вместе с запросом.

Используйте маски поля.

Для достижения наилучших результатов включите в запрос заголовок X-Goog-FieldMask , чтобы точно указать, какие поля вы хотите видеть в ответе. Маски полей уменьшают задержку и гарантируют получение важных рекомендательных полей. Как минимум, всегда включайте routes.travelAdvisory.routeRestrictionsPartiallyIgnored в маску поля, поскольку это указывает, имеет ли маршрут одно или несколько ограничений, применимых к вашему транспортному средству.

Более подробную информацию о FieldMasks в Routes API см. в этой статье .

Плата за проезд

Чтобы отдавать предпочтение бесплатным маршрутам, укажите avoidTolls в свойстве routeModifiers запроса. Дополнительную информацию о модификаторах маршрута см. в разделе «Указание характеристик маршрута для избегания» .

Specifying avoidTolls does not guarantee toll-free routes in the response. In some cases, using a toll road is required to travel between the origin and destination. If you include routes.warnings in the fieldmask of your Routes API request, routes containing toll roads will be annotated accordingly within this field.

Другие варианты маршрутизации

When you set the travelMode to TRUCK , the API automatically optimizes the route for the maneuverability of large vehicles. Generated routes avoid U-turns and strongly prefer interstates and highways over smaller roads. You don't need to set any additional parameters or modifiers to enable these behaviors.

Рассчитайте единый маршрут с помощью computeRoutes

Используйте конечную точку computeRoutes для расчета маршрута, специфичного для грузовых автомобилей, между одной точкой отправления и одной точкой назначения.

Пример запроса computeRoutes

Вот полный пример запроса curl для типичного грузового автомобиля с полуприцепом. В этом примере указаны конечная точка, заголовки и тело запроса.

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
      }]
    }
  }
}'

Пример ответа computeRoutes

This is an example response for the previous request shown above. Note that in the travelAdvisory object, the routeRestrictionsPartiallyIgnored flag is not included. This indicates that the route is not flagged and is believed to be fully compliant with the vehicle's attributes.

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

Проанализируйте ответ computeRoutes

Успешный запрос к конечной точке computeRoutes возвращает объект JSON, содержащий один или несколько возможных маршрутов.

Ключевые поля ответа

• Закодированная геометрия маршрута : routes.polyline . Это можно использовать для отображения маршрута на карте.
• Estimated trip duration : routes.duration (in seconds). Large vehicle routing trip duration uses a new model trained on observed travel speeds of actual trucks on the road network. It can also be used to compute ETA by adding the estimated trip duration to the expected departure time.
• Общая протяженность маршрута : routes.distanceMeters (в метрах).
• Route token : routes.routeToken . This is an opaque token that represents the exact calculated route. You pass this token to the Navigation SDK to ensure the driver is shown the same truck-specific route. For details, see the Navigation SDK guides for Android or iOS .

Проверьте наличие флажков безопасности на маршруте.

When you get a response, the first thing you should do is check for route safety flags. If a provided route contains one or more restrictions making it unsuitable for the vehicle, you will find the travelAdvisory.routeRestrictionsPartiallyIgnored field set to true .

Это поле служит своего рода флагом, позволяющим ответить на вопрос: « Отмечен ли этот маршрут как потенциально проблемный ?»

• false (или отсутствует в ответе): Маршрут не помечен. Система обнаружила маршрут, который, по ее мнению, полностью соответствует параметрам, указанным вами в запросе.
• true : The route is flagged. The system could not find a fully compliant route and has returned a "best effort" route that may not be safe or legal . This route must be used with extreme caution.

Вычислить матрицу маршрутов ( computeRouteMatrix )

Используйте конечную точку computeRouteMatrix для эффективного сравнения времени в пути и расстояний между множеством пунктов отправления и назначения. Например, вы можете использовать ее для поиска ближайшего грузовика к новому месту погрузки. После того, как вы определите пункт отправления транспортного средства, который хотите использовать для своих целей, вы можете отправить запрос computeRoutes , чтобы получить подробную информацию о маршруте и токен маршрута для предлагаемого транспортного средства.

Для использования computeRouteMatrix необходимо указывать vehicleInfo внутри каждого объекта origin , а не в корне запроса.

Пример запроса 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"
}

Пример ответа computeRouteMatrix

В ответе получается массив, где каждый объект содержит значения duration и distanceMeters для одной пары "пункт отправления - пункт назначения".

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

Следующие шаги

• Обеспечьте пошаговую навигацию : узнайте, как использовать routeToken в SDK навигации для Android или iOS .
• Выполните оптимизацию на уровне автопарка : используйте API оптимизации маршрутов с маршрутизацией для крупногабаритных транспортных средств .
• Справочник по API : Полный список всех возможных полей и значений см. в Справочнике по API маршрутов .