Расчет маршрутов

Инструмент compute_routes возвращает маршрут между пунктами отправления и назначения для заданного способа передвижения. Ответ включает расстояние и продолжительность маршрута. По умолчанию маршруты рассчитываются без учета загруженности дорог. В Pro добавляется маршрутизация с учетом загруженности дорог в реальном времени и маршруты с большим количеством промежуточных остановок.

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

Параметры запроса

Option Описание
origin, destination Обязательно. Каждый из них представляет собой путевую точку: address (человекочитаемый адрес или плюс-код), place_id или lat_lng. Вы можете использовать разные форматы, например адрес для пункта отправления и идентификатор места для пункта назначения.
travel_mode Способ передвижения: DRIVE (по умолчанию), WALK, BICYCLE или TRANSIT. Маршруты для WALK находятся на этапе бета-тестирования, поэтому на них могут отсутствовать тротуары или пешеходные дорожки. Вы должны показывать это предупреждение пользователю для всех пешеходных маршрутов, которые вы показываете в своем приложении.
routing_preference Как данные о трафике используются для расчета маршрута: ROUTING_PREFERENCE_TRAFFIC_UNAWARE (по умолчанию) или ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL (функция Pro). ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL не поддерживается для WALK или BICYCLE. Подробнее о маршрутах с учетом загруженности дорог…
intermediate_waypoints Упорядоченные остановки между пунктами отправления и назначения. Маршрут проходит через них в указанном порядке. Запрос может содержать до 10 промежуточных путевых точек или от 11 до 25, если вы используете версию Pro. Если в запросе указано больше 25 пунктов, возвращается ошибка INVALID_ARGUMENT. Маршруты общественного транспорта не поддерживают промежуточные путевые точки.
departure_time или arrival_time Время отправления из пункта отправления или прибытия в пункт назначения в формате RFC 3339. Укажите не более одного значения. По умолчанию используется текущее время отправления. Для TRANSIT можно указать время в пределах 7 дней в прошлом или 100 дней в будущем. Для других способов передвижения время не может быть в прошлом и может быть до 365 дней в будущем.
compute_alternative_routes Если задано значение true, ответ включает альтернативные маршруты в дополнение к рекомендуемому (если они доступны). Значение по умолчанию – false.
include_polyline Если true, каждый маршрут в ответе включает encodedPolyline. Значение по умолчанию – false.
location_bias Широта и долгота, которые влияют на то, как разрешаются текстовые путевые точки, например, для устранения неоднозначности адреса.

Профессиональные функции

Два варианта выбора SKU Pro. Запрос, в котором используется одна или обе функции, оплачивается по коду Pro:

Версия Pro Для чего его можно использовать
Адрес "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL" сохранен с ярлыком "routing_preference". Пользователь спрашивает о пробках, заторах или времени в пути с учетом текущей ситуации на дорогах. Подробнее о маршрутах с учетом загруженности дорог…
11–25 intermediate_waypoints На маршруте между пунктами отправления и назначения должно быть более 10 остановок.

Все остальные варианты, включая режим поездки, время, альтернативные маршруты, ломаные линии и приоритет местоположения, оплачиваются по коду Essentials.

Маршруты с учетом загруженности дорог

По умолчанию маршруты рассчитываются без учета загруженности дорог (ROUTING_PREFERENCE_TRAFFIC_UNAWARE). При этом задержка минимальна. Этот вариант подходит для запросов, в которых трафик не имеет значения или не применяется, например для пешеходных маршрутов или приблизительного планирования.

Задайте для параметра routing_preference значение ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL, чтобы рассчитать маршрут и его продолжительность с учетом текущей загруженности дорог (если данные о ней доступны). Используйте его, когда пользователь спрашивает, сколько времени займет поездка прямо сейчас. Для маршрутов TRANSIT эта настройка использует данные о транспорте в реальном времени, например о задержках и отменах, если они доступны. Он не поддерживается для маршрутов WALK и BICYCLE. Запросы с такими маршрутами возвращают ошибку INVALID_ARGUMENT. Это вариант Pro, поэтому счет за запрос выставляется по коду Pro. Кроме того, этот вариант увеличивает задержку.

Во время ограниченной общей доступности, если ваш проект не находится в белом списке Pro, этот параметр обрабатывается как ROUTING_PREFERENCE_TRAFFIC_UNAWARE. Подробнее о возможностях Pro во время ограниченного общего доступа…

Пример

В следующем запросе запрашивается маршрут с учетом трафика с одной промежуточной остановкой и закодированной ломаной линией. Оплата взимается по коду Pro:

{
  "method": "tools/call",
  "params": {
    "name": "compute_routes",
    "arguments": {
      "origin": {"address": "Ferry Building, San Francisco, CA"},
      "destination": {"address": "Golden Gate Park, San Francisco, CA"},
      "intermediate_waypoints": [
        {"address": "Palace of Fine Arts, San Francisco, CA"}
      ],
      "travel_mode": "DRIVE",
      "routing_preference": "ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL",
      "include_polyline": true
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}

Ответ

Ответ содержит routes[], упорядоченные от наиболее до наименее рекомендуемых. Возвращается только один маршрут, если для параметра compute_alternative_routes не задано значение true. Каждый маршрут включает:

  • distanceMeters – расстояние маршрута в метрах.
  • duration – время, необходимое для прохождения маршрута. При использовании ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL продолжительность рассчитывается с учетом загруженности дорог.
  • encodedPolyline – путь маршрута в виде закодированной ломаной линии, если для include_polyline задано значение true. Вы можете использовать его, чтобы нарисовать маршрут на карте с помощью других API платформы Google Карт.
  • attribution – указание авторства, которое должно отображаться вместе с маршрутом. Подробнее о требованиях к указанию авторства…

Варианты перехода на Pro в период ограниченной общей доступности

В период ограниченной общей доступности функции Pro доступны только для проектов из белого списка Pro. Если ваш проект ещё не добавлен в белый список:

  • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL обрабатывается как ROUTING_PREFERENCE_TRAFFIC_UNAWARE, и запрос оплачивается по коду Essentials.
  • Если в запросе указано более 10 промежуточных путевых точек, возвращается ошибка INVALID_ARGUMENT ("Поддерживается не более 10 промежуточных путевых точек").

Чтобы запросить доступ, ознакомьтесь с разделом Варианты Pro во время ограниченного общего доступа.

Оплата и квоты

Каждый запрос compute_routes – это одно оплачиваемое событие:

  • Запрос, в котором не используются функции Pro, оплачивается по коду Essentials SKU.
  • Запрос, в котором используется вариант Pro, оплачивается по коду Pro. Если вы используете обе функции Pro в одном запросе, стоимость не изменится. Цены на Pro указаны в разделе Сравнение Essentials, Pro и обоснования с Google Картами.

Запрос альтернативных маршрутов, ломаной линии, времени отправления или времени прибытия, а также другого способа передвижения не влияет на SKU.

Квота compute_routes составляет 300 запросов в минуту на проект и распространяется на оба SKU. Цены приведены в основной таблице цен и таблице цен для Индии.

Ограничения

  • Запрос может содержать не более 25 промежуточных путевых точек. От 11 до 25 – это вариант Pro. Если в запросе указано большее количество, возвращается ошибка INVALID_ARGUMENT.
  • Маршруты общественного транспорта не поддерживают промежуточные путевые точки. Запрос на построение маршрута общественного транспорта с промежуточными путевыми точками возвращает ошибку INVALID_ARGUMENT.
  • ROUTING_PREFERENCE_TRAFFIC_AWARE_OPTIMAL не поддерживается для пеших и велосипедных маршрутов.
  • Для маршрутов общественного транспорта время отправления и время прибытия может быть до 7 дней в прошлом или до 100 дней в будущем. Для других способов передвижения время отправления не может быть в прошлом и может быть установлено на 365 дней вперед.
  • Координаты путевой точки должны находиться в допустимых географических границах (широта от -90 до 90, долгота от -180 до 180).
  • Инструмент не возвращает пошаговые инструкции, этапы или сведения о маршрутах общественного транспорта.