Этот продукт имеет устаревший статус. С октября 2026 г. Directions API (Legacy) нельзя будет включить для новых облачных проектов Google Cloud. Существующие проекты по-прежнему полностью поддерживаются. Чтобы получить доступ к новым функциям и повысить производительность, перейдите на Routes API.
Для расчета маршрутов, которые реагируют на действия пользователя в реальном времени (например, в элементе пользовательского интерфейса), можно использовать Directions API (Legacy) или, если вы используете Maps JavaScript API, сервис Directions. Для использования на стороне сервера можно использовать клиенты Java, Python, Go и Node.js для сервисов Google Карт.
С помощью Directions API (Legacy) вы можете:
- Поиск маршрутов для разных способов передвижения, включая общественный транспорт, автомобиль, велосипед и пешую прогулку.
- Отображение маршрутов, состоящих из нескольких частей, с использованием наборов промежуточных точек маршрута.
- Укажите пункты отправления и назначения, а также путевые точки в виде текстовых строк (например, "Чикаго, Иллинойс" или "Дарвин, Северная территория, Австралия"), идентификаторов мест или координат широты и долготы.
При расчете маршрутов 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).
-
Глобальный код содержит 4 знака кода региона и 6 и более знаков местного кода (849VCWC8+R9 – это
Необязательные параметры
альтернативы
Если задано значение 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 автоматически заменит ее на departure_time 31 декабря 9999 г., 23:59:59.999999999. В качестве альтернативы можно указать значение 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– запрашивает маршрут или расстояние на общественном транспорте (в регионах, где это возможно). Если вы выбрали режим transit, то можете указатьdeparture_timeилиarrival_time. Если ни одно из значений не указано, то дляdeparture_timeпо умолчанию используется текущее время. Вы также можете добавитьtransit_modeи/илиtransit_routing_preference. Поездки на общественном транспорте доступны за период до 7 дней в прошлом или до 100 дней в будущем, в зависимости от наличия информации о транспорте, предоставленной поставщиками данных. Расписание общественного транспорта часто меняется, поэтому доступные маршруты могут со временем меняться, и нет гарантии, что результаты прогнозов на долгосрочную перспективу будут стабильными.
регион
Код региона, указываемый как двухсимвольное значение национального домена верхнего уровня (ccTLD). Большинство кодов 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– указывает, что в предпочтительном маршруте должно быть как можно меньше пересадок.
ед.
Указывает систему единиц измерения, которая будет использоваться при отображении результатов.
Результаты маршрута содержат текст в полях расстояния, который может быть показан пользователю для указания расстояния определенного "шага" маршрута. По умолчанию в этом тексте используется система единиц, применяемая в стране или регионе начальной точки.
Например, маршрут от "Чикаго, Иллинойс" до "Торонто, Онтарио" отображает результаты в милях, а обратный маршрут – в километрах. Единицы измерения можно переопределить, передав в запросе одно из следующих значений параметра units:
-
metric– определяет использование метрической системы. Текстовые расстояния возвращаются в километрах и метрах. -
imperial– определяет использование британской системы Для маршрутов, заданных текстовой строкой, результаты указываются в милях и футах.
путевые точки
Массив промежуточных точек, через которые должен проходить маршрут между пунктами отправления и назначения. Путевые точки позволяют изменить маршрут так, чтобы он проходил через указанные места. 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 ]
Дальнейшие действия
Примеры маршрутов
- Способы передвижения
- Информация о загруженности дорог
- Путевые точки и их оптимизация
- Ограничения на маршруте
- Системы единиц
- Смещение по региону
- Модификаторы местоположения
Ответы на запросы маршрутов
- DirectionsResponse
- DirectionsRoute
- DirectionsLeg
- DirectionsStep и DirectionsPolyline
- DirectionsTransitDetails
- DirectionsStatus
- DirectionsGeocodedWaypoint