Как проложить маршрут с помощью Directions API (устаревшая версия)

Разработчики из Европейской экономической зоны (ЕЭЗ)

Этот продукт имеет устаревший статус. С октября 2026 г. Directions API (Legacy) нельзя будет включить для новых облачных проектов Google Cloud. Существующие проекты по-прежнему полностью поддерживаются. Чтобы получить доступ к новым функциям и повысить производительность, перейдите на Routes API.

Для расчета маршрутов, которые реагируют на действия пользователя в реальном времени (например, в элементе пользовательского интерфейса), можно использовать Directions API (Legacy) или, если вы используете Maps JavaScript API, сервис Directions. Для серверной части можно использовать клиенты Java, Python, Go и Node.js для веб-сервисов Google Карт.

С помощью Directions API (устаревшая версия) вы можете:

  • Поиск маршрутов для разных способов передвижения, включая общественный транспорт, автомобиль, велосипед и пешую прогулку.
  • Отображение маршрутов, состоящих из нескольких частей, с использованием наборов промежуточных точек маршрута.
  • Укажите пункты отправления и назначения, а также путевые точки в виде текстовых строк (например, "Чикаго, Иллинойс" или "Дарвин, Северная территория, Австралия"), идентификаторов мест или координат широты и долготы.

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

Подготовка

Чтобы начать работу, вам потребуется создать проект с платежным аккаунтом и включенным Directions API (Legacy). Подробнее о настройке в Cloud Console…

Как создавать запросы к Directions API (Legacy)

Запрос к Directions API (Legacy) имеет следующий вид:

https://maps.googleapis.com/maps/api/directions/outputFormat?parameters

где outputFormat может принимать одно из следующих значений:

  • json (рекомендуется) – вывод в формате JSON (JavaScript Object Notation).
  • xml указывает, что выходные данные должны быть в формате XML.

Примечание. Чтобы URL был действительным, он должен быть правильно закодирован. Для всех веб-сервисов длина URL не должна превышать 16 384 символа. Учитывайте это ограничение при создании URL.

Параметры разделяются амперсандами (&) в соответствии со стандартом написания URL. Все зарезервированные символы (например, знак плюса "+") должны быть закодированы в URL. Ниже представлен список параметров и их допустимых значений.

Обязательные параметры

  • целевой аккаунт

    Идентификатор места, адрес или текстовое значение широты/долготы, до которого вы хотите рассчитать маршрут. Варианты для параметра destination такие же, как и для origin.

  • происхождение

    Идентификатор места, адрес или текстовое значение широты/долготы, от которого вы хотите рассчитать маршрут.

    • Идентификаторы мест должны начинаться с префикса place_id:. Идентификаторы мест можно получить от Geocoding API и Places API (включая автозаполнение мест). Пример использования идентификаторов мест из сервиса автозаполнения мест можно найти в документе Автозаполнение мест и маршруты. Подробнее об идентификаторах мест… 

      origin=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE

    • Если вы передаете адрес, сервис Directions геокодирует строку и преобразует ее в координаты широты и долготы, чтобы рассчитать маршрут. Эти координаты могут отличаться от тех, которые возвращает Geocoding API, например указывать на вход в здание, а не на его центр. 

      origin=24+Sussex+Drive+Ottawa+ON

      Использовать идентификаторы мест предпочтительнее, чем адреса или координаты широты и долготы. Если вы используете координаты, точка всегда будет привязана к ближайшей к ним дороге. Это может быть не подъезд к объекту и даже не дорога, по которой можно быстро или безопасно добраться до пункта назначения.

    • Если вы передаете координаты, точка будет привязана к ближайшей дороге. Рекомендуется передавать идентификатор места. Если вы передаете координаты, убедитесь, что между значениями широты и долготы нет пробела. 

      origin=41.43206,-81.38992

    • Коды Plus Code должны быть отформатированы как глобальные или составные. Коды Plus Code следует форматировать так, как в примере ниже (символы плюса экранируются в URL как %2B, а пробелы – как %20).

      • Глобальный код содержит 4 знака кода региона и 6 и более знаков местного кода (849VCWC8+R9 – это 849VCWC8%2BR9).
      • Составной код содержит 6 и более знаков местного кода с точными данными о местоположении (CWC8+R9 для Маунтин-Вью, Калифорния, США, имеет значение CWC8%2BR9%20Mountain%20View%20CA%20USA).
    Примечание. Для эффективности и точности по возможности используйте идентификаторы мест. Эти идентификаторы уникальны, как и пары значений широты и долготы, и обеспечивают преимущества геокодирования для маршрутизации, например точки доступа и переменные трафика. В отличие от адреса, идентификатор не требует от сервиса выполнять поиск или промежуточный запрос информации о месте, поэтому производительность выше.

Необязательные параметры

  • альтернативы

    Если задано значение true, сервис Directions может предложить несколько альтернативных маршрутов. Обратите внимание, что в этом случае время ответа сервера может увеличиться. Альтернативные маршруты могут предлагаться только для запросов без промежуточных путевых точек. Дополнительную информацию вы найдете в руководстве по путевым точкам.

  • arrival_time

    Предпочтительное время прибытия для маршрутов на общественном транспорте в секундах с полуночи 1 января 1970 года по UTC. Вы можете указать либо departure_time, либо arrival_time, но не оба значения. Обратите внимание, что значение arrival_time должно быть целым числом.

  • избегать

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

    • tolls – указывает, что в маршруте не должно быть платных дорог и мостов.
    • highways – указывает, что в маршруте не должно быть шоссе.
    • ferries – указывает, что в маршруте не должно быть паромных переправ.
    • indoor – указывает, что в рассчитанном маршруте не должно быть лестниц внутри помещений при построении пеших маршрутов и маршрутов на общественном транспорте.

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

    avoid=tolls|highways|ferries.

  • departure_time

    Указывает предпочтительное время отправления. Время можно указать в виде целого числа, обозначающего количество секунд, прошедших с полуночи 1 января 1970 г. по всемирному координированному времени. Если указать в поле departure_time дату позже 31 декабря 9999 г., 23:59:59.999999999, API автоматически заменит ее на 31 декабря 9999 г., 23:59:59.999999999.departure_time В качестве альтернативы можно указать значение now, которое устанавливает время отправления на текущее время (с точностью до секунды). Время отправления можно указывать в двух следующих случаях:

    • Для запросов, в которых выбран способ передвижения на общественном транспорте, можно указать departure_time или arrival_time. Если не указано ни одно из значений, то по умолчанию для departure_time используется текущее время (то есть время отправления по умолчанию – это текущее время).
    • Для запросов, в которых указан способ передвижения на автомобиле, можно задать параметр departure_time, чтобы получить маршрут и продолжительность поездки (поле duration_in_traffic в ответе) с учетом загруженности дорог. Для departure_time должно быть установлено текущее время или момент времени в будущем. Время в прошлом указать нельзя.
    Примечание. Если время отправления не задано, выбор маршрута и расчет длительности поездки будут произведены с учетом средней загруженности дорог. Результаты такого запроса могут меняться со временем в связи с изменениями дорожной сети и средней загруженности дорог или как следствие распределенной архитектуры сервиса. Результаты также могут быть разными для практически равноценных маршрутов в зависимости от времени и частоты запросов.
    Примечание. Запросы матрицы расстояний, в которых указано departure_time, когда mode=driving, ограничены максимум 100 элементами на запрос. Оно рассчитывается как произведение числа начальных и конечных точек.

  • language

    Язык, на котором будут возвращены результаты. Обратите внимание, что это относится только к геокодированным адресам в полях start_address и end_address, локализованному тексту в полях distance и duration (в этапах и шагах) и описанию маневров в поле html_instructions, но не к названиям и адресам в поле html_instructions, которые форматируются на местном языке и с использованием местной письменности.

    • Вы можете ознакомиться со списком поддерживаемых языков. Google часто обновляет список поддерживаемых языков, поэтому он может быть неполным.
    • Если параметр language не указан, API пытается использовать язык, заданный в заголовке Accept-Language.
    • API пытается предоставить почтовый адрес, понятный как пользователю, так и местным жителям. Для этого он возвращает почтовые адреса на местном языке, при необходимости транслитерируя их в систему письма, понятную пользователю, с учетом предпочитаемого языка. Все остальные адреса возвращаются на предпочитаемом языке. Все компоненты адреса возвращаются на одном языке, который выбирается по первому компоненту.
    • Если название на выбранном языке недоступно, API использует наиболее близкое соответствие.
    • Предпочтительный язык немного влияет на набор результатов, возвращаемых API, и на порядок их возврата. Геокодер интерпретирует сокращения по-разному в зависимости от языка. Это касается, например, сокращений для типов улиц или синонимов, которые могут быть допустимы в одном языке, но не в другом. Например, utca и tér – это синонимы слова "улица" на венгерском языке.

  • режим

    При расчете расстояний и маршрутов можно указать способ передвижения. По умолчанию используется режим driving. По умолчанию маршруты рассчитываются для автомобилей. Поддерживаются следующие способы передвижения:

    • driving (по умолчанию) – запрашивает стандартный маршрут или расстояние для автомобиля.
    • walking – запрашивает пеший маршрут или расстояние по пешеходным дорожкам и тротуарам (в регионах, где это возможно).
    • bicycling – запрашивает велосипедный маршрут или расстояние по велосипедным дорожкам и улицам, где удобнее передвигаться на велосипеде (в регионах, где это возможно).
    • transit – запрашивает маршрут или расстояние на общественном транспорте (в регионах, где это возможно). Если вы выбрали режим "Общественный транспорт", то можете указать departure_time или arrival_time. Если не указано ни одно из значений, то по умолчанию для departure_time используется текущее время (то есть время отправления по умолчанию равно текущему времени). Вы также можете добавить transit_mode и/или transit_routing_preference. Поездки на общественном транспорте доступны за последние 7 дней или на 100 дней вперед, если поставщики данных предоставили информацию о них. Расписание общественного транспорта часто меняется, поэтому доступные маршруты могут со временем меняться. Мы не гарантируем, что результаты прогнозирования на длительный срок будут стабильными.
    Примечание. Пешие и велосипедные маршруты могут не содержать четко определенных пешеходных или велосипедных дорожек, поэтому возвращаемый результат может содержать предупреждения, которые нужно показывать пользователю.

  • регион

    Код региона, указываемый как двухсимвольное значение национального домена верхнего уровня. Большинство кодов ccTLD совпадают с кодами ISO 3166-1, однако имеются некоторые исключения. Например, ccTLD Великобритании – uk (.co.uk), а код ISO 3166-1 – gb (технически относится к Соединенному Королевству Великобритании и Северной Ирландии).

  • traffic_model

    Определяет выбор модели расчета в зависимости от загруженности дорог. Этот параметр влияет на возвращаемое значение поля duration_in_traffic в ответе (прогнозируемое время в пути с учетом средних статистических показателей). Параметр traffic_model можно указывать только для автомобильных маршрутов, если запрос содержит departure_time. Для данного параметра доступны следующие значения.

    • best_guess (по умолчанию) – возвращаемое в duration_in_traffic значение должно содержать наиболее вероятную оценку времени в пути с учетом статистики и текущей загруженности дорог. Чем ближе время отправления departure_time к текущему моменту, тем сильнее результат будет зависеть от текущей ситуации.
    • pessimistic – возвращаемое в duration_in_traffic значение должно быть больше фактического времени в пути по этому маршруту в обычные дни (кроме дней с крайне высокой загруженностью дорог).
    • optimistic – возвращаемое в duration_in_traffic значение должно быть меньше фактического времени в пути по этому маршруту в большинстве дней (кроме дней с крайне низкой загруженностью дорог).

    Значение по умолчанию (best_guess) позволяет получить наиболее полезные прогнозы в большинстве случаев. Прогнозируемое время в пути best_guess может быть меньше, чем optimistic, или больше, чем pessimistic, из-за того, как модель прогнозирования best_guess интегрирует информацию о дорожном движении в реальном времени.

  • transit_mode

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

    • bus – указывает, что предпочтительным способом передвижения по возможности должен быть автобус.
    • subway – указывает, что предпочтительным способом передвижения по возможности должно быть метро.
    • train – указывает, что предпочтительным способом передвижения по возможности должен быть поезд.
    • tram – указывает, что предпочтительным способом передвижения по возможности должен быть трамвай или легкое метро.
    • rail – указывает, что предпочтительным способом передвижения по возможности должен быть поезд, трамвай, метро или легкое метро. Это эквивалентно transit_mode=train|tram|subway.

  • transit_routing_preference

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

    • less_walking – указывает, что в предпочтительном маршруте должно быть как можно меньшим расстояние, преодолеваемое пешком.
    • fewer_transfers – указывает, что в предпочтительном маршруте должно быть как можно меньше пересадок.

  • ед.

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

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

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

    • metric – определяет использование метрической системы. Текстовые расстояния возвращаются в километрах и метрах.
    • imperial – определяет использование британской системы Для маршрутов, заданных текстовой строкой, результаты указываются в милях и футах.
    Примечание. Этот параметр влияет только на текст, который видит пользователь. Поля расстояния также содержат значения, которые всегда выражаются в метрах.

  • путевые точки

    Внимание! За запросы с более чем 10 путевыми точками (от 11 до 25) и запросы их оптимизации взимается более высокая плата. Подробнее об оплате на платформе Google Карт…

    Массив промежуточных точек, через которые должен проходить маршрут между пунктами отправления и назначения. Путевые точки позволяют изменить маршрут так, чтобы он проходил через указанные места. API поддерживает путевые точки для следующих способов передвижения: на автомобиле, пешком и на велосипеде. Путевые точки не поддерживаются для маршрутов на общественном транспорте. Вы можете указать одно или несколько местоположений, разделенных вертикальной чертой (| или %7C), в виде идентификатора места, адреса или координат широты и долготы. По умолчанию маршрут прокладывается через путевые точки в том порядке, в котором они указаны. Приоритет при обработке значения путевой точки: идентификатор места, координаты широты и долготы, адрес.

    • Если вы передаете идентификатор места, перед ним нужно указать place_id:. Идентификаторы мест можно получить от Geocoding API и Places API (включая автозаполнение мест). Пример использования идентификаторов мест из сервиса автозаполнения мест можно найти в документе Подсказки мест и маршруты. Подробнее об идентификаторах мест…
      Для повышения эффективности и точности по возможности используйте идентификаторы мест. Эти идентификаторы уникальны, как и пары значений широты и долготы, и обеспечивают преимущества геокодирования для маршрутизации, например точки доступа и переменные трафика. В отличие от адреса, идентификатор не требует от сервиса выполнять поиск или промежуточный запрос информации о месте, поэтому производительность выше.
    • Если вы передаете координаты широты и долготы, значения отправляются непосредственно на сервер внешнего интерфейса для расчета маршрутов без геокодирования. Точки привязываются к дорогам и могут не обеспечивать точность, необходимую для вашего приложения. Используйте координаты, если вы уверены, что значения действительно указывают на точки, необходимые вашему приложению для маршрутизации, без учета возможных точек доступа или дополнительных сведений о геокодировании. Убедитесь, что значения широты и долготы разделены запятой (%2C), а не пробелом (%20).
    • Если вы передадите адрес, сервис Directions геокодирует строку и преобразует ее в координаты широты и долготы, чтобы рассчитать маршрут. Если значение адреса неоднозначно, может быть выполнен поиск, чтобы отличить его от похожих адресов. Например, "1-я улица" может быть полным значением или частью значения "1-я улица, СВ" или "1-я улица, ЮВ". Этот результат может отличаться от возвращаемого Geocoding API. Использование идентификаторов мест позволяет избежать возможных ошибок.
    • Вы также можете указать закодированный набор точек, используя алгоритм кодированной ломаной линии. Закодированный набор полезен при большом количестве путевых точек, поскольку URL-адрес значительно короче. Для всех веб-сервисов действует ограничение на длину URL – 16 384 символа.
      • Закодированные ломаные линии должны начинаться с префикса enc:, за которым следует двоеточие (:). Пример: waypoints=enc:gfo}EtohhU:.
      • Вы также можете включить несколько закодированных ломаных линий, разделенных вертикальной чертой (|). Пример: waypoints=via:enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:| via:enc:udymA{~bxM:.
    Как влиять на маршруты с помощью остановок и транзитных точек

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

    Если вы хотите, чтобы маршрут проходил через путевые точки, но не хотите делать там остановки, добавьте к путевой точке префикс via:. Путевые точки с префиксом via: не добавляют запись в массив legs, но маршрут будет проходить через них.

    В следующем URL предыдущий запрос изменен так, что маршрут проходит через Лексингтон без остановки: 

    https://maps.googleapis.com/maps/api/directions/json?
origin=Boston,MA&destination=Concord,MA
&waypoints=Charlestown,MA|via:Lexington,MA

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

    Внимание! Если использовать префикс via:, интерпретация путевых точек будет слишком строгой. Это может привести к серьезным отклонениям от маршрута или получению ZERO_RESULTS в коде статуса ответа, если Directions API не сможет проложить маршрут через указанную точку.
    Оптимизация промежуточных точек

    По умолчанию маршрут прокладывается через путевые точки в том порядке, в котором они указаны. Также вы можете использовать параметр optimize:true в качестве первого аргумента в параметре waypoints, чтобы сервис Directions мог оптимизировать маршрут, поменяв очередность путевых точек. (Эта оптимизация является практическим примером решения задачи коммивояжера.) Время в пути является главным критерием оптимизации, но могут учитываться также расстояние, количество поворотов и прочие факторы. Для оптимизации маршрута сервисом Directions все путевые точки должны быть остановками.

    Если дать указание сервису Directions оптимизировать порядок путевых точек, их последовательность будет показана в поле waypoint_order объекта routes. Поле waypoint_order возвращает значения, отсчет которых начинается с нуля.

    В следующем примере рассчитывается автомобильный маршрут из Аделаиды (Южная Австралия) в каждый из основных винодельческих регионов Южной Австралии с использованием оптимизации маршрута. 

    https://maps.googleapis.com/maps/api/directions/json?
origin=Adelaide,SA&destination=Adelaide,SA
&waypoints=optimize:true|Barossa+Valley,SA|Clare,SA|Connawarra,SA|McLaren+Vale,SA

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

    "waypoint_order": [ 3, 2, 0, 1 ]
    Внимание! За запросы с оптимизацией путевых точек взимается более высокая плата. Подробнее об оплате на платформе Google Карт…

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

Примеры маршрутов

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