Присоединяйтесь к нам на следующем Дне сообщества разработчиков платформы Google Карт в Сан-Франциско в декабре. Чтобы принять участие, подайте заявку.

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

Как создавать маршруты и рассчитывать время прибытия для крупногабаритного транспорта

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

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

Информацию о том, как выполнять расчеты на уровне автопарка для крупных транспортных средств с помощью Route Optimization API, можно найти в документации по Route Optimization Truck Routing.

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

Вы узнаете, как:

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

Требования

У вас должен быть создан облачный проект Google Cloud с включенным Routes API.
Ваш проект должен быть подготовлен для Large Vehicle Routing. Прокладка маршрутов для крупногабаритного транспорта доступна ограниченному числу клиентов. Чтобы запросить доступ, свяжитесь с нами.

Ограничения

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

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

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

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

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

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

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

Основные параметры запроса

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

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

Укажите атрибуты транспортного средства

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

Размеры транспортного средства

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

Преобразование из британской системы мер в метрическую

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

Пример:

Ширина. Многие прицепы в США имеют ширину 8 футов 6 дюймов, что составляет 2590,8 мм. Если округлить это значение до 2591 мм, то получится, что ширина автомобиля превышает 8 футов 6 дюймов, а значит, он будет классифицирован как крупногабаритный. В результате маршрут будет рассчитан с учетом ограничений, которые существенно отличаются от заданных.
Высота. Маршрут, проходящий под мостом высотой 3,3 м, не подходит для стандартного тягача с полуприцепом высотой 4,1 м. Однако небольшие грузовики, около 3 метров, смогут проехать под путепроводом. Поэтому очень важно точно указывать атрибуты автомобилей.

Диаграмма, на которой сравниваются размеры грузовика и путепровода

Ниже приведен пример фрагмента кода vehicleInfo:

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

Поля объекта `vehicleInfo`

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

Поле	Описание	Примечания / значения
`totalHeightMm`	Максимальная высота транспортного средства.	В миллиметрах, округленных в меньшую сторону. Подробнее о преобразовании английских единиц измерения в метрические…
`totalWidthMm`	Максимальная ширина транспортного средства.	В миллиметрах, округленных в меньшую сторону.
`totalLengthMm`	Общая длина транспортного средства и всех прицепов.	В миллиметрах, округленных в меньшую сторону.
`totalWeightKg`	Полная масса транспортного средства (включая прицепы и груз).	В килограммах, округленное в меньшую сторону.
`totalAxleCount`	Общее количество осей автомобиля и прицепов.	Точное.
`trailerInfo` (необязательно)	Массив объектов, по одному для каждого трейлера.	Для транспортных средств без прицепов, например фургонов, указывать это значение не нужно.
`hazardousGoodsTypes` (необязательно)	Массив, указывающий на наличие опасных материалов на борту.	EXPLOSIVES, GASES, FLAMMABLE, COMBUSTIBLE, ORGANIC, POISON, CORROSIVE, ASPIRATION_HAZARD, ENVIRONMENTAL_HAZARD, OTHER

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

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

Подробнее о FieldMasks в Routes API читайте в этой статье.

Платные дороги

Чтобы предпочесть бесплатные маршруты, укажите avoidTolls в свойстве routeModifiers запроса. Подробнее о модификаторах маршрута…

Указание avoidTolls не гарантирует, что в ответе будут только бесплатные маршруты. В некоторых случаях без платных дорог не обойтись. Если вы включите routes.warnings в маску поля запроса к 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. Это непрозрачный токен, который представляет точно рассчитанный маршрут. Вы передаете этот токен в Navigation SDK, чтобы водителю был показан тот же маршрут для грузовиков. Подробную информацию вы найдете в руководствах по Navigation SDK для Android и iOS.

Проверьте, есть ли на маршруте пометки о безопасности

Получив ответ, в первую очередь проверьте, есть ли в нем пометки о безопасности маршрута. Если маршрут содержит одно или несколько ограничений, делающих его непригодным для транспортного средства, поле 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`

Ответ представляет собой массив, в котором каждый объект содержит продолжительность и distanceMeters для одной пары "пункт отправления – пункт назначения".

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

Дальнейшие действия

Пошаговая навигация. Узнайте, как использовать routeToken в Navigation SDK для Android или iOS.
Оптимизация на уровне автопарка. Используйте Route Optimization API с Large Vehicle Routing.
Документация по API. Полный список всех возможных полей и значений приведен в документации по Routes API.