Запрос и ответ Distance Matrix API (устаревшая версия)

Введение

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

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

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

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

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

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

• целевые страницы

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

• источники

  Начальная точка для расчета расстояния и времени в пути. Вы можете указать одно или несколько местоположений, разделенных вертикальной чертой (|), в виде идентификатора места, адреса или координат широты и долготы:

  • Идентификатор места. Если вы указываете идентификатор места, перед ним нужно добавить префикс place_id:.
  • Адрес. Если вы передаете адрес, сервис геокодирует строку и преобразует ее в координаты широты и долготы, чтобы рассчитать расстояние. Эти координаты могут отличаться от тех, которые возвращает Geocoding API, например указывать на вход в здание, а не на его центр.
    Примечание. Идентификаторы мест предпочтительнее адресов и координат. Если вы используете координаты, точка всегда будет привязана к ближайшей к ним дороге. Это может быть не подъезд к объекту и даже не дорога, по которой можно быстро или безопасно добраться до пункта назначения. Если вы укажете адрес, будет рассчитано расстояние до центра здания, а не до входа в него.
  • Координаты. Если вы передадите координаты широты и долготы, они будут привязаны к ближайшей дороге. Рекомендуется передавать идентификатор места. Если вы передаете координаты, убедитесь, что между значениями широты и долготы нет пробела.
  • Коды Plus Code должны быть отформатированы как глобальные или составные коды. Коды Plus Code следует форматировать так, как в примере ниже (символы плюса экранируются в URL как %2B, а пробелы – как %20):
    • Глобальный код содержит 4 знака кода региона и 6 и более знаков местного кода (849VCWC8+R9 – это 849VCWC8%2BR9).
    • Составной код содержит 6 и более знаков местного кода с точными данными о местоположении (CWC8+R9 Mountain View, CA, USA имеет значение CWC8%2BR9%20Mountain%20View%20CA%20USA).
  • Закодированная ломаная линия. Вы также можете указать закодированный набор координат, используя алгоритм кодированной ломаной линии. Это особенно полезно, если у вас много точек отправления, поскольку URL-адрес значительно короче при использовании закодированной ломаной линии.
    • Закодированные ломаные линии должны начинаться с префикса enc:, за которым следует двоеточие :. Пример: origins=enc:gfo}EtohhU:
    • Вы также можете включить несколько закодированных ломаных линий, разделенных вертикальной чертой |. Пример:

      origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
      

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

• arrival_time

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

• избегать

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

  • 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

  Язык, на котором будут возвращены результаты.

  • Вы можете ознакомиться со списком поддерживаемых языков. 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 – указывает, что в предпочтительном маршруте должно быть как можно меньше пересадок.

• ед.

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

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

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

В этом примере для указания координат пункта назначения используются широта и долгота:

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626&key=YOUR_API_KEY'

В этом примере для указания координат пункта назначения используются плюскоды:

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco
  &origins=849VCWC8%2BR9
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=849VCWC8%2BR9&destinations=San%20Francisco&key=YOUR_API_KEY'

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

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A
  &origins=40.6655101%2C-73.89188969999998
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=40.6655101%2C-73.89188969999998&destinations=enc%3A_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV%3A&key=YOUR_API_KEY'

Информация о пробках

Она используется, если соблюдаются все перечисленные ниже условия (именно они позволяют получить поле duration_in_traffic в ответе от Distance Matrix).

• Параметр mode для способа передвижения имеет значение driving или не указан (driving является значением по умолчанию).
• Запрос содержит допустимое значение параметра departure_time. Для departure_time можно задать текущее время или произвольное время в будущем. Время в прошлом указать нельзя.

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

Следующий URL инициирует запрос к Distance Matrix API для расчета расстояний между Бостоном (штат Массачусетс) или Чарльстауном (штат Массачусетс) и Лексингтоном (штат Массачусетс) и Конкордом (штат Массачусетс). Запрос включает время отправления и соответствует всем требованиям, необходимым для возврата поля duration_in_traffic в ответе матрицы расстояний.

https://maps.googleapis.com/maps/api/distancematrix/json
  ?departure_time=now
  &destinations=Lexington%2CMA%7CConcord%2CMA
  &origins=Boston%2CMA%7CCharlestown%2CMA
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Boston%2CMA%7CCharlestown%2CMA&destinations=Lexington%2CMA%7CConcord%2CMA&departure_time=now&key=YOUR_API_KEY'

{
  "destination_addresses": ["Lexington, MA, USA", "Concord, MA, USA"],
  "origin_addresses": ["Boston, MA, USA", "Charlestown, Boston, MA, USA"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "33.3 km", "value": 33253 },
              "duration": { "text": "27 mins", "value": 1620 },
              "duration_in_traffic": { "text": "34 mins", "value": 2019 },
              "status": "OK",
            },
            {
              "distance": { "text": "41.5 km", "value": 41491 },
              "duration": { "text": "33 mins", "value": 1981 },
              "duration_in_traffic": { "text": "39 mins", "value": 2342 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "31.1 km", "value": 31100 },
              "duration": { "text": "26 mins", "value": 1543 },
              "duration_in_traffic": { "text": "29 mins", "value": 1754 },
              "status": "OK",
            },
            {
              "distance": { "text": "39.3 km", "value": 39338 },
              "duration": { "text": "32 mins", "value": 1904 },
              "duration_in_traffic": { "text": "35 mins", "value": 2077 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

 OK
 Boston, MA, USA
 Charlestown, Boston, MA, USA
 Lexington, MA, USA
 Concord, MA, USA
 
  
   OK
   
    1620
    27 mins
   
   
    33253
    33.3 km
   
   
    2018
    34 mins
   
  
  
   OK
   
    1981
    33 mins
   
   
    41491
    41.5 km
   
   
    2342
    39 mins
   
  
 
 
  
   OK
   
    1543
    26 mins
   
   
    31100
    31.1 km
   
   
    1759
    29 mins
   
  
  
   OK
   
    1904
    32 mins
   
   
    39338
    39.3 km
   
   
    2077
    35 mins
   
  
 

Модификаторы местоположения

Вы можете использовать модификаторы местоположения, чтобы указать, как водители должны подъезжать к определенному месту. Например, модификатор side_of_road позволяет указать, по какой стороне дороги нужно ехать, а заголовок – правильное направление движения.

Как указать, что маршрут должен проходить по определенной стороне дороги

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

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3A37.7663444%2C-122.4412006
  &origins=37.7680296%2C-122.4375126
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=37.7680296%2C-122.4375126&destinations=side_of_road%3A37.7663444%2C-122.4412006&key=YOUR_API_KEY'

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

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A
  &origins=San%20Francisco%20City%20hall
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=San%20Francisco%20City%20hall&destinations=side_of_road%3Aenc%3A%7BoqeF%60fejV%5BnC%3A&key=YOUR_API_KEY'

Модификатор side_of_road: можно использовать только со следующим ограничением:

• Параметр mode для способа передвижения имеет значение driving или не указан (driving является значением по умолчанию).

Как указать, что у рассчитанных маршрутов должен быть определенный заголовок

При указании местоположения вы можете запросить, чтобы рассчитанный маршрут проходил через него в определенном направлении. Направление задается с помощью префикса heading=X:, где X – целое число от 0 (включительно) до 360 (не включительно). Значение 0 соответствует северу, 90 – востоку и т. д. по часовой стрелке. Например, в этом запросе рассчитанный маршрут идет на восток от начальной точки, а затем делает разворот:

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=37.773245%2C-122.469502
  &origins=heading%3D90%3A37.773279%2C-122.468780
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=heading%3D90%3A37.773279%2C-122.468780&destinations=37.773245%2C-122.469502&key=YOUR_API_KEY'

Модификатор heading=X: можно использовать только со следующими ограничениями:

• Параметр mode для способа передвижения имеет значение driving или bicycling либо не указан (driving является значением по умолчанию).
• Для того же местоположения не указан модификатор side_of_road.
• Местоположение задается с помощью значений широты и долготы. Нельзя использовать heading с адресами, идентификаторами мест или закодированными ломаными линиями.

Запросы и ответы Distance Matrix

Ниже приведен пример HTTP-запроса, в котором запрашивается расстояние и время в пути от Ванкувера (Британская Колумбия, Канада) и Сиэтла (Вашингтон, США) до Сан-Франциско (Калифорния, США) и Виктории (Британская Колумбия, Канада).

https://maps.googleapis.com/maps/api/distancematrix/json
  ?destinations=San%20Francisco%7CVictoria%20BC
  &language=fr-FR
  &mode=bicycling
  &origins=Vancouver%20BC%7CSeattle
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver%20BC%7CSeattle&destinations=San%20Francisco%7CVictoria%20BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY'

По запросу будут возвращены четыре элемента – количество исходных точек (2) умноженное на количество конечных точек (2):

Результаты возвращаются в виде строк, каждая из которых содержит одну точку отправления и все точки назначения.

{
  "destination_addresses":
    ["San Francisco, Californie, États-Unis", "Victoria, BC, Canada"],
  "origin_addresses":
    ["Vancouver, BC, Canada", "Seattle, Washington, États-Unis"],
  "rows":
    [
      {
        "elements":
          [
            {
              "distance": { "text": "1 712 km", "value": 1711765 },
              "duration": { "text": "3 jours 16 heures", "value": 318119 },
              "status": "OK",
            },
            {
              "distance": { "text": "140 km", "value": 139695 },
              "duration": { "text": "6 heures 49 minutes", "value": 24567 },
              "status": "OK",
            },
          ],
      },
      {
        "elements":
          [
            {
              "distance": { "text": "1 452 km", "value": 1451704 },
              "duration": { "text": "3 jours 2 heures", "value": 266680 },
              "status": "OK",
            },
            {
              "distance": { "text": "146 km", "value": 146500 },
              "duration": { "text": "2 heures 53 minutes", "value": 10374 },
              "status": "OK",
            },
          ],
      },
    ],
  "status": "OK",
}

 OK
 Vancouver, BC, Canada
 Seattle, Washington, États-Unis
 San Francisco, Californie, États-Unis
 Victoria, BC, Canada
 
  
   OK
   
    318119
    3 jours 16 heures
   
   
    1711765
    1 712 km
   
  
  
   OK
   
    24567
    6 heures 49 minutes
   
   
    139695
    140 km
   
  
 
 
  
   OK
   
    266680
    3 jours 2 heures
   
   
    1451704
    1 452 km
   
  
  
   OK
   
    10374
    2 heures 53 minutes
   
   
    146500
    146 km
   
  
 

DistanceMatrixResponse

DistanceMatrixStatus

Коды статуса, возвращаемые сервисом.

• OK – ответ содержит действительный результат.
• INVALID_REQUEST означает, что запрос недействителен.
• MAX_ELEMENTS_EXCEEDED означает, что результат умножения числа пунктов отправления и назначения в запросе превышает установленное ограничение.
• MAX_DIMENSIONS_EXCEEDED указывает, что количество пунктов отправления или назначения превышает ограничение на запрос.
• OVER_DAILY_LIMIT указывает на одно из следующих значений:
  • Ключ API отсутствует или недействителен.
  • В вашем аккаунте не включены платежные функции.
  • Превышено заданное ограничение на использование.
  • Указанный способ оплаты больше не действует (например, истек срок действия кредитной карты).
• OVER_QUERY_LIMIT – сервис получил слишком много запросов от вашего приложения за промежуток времени.
• REQUEST_DENIED – вашему приложению отказано в использовании сервиса Distance Matrix.
• UNKNOWN_ERROR указывает на то, что запрос матрицы расстояний не удалось обработать из-за ошибки сервера. Если повторить попытку, запрос может оказаться успешным.

DistanceMatrixRow

DistanceMatrixElement

Тариф

Общая стоимость проезда по маршруту.

{
  "currency" : "USD",
  "value" : 6,
  "text" : "$6.00"
}

DistanceMatrixElementStatus

• OK – ответ содержит действительный результат.
• NOT_FOUND – не удалось выполнить геокодирование в паре пунктов отправления/назначения.
• ZERO_RESULTS – между пунктом отправления и пунктом назначения не найдено ни одного маршрута.
• MAX_ROUTE_LENGTH_EXCEEDED – запрос нельзя обработать: слишком длинный маршрут.

TextValueObject

Объект, содержащий числовое значение и его форматированное текстовое представление.