Google Maps Distance Matrix API

Введение

Google Maps Distance Matrix API – это служба, которая предоставляет информацию о расстоянии и времени поездки для матрицы исходных точек и пунктов назначения. Возвращаемая информация основывается на рекомендованном маршруте между исходной точкой и пунктом назначения в соответствии с расчетами Google Maps API и состоит из строк, которые содержат значения duration и distance для каждой пары.

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

Получение ключа Ограничения на использование

Целевая аудитория

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

Запросы службы Distance Matrix

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

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

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

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

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

URL-адреса Google Maps Distance Matrix API должны содержать не более 2000 символов после кодирования URL. Поскольку некоторые URL-адреса службы Google Maps Distance Matrix API могут содержать множество мест, следует учитывать данное ограничение при создании собственных URL-адресов. Обратите внимание на то, что разные браузеры, прокси и серверы также могут иметь разные ограничения для количества символов в URL-адресе.

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

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

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

• origins – один или несколько адресов и/или текстовых значений широты или долготы, разделяемых вертикальной чертой (|), из которых рассчитываются расстояние и время. При отправке адреса в виде строки служба выполнит геокодирование строки и преобразует ее в координаты широты/долготы для расчета расстояний. При передаче координат убедитесь, что между значениями широты и долготы отсутствует пробел.

  origins=Bobcaygeon+ON|41.43206,-81.38992

• destinations – один или несколько адресов и/или текстовых значений широты или долготы, разделяемых вертикальной чертой (|), до которых рассчитываются расстояние и время. При отправке адреса в виде строки служба выполнит геокодирование строки и преобразует ее в координаты широты/долготы для расчета расстояний. При передаче координат убедитесь, что между значениями широты и долготы отсутствует пробел.

  destinations=Darling+Harbour+NSW+Australia|24+Sussex+Drive+Ottawa+ON|Capitola+CA

• key – ключ API вашего приложения. Этот ключ используется для идентификации приложения в целях управления квотами. См. дополнительную информацию о получении ключа.

В своих запросах службы Distance Matrix пользователи Google Maps API for Work должны указывать действительные параметры client и signature. Дополнительную информацию см. в разделе Google Maps API for Work Web Services.

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

• mode (по умолчанию driving) – указывает, какой способ передвижения использовать при расчете расстояния. Допустимые значения и другие сведения о запросах описаны в разделе Способы передвижения этого документа.
• language – язык, на котором выводятся результаты. См. список поддерживаемых языков домена. Обратите внимание, что список языков постоянно пополняется, поэтому он может быть неполным.
• avoid – указывает ограничения для маршрута. Допустимые значения указаны в разделе Ограничения этого документа. Можно указывать только одно ограничение.
• unit – указывает, какую систему единиц измерения следует использовать для выражения расстояния в виде текста. Дополнительные сведения приведены в разделе Системы единиц этого документа.
• 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 API for Work и подпись. В параметре departure_time должно быть установлено текущее время или определенный момент времени в будущем. Прошедший момент времени является недопустимым.
• traffic_model (по умолчанию best_guess) – указывает предположения, используемые при расчете времени в пути. Этот параметр влияет на возвращаемое значение поля duration_in_traffic в ответе (прогнозируемое время в пути с учетом средних статистических показателей). Параметр traffic_model может быть указан только для тех запросов, в которых средством передвижения является автомобиль и указано значение departure_time, а также указан ключ API или идентификатор клиента Google Maps API for Work. Доступными значениями для данного параметра являются:
  • best_guess (по умолчанию) – означает, что возвращаемое в поле duration_in_traffic значение должно содержать наилучшую оценку ожидаемого времени пути с учетом имеющейся статистической информации по движению и текущей дорожной обстановки. Чем ближе время departure_time к настоящему моменту, тем выше важность текущей дорожной обстановки.
  • pessimistic – означает, что возвращаемое значение duration_in_traffic должно быть больше, чем фактическое время поездки в большинство дней, хотя в отдельные дни из-за очень плохой дорожной обстановки данное значение может быть и больше.
  • optimistic – означает, что возвращаемое значение duration_in_traffic должно быть меньше, чем фактическое время поездки в большинство дней, хотя в отдельные дни из-за очень хорошей дорожной обстановки для поездки может требоваться еще меньше времени.
• transit_mode – указывает один или несколько предпочитаемых способов передвижения. Этот параметр может быть указан только для запросов, в которых в качестве способа передвижения (mode) используется общественный транспорт (transit). Данный параметр поддерживает следующие аргументы:
  • bus – указывает, что в рассчитанном маршруте следует отдать приоритет передвижению на автобусе.
  • subway – указывает, что в рассчитанном маршруте следует отдать приоритет передвижению на метро.
  • train – указывает, что в рассчитанном маршруте следует отдать приоритет передвижению на поезде.
  • tram – указывает, что в рассчитанном маршруте следует отдать приоритет передвижению на трамвае и легком метро.
  • rail – указывает, что в рассчитанном маршруте следует отдать приоритет передвижению на поезде, трамвае, метрополитене и легком метро. Это значение аналогично указанию transit_mode=train|tram|subway.
• transit_routing_preference – указывает предпочтения для запросов маршрутов на общественном транспорте. С помощью этого параметра можно указать предпочтения для возвращаемых вариантов вместо принятия маршрута, который был выбран по умолчанию API в качестве оптимального. Этот параметр может быть указан только для запросов, в которых в качестве способа передвижения (mode) используется общественный транспорт (transit). Данный параметр поддерживает следующие аргументы:
  • less_walking – указывает, что в рассчитанном маршруте следует отдать приоритет уменьшению расстояния, которое нужно пройти пешком.
  • fewer_transfers – указывает, что в рассчитанном маршруте следует отдать приоритет уменьшению количества пересадок.

* Примечание. Запросы, которые включают в себя параметр departure_time, ограничены 100 элементами.

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

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

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

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

Ограничения

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

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

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

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

Результаты Distance Matrix содержат параметр text в поле distance, которое указывает расстояние для рассчитанного маршрута. Используемая система единиц может быть указана как:

• units=metric (по умолчанию) – указывает расстояния в метрах и километрах,
• units=imperial – указывает расстояния в милях и футах.

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

Ответы службы Distance Matrix

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

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

Следующий запрос содержит пример использования флага output в формате JSON:

https://maps.googleapis.com/maps/api/distancematrix/json?origins=Vancouver+BC|Seattle&destinations=San+Francisco|Victoria+BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY

Следующий запрос содержит пример использования флага output в формате XML:

https://maps.googleapis.com/maps/api/distancematrix/xml?origins=Vancouver+BC|Seattle&destinations=San+Francisco|Vancouver+BC&mode=bicycling&language=fr-FR&key=YOUR_API_KEY

Данный запрос вернет четыре элемента – две исходные точки умноженные на два пункта назначения:

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

Попробуйте сделать это сами. Щелкните здесь, чтобы открыть этот пример запроса в своем браузере. (Если вам будет предложено выбрать приложение для открытия файла, выберите свой браузер или предпочитаемый текстовый редактор.)

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

{
  "status": "OK",
  "origin_addresses": [ "Vancouver, BC, Canada", "Seattle, État de Washington, États-Unis" ],
  "destination_addresses": [ "San Francisco, Californie, États-Unis", "Victoria, BC, Canada" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 340110,
        "text": "3 jours 22 heures"
      },
      "distance": {
        "value": 1734542,
        "text": "1 735 km"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 24487,
        "text": "6 heures 48 minutes"
      },
      "distance": {
        "value": 129324,
        "text": "129 km"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 288834,
        "text": "3 jours 8 heures"
      },
      "distance": {
        "value": 1489604,
        "text": "1 490 km"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 14388,
        "text": "4 heures 0 minutes"
      },
      "distance": {
        "value": 135822,
        "text": "136 km"
      }
    } ]
  } ]
}

<?xml version="1.0" encoding="UTF-8"?>
<DistanceMatrixResponse>
 <status>OK</status>
 <origin_address>Vancouver, BC, Canada</origin_address>
 <origin_address>Seattle, État de Washington, États-Unis</origin_address>
 <destination_address>San Francisco, Californie, États-Unis</destination_address>
 <destination_address>Victoria, BC, Canada</destination_address>
 <row>
  <element>
   <status>OK</status>
   <duration>
    <value>340110</value>
    <text>3 jours 22 heures</text>
   </duration>
   <distance>
    <value>1734542</value>
    <text>1 735 km</text>
   </distance>
  </element>
  <element>
   <status>OK</status>
   <duration>
    <value>24487</value>
    <text>6 heures 48 minutes</text>
   </duration>
   <distance>
    <value>129324</value>
    <text>129 km</text>
   </distance>
  </element>
 </row>
 <row>
  <element>
   <status>OK</status>
   <duration>
    <value>288834</value>
    <text>3 jours 8 heures</text>
   </duration>
   <distance>
    <value>1489604</value>
    <text>1 490 km</text>
   </distance>
  </element>
  <element>
   <status>OK</status>
   <duration>
    <value>14388</value>
    <text>4 heures 0 minutes</text>
   </duration>
   <distance>
    <value>135822</value>
    <text>136 km</text>
   </distance>
  </element>
 </row>
</DistanceMatrixResponse>

Элементы ответа службы Distance Matrix

Ответы службы Distance Matrix содержат следующие корневые элементы:

• status – содержит метаданные по запросу. См. раздел Коды состояния ниже.
• origin_addresses – содержит массив адресов, возвращаемых API-интерфейсом из вашего исходного запроса. Эти данные форматируются геокодировщиком и отображаются на языке, который указан в параметре language, передаваемом с запросом.
• destination_addresses – содержит массив адресов, возвращаемых API-интерфейсом из вашего исходного запроса. Как и в случае с origin_addresses, они отображаются на соответствующем языке (если возможно).
• rows – содержит массив элементов elements, каждый из которых в свою очередь содержит элементы status, duration и distance.

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

Поля status в объекте ответа содержат данные о состоянии запроса и могут содержать полезную отладочную информацию. Distance Matrix API возвращает поле состояния верхнего уровня с общей информацией о запросе, а также поле состояния для каждого поля элемента с информацией об этой конкретной паре "исходная точка – пункт назначения".

Коды состояния верхнего уровня

• OK – указывает, что ответ содержит корректный результат result.
• INVALID_REQUEST – указывает на недопустимый запрос.
• MAX_ELEMENTS_EXCEEDED – указывает, что произведение числа исходных точек и числа пунктов назначения превысило ограничение по запросу.
• OVER_QUERY_LIMIT – указывает, что служба получила слишком много запросов от вашего приложения в течение разрешенного периода.
• REQUEST_DENIED – указывает, что вашему приложению отказано в использовании службы Distance Matrix.
• UNKNOWN_ERROR – не удалось выполнить запрос Distance Matrix из-за ошибки сервера. Если повторить попытку, запрос может оказаться успешным.

Коды состояния элементов

• OK – указывает, что ответ содержит корректный результат result.
• NOT_FOUND – не удалось выполнить геокодирование исходной точки или точки назначения для этой пары.
• ZERO_RESULTS – означает, что не удалось проложить маршрут между исходной точкой и точкой назначения.

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

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

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

Строки

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

Порядок расположения строк соответствует значениям параметра origin в запросе. Каждая строка соответствует исходной точке, а каждая запись element в этой строке соответствует паре исходной точки и значения destination.

Каждый массив row содержит одну или несколько записей element, которые в свою очередь содержат информацию об отдельной паре "исходная точка – пункт назначения".

Элементы

Информация о каждой паре "исходная точка – пункт назначения" возвращается в записи element. element содержит следующие поля:

• status: перечень возможных кодов состояния приведен в разделе Коды состояния.
• duration: длительность поездки по этому маршруту, выраженная в секундах (поле value) и в виде текста. Для текстового представления используется язык, указанный в параметре запроса language.

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

  • Запрос содержит параметр departure_time.
  • Запрос содержит действительный ключ API или действительный идентификатор клиента Google Maps API for Work и подпись.
  • Сведения о дорожной ситуации доступны для запрошенного маршрута.
  • Для параметра mode установлено значение driving.
• distance: общее расстояние этого маршрута, выраженное в метрах (value) и в виде текста. Текстовое значение использует систему единиц, указанную в параметре исходного запроса unit, или соответствующую региону исходной точки.
• fare: если имеется, содержит информацию об общей стоимости (т. е. общей стоимости билетов) этого маршрута. Это свойство возвращается только для запросов маршрутов на общественном транспорте и только для тех транспортных операторов, которые предоставили информацию о стоимости проезда. Эта информация включает следующие сведения:
  • currency: код валюты ISO 4217, указывающий валюту отображаемой суммы.
  • value: общая стоимость проезда в указанной выше валюте.
  • text: общая стоимость проезда в формате запрошенного языка.

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

{
  "status": "OK",
  "duration": {
    "value": 340110,
    "text": "3 jours 22 heures"
  },
  "distance": {
    "value": 1734542,
    "text": "1 735 km"
  }
  "fare" : {
    "currency" : "USD",
    "value" : 6,
    "text" : "$6.00"
  },
}

Параметр sensor

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