Маршрутизация

MapKit SDK можно использовать для построения оптимальных маршрутов по промежуточным точкам. Маршрутизация осуществляется с учетом параметров построения маршрута и особенностей вашего транспортного средства.

Запрос построения маршрутовЗапрос построения маршрутов

1. Создайте экземпляр класса YMKDrivingRouter.

   let drivingRouter: YMKDrivingRouter = YMKDirections.sharedInstance().createDrivingRouter(withType: .combined)
   

2. Задайте параметры построения маршрута при помощи класса YMKDrivingOptions.

   Пример создания параметров маршрута для запроса трех маршрутов.

   let drivingOptions: YMKDrivingOptions = {
       let options = YMKDrivingOptions()
       options.routesCount = 3
       return options
   }()
   

3. Чтобы определить параметры транспортного средства используйте класс YMKDrivingVehicleOptions.

   let vehicleOptions = YMKDrivingVehicleOptions()
   

4. Создайте новую сессию построения маршрута при помощи метода YMKDrivingRouter.requestRoutes(with:drivingOptions:vehicleOptions:routeHandler:).

   Пример запроса построения маршрута по двум точками.

   let points = [
       YMKRequestPoint(point: YMKPoint(latitude: 25.196141, longitude: 55.278543), type: .waypoint, pointContext: nil, drivingArrivalPointId: nil),
       YMKRequestPoint(point: YMKPoint(latitude: 25.171148, longitude: 55.238034), type: .waypoint, pointContext: nil, drivingArrivalPointId: nil)
   ]
   
   let drivingSession = drivingRouter.requestRoutes(
       with: requestPoints,
       drivingOptions: drivingOptions,
       vehicleOptions: vehicleOptions,
       routeHandler: drivingRouteHandler
   )
   

5. Используйте следующий механизм для получения результатов построения маршрута.

   Создайте объект типа YMKDrivingSessionRouteHandler:

   func drivingRouteHandler(drivingRoutes: [YMKDrivingRoute]?, error: Error?) {
       if let error {
           // Handle request routes error
           return
       }
   
       guard let drivingRoutes else {
           return
       }
   
       // Handle request routes success
   }
   

   Данная функция-обработчик передается в качестве аргумента во все методы создания сессии построения маршрутов.

Параметры построения маршрутаПараметры построения маршрута

Класс YMKDrivingOptions позволяет задать следующие параметры построения маршрута:

• initialAzimuth - задает направление движения в начальной точке маршрута, что позволяет определить, нужно ли делать разворот, и на какой полосе движется транспортное средство - на попутной или противоположной;
• routesCount - количество альтернативных маршрутов;
• avoidTolls - позволяет не строить маршруты по платным дорогам;
• avoidPoorConditions - позволяет не строить маршруты по дорогам в плохом состоянии, если это возможно;
• avoidUnpaved - позволяет избегать дорог грунтового покрытия, если это возможно;
• departureTime - время отправления.

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

При помощи класса YMKDrivingVehicleOptions можно задать вид транспортного средства, на котором передвигается пользователь. Поддерживаются следующие типы YMKDrivingVehicleType транспортных средств:

• стандартный - легковой автомобиль;
• грузовик;
• мотоцикл.

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

Существуют следующие виды грузовых ограничений:

• габариты: высота, длина и ширина;
• масса: общий вес, вес подвески, максимально допустимый вес и т.д.;
• наличие прицепа и эко-класс транспорта.

Сессия построения маршрутовСессия построения маршрутов

Для создания новой сессии построения маршрутов используется метод YMKDrivingRouter.requestRoutes(with:drivingOptions:vehicleOptions:routeHandler:). Построение маршрутов происходит по списку точек, которые передаются в качестве первого аргумента.

Точки маршрута делятся на два вида:

1. waypoint - используются для точек назначения. Например, для точек откуда, куда и точек остановок.
2. viapoint - используются для корректировки траектории маршрута. Маршрут обязательно должен быть построен через все via-точки.

В результате вызова метода построения маршрутов YMKDrivingRouter.requestRoutes(with:drivingOptions:vehicleOptions:routeHandler:) будет создана сессия запроса маршрутов. Сессия построения маршрутов представлена классом YMKDrivingSession. Она позволяет управлять состоянием процесса запроса маршрутов при помощи следующих методов:

• retry - перезапуск запроса построения маршрута;
• cancel - отмена текущего запроса.

Результаты построения маршрутовРезультаты построения маршрутов

Для получения результатов запроса построения маршрутов используется обработчик YMKDrivingSessionRouteHandler. Он принимается в качестве аргумента при вызове метода создания запроса построения маршрутов YMKDrivingRouter.requestRoutes(with:drivingOptions:vehicleOptions:routeHandler:).

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

1. response - оповещает об успешном завершении запроса построения маршрутов, если содержит не nil значение. Предоставляет список YMKDrivingRoute, который содержит информацию о результатах запроса.
2. error - оповещает о завершении запроса построения маршрутов с ошибкой, если не nil.

Запрос информации о маршрутах без геометрииЗапрос информации о маршрутах без геометрии

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

При помощи метода YMKDrivingRouter.requestRoutesSummary(with:drivingOptions:vehicleOptions:summaryHandler:) можно получить следующую информацию о маршрутах:

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

При помощи интерфейса YMKDrivingSummarySessionSummaryHandler можно получить результаты запроса сводки маршрутов. Он передается в качестве аргумента при вызове метода YMKDrivingRouter.requestRoutesSummary(with:drivingOptions:vehicleOptions:summaryHandler:).

Исходный кодИсходный код

Подробнее с примерами использования API можно ознакомиться в MapRouting демо-приложении в нашем репозитории на Github.