Все готово!

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

Активация Google Maps Directions API

Чтобы помочь вам освоиться, мы покажем, как выполнить некоторые необходимые действия в консоли разработчика Google:

  1. Создание или выбор проекта
  2. Активация Google Maps Directions API
  3. Создание соответствующих ключей

Руководство для разработчиков

Google Maps Directions API – это служба, которая позволяет рассчитывать маршруты между разными точками с использованием запроса HTTP.

Эта служба также доступна как часть Google Maps JavaScript API на стороне клиента или для использования на стороне сервера с Java Client, Python Client, Go Client и Node.js Client for Google Maps Services. Примечание. Вне зависимости от того, как используется служба, к ней применяются одни и те же ежедневные ограничения на использование. Число запросов в день рассчитывается как сумма запросов на стороне клиента и на стороне сервера.

Данный документ предназначен для разработчиков веб-сайтов и мобильных приложений, которые хотят использовать в картах данные о маршрутах, предоставляемые одним из интерфейсов Google Maps API. Документ содержит основные сведения по использованию API и справочные материалы по доступным параметрам.

Введение

Этот видеоролик иллюстрирует использование Google Maps Directions API для поиска маршрута. В видеоролике содержатся советы по защите ключа API путем проксирования веб-службы через ваш сервер при использовании API в мобильном приложении.

С помощью Directions API можно выполнять следующие действия.

  • Поиск комбинированных маршрутов, включающих общественный транспорт, поездки на автомобиле, перемещения пешком или на велосипеде.
  • Отображение маршрутов, состоящих из нескольких частей, с использованием наборов промежуточных точек маршрута.
  • Указание начальных, конечных и промежуточных точек в виде текстовых строк (например, "Chicago, IL" или "Darwin, NT, Australia"), в виде координат широты/долготы или в виде идентификаторов мест.

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

Примечание. Эта служба не предназначена для реагирования на ввод данных в режиме реального времени. Для расчета динамических маршрутов (например, в рамках элемента пользовательского интерфейса) обратитесь к документации Служба Google Maps JavaScript API Directions.

Перед началом разработки с использованием Directions API проверьте требования аутентификации (необходим ключ API) и лимиты использования API.

Запросы маршрутов

Запрос Google Maps Directions API имеет следующий вид:

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

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

  • json (рекомендуется) – задает вывод в формате JavaScript Object Notation (JSON);
  • xml – задает вывод в формате XML.

Примечание. URL-адреса должны быть правильно закодированы, чтобы быть действительными, и ограничены 8192 символами для всех веб-служб. Помните об этом ограничении при построении своих URL-адресов.

HTTPS или HTTP

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

Если использование HTTPS невозможно, для доступа к Google Maps Directions API через HTTP используйте следующий запрос:

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

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

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

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

  • origin – адрес, текстовое значение широты/долготы или идентификатор места, от которого требуется провести расчет маршрутов.
    • При отправке адреса служба Directions геокодирует строку, преобразуя ее в координаты широты и долготы для вычисления маршрутов. Данные координаты могут отличаться от координат, полученных от Google Maps Geocoding API, например может быть указан вход в здание, а не его центр.
      origin=24+Sussex+Drive+Ottawa+ON
    • Если вы передаете координаты, они используются без изменений в расчетах маршрута. Убедитесь, что между значениями широты и долготы отсутствует пробел.
      origin=41.43206,-81.38992
    • Идентификаторы мест должны иметь префикс place_id:. Идентификатор места можно указать только в том случае, если запрос содержит ключ API или идентификатор клиента Google Maps APIs Premium Plan. Идентификаторы мест можно извлекать из Google Maps Geocoding API и Google Places API (включая подсказки мест). Пример использования идентификаторов мест из службы подсказок мест можно найти в документе Подсказки мест и маршруты. Подробные сведения об идентификаторах мест см. в соответствующем обзоре.
      origin=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE
  • destination – адрес, текстовое значение широты/долготы или идентификатор места, до которого требуется провести расчет маршрутов. Параметры для поля destination аналогичны описанным выше параметрам поля origin.
  • key – ключ API вашего приложения. Этот ключ используется для идентификации приложения в целях управления квотами. См. дополнительную информацию о получении ключа.

    Примечание. Пользователи Google Maps APIs Premium Plan в запросах Directions могут использовать либо ключ API, либо действительный идентификатор клиента и цифровую подпись. См. дополнительную информацию о параметрах аутентификации пользователей Premium Plan.

Дополнительные параметры

  • mode (по умолчанию driving) – указывает, какой способ передвижения использовать при расчете маршрута. Допустимые значения и другие сведения о запросах указаны в разделе Способы передвижения.
  • waypoints – определяет массив промежуточных точек. Промежуточные точки позволяют изменить маршрут так, чтобы он проходил через указанные места. Промежуточные точки указываются либо как координаты широты/долготы, либо как кодированная ломаная линия, либо как идентификатор места, либо как адрес, для которого будет выполнено геокодирование. Кодированные ломаные линии должны использоваться с префиксом enc: и последующим двоеточием (:). Идентификаторы мест должны иметь префикс place_id:. Идентификатор места можно указать только в том случае, если запрос содержит ключ API или идентификатор клиента Google Maps APIs Premium Plan. Промежуточные точки поддерживаются только для автомобильных, пешеходных и велосипедных маршрутов. Подробнее о промежуточных точках см. руководство по промежуточным точкам ниже.
  • alternatives – если это поле имеет значение true, служба маршрутов может предоставлять несколько альтернативных маршрутов в ответе. Следует отметить, что при наличии альтернативных маршрутов время ответа сервера может быть больше.
  • avoid – указывает, что в рассчитанном маршруте следует избегать указанных особенностей. Данный параметр поддерживает следующие аргументы:
    • tolls – указывает, что в рассчитанном маршруте следует избегать платных дорог/мостов.
    • highways – указывает, что в рассчитанном маршруте следует избегать шоссе.
    • ferries – указывает, что в рассчитанном маршруте следует избегать паромов.
    • indoor – указывает, что в рассчитанном маршруте следует избегать внутренних переходов по лестницам и маршрутов на общественном транспорте. По умолчанию сведения о лестницах получат только запросы, содержащие ключ API или идентификатор клиента Google Maps APIs Premium Plan.
    Для получения дополнительной информации см. раздел Ограничения для маршрутов ниже.
  • language – язык, на котором выводятся результаты.
    • См. список поддерживаемых языков. Обратите внимание, что список языков постоянно пополняется, поэтому он может быть неполным.
    • Если параметр language не указан, API будет использовать язык, указанный как предпочтительный в заголовке Accept-Language, либо основной язык домена, от которого отправлен запрос.
    • API старается предоставить почтовый адрес, который будет понятен как пользователю, так и местным жителям. Чтобы достичь этой цели, он возвращает почтовые адреса на местном языке, при необходимости используя транслитерацию, понятную пользователю, с соблюдением предпочтительного языка. Все остальные адреса возвращаются на предпочтительном языке. Все компоненты адреса возвращаются на одном языке, выбранном для первого компонента.
    • Если на предпочтительном языке такого названия нет, API использует ближайшее соответствие.
    • Предпочтительный язык оказывает небольшое влияние на набор результатов, которые возвращает API, равно как и на порядок их отображения. Интерпретация сокращений геокодировщиком может различаться в зависимости от языка, например, сокращения типов улиц или синонимов, действующие в одном языке, могут не допускаться в другом. Например, utca и tér в венгерском языке являются синонимами улицы.
  • unit – указывает, какую систему единиц измерения следует использовать для отображения результатов. Допустимые значения указаны в разделе Системы единиц ниже.
  • region – указывает код региона в виде значения ccTLD ("домен верхнего уровня") из двух символов. (Дополнительную информацию см. в разделе Привязка к региону ниже.)
  • arrival_time – указывает желаемое время прибытия для перемещения на общественном транспорте, измеренное в секундах с полуночи 1 января 1970 г. по UTC. Вы можете указать либо departure_time, либо arrival_time, но не оба значения. Обратите внимание, что для arrival_time необходимо указать целое значение.
  • departure_time – указывает желаемое время отправления. Можно указать время как целое число в секундах с полуночи 1 января 1970 г. по UTC. Вы также можете указать значение now, которое устанавливает для времени отправления текущий момент времени (с точностью до секунды). Время отправления можно указывать в двух следующих случаях:
    • Для запросов, в которых в качестве способа передвижения используется общественный транспорт, вы можете дополнительно указать departure_time либо arrival_time. Если ни один из этих параметров не указан, в departure_time в качестве времени отправления по умолчанию используется текущее время.
    • Для запросов, в которых в качестве способа передвижения используется автомобиль, вы можете указать departure_time для получения сведений о маршруте и его продолжительности (поле ответа: duration_in_traffic) с учетом ситуации на дорогах. Данный параметр доступен только в том случае, если запрос содержит действительный ключ API или действительный идентификатор клиента Google Maps APIs Premium Plan и подпись. В параметре departure_time должно быть установлено текущее время или определенный момент времени в будущем. Прошедший момент времени является недопустимым.
  • traffic_model (по умолчанию best_guess) – указывает предположения, используемые при расчете времени в пути. Этот параметр влияет на возвращаемое значение поля duration_in_traffic в ответе (прогнозируемое время в пути с учетом средних статистических показателей). Параметр traffic_model может быть указан для автомобильных маршрутов только в том случае, если запрос содержит departure_time и ключ API или идентификатор клиента Google Maps APIs Premium Plan. Доступными значениями для данного параметра являются:
    • 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 – указывает один или несколько предпочитаемых способов передвижения. Данный параметр может быть указан для маршрутов на общественном транспорте только в том случае, если запрос содержит ключ API или идентификатор клиента Google Maps APIs Premium Plan. Данный параметр поддерживает следующие аргументы:
    • bus – указывает, что в рассчитанном маршруте следует отдать приоритет передвижению на автобусе.
    • subway – указывает, что в рассчитанном маршруте следует отдать приоритет передвижению на метро.
    • train – указывает, что в рассчитанном маршруте следует отдать приоритет передвижению на поезде.
    • tram – указывает, что в рассчитанном маршруте следует отдать приоритет передвижению на трамвае и легком метро.
    • rail – указывает, что в рассчитанном маршруте следует отдать приоритет передвижению на поезде, трамвае, метрополитене и легком метро. Это значение аналогично указанию transit_mode=train|tram|subway.
  • transit_routing_preference – указывает предпочтения для маршрутов на общественном транспорте. С помощью этого параметра можно указать предпочтения для выводимых вариантов вместо принятия маршрута, который API выбирает по умолчанию в качестве оптимального. Данный параметр может быть указан для маршрутов на общественном транспорте только в том случае, если запрос содержит ключ API или идентификатор клиента Google Maps APIs Premium Plan. Данный параметр поддерживает следующие аргументы:
    • less_walking – указывает, что в рассчитанном маршруте следует отдать приоритет уменьшению расстояния, которое нужно пройти пешком.
    • fewer_transfers – указывает, что в рассчитанном маршруте следует отдать приоритет уменьшению количества пересадок.

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

Следующий запрос возвращает маршруты для автомобилей из Торонто (провинция Онтарио, Канада) в Монреаль (провинция Квебек, Канада).

https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&key=YOUR_API_KEY

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

https://maps.googleapis.com/maps/api/directions/json?origin=Toronto&destination=Montreal&avoid=highways&mode=bicycling&key=YOUR_API_KEY

В следующем запросе выполняется поиск маршрутов на общественном транспорте из Бруклина (Нью-Йорк, США) в Квинс (Нью-Йорк, США). Если в запросе не указано значение departure_time, в качестве времени отправления по умолчанию используется текущее время.

https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&mode=transit&key=YOUR_API_KEY

В следующем запросе указано определенное время отправления.

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

https://maps.googleapis.com/maps/api/directions/json?origin=Brooklyn&destination=Queens&departure_time=1343641500&mode=transit&key=YOUR_API_KEY

В следующем запросе, использующем идентификаторы мест, возвращаются маршруты для автомобилей из Глазго (Великобритания) в Перт (Великобритания).

https://maps.googleapis.com/maps/api/directions/json?origin=place_id:ChIJ685WIFYViEgRHlHvBbiD5nE&destination=place_id:ChIJA01I-8YVhkgRGJb0fW4UX7Y&key=YOUR_API_KEY

Способы передвижения

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

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

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

Промежуточные точки

При расчете маршрутов с помощью Google Maps Directions API вы можете также указать промежуточные точки (waypoints) для автомобильных, пешеходных или велосипедных маршрутов. Промежуточные точки недоступны для маршрутов на общественном транспорте. Чтобы рассчитать путь через дополнительные места, можно использовать промежуточные точки. В этом случае отображаемый маршрут будет включать остановки в указанных промежуточных точках.

Укажите промежуточные точки в параметре waypoints.

  • Можно задавать одно или несколько мест, отделяемых вертикальной чертой (|), в виде адреса, координат широты и долготы или идентификатора места.
    • Если вы передаете адрес, служба Directions геокодирует строку, преобразуя ее в координаты широты и долготы для вычисления маршрута. Данные координаты могут отличаться от координат, полученных от Google Maps Geocoding API, например может быть указан вход в здание, а не его центр.
    • Если вы передаете координаты широты и долготы, они будут использоваться в неизменном виде для расчета маршрутов. Убедитесь, что между значениями широты и долготы отсутствует пробел.
    • Если вы указываете идентификатор места, к нему необходимо добавлять префикс place_id:. Указать идентификатор места можно лишь в том случае, если запрос содержит ключ API или идентификатор клиента Google Maps APIs Premium Plan. Идентификаторы мест можно извлекать из Google Maps Geocoding API и Google Places API (включая подсказки мест). Пример использования идентификаторов мест из службы подсказок мест можно найти в документе Подсказки мест и маршруты. Подробные сведения об идентификаторах мест см. в соответствующем обзоре.
  • Вы также можете указать совокупность кодированных координат, используя алгоритм кодирования ломаной линии. Он особенно полезен при наличии большого количества промежуточных точек, так как URL-адрес значительно короче при использовании кодированной ломаной линии.
    • Кодированные ломаные линии должны использоваться с префиксом enc: и последующим двоеточием (:). Например, waypoints=enc:gfo}EtohhU:
    • Вы также можете включить несколько кодированных ломаных линий, разделив их вертикальной чертой (|). Например: waypoints=via:enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|via:enc:udymA{~bxM:

Следующий URL-адрес инициирует запрос службы Directions на получение маршрута между Бостоном (штат Массачусетс, США) и Конкордом (штат Массачусетс, США) с остановками в Чарлстоне и Лексингтоне в указанном порядке:

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

Для каждой промежуточной точки в запросе маршрут имеет дополнительную запись в массиве 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&key=YOUR_API_KEY

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

Следующий URL-адрес запрашивает промежуточные точки, используя координаты широты и долготы:

https://maps.googleapis.com/maps/api/directions/json?origin=sydney,au&destination=perth,au&waypoints=via:-37.81223%2C144.96254%7Cvia:-34.92788%2C138.60008&key=YOUR_API_KEY

Ниже приведен тот же запрос с использованием кодированной ломаной линии:

https://maps.googleapis.com/maps/api/directions/json?origin=sydney,au&destination=perth,au&waypoints=via:enc:lexeF{~wsZejrPjtye@:&key=YOUR_API_KEY

Оптимизация промежуточных точек

По умолчанию служба Directions рассчитывает маршрут через указанные промежуточные точки в порядке их указания. Также вы можете передать 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&key=YOUR_API_KEY

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

"waypoint_order": [ 1, 0, 2, 3 ]

Ограничения

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

  • avoid=tolls
  • avoid=highways
  • avoid=ferries

Путем передачи ограничений параметру avoid можно запросить маршрут, в котором учтена какая-либо комбинация ограничений на использование платных дорог, шоссе и паромов. Например: avoid=tolls|highways|ferries.

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

Системы единиц

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

Например, для маршрута из Чикаго (штат Иллинойс, США) в Торонто (провинция Онтарио, Канада) результат будет отображаться в милях, а для обратного маршрута результат будет отображаться в километрах. Вы можете заменить эту систему единиц, указав ее непосредственно в параметре units с помощью одного из следующих значений:

  • metric указывает на использование метрической системы единиц. Расстояния возвращаются в километрах и метрах.
  • imperial указывает на использование британской системы единиц. Расстояния возвращаются в милях и футах.

Примечание. Настройка системы единиц влияет только на параметр text, который отображается в полях distance. Поля distance также содержат значения values, которые всегда выражаются в метрах.

Привязка к региону

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

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

Например, запрос маршрута из Толедо в Мадрид возвращает результат, когда для параметра region установлено значение es, поскольку Толедо интерпретируется как испанский город:

https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&region=es&key=YOUR_API_KEY

{
  "status": "OK",
  "routes": [ {
    "summary": "AP-41",
    "legs": [ {
        ...
    } ],
    "copyrights": "Map data ©2010 Europa Technologies, Tele Atlas",
    "warnings": [ ],
    "waypoint_order": [ ]
  } ]
}

Если параметр region не был указан, то маршрут из Толедо в Мадрид не будет получен, поскольку Толедо будет интерпретирован как город в Огайо.

https://maps.googleapis.com/maps/api/directions/json?origin=Toledo&destination=Madrid&key=YOUR_API_KEY

{
  "status": "ZERO_RESULTS",
  "routes": [ ]
}

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

Ответы на запросы маршрутов возвращаются в формате, указанном с помощью флага output в URL-адресе запроса.

Примеры ответов

Ниже приведен пример запроса HTTP, рассчитывающий маршрут из Чикаго (штат Иллинойс) в Лос-Анджелес (штат Калифорния) с помощью двух промежуточных точек: Джоплин (штат Миссури) и Оклахома-Сити (штат Оклахома).

https://maps.googleapis.com/maps/api/directions/json?origin=Chicago,IL&destination=Los+Angeles,CA&waypoints=Joplin,MO|Oklahoma+City,OK&key=YOUR_API_KEY

В примере выше запрашивается вывод в формате JSON. Также можно запросить вывод в формате XML. Откройте обе показанные ниже вкладки, чтобы просмотреть примеры ответов в формате JSON и XML.

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

JSON
{
  "status": "OK",
  "geocoded_waypoints" : [
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJ7cv00DwsDogRAMDACa2m4K8",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJ69Pk6jdlyIcRDqM1KDY3Fpg",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJgdL4flSKrYcRnTpP0XQSojM",
        "types" : [ "locality", "political" ]
     },
     {
        "geocoder_status" : "OK",
        "place_id" : "ChIJE9on3F3HwoAR9AhGJW_fL-I",
        "types" : [ "locality", "political" ]
     }
  ],
  "routes": [ {
    "summary": "I-40 W",
    "legs": [ {
      "steps": [ {
        "travel_mode": "DRIVING",
        "start_location": {
          "lat": 41.8507300,
          "lng": -87.6512600
        },
        "end_location": {
          "lat": 41.8525800,
          "lng": -87.6514100
        },
        "polyline": {
          "points": "a~l~Fjk~uOwHJy@P"
        },
        "duration": {
          "value": 19,
          "text": "1 min"
        },
        "html_instructions": "Head \u003cb\u003enorth\u003c/b\u003e on \u003cb\u003eS Morgan St\u003c/b\u003e toward \u003cb\u003eW Cermak Rd\u003c/b\u003e",
        "distance": {
          "value": 207,
          "text": "0.1 mi"
        }
      },
      ...
      ... additional steps of this leg
    ...
    ... additional legs of this route
      "duration": {
        "value": 74384,
        "text": "20 hours 40 mins"
      },
      "distance": {
        "value": 2137146,
        "text": "1,328 mi"
      },
      "start_location": {
        "lat": 35.4675602,
        "lng": -97.5164276
      },
      "end_location": {
        "lat": 34.0522342,
        "lng": -118.2436849
      },
      "start_address": "Oklahoma City, OK, USA",
      "end_address": "Los Angeles, CA, USA"
    } ],
    "copyrights": "Map data ©2010 Google, Sanborn",
    "overview_polyline": {
      "points": "a~l~Fjk~uOnzh@vlbBtc~@tsE`vnApw{A`dw@~w\\|tNtqf@l{Yd_Fblh@rxo@b}@xxSfytAblk@xxaBeJxlcBb~t@zbh@jc|Bx}C`rv@rw|@rlhA~dVzeo@vrSnc}Axf]fjz@xfFbw~@dz{A~d{A|zOxbrBbdUvpo@`cFp~xBc`Hk@nurDznmFfwMbwz@bbl@lq~@loPpxq@bw_@v|{CbtY~jGqeMb{iF|n\\~mbDzeVh_Wr|Efc\\x`Ij{kE}mAb~uF{cNd}xBjp]fulBiwJpgg@|kHntyArpb@bijCk_Kv~eGyqTj_|@`uV`k|DcsNdwxAott@r}q@_gc@nu`CnvHx`k@dse@j|p@zpiAp|gEicy@`omFvaErfo@igQxnlApqGze~AsyRzrjAb__@ftyB}pIlo_BflmA~yQftNboWzoAlzp@mz`@|}_@fda@jakEitAn{fB_a]lexClshBtmqAdmY_hLxiZd~XtaBndgC"
    },
    "warnings": [ ],
    "waypoint_order": [ 0, 1 ],
    "bounds": {
      "southwest": {
        "lat": 34.0523600,
        "lng": -118.2435600
      },
      "northeast": {
        "lat": 41.8781100,
        "lng": -87.6297900
      }
    }
  } ]
}

Обычно при поиске маршрутов возвращается только одна запись в массиве routes, хотя служба Directions может вернуть несколько вариантов при передаче alternatives=true.

Обратите внимание, что для извлечения значения из результатов необходимо выполнить их синтаксический анализ. Синтаксический анализ JSON выполняется сравнительно просто. Рекомендуемые шаблоны приведены в разделе Синтаксический анализ JSON.

XML
<DirectionsResponse>
 <status>OK</status>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ7cv00DwsDogRAMDACa2m4K8</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJ69Pk6jdlyIcRDqM1KDY3Fpg</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJgdL4flSKrYcRnTpP0XQSojM</place_id>
 </geocoded_waypoint>
 <geocoded_waypoint>
  <geocoder_status>OK</geocoder_status>
  <type>locality</type>
  <type>political</type>
  <place_id>ChIJE9on3F3HwoAR9AhGJW_fL-I</place_id>
 </geocoded_waypoint>
 <route>
  <summary>I-40 W</summary>
  <leg>
   <step>
    <travel_mode>DRIVING</travel_mode>
    <start_location>
     <lat>41.8507300</lat>
     <lng>-87.6512600</lng>
    </start_location>
    <end_location>
     <lat>41.8525800</lat>
     <lng>-87.6514100</lng>
    </end_location>
    <polyline>
     <points>a~l~Fjk~uOwHJy@P</points>
    </polyline>
    <duration>
     <value>19</value>
     <text>1 min</text>
    </duration>
    <html_instructions>Head <b>north</b> on <b>S Morgan St</b> toward <b>W Cermak Rd</b></html_instructions>
    <distance>
     <value>207</value>
     <text>0.1 mi</text>
    </distance>
   </step>
   ...
   ... additional steps of this leg
  ...
  ... additional legs of this route
   <duration>
    <value>74384</value>
    <text>20 hours 40 mins</text>
   </duration>
   <distance>
    <value>2137146</value>
    <text>1,328 mi</text>
   </distance>
   <start_location>
    <lat>35.4675602</lat>
    <lng>-97.5164276</lng>
   </start_location>
   <end_location>
    <lat>34.0522342</lat>
    <lng>-118.2436849</lng>
   </end_location>
   <start_address>Oklahoma City, OK, USA</start_address>
   <end_address>Los Angeles, CA, USA</end_address>
  <copyrights>Map data ©2010 Google, Sanborn</copyrights>
  <overview_polyline>
   <points>a~l~Fjk~uOnzh@vlbBtc~@tsE`vnApw{A`dw@~w\|tNtqf@l{Yd_Fblh@rxo@b}@xxSfytAblk@xxaBeJxlcBb~t@zbh@jc|Bx}C`rv@rw|@rlhA~dVzeo@vrSnc}Axf]fjz@xfFbw~@dz{A~d{A|zOxbrBbdUvpo@`cFp~xBc`Hk@nurDznmFfwMbwz@bbl@lq~@loPpxq@bw_@v|{CbtY~jGqeMb{iF|n\~mbDzeVh_Wr|Efc\x`Ij{kE}mAb~uF{cNd}xBjp]fulBiwJpgg@|kHntyArpb@bijCk_Kv~eGyqTj_|@`uV`k|DcsNdwxAott@r}q@_gc@nu`CnvHx`k@dse@j|p@zpiAp|gEicy@`omFvaErfo@igQxnlApqGze~AsyRzrjAb__@ftyB}pIlo_BflmA~yQftNboWzoAlzp@mz`@|}_@fda@jakEitAn{fB_a]lexClshBtmqAdmY_hLxiZd~XtaBndgC</points>
  </overview_polyline>
  <waypoint_index>0</waypoint_index>
  <waypoint_index>1</waypoint_index>
  <bounds>
   <southwest>
    <lat>34.0523600</lat>
    <lng>-118.2435600</lng>
   </southwest>
   <northeast>
    <lat>41.8781100</lat>
    <lng>-87.6297900</lng>
   </northeast>
  </bounds>
 </route>
</DirectionsResponse>

Обратите внимание, что ответ в формате XML состоит из отдельного элемента <DirectionsResponse> и следующих элементов верхнего уровня:

  • <status> – содержит метаданные по запросу. См. раздел Коды состояния ниже.
  • По одному элементу <geocoded_waypoint> для всех промежуточных, начальной и конечной точек с результатом их геокодирования. Элементы <geocoded_waypoint/> могут быть пустыми. См. Промежуточные точки с геокодами ниже.
  • Несколько (в том числе ни одного) элементов <route>, каждый из которых содержит один набор информации о маршруте между начальной и конечной точками.

Рекомендуется использовать в качестве предпочтительного формата json, а формат xml использовать только в случае, если это требуется для службы. Настраивать обработку XML-деревьев следует внимательно, чтобы обеспечить обращение к нужным узлам и элементам. Рекомендуемые шаблоны для обработки вывода приведены в разделе Синтаксический анализ XML с помощью XPath.

Далее в данной документации будет использоваться синтаксис JSON. В большинстве случаев формат вывода не имеет значения для иллюстрации основных понятий или названий полей в документации. Однако обратите внимание на следующие отличия:

  • Результаты XML заключены в корневом элементе <DirectionsResponse>.
  • JSON обозначает записи с несколькими элементами с помощью массивов во множественном числе (например, steps и legs), а XML – с помощью множества элементов в единственном числе (например, <step> и <leg>).
  • JSON определяет порядок промежуточных точек через поле waypoint_order, а XML использует для этого отдельные элементы <waypoint_index>.
  • Пустые элементы обозначаются как пустые массивы в JSON, а в XML отсутствуют. Например, ответ без полученных результатов вернет пустой массив routes в JSON, а в XML будут отсутствовать элементы <route>.

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

Ответы на запросы маршрутов содержат следующие корневые элементы:

  • status – содержит метаданные по запросу. См. раздел Коды состояния ниже.
  • geocoded_waypoints – содержит массив со сведениями о геокодах начальной, конечной и промежуточных точек. См. Промежуточные точки с геокодами ниже.
  • routes – содержит массив маршрутов от начальной точки до конечной. См. Маршруты ниже. Маршруты состоят из вложенных участков и шагов.
  • available_travel_modes содержит массив доступных способов передвижения. Данное поле возвращается в том случае, когда запрос указывает способ передвижения mode и не получает результат. Массив содержит доступные способы передвижения в странах с заданным набором промежуточных точек. Это поле не возвращается, если одна или более промежуточных точек содержат префикс via:. См. подробности ниже.

Коды состояния

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

  • OK – указывает, что ответ содержит корректный результат result.
  • NOT_FOUND – означает, что не удалось найти геокод хотя бы одного места, указанного в качестве исходной точки, пункта назначения или промежуточной точки маршрута.
  • ZERO_RESULTS – означает, что не удалось проложить маршрут между исходной точкой и точкой назначения.
  • MAX_WAYPOINTS_EXCEEDED – означает, что в запросе указано слишком много промежуточных точек waypoints. Для приложений, использующих Google Maps Directions API как веб-службу либо службу построения маршрутов в Google Maps JavaScript API, максимальное разрешенное количество промежуточных точек waypoints составляет 23, плюс начальная и конечная точки. Пользователи Google Maps APIs Premium Plan могут отправлять запросы, содержащие до 23 промежуточных точек, плюс начальная и конечная точки.
  • INVALID_REQUEST – указывает на недопустимый запрос. Обычными причинами такого состояния являются недопустимый параметр или его значение.
  • OVER_QUERY_LIMIT – указывает, что служба получила слишком много запросов от вашего приложения в течение разрешенного периода.
  • REQUEST_DENIED – указывает, что вашему приложению отказано в использовании службы маршрутов.
  • UNKNOWN_ERROR – указывает, что запрос маршрутов не удалось обработать из-за ошибки сервера. Если повторить попытку, запрос может оказаться успешным.

Сообщения об ошибках

Если код состояния отличается от OK, в объекте ответа службы Directions может быть дополнительное поле error_message. Это поле содержит более подробную информацию о причинах указанного кода состояния.

Примечание. В ответе может и не быть этого поля, а содержимое самого поля может быть другим.

Промежуточные точки с геокодами

Сведения о геокодировании каждой промежуточной, начальной и конечной точки находятся в массиве (JSON) geocoded_waypoints. Их можно использовать для получения выводов о причинах возврата неверных маршрутов или отсутствия результатов.

Позиция элементов в массиве geocoded_waypoints, начиная с нулевого, соответствует начальной точке, промежуточным точкам в указанном порядке и конечной точке. Каждый элемент содержит следующие сведения о геокодировании для соответствующей промежуточной точки:

  • geocoder_status – код состояния, полученный от операции геокодирования. Это поле может содержать следующие значения.
    • "OK" – ошибок нет, адрес обработан и получен хотя бы один геокод.
    • "ZERO_RESULTS" – геокодирование успешно выполнено, однако результаты не найдены. Это может произойти, если геокодировщику был передан несуществующий адрес (address).
  • partial_match – указывает, что геокодировщик не вернул точное совпадение для начального запроса, хотя и обнаружил частичное совпадение с запрашиваемым адресом. Рекомендуется проверить исходный запрос на наличие в нем опечаток и/или неполного адреса.

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

  • place_id – уникальный идентификатор, который можно использовать и с другими API Google. Например, можно использовать place_id из ответа службы подсказки мест Google для расчета маршрутов до местной организации. Более подробную информацию см. в обзоре идентификаторов мест.
  • types – обозначает тип адреса результата геокодирования, используемого для расчета маршрутов. Возвращаются следующие типы:
    • street_address – указывает точный почтовый адрес.
    • route – указывает шоссе с названием (например, "US 101").
    • intersection – указывает крупные перекрестки, как правило, пересечения двух крупных дорог.
    • political – указывает политическую единицу. Чаще всего такой тип используется для обозначения некоторых административных объектов.
    • country – указывает государственную политическую единицу и обычно представляет собой тип наивысшего порядка, который возвращается геокодировщиком.
    • administrative_area_level_1 – указывает гражданскую единицу первого порядка ниже уровня страны. В США такими административными уровнями являются штаты. Эти административные уровни используются не во всех странах. В большинстве случаев краткие имена administrative_area_level_1 будут близко соответствовать подразделениям в стандарте ISO 3166-2 и других широко распространенных списках; тем не менее, поскольку результаты геокодирования зависят от различных сигналов и данных о местоположении, никаких гарантий здесь не дается.
    • administrative_area_level_2 – указывает гражданскую единицу второго порядка ниже уровня страны. В США такими административными уровнями являются округи. Эти административные уровни используются не во всех странах.
    • administrative_area_level_3 – указывает гражданскую единицу третьего порядка ниже уровня страны. Такой тип представляет меньшее административное подразделение. Эти административные уровни используются не во всех странах.
    • administrative_area_level_4 – указывает гражданскую единицу четвертого порядка ниже уровня страны. Такой тип представляет меньшее административное подразделение. Эти административные уровни используются не во всех странах.
    • administrative_area_level_5 – указывает гражданскую единицу пятого порядка ниже уровня страны. Такой тип представляет меньшее административное подразделение. Эти административные уровни используются не во всех странах.
    • colloquial_area – указывает общепринятое альтернативное название единицы.
    • locality – указывает политическую единицу в составе города.
    • ward – указывает определенный тип округа в Японии, чтобы установить различие между несколькими частями населенного пункта в японском адресе.
    • sublocality – указывает гражданскую единицу первого порядка ниже уровня населенного пункта. Для некоторых местоположений возможно предоставление одного из дополнительных типов: от sublocality_level_1 до sublocality_level_5. Каждый уровень ниже населенного пункта является гражданской единицей. Большее значение указывает меньшую географическую область.
    • neighborhood – указывает именованный район.
    • premise – указывает именованное местоположение, обычно одно или несколько зданий с общепринятым названием.
    • subpremise – указывает единицу первого порядка ниже именованного местоположения, обычно одно здание в границах комплекса зданий с общепринятым названием.
    • postal_code – указывает почтовый индекс в том виде, в котором он используется в стране для обработки почты.
    • natural_feature – указывает важный природный объект.
    • airport – указывает аэропорт.
    • park – указывает парк с названием.
    • point_of_interest – указывает достопримечательность с названием. Как правило, такие достопримечательности являются важными местными единицами, которые не подходят для других категорий, например, небоскреб "Эмпайр-стейт-билдинг" или статуя Свободы.

    Пустой список типов указывает, что для того или иного элемента адреса нет известных типов, например, Lieu-dit во Франции.

Эти сведения не будут представлены для промежуточных точек, указанных в виде текстовых значений широты/долготы, если служба не возвращает результаты. Это связано с тем, что для таких промежуточных точек выполняется только обратное геокодирование для получения адресов после нахождения маршрута. Пустой объект JSON займет соответствующие места в массиве geocoded_waypoints.

Маршруты

Результаты, возвращаемые Google Maps Directions API, помещаются в массив (JSON) routes. Даже если служба не находит результатов (например, если начальная или конечная точка не существует), все равно возвращается пустой массив routes. (XML-ответы могут содержать любое, в том числе нулевое, число элементов <route>.)

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

Каждый маршрут в поле routes может содержать следующие поля:

  • summary – содержит краткое описание маршрута, которое позволяет присвоить маршруту имя и отличить его от альтернативных маршрутов.
  • legs[] – содержит массив с информацией об участке между двумя точками указанного маршрута. Для каждой промежуточной или конечной точки используется отдельный участок. (Маршрут без промежуточных точек содержит ровно один участок в массиве legs.) Каждый участок состоит из набора объектов steps. (См. Участки маршрута ниже.)
  • waypoint_order (либо <waypoint_index> в XML) – содержит массив, указывающий порядок промежуточных точек на рассчитанном маршруте. Эти промежуточные точки можно переупорядочить, если запрос передал значение optimize:true в параметре waypoints.
  • overview_polyline – содержит один объект points, в котором хранится представление маршрута в форме кодированной ломаной линии. Эта ломаная линия представляет собой приблизительный (сглаженный) путь полученного маршрута.
  • bounds – содержит границу отображаемой области для overview_polyline.
  • copyrights – содержит текст уведомления об авторских правах, которое должно отображаться для этого маршрута. Вы должны самостоятельно обрабатывать и выводить данную информацию.
  • warnings[] – содержит массив предупреждений, которые должны отображаться для этого маршрута. Вы должны самостоятельно обрабатывать и выводить эти предупреждения.
  • fare: если имеется, содержит информацию об общей стоимости (т. е. общей стоимости билетов) этого маршрута. Это свойство возвращается только для маршрутов на общественном транспорте с доступной информацией о стоимости проезда по всем участкам. Эта информация включает следующие сведения:
    • currency: код валюты ISO 4217, указывающий валюту отображаемой суммы.
    • value: общая стоимость проезда в указанной выше валюте.
    • text: общая стоимость проезда в формате запрошенного языка.

Ниже приведен пример информации о стоимости проезда на маршруте:

"routes" : [
   {
      "bounds" : {
         "northeast" : {
            "lat" : 37.8079996,
            "lng" : -122.4074334
         },
         "southwest" : {
            "lat" : 37.7881005,
            "lng" : -122.4203553
         }
      },
      "copyrights" : "Map data ©2015 Google",
      "fare" : {
         "currency" : "USD",
         "value" : 6
         "text" : "$6.00"
      },
      ...
   }]

Участки

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

Каждый участок в поле legs может содержать следующие поля:

  • steps[] – содержит массив с информацией о каждом отдельном шаге на участке маршрута. (См. Шаги маршрута ниже.)
  • distance – указывает общее расстояние на этом участке в виде поля со следующими элементами:

    • value – указывает расстояние в метрах.
    • text – содержит понятное текстовое описание маршрута, в котором по умолчанию используются единицы измерения для начальной точки (либо в соответствии с параметром units, указанным в запросе). (Например, для любой начальной точки в пределах США используются мили и футы.) Обратите внимание, что вне зависимости от отображаемой в виде текста системы единиц измерения, поле distance.value всегда содержит значение в метрах.

    Эти поля могут отсутствовать, если расстояние неизвестно.

  • duration – указывает общее время поездки по этому участку в виде поля со следующими элементами:

    • value – указывает время поездки в секундах.
    • text – содержит понятное текстовое представление времени поездки.

    Эти поля могут отсутствовать, если время поездки неизвестно.

  • duration_in_traffic – указывает общее время поездки по этому участку. Данное значение является приблизительным временем на основе статистической информации по движению и текущей дорожной обстановки. Варианты запросов для получения оптимистичных, пессимистичных или наилучших оценок см. в описании параметра запроса traffic_model. Время поездки с учетом дорожной ситуации возвращается только при выполнении следующих условий:

    • Запрос содержит действительный ключ API или действительный идентификатор клиента Google Maps APIs Premium Plan и подпись.
    • Запрос не содержит промежуточных точек для остановок. Если запрос содержит промежуточные точки, они должны иметь префикс via:, чтобы избежать остановок.
    • Данный запрос предназначен для автомобильных маршрутов – для параметра mode установлено значение driving.
    • Запрос содержит параметр departure_time.
    • Сведения о дорожной ситуации доступны для запрошенного маршрута.

    Объект duration_in_traffic содержит следующие поля:

    • value – указывает время поездки в секундах.
    • text – содержит понятное текстовое представление времени поездки.
  • arrival_time – указывает ожидаемое время прибытия в конечную точку этого участка. Это свойство возвращается только для маршрутов на общественном транспорте. Результат возвращается в виде объекта Time, который имеет три свойства:
    • value – время, указанное в виде объекта JavaScript Date.
    • text – время, указанное в виде строки. Время указывается в часовом поясе остановки общественного транспорта.
    • time_zone – содержит часовой пояс остановки. Его значение – название часового пояса, определенное в базе данных часовых поясов IANA, например, "America/New_York".
  • departure_time – примерное время отъезда для этого участка, указанное в виде объекта Time. Поле departure_time доступно только для маршрутов на общественном транспорте.
  • start_location – содержит координаты широты/долготы для начальной точки этого участка. Поскольку Directions API рассчитывает маршруты между точками, используя ближайший транспортный путь для начальных и конечных точек (обычно дорогу), значение start_location может отличаться от указанной начальной точки этого участка, например, если дорога находится не рядом с начальной точкой.
  • end_location – содержит координаты широты/долготы для конечной точки этого участка. Поскольку Google Maps Directions API рассчитывает маршруты между точками, используя ближайший транспортный путь для начальных и конечных точек (обычно дорогу), значение end_location может отличаться от указанной конечной точки этого участка, например, если дорога находится не рядом с конечной точкой.
  • start_address – содержит понятный адрес в текстовой форме (обычно полный адрес), полученный в результате обратного геокодирования start_location этого участка.
  • end_address – содержит понятный адрес (обычно полный адрес), полученный в результате обратного геокодирования end_location этого участка.

Шаги

Каждый элемент массива steps определяет один шаг рассчитанного маршрута. Шаг является базовым элементом маршрута. Он содержит описание одного конкретного указания по поездке. Например: «Повернуть налево на 4-й улице» Шаг содержит не только описание указания, но также данные о расстоянии и времени поездки, показывающие связь этого шага со следующим шагом. Например, шаг "Повернуть на М-80" может содержать указание длительности "37 км" или "40 минут", что означает, что следующий шаг начинается через 37 км или 40 минут после этого шага.

Когда Google Maps Directions API используется для поиска маршрутов на общественном транспорте, массив шагов будет содержать дополнительную информацию о транспорте в виде массива transit_details. Если в маршрут включено несколько способов передвижения, подробные указания по шагам пешего маршрута или автомобильного маршрута предоставляются во внутреннем массиве steps. Например, описание шага пешего маршрута содержат указания по начальной и конечной точкам: "Дойти до перекрестка Иннес-Авеню и Фич-Стрит". Этот шаг будет содержать подробные указания для движения по этому маршруту во внутреннем массиве steps, например: "Двигайтесь на северо-запад", "Поверните налево на Арелиос-Уокер" и "Поверните налево на Иннес-Авеню".

Каждый шаг в поле steps может содержать следующие поля:

  • html_instructions – содержит инструкции в соответствующем формате по этому шагу в виде текстовой строки HTML.
  • distance – расстояние, покрываемое этим шагом до следующего шага. (См. описание этого поля в разделе Участки маршрута выше.) Если расстояние неизвестно, это поле может остаться без определения.
  • duration – содержит стандартное время, требуемое для выполнения этого шага вплоть до начала следующего шага. (См. описание в разделе Участки маршрута выше.) Если время в пути неизвестно, это поле может быть не определено.
  • start_location – содержит местоположение начальной точки этого шага в виде одного набора полей lat и lng.
  • end_location – содержит местоположение конечной точки этого шага в виде одного набора полей lat и lng.
  • polyline – содержит один объект points, в котором хранится представление шага в форме кодированной ломаной линии. Эта ломаная линия представляет собой приблизительный (сглаженный) путь для данного шага.
  • steps – содержит подробные инструкции по шагам движения или поездки для маршрутов на общественном транспорте. Подшаги доступны только в том случае, если для параметра travel_mode установлено значение "transit". Внутренний массив steps имеет тот же тип, что и основной массив steps.
  • transit_details – содержит информацию о маршрутах на общественном транспорте. Данное поле возвращается только в том случае, если для параметра travel_mode установлено значение "transit". См. Сведения об общественном транспорте ниже.

Сведения об общественном транспорте

Для маршрутов на общественном транспорте возвращается дополнительная информация, не актуальная для других способов передвижения. Эти дополнительные свойства передаются через объект transit_details, который возвращается как поле элемента в массиве steps[]. Объект TransitDetails можно использовать для получения дополнительной информации об остановках и маршрутах транспорта, а также транспортных агентствах.

Объект transit_details может содержать следующие поля:

  • arrival_stop и departure_stop – содержат информацию об остановках/станциях для данного участка путешествия. Сведения об остановках включают:
    • name – название остановки/станции, например, "Площадь Союза".
    • location – месторасположение остановки/станции общественного транспорта в виде полей lat и lng.
  • arrival_time и departure_time – время прибытия и отправления для данного участка маршрута, выраженное в виде следующих трех свойств:
    • text – время, указанное в виде строки. Время указывается в часовом поясе остановки общественного транспорта.
    • value – время в формате Unix или в секундах с полуночи 1 января 1970 г. по UTC.
    • time_zone – содержит часовой пояс остановки. Его значение – название часового пояса, определенное в базе данных часовых поясов IANA, например, "America/New_York".
  • headsign – указывает направление движения по этому маршруту, обозначенное на транспортном средстве или на остановке отъезда. Обычно это бывает конечная остановка или станция.
  • headway – указывает ожидаемый период в секундах между временем отправки транспорта с одной и той же остановки в это время. Например, если значение headway равняется 600, следующего автобуса нужно ждать десять минут.
  • num_stops – содержит количество остановок на этом шаге, включая остановку прибытия, но не отправления. Например, если вы отъезжаете с остановки A, проезжаете остановки B и C и выходите на остановке D, значение num_stops будет равняться 3.
  • line – содержит информацию о маршруте общественного транспорта, который используется на этом шаге, и может включать следующие свойства.
    • name – полное название маршрута общественного транспорта, например, "Экспресс 7 авеню".
    • short_name – краткое название маршрута общественного транспорта. Обычно это номер маршрута, например "М7" или "355".
    • color – цвет, обычно используемый в знаках этого маршрута общественного транспорта. Цвет указывается в виде шестнадцатеричной строки, например: #FF0033.
    • agencies – содержит массив объектов TransitAgency с информацией об операторе этого маршрута, включающую следующие свойства:
      • name – содержит название транспортного агентства.
      • url – URL-адрес сайта транспортного агентства.
      • phone – номер телефона транспортного агентства.

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

    • url – URL-адрес этого маршрута общественного транспорта, указанный транспортным агентством.
    • icon – URL-адрес значка, связанного с этим маршрутом общественного транспорта.
    • text_color – цвет текста, обычно используемого в знаках этого вида транспорта. Цвет указывается в виде шестнадцатеричной строки.
    • vehicle – тип транспорта на этом маршруте. Может включать следующие свойства:
      • name – название транспортного средства на этом маршруте, например, "Метро".
      • type – вид транспорта на этом маршруте. Полный список поддерживаемых значений содержится в разделе Вид транспорта.
      • icon – URL-адрес значка, связанного с этим видом транспорта.
      • local_icon – содержит URL-адрес значка, связанного с этим видом транспорта, с учетом его местного обозначения.

Вид транспорта

Свойство vehicle.type может возвращать одно из следующих значений:

Значение Определение
RAIL Рельсовый транспорт.
METRO_RAIL Легкое метро.
SUBWAY Метро.
TRAM Трамвай.
MONORAIL Монорельс.
HEAVY_RAIL Поезд.
COMMUTER_TRAIN Пригородный электропоезд.
HIGH_SPEED_TRAIN Скоростной поезд.
BUS Автобус.
INTERCITY_BUS Междугородный автобус.
TROLLEYBUS Троллейбус.
SHARE_TAXI Маршрутное такси (вид автобуса с возможностью посадки и выхода пассажиров на любой точке своего маршрута).
FERRY Паром.
CABLE_CAR Канатная дорога (транспорт, передвигающийся с помощью троса, обычно наземный). Воздушные канатные дороги могут относиться к типу GONDOLA_LIFT.
GONDOLA_LIFT Воздушная канатная дорога.
FUNICULAR Транспортное средство для подъема по крутому склону. Фуникулер обычно состоит из двух вагончиков, каждый из которых служит противовесом другому.
OTHER К этому типу относятся все другие транспортные средства.

Доступные способы передвижения

Поле ответа available_travel_modes содержит массив доступных способов передвижения. Данное поле возвращается в том случае, когда запрос указывает способ передвижения mode и не получает результат. Массив содержит доступные способы передвижения в странах с заданным набором промежуточных точек, которые имеют результаты. Это поле не отображается, если какая-либо промежуточная точка содержит префикс via:.

Например, попробуйте выполнить следующий запрос:

https://maps.googleapis.com/maps/api/directions/json?&mode=transit&origin=frontera+el+hierro&destination=la+restinga+el+hierro&departure_time=1399995076&key=YOUR_API_KEY

Он дает следующий ответ:

{
   "available_travel_modes" : [ "DRIVING", "BICYCLING", "WALKING" ],
   "geocoded_waypoints" : [
      {
         "geocoder_status" : "OK",
         "partial_match" : true,
         "place_id" : "ChIJwZNMti1fawwRO2aVVVX2yKg",
         "types" : [ "locality", "political" ]
      },
      {
         "geocoder_status" : "OK",
         "partial_match" : true,
         "place_id" : "ChIJ3aPgQGtXawwRLYeiBMUi7bM",
         "types" : [ "locality", "political" ]
      }
   ],
   "routes" : [],
   "status" : "ZERO_RESULTS"
}

Параметр sensor

Ранее запросы Google Maps API обязательно должны были содержать параметр sensor, чтобы указать, использовался ли приложением датчик для определения местоположения пользователя. Этот параметр больше не используется.

Оставить отзыв о...

Текущей странице
Google Maps Directions API
Google Maps Directions API
Нужна помощь? Обратитесь в службу поддержки.