Все готово!

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

Активация Google Maps Distance Matrix API

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

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

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

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

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

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

Введение

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

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

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

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

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

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

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

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

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

HTTPS или HTTP

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

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

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

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

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

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

  • origins – исходная точка для вычисления расстояния и времени пути. Можно задавать одно или несколько мест, отделяемых вертикальной чертой (|), в виде адреса, координат широты и долготы или идентификатора места.
    • При отправке адреса служба геокодирует строку, преобразуя ее в координаты широты и долготы, чтобы вычислить расстояние. Данные координаты могут отличаться от координат, полученных от Google Maps Geocoding API, например может быть указан вход в здание, а не его центр.
      origins=Bobcaygeon+ON|24+Sussex+Drive+Ottawa+ON
    • Если вы передаете координаты широты и долготы, они используются без изменений в расчетах расстояния. Убедитесь, что между значениями широты и долготы отсутствует пробел.
      origins=41.43206,-81.38992|-33.86748,151.20699
    • Если вы указываете идентификатор места, к нему необходимо добавлять префикс place_id:. Указать идентификатор места можно лишь в том случае, если запрос содержит ключ API или идентификатор клиента Google Maps APIs Premium Plan. Идентификаторы мест можно извлекать из Google Maps Geocoding API и Google Places API (включая подсказки мест). Пример использования идентификаторов мест из службы подсказок мест можно найти в документе Подсказки мест и маршруты. Подробные сведения об идентификаторах мест см. в соответствующем обзоре.
      origins=place_id:ChIJ3S-JXmauEmsRUcIaWtf4MzE
    • Вы также можете указать совокупность кодированных координат, используя алгоритм кодирования ломаной линии. Он особенно полезен при наличии большого количества исходных точек, так как URL-адрес значительно короче при использовании кодированной ломаной линии.
      • Кодированные ломаные линии должны использоваться с префиксом enc: и последующим двоеточием (:). Например, origins=enc:gfo}EtohhU:
      • Вы также можете включить несколько кодированных ломаных линий, разделив их вертикальной чертой (|). Например: origins=enc:wc~oAwquwMdlTxiKtqLyiK:|enc:c~vnAamswMvlTor@tjGi}L:|enc:udymA{~bxM:
  • destinations – одно или несколько мест, используемых как конечные точки при вычислении расстояния и времени пути. Параметры поля destinations аналогичны описанным выше параметрам поля origins.
  • key – ключ API вашего приложения. Этот ключ используется для идентификации приложения в целях управления квотами. См. дополнительную информацию о получении ключа.

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

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

https://maps.googleapis.com/maps/api/distancematrix/json?units=imperial&origins=40.6655101,-73.89188969999998&destinations=40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.6905615%2C-73.9976592%7C40.659569%2C-73.933783%7C40.729029%2C-73.851524%7C40.6860072%2C-73.6334271%7C40.598566%2C-73.7527626%7C40.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?units=imperial&origins=40.6655101,-73.89188969999998&destinations=enc:_kjwFjtsbMt%60EgnKcqLcaOzkGari%40naPxhVg%7CJjjb%40cqLcaOzkGari%40naPxhV:&key=YOUR_API_KEY

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

  • mode (по умолчанию driving) – указывает, какой способ передвижения использовать при расчете расстояния. Допустимые значения и другие сведения о запросах описаны в разделе Способы передвижения этого документа.
  • language – язык, на котором выводятся результаты.
    • См. список поддерживаемых языков. Обратите внимание, что список языков постоянно пополняется, поэтому он может быть неполным.
    • Если параметр language не указан, API будет использовать язык, указанный как предпочтительный в заголовке Accept-Language, либо основной язык домена, от которого отправлен запрос.
    • API старается предоставить почтовый адрес, который будет понятен как пользователю, так и местным жителям. Чтобы достичь этой цели, он возвращает почтовые адреса на местном языке, при необходимости используя транслитерацию, понятную пользователю, с соблюдением предпочтительного языка. Все остальные адреса возвращаются на предпочтительном языке. Все компоненты адреса возвращаются на одном языке, выбранном для первого компонента.
    • Если на предпочтительном языке такого названия нет, API использует ближайшее соответствие.
    • Предпочтительный язык оказывает небольшое влияние на набор результатов, которые возвращает API, равно как и на порядок их отображения. Интерпретация сокращений геокодировщиком может различаться в зависимости от языка, например, сокращения типов улиц или синонимов, действующие в одном языке, могут не допускаться в другом. Например, utca и tér в венгерском языке являются синонимами улицы.
  • 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 APIs Premium Plan и подпись. В параметре departure_time должно быть установлено текущее время или определенный момент времени в будущем. Прошедший момент времени является недопустимым.

      Примечание. Запросы Distance Matrix, определяющие departure_time при mode=driving, ограничены максимальным количеством 100 элементов на запрос. Количество элементов определяется произведением значений origins и destinations.

  • traffic_model (по умолчанию best_guess) – указывает предположения, используемые при расчете времени в пути. Этот параметр влияет на возвращаемое значение поля duration_in_traffic в ответе (прогнозируемое время в пути с учетом средних статистических показателей). Параметр traffic_model можно указать только для запросов со способом передвижения driving и указанным значением departure_time, содержащих ключ API или идентификатор клиента Google Maps APIs Premium Plan. Доступными значениями для данного параметра являются:
    • 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 – указывает, что в рассчитанном маршруте следует отдать приоритет уменьшению количества пересадок.

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

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

  • driving (по умолчанию) – указывает расчет расстояния по дорожной сети.
  • walking – запрос расчета расстояния для передвижения пешком по пешеходным дорожкам и тротуарам (где это возможно).
  • bicycling – запрос расчета расстояния для передвижения на велосипеде по велосипедным дорожкам и предпочитаемым улицам (где это возможно).
  • transit – запрос расчета расстояния для передвижения на общественном транспорте (где это возможно). Это значение можно указать только в том случае, если запрос содержит ключ API или идентификатор клиента Google Maps APIs Premium Plan. При выборе способа передвижения на общественном транспорте (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.

JSON
{
  "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"
      }
    } ]
  } ]
}

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

XML
<?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>

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

Далее в данной документации будет использоваться синтаксис JSON.

Элементы ответа службы 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 APIs Premium Plan и подпись.
    • Сведения о дорожной ситуации доступны для запрошенного маршрута.
    • Для параметра 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, чтобы указать, использовался ли приложением датчик для определения местоположения пользователя. Этот параметр больше не используется.

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

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