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

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

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

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

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

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

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

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

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

Ограничения

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

  • Географическая доступность : Маршрутизация для крупногабаритных транспортных средств доступна только на территории 48 смежных штатов США .
  • Рекомендации для водителей и правила безопасности . Водители не должны полагаться исключительно на маршруты, возвращаемые этим API, как на безопасные или законные. Маршруты не гарантируют соответствия транспортному средству, и следование им может подвергнуть водителей опасностям, таким как низкие мосты или дороги, где запрещено движение крупногабаритных транспортных средств.
  • Маршруты, соответствующие ограничениям . В некоторых случаях API не может найти маршрут, полностью соответствующий ограничениям на передвижение. Вместо этого он возвращает маршрут, соответствующий ограничениям, который может проходить через зоны с ограничениями. Ответ API Routes четко помечает такие маршруты в поле routeRestrictionsPartiallyIgnored . В таких случаях тщательно планируйте свой маршрут, в идеале используя другие исходные данные. Не используйте помеченный маршрут в качестве единственного источника достоверной информации для планирования или навигации.
  • Неподдерживаемые функции : Маршрутизация крупногабаритных транспортных средств не поддерживает следующие функции:
    • цены на проезд по платным дорогам для грузовиков
    • Ограничения скорости
    • Маршрутизация радиоактивных опасных материалов
  • Ограничения на использование: Все запросы подлежат стандартным ограничениям по количеству запросов в секунду (QPS) .

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

Чтобы получить маршрут для грузовика, необходимо отправить HTTPS-запрос к конечной точке API маршрутов с указанием параметров, описывающих ваше транспортное средство. Принципы, описанные в этом разделе, применимы как к запросам отдельных маршрутов, так и к запросам матрицы маршрутов.

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

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

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

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

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

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

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

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

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

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

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

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

Например:

  • Ширина : Ширина многих прицепов в США составляет 8 футов 6 дюймов, что в пересчете на 2590,8 мм. Округление до 2591 мм означает, что транспортное средство превышает 8 футов 6 дюймов, что классифицирует его как негабаритное транспортное средство на дорогах США. В результате маршрут будет рассчитан с учетом существенно отличающихся от запланированных ограничений.
  • Высота : Маршрут, проходящий под мостом высотой 11 футов, не подойдет для типичного грузовика с прицепом высотой 13,5 футов. Однако небольшие грузовые автомобили высотой около 10 футов смогут проехать под путепроводом. Соответственно, крайне важно точно указать характеристики вашего транспортного средства.

A diagram illustrating the dimensions of a truck against the dimensions of an underpass

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

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

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

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

Поле Описание Примечания / Значения
totalHeightMm Максимальная высота транспортного средства. В миллиметрах, округлено в меньшую сторону. Подробнее об округлении см. раздел «Перевод из имперской системы в метрическую» .
totalWidthMm Максимальная ширина транспортного средства. В миллиметрах, округлено в меньшую сторону.
totalLengthMm Общая длина транспортного средства и всех прицепов. В миллиметрах, округлено в меньшую сторону.
totalWeightKg Полная масса транспортного средства (включая прицепы и груз). В килограммах, округлено в меньшую сторону.
totalAxleCount Общее количество осей на транспортном средстве и любых прицепах. Точный.
trailerInfo (Необязательно) Набор объектов, по одному для каждого прицепа. Исключить для транспортного средства без прицепа, например, грузового автомобиля.
hazardousGoodsTypes (необязательно) Массив, указывающий на наличие на борту любых опасных материалов. Взрывчатые вещества, газы, легковоспламеняющиеся, горючие, органические, ядовитые, коррозионные, опасность при вдыхании, опасность для окружающей среды, другие.

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

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

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

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

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

Указание параметра avoidTolls не гарантирует бесплатных маршрутов в ответе. В некоторых случаях для поездки между пунктом отправления и пунктом назначения требуется использование платной дороги. Если вы включите routes.warnings в fieldmask вашего запроса Routes API, маршруты, содержащие платные дороги, будут соответствующим образом помечены в этом поле.

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

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

Рассчитайте единый маршрут с помощью 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

Это пример ответа на предыдущий запрос, показанный выше. Обратите внимание, что в объекте travelAdvisory отсутствует флаг routeRestrictionsPartiallyIgnored . Это означает, что маршрут не помечен и считается полностью соответствующим атрибутам транспортного средства.

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

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

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

Ключевые поля ответа
  • Закодированная геометрия маршрута : routes.polyline . Это можно использовать для отображения маршрута на карте.
  • Расчетная продолжительность поездки : routes.duration (в секундах). Расчет продолжительности поездки для крупногабаритных транспортных средств использует новую модель, обученную на основе наблюдаемых скоростей движения реальных грузовиков по дорожной сети. Ее также можно использовать для расчета расчетного времени прибытия, сложив расчетную продолжительность поездки с ожидаемым временем отправления.
  • Общая протяженность маршрута : routes.distanceMeters (в метрах).
  • Токен маршрута : routes.routeToken . Это непрозрачный токен, представляющий собой точный рассчитанный маршрут. Вы передаете этот токен в SDK навигации, чтобы гарантировать, что водителю будет показан тот же маршрут, специфичный для грузовика. Для получения более подробной информации о том, как это сделать, ознакомьтесь с руководством по предоставлению пошаговой навигации .
Проверьте наличие флажков безопасности на маршруте.

Получив ответ, первым делом следует проверить наличие флагов безопасности маршрута. Если предоставленный маршрут содержит одно или несколько ограничений, делающих его непригодным для данного транспортного средства, поле travelAdvisory.routeRestrictionsPartiallyIgnored будет установлено в значение true .

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

  • false (или отсутствует в ответе): Маршрут не помечен. Система обнаружила маршрут, который, по ее мнению, полностью соответствует параметрам, указанным вами в запросе.
  • true : Маршрут помечен как небезопасный. Система не смогла найти полностью соответствующий требованиям маршрут и вернула маршрут, предложенный «наиболее вероятно», который может быть небезопасным или незаконным . Этот маршрут следует использовать с особой осторожностью.

Вычислить матрицу маршрутов ( 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"
  },
  { ... }
]

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