Рекомендации по использованию службы "Построение маршрутов" в Azure Maps

API маршрутов и матрицы маршрутов в службе маршрутов Azure Maps можно использовать для вычисления предполагаемого времени прибытия (ETAs) для каждого запрошенного маршрута. API маршрута учитывают такие факторы, как информация о дорожном движении в режиме реального времени и исторические данные дорожного движения, такие как типичные скорости дорожного движения по запрошенной дате и времени. Этот API возвращает самые короткие или самые быстрые маршруты до нескольких мест назначения одновременно, упорядочивая их в порядке увеличения времени или расстояния, а также с оптимизацией. Пользователи также могут запрашивать особые маршруты и данные для пешеходов, велосипедистов и коммерческих автомобилей, таких как грузовики. В этой статье рассматриваются рекомендации по вызову службы маршрутизации Azure Maps, включая практическое руководство.

• Выбор между интерфейсами API маршрутных инструкций и матрицы маршрутов
• Запрос с предысторией и прогнозируемым временем поездки на основе данных в реальном времени и истории трафика
• Запрос сведений о маршруте, например времени и расстояния, для всего маршрута и каждого его участка
• Запрос маршрута для коммерческого транспортного средства, например грузовика
• Запрос сведений о трафике на маршруте, например о наличии заторов и платных участков
• Запрос маршрута, состоящего из одной или нескольких остановок (маршрутных точек)
• Оптимизация маршрута из одной или нескольких остановок (маршрутных точек) таким образом, чтобы выбрать оптимальный порядок посещения каждой из них
• Оптимизация альтернативных маршрутов с использованием вспомогательных точек. Например, можно выбирать альтернативные маршруты, которые проходят через зарядные станции для электромобилей.
• Использование службы маршрутизации с веб-пакетом SDK для Azure Maps

Необходимые компоненты

• Учетная запись Azure Maps
• Ключ подписки

Дополнительные сведения о охвате службы маршрутизации см. в разделе "Покрытие маршрутизации".

Вы можете использовать любую среду разработки API, например Postman или бруно , для выполнения примеров HTTP-запросов, показанных в этой статье, или для создания вызовов REST.

Выбор между маршрутными инструкциями и матрицей маршрутов

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

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

• Определение самого короткого или самого быстрого маршрута между двумя или более известными точками, чтобы рассчитать точное время прибытия автомобиля службы доставки.
• Выработка подробных маршрутных инструкций, включая геометрию маршрута, для визуализации маршрутов на карте.
• Расчет кратчайших возможных маршрутов на основе списка расположений клиентов таким образом, чтобы посетить каждую точку и вернуться в точку отправления. Этот сценарий обычно называют задачей коммивояжера. В одном запросе можно передать до 150 маршрутных точек (остановок).
• Для отправки пакетных запросов в API пакетной обработки маршрутных инструкций достаточно всего одного вызова API.

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

• Расчет времени поездки или расстояний между набором исходных точек и точек назначения. Например, у вас есть 12 водителей и вам нужно найти ближайшего доступного из них, чтобы забрать еду из ресторана для доставки.
• Сортировка потенциальных маршрутов по фактическому расстоянию или времени поездки. API матриц возвращает только время и расстояния для каждого сочетания точек отправки и назначения.
• Данные кластеризуются на основе времени поездки или расстояний. Например, у вашей компании есть 50 сотрудников, найдите всех сотрудников, которые живут в течение 20 минут времени от офиса.

Ниже приведено сравнение некоторых возможностей API маршрутов и матриц:

Дополнительные сведения о возможностях построения маршрутов для электромобилей см. в нашем руководстве по построению маршрутов для электромобилей с помощью Azure Notebooks и Python.

Запрос накопленных данных и данных реального времени

По умолчанию служба "Построение маршрутов" предполагает, что используется легковой автомобиль, а время отправления — сейчас. Она возвращает маршрут на основе сведений о дорожном движении в режиме реального времени, если в запросе на вычисление маршрута не указано иное. Факторы подсистемы маршрутизации фиксированные ограничения трафика, зависящие от времени, например "Левые повороты не допускаются в период от 4:00 до 6:00 вечера". Закрытие дорог, таких как дорожные работы, считаются, если вы специально не запрашиваете маршрут, который игнорирует текущий динамический трафик. Чтобы проигнорировать текущие дорожные условия, задайте в запросе API для параметра traffic значение false.

Значение travelTimeInSeconds в запросе API вычисления маршрута включает задержку из-за дорожного движения. Он создается с помощью текущих и исторических данных времени путешествия, когда задано время отъезда. Если задать время отправления в будущем, интерфейсы API вернут прогнозируемое время поездки на основе накопленных данных.

Если в запрос включен параметр computeTravelTimeFor=all , элемент сводки в ответе содержит следующие поля, включая исторические условия трафика:

В следующих разделах показано, как выполнять вызовы интерфейсов API построения маршрутов с использовать рассматриваемых параметров.

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

В первом примере ниже время отправления задается в будущем относительно момента написания статьи.

https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0&query=51.368752,-0.118332:51.385426,-0.128929&travelMode=car&traffic=true&departAt=2025-03-29T08:00:20&computeTravelTimeFor=all

Ответ содержит элемент сводки, как показано в следующем примере. Так как время отправления относится к будущему, значение trafficDelayInSeconds равно нулю. Значение travelTimeInSeconds вычисляется с использованием данных о дорожном движении для конкретного времени. Таким образом, в данном случае значение travelTimeInSeconds равно значению historicTrafficTravelTimeInSeconds.

"summary": {
    "lengthInMeters": 2131,
    "travelTimeInSeconds": 248,
    "trafficDelayInSeconds": 0,
    "departureTime": "2025-03-29T08:00:20Z",
    "arrivalTime": "2025-03-29T08:04:28Z",
    "noTrafficTravelTimeInSeconds": 225,
    "historicTrafficTravelTimeInSeconds": 248,
    "liveTrafficIncidentsTravelTimeInSeconds": 248
},

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

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

https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0&query=47.6422356,-122.1389797:47.6641142,-122.3011268&travelMode=car&traffic=true&computeTravelTimeFor=all

Ответ содержит сводку, как показано в следующем примере. Из-за перегрузки значение trafficDelaysInSeconds больше нуля. Оно также больше, чем historicTrafficTravelTimeInSeconds.

"summary": {
    "lengthInMeters": 16637, 
    "travelTimeInSeconds": 2905, 
    "trafficDelayInSeconds": 1604, 
    "departureTime": "2020-02-28T01:00:20+00:00",
    "arrivalTime": "2020-02-28T01:48:45+00:00", 
    "noTrafficTravelTimeInSeconds": 872, 
    "historicTrafficTravelTimeInSeconds": 1976, 
    "liveTrafficIncidentsTravelTimeInSeconds": 2905 
},

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

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

На изображении ниже показан элемент points.

Разверните элемент point, чтобы просмотреть список координат пути:

API маршрутных инструкций поддерживают различные форматы инструкций, которые можно выбрать с помощью параметра instructionsType. Для приведения инструкций в удобный формат для компьютерной обработки используйте параметр instructionsType=coded. Чтобы отобразить инструкции в виде текста для пользователя, используйте параметр instructionsType=tagged. Кроме того, инструкции можно отформатировать как текст, в котором отмечены некоторые элементы инструкций, а инструкции отображаются с применением специального форматирования. Дополнительные сведения см. в списке поддерживаемых тегов инструкций.

При запросе инструкций ответ возвращает новый элемент под названием guidance. Элемент guidance содержит два фрагмента данных: пошаговые инструкции и обобщенные инструкции.

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

Запрос маршрута для коммерческого автомобиля

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

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

В примере запроса ниже запрашивается маршрут для коммерческого грузовика. Грузовик везет опасные отходы класса 1.

https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0&vehicleWidth=2&vehicleHeight=2&vehicleCommercial=true&vehicleLoadType=USHazmatClass1&travelMode=truck&instructionsType=text&query=51.368752,-0.118332:41.385426,-0.128929

API маршрутов возвращает инструкции с учетом размеров грузовика и опасного характера груза. Чтобы прочитать маршрутные инструкции, разверните элемент guidance.

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

Изменение класса US Hazmat из приведенного выше запроса приводит к изменению другого маршрута.

https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0&vehicleWidth=2&vehicleHeight=2&vehicleCommercial=true&vehicleLoadType=USHazmatClass9&travelMode=truck&instructionsType=text&query=51.368752,-0.118332:41.385426,-0.128929

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

Запрос сведений о дорожном движении на маршруте

С помощью API маршрутных инструкций Azure Maps разработчики могут запрашивать сведения для сегментов каждого типа, добавляя в запрос параметр sectionType. Например, можно запросить сведения о скорости для каждого сегмента с затором. Сведения о различных данных, которые можно запрашивать, см. в списке значений для ключа sectionType.

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

В следующем запросе для параметра sectionType установлено значение traffic. Он запрашивает секции, содержащие сведения о дорожном движении на участке от Сиэтла до Сан-Диего.

https://atlas.microsoft.com/route/directions/json?subscription-key={Your-Azure-Maps-Subscription-key}&api-version=1.0&sectionType=traffic&query=47.6062,-122.3321:32.7157,-117.1611

Ответ содержит сегменты, которые соответствуют дорожному движению по заданным координатам.

Этот параметр можно использовать для цвета разделов при отрисовке карты, как показано на следующем рисунке:

Вычисление и оптимизация маршрутов с остановками

В настоящее время Azure Maps предлагает две формы оптимизации маршрутов:

• Оптимизации на основе запрошенного типа маршрута без изменения порядка маршрутных точек. Дополнительные сведения см. в разделе RouteType.

• Оптимизация для задачи коммивояжера, которая изменяет порядок маршрутных точек, чтобы получить оптимальную последовательность их посещения.

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

Если вы хотите оптимизировать маршрут для оптимальной последовательности посещения заданных маршрутных точек, необходимо указать параметр computeBestOrder=true. Этот сценарий также известен как оптимизация решения задачи коммивояжера.

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

Следующий запрос запрашивает путь для шести маршрутных точек, и для параметра computeBestOrder задано значение false. Это значение для параметра computeBestOrder используется по умолчанию.

https://atlas.microsoft.com/route/directions/json?api-version=1.0&subscription-key={Your-Azure-Maps-Subscription-key}&computeBestOrder=false&query=47.606544,-122.336502:47.759892,-122.204821:47.670682,-122.120415:47.480133,-122.213369:47.615556,-122.193689:47.676508,-122.206054:47.495472,-122.360861

В ответе представлен маршрут длиной 140 851 м, поездка по которому займет 9991 секунду.

На следующем рисунке показан путь, полученный из этого запроса. Этот путь является одним из возможных маршрутов. Он не является оптимальным по времени или расстоянию.

Для этого маршрута порядок точек таков: 0, 1, 2, 3, 4, 5 и 6.

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

Следующий запрос запрашивает путь для тех же шести точек, что и в приведенном выше примере. На этот раз для параметра computeBestOrder задано значение true (оптимизация решения задачи коммивояжера).

https://atlas.microsoft.com/route/directions/json?api-version=1.0&subscription-key={Your-Azure-Maps-Subscription-key}&computeBestOrder=true&query=47.606544,-122.336502:47.759892,-122.204821:47.670682,-122.120415:47.480133,-122.213369:47.615556,-122.193689:47.676508,-122.206054:47.495472,-122.360861

В ответе представлен маршрут длиной 91 814 м, поездка по которому займет 7797 секунд. Расстояние и время поездки меньше, так как API вернул оптимизированный маршрут.

На следующем рисунке показан путь, полученный из этого запроса.

Для оптимального маршрута порядок точек таков: 0, 5, 1, 2, 4, 3 и 6.

Расчет альтернативных маршрутов и их смещение с использованием вспомогательных точек

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

1. Рассчитайте изначальный маршрут и возьмите путь из полученного ответа.
2. На основе этого маршрута найдите нужные точки вдоль пути. Например, можно использовать запрос "Точка интереса" или запрашивать собственные данные в базе данных.
3. Упорядочьте точки в зависимости от расстояния от начала маршрута.
4. Добавьте эти расположения в качестве вспомогательных точек в новом запросе маршрута в пути после маршрута. Дополнительные сведения о вспомогательных точках см. в документации по POST-запросам к API маршрутных инструкций.

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

На следующем рисунке показан пример отрисовки альтернативных маршрутов с указанными ограничениями отклонения для времени и расстояния.

Использование службы "Построение маршрутов" в веб-приложении

Пакет SDK веб-версии Azure Maps содержит модуль служб. Этот модуль является вспомогательной библиотекой, упрощающей работу с REST API Azure Maps в веб-приложениях и приложениях Node.js за счет использования JavaScript или TypeScript. Модуль служб можно использовать для отрисовки возвращаемых маршрутов на карте. Он автоматически определяет, какой API следует использовать с запросами GET и POST.