Сервис Distance Matrix

Примечание. Серверные библиотеки.

На этой странице описывается клиентская служба, доступная с помощью Maps JavaScript API. Если вы хотите работать с веб-службами Google Maps на своем сервере, обратите внимание на клиент Node.js для служб Google Maps . На странице по этой ссылке также представлены клиент Java, клиент Python и клиент Go для служб Google Maps.

Обзор

Также см. Справочник по Maps JavaScript API: Матрица расстояний.

Служба Distance Matrix от Google рассчитывает расстояние и продолжительность поездки между несколькими пунктами отправления и назначения с использованием заданного способа передвижения.

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

Начиная

Прежде чем использовать службу Distance Matrix в Maps JavaScript API, сначала убедитесь, что Distance Matrix API включен в Google Cloud Console в том же проекте, который вы настроили для Maps JavaScript API.

Чтобы просмотреть список включенных API:

1. Перейдите в облачную консоль Google .
2. Нажмите кнопку «Выбрать проект» , затем выберите тот же проект, который вы настроили для Maps JavaScript API, и нажмите « Открыть» .
3. В списке API на информационной панели найдите Distance Matrix API .
4. Если вы видите API в списке, все готово. Если API нет в списке, включите его:
   1. В верхней части страницы выберите ВКЛЮЧИТЬ API , чтобы отобразить вкладку «Библиотека» . Либо в меню слева выберите «Библиотека» .
   2. Найдите Distance Matrix API , затем выберите его из списка результатов.
   3. Выберите ВКЛЮЧИТЬ . Когда процесс завершится, Distance Matrix API появится в списке API на информационной панели .

Ценообразование и политика

Цены

С 16 июля 2018 года вступил в силу новый тарифный план с оплатой по мере использования для Карт, Маршрутов и Мест. Чтобы узнать больше о новых ценах и ограничениях на использование службы JavaScript Distance Matrix, см. Использование и выставление счетов для Distance Matrix API.

Примечание . Каждый запрос, отправляемый в службу Distance Matrix, ограничен количеством разрешенных элементов, при этом количество элементов определяется количеством источников , умноженным на количество пунктов назначения .

Политика

Использование сервиса Distance Matrix должно осуществляться в соответствии с политиками, описанными для Distance Matrix API .

Запросы матрицы расстояний

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

Вы получаете доступ к службе Distance Matrix в своем коде через объект-конструктор google.maps.DistanceMatrixService . Метод DistanceMatrixService.getDistanceMatrix() инициирует запрос к службе Distance Matrix, передавая ему литерал объекта DistanceMatrixRequest , содержащий пункты отправления, пункты назначения и режим путешествия, а также метод обратного вызова для выполнения после получения ответа.

var origin1 = new google.maps.LatLng(55.930385, -3.118425);
var origin2 = 'Greenwich, England';
var destinationA = 'Stockholm, Sweden';
var destinationB = new google.maps.LatLng(50.087692, 14.421150);

var service = new google.maps.DistanceMatrixService();
service.getDistanceMatrix(
  {
    origins: [origin1, origin2],
    destinations: [destinationA, destinationB],
    travelMode: 'DRIVING',
    transitOptions: TransitOptions,
    drivingOptions: DrivingOptions,
    unitSystem: UnitSystem,
    avoidHighways: Boolean,
    avoidTolls: Boolean,
  }, callback);

function callback(response, status) {
  // See Parsing the Results for
  // the basics of a callback function.
}

Посмотреть пример

DistanceMatrixRequest содержит следующие поля:

• origins (обязательно) — массив, содержащий одну или несколько адресных строк, объекты google.maps.LatLng или объекты Place , на основе которых рассчитывается расстояние и время.
• destinations (обязательно) — массив, содержащий одну или несколько адресных строк, объекты google.maps.LatLng или объекты Place , до которых рассчитывается расстояние и время.
• travelMode ( необязательно ) — вид транспорта, который будет использоваться при расчете направлений. См. раздел о режимах передвижения .
• transitOptions ( необязательный ) — параметры, которые применяются только к запросам, где travelMode имеет значение TRANSIT . Допустимые значения описаны в разделе « Параметры транзита» .
• drivingOptions ( необязательный ) определяет значения, которые применяются только к запросам, где travelMode имеет значение DRIVING . Допустимые значения описаны в разделе « Параметры вождения» .
• unitSystem ( необязательно ) — Система единиц измерения, используемая при отображении расстояния. Принятые значения:
  • google.maps.UnitSystem.METRIC (по умолчанию)
  • google.maps.UnitSystem.IMPERIAL
• avoidHighways ( необязательно ) — если true , маршруты между пунктами отправления и назначениями будут рассчитываться так, чтобы избегать шоссе, где это возможно.
• avoidTolls ( необязательно ) — если true , направления между точками будут рассчитываться с использованием платных маршрутов, где это возможно.

Примечание. Поле durationInTraffic устарело . Ранее для клиентов Премиум-плана платформы Google Карт был рекомендован способ указать, должен ли результат включать продолжительность, учитывающую текущие условия на дорогах. Теперь вам следует использовать поле drivingOptions .

Режимы путешествия

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

• BICYCLING запрашивает велосипедные маршруты по велосипедным дорожкам и предпочтительным улицам (в настоящее время доступно только в США и некоторых городах Канады).
• DRIVING (по умолчанию) указывает стандартные направления движения с использованием дорожной сети.
• TRANSIT запрашивает указания по маршрутам общественного транспорта. Эту опцию можно указать только в том случае, если запрос включает ключ API. Доступные варианты в запросе этого типа см. в разделе « Варианты транзита» .
• WALKING запрашивает пешеходные маршруты по пешеходным дорожкам и тротуарам (если таковые имеются).

Варианты транзита

Транзитная служба в настоящее время находится в «экспериментальном режиме». На этом этапе мы будем внедрять ограничения скорости, чтобы предотвратить злоупотребление API. В конечном итоге мы введем ограничение на общее количество запросов на загрузку карты на основе добросовестного использования API.

Доступные параметры запроса матрицы расстояний различаются в зависимости от режима движения. В транзитных запросах параметры avoidHighways и avoidTolls игнорируются. Вы можете указать параметры маршрутизации для конкретного транзита через литерал объекта TransitOptions .

Запросы на транзит чувствительны ко времени. Расчеты будут возвращены только для раз в будущем.

Литерал объекта TransitOptions содержит следующие поля:

{
  arrivalTime: Date,
  departureTime: Date,
  modes: [transitMode1, transitMode2]
  routingPreference: TransitRoutePreference
}

Эти поля описаны ниже:

• arrivalTime ( необязательный ) указывает желаемое время прибытия в виде объекта Date . Если указано время прибытия, время отправления игнорируется.
• departureTime ( необязательно ) указывает желаемое время отъезда в виде объекта Date . departureTime будет игнорироваться, если указано arrivalTime . По умолчанию используется значение now (то есть текущее время), если не указано значение ни для departureTime , ни arrivalTime .
• modes ( необязательный ) — это массив, содержащий один или несколько литералов объекта TransitMode . Это поле можно включить только в том случае, если запрос включает ключ API. Каждый TransitMode определяет предпочтительный режим транзита. Допускаются следующие значения:
  • BUS указывает, что в расчетном маршруте предпочтение должно отдаваться проезду на автобусе.
  • RAIL указывает, что для расчетного маршрута следует предпочесть проезд на поезде, трамвае, легкорельсовом транспорте и метро.
  • SUBWAY указывает, что при расчете маршрута предпочтение должно отдаваться проезду на метро.
  • TRAIN указывает, что в расчетном маршруте предпочтение должно быть отдано поезду.
  • TRAM указывает, что в расчетном маршруте предпочтение следует отдать трамваю и легкорельсовому транспорту.
• routingPreference ( необязательный ) определяет предпочтения для транзитных маршрутов. Используя эту опцию, вы можете смещать возвращаемые параметры вместо того, чтобы принимать лучший маршрут по умолчанию, выбранный API. Это поле можно указать только в том случае, если запрос включает ключ API. Допускаются следующие значения:
  • FEWER_TRANSFERS указывает, что рассчитанный маршрут должен отдавать предпочтение ограниченному количеству пересадок.
  • LESS_WALKING указывает, что рассчитанный маршрут должен отдавать предпочтение ограниченному количеству прогулок.

Варианты вождения

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

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

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Эти поля описаны ниже:

• departureTime ( необходимый для корректности литерала объекта drivingOptions ) указывает желаемое время отъезда в виде объекта Date . Значение должно быть установлено на текущее время или некоторое время в будущем. Это не может быть в прошлом. (API преобразует все даты в формат UTC, чтобы обеспечить единообразную обработку во всех часовых поясах.) Если вы включаете в запрос значение departureTime , API возвращает лучший маршрут с учетом ожидаемых условий дорожного движения в данный момент и включает прогнозируемое время в пробке ( duration_in_traffic ) в ответе. Если вы не укажете время отправления (то есть, если запрос не включает drivingOptions ), возвращаемый маршрут, как правило, является хорошим маршрутом без учета условий движения.
  Внимание: если вы не укажете время отправления, выбранный маршрут и продолжительность будут основаны на дорожной сети и средних условиях движения, не зависящих от времени, а не на текущих дорожных условиях. Следовательно, маршруты могут включать дороги, которые временно закрыты. Результаты для данного запроса могут меняться со временем из-за изменений в дорожной сети, обновленных средних условий дорожного движения и распределенного характера услуги. Результаты также могут различаться между почти эквивалентными маршрутами в любое время и с любой частотой.
• trafficModel ( необязательный ) указывает предположения, которые следует использовать при расчете времени в пробке. Этот параметр влияет на значение, возвращаемое в поле duration_in_traffic в ответе, которое содержит прогнозируемое время в трафике на основе исторических средних значений. По умолчанию — best_guess . Допускаются следующие значения:
  • bestguess (по умолчанию) указывает, что возвращаемое duration_in_traffic должно быть наилучшей оценкой времени в пути с учетом того, что известно как об исторических условиях дорожного движения, так и о реальном трафике. Живое движение становится тем более важным, чем ближе departureTime к настоящему моменту.
  • pessimistic указывает, что возвращаемое duration_in_traffic должно быть больше фактического времени в пути в большинстве дней, хотя в отдельные дни с особенно плохими дорожными условиями может превышать это значение.
  • optimistic указывает, что возвращаемое duration_in_traffic должно быть короче фактического времени в пути в большинстве дней, хотя в отдельные дни с особенно хорошими дорожными условиями может быть быстрее, чем это значение.

Ниже приведен пример DistanceMatrixRequest для автомобильных маршрутов, включая время отправления и модель трафика:

{
  origins: [{lat: 55.93, lng: -3.118}, 'Greenwich, England'],
  destinations: ['Stockholm, Sweden', {lat: 50.087, lng: 14.421}],
  travelMode: 'DRIVING',
  drivingOptions: {
    departureTime: new Date(Date.now() + N),  // for the time N milliseconds from now.
    trafficModel: 'optimistic'
  }
}

Ответы матрицы расстояний

Успешный вызов службы Distance Matrix возвращает объект DistanceMatrixResponse и объект DistanceMatrixStatus . Они передаются в функцию обратного вызова, указанную в запросе.

Объект DistanceMatrixResponse содержит информацию о расстоянии и продолжительности для каждой пары отправления/назначения, для которой может быть рассчитан маршрут.

{
  "originAddresses": [ "Greenwich, Greater London, UK", "13 Great Carleton Square, Edinburgh, City of Edinburgh EH16 4, UK" ],
  "destinationAddresses": [ "Stockholm County, Sweden", "Dlouhá 609/2, 110 00 Praha-Staré Město, Česká republika" ],
  "rows": [ {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 70778,
        "text": "19 hours 40 mins"
      },
      "distance": {
        "value": 1887508,
        "text": "1173 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 44476,
        "text": "12 hours 21 mins"
      },
      "distance": {
        "value": 1262780,
        "text": "785 mi"
      }
    } ]
  }, {
    "elements": [ {
      "status": "OK",
      "duration": {
        "value": 96000,
        "text": "1 day 3 hours"
      },
      "distance": {
        "value": 2566737,
        "text": "1595 mi"
      }
    }, {
      "status": "OK",
      "duration": {
        "value": 69698,
        "text": "19 hours 22 mins"
      },
      "distance": {
        "value": 1942009,
        "text": "1207 mi"
      }
    } ]
  } ]
}

Результаты матрицы расстояний

Поддерживаемые поля в ответе описаны ниже.

• originAddresses — это массив, содержащий местоположения, переданные в поле origins запроса матрицы расстояний. Адреса возвращаются в том виде, в котором они отформатированы геокодером.
• destinationAddresses — это массив, содержащий местоположения, переданные в поле destinations , в формате, возвращаемом геокодировщиком.
• rows — это массив объектов DistanceMatrixResponseRow , где каждая строка соответствует началу координат.
• elements являются дочерними элементами rows и соответствуют паре источника строки с каждым пунктом назначения. Они содержат информацию о статусе, продолжительности, расстоянии и тарифе (если таковая имеется) для каждой пары отправления/назначения.
• Каждый element содержит следующие поля:
  • status : список возможных кодов состояния см. в разделе «Коды состояния ».
  • duration : время, необходимое для прохождения этого маршрута, выраженное в секундах (поле value ) и в виде text . Текстовое значение форматируется в соответствии с unitSystem , указанной в запросе (или в метрике, если предпочтение не указано).
  • duration_in_traffic : продолжительность времени, необходимого для проезда по этому маршруту с учетом текущих условий дорожного движения, выраженная в секундах (поле value ) и в виде text . Текстовое значение форматируется в соответствии с unitSystem , указанной в запросе (или в метрике, если предпочтение не указано). duration_in_traffic возвращается только в том случае, если доступны данные о трафике, установлен mode driving , а departureTime включено как часть поля distanceMatrixOptions в запросе.
  • distance : общее расстояние этого маршрута, выраженное в метрах ( value ) и в виде text . Текстовое значение форматируется в соответствии с unitSystem , указанной в запросе (или в метрике, если предпочтение не указано).
  • fare : Содержит общий тариф (то есть общую стоимость билета) по этому маршруту. Это свойство возвращается только для запросов на транзит и только для поставщиков транзита, у которых доступна информация о тарифах. Информация включает в себя:
    • currency : код валюты ISO 4217, указывающий валюту, в которой выражена сумма.
    • value : общая сумма тарифа в валюте, указанной выше.

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

Ответ Distance Matrix включает код состояния для ответа в целом, а также статус для каждого элемента.

Коды состояния ответа

Коды состояния, применимые к DistanceMatrixResponse передаются в объекте DistanceMatrixStatus и включают в себя:

• OK — запрос действителен. Этот статус можно вернуть, даже если не найдено ни одного маршрута между пунктами отправления и назначения. См. «Коды состояния элемента» для получения информации о состоянии на уровне элемента.
• INVALID_REQUEST — Предоставленный запрос недействителен. Часто это происходит из-за отсутствия обязательных полей. См. список поддерживаемых полей выше.
• MAX_ELEMENTS_EXCEEDED — Продукт отправителей и пунктов назначения превышает лимит для каждого запроса .
• MAX_DIMENSIONS_EXCEEDED — ваш запрос содержал более 25 пунктов отправления или более 25 пунктов назначения.
• OVER_QUERY_LIMIT — Ваше приложение запросило слишком много элементов в течение разрешенного периода времени. Запрос должен быть успешным, если вы повторите попытку через разумное время.
• REQUEST_DENIED — служба запретила использование службы Distance Matrix вашей веб-страницей.
• UNKNOWN_ERROR — запрос матрицы расстояний не удалось обработать из-за ошибки сервера. Запрос может быть успешным, если вы повторите попытку.

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

Следующие коды состояния применяются к конкретным объектам DistanceMatrixElement :

• NOT_FOUND — Не удалось геокодировать отправную точку и/или место назначения этой пары.
• OK — ответ содержит действительный результат.
• ZERO_RESULTS — Не удалось найти маршрут между пунктом отправления и пунктом назначения.

Анализ результатов

Объект DistanceMatrixResponse содержит одну row для каждого источника, переданного в запросе. Каждая строка содержит поле element для каждой пары этого источника с указанным пунктом назначения(ов).

function callback(response, status) {
  if (status == 'OK') {
    var origins = response.originAddresses;
    var destinations = response.destinationAddresses;

    for (var i = 0; i < origins.length; i++) {
      var results = response.rows[i].elements;
      for (var j = 0; j < results.length; j++) {
        var element = results[j];
        var distance = element.distance.text;
        var duration = element.duration.text;
        var from = origins[i];
        var to = destinations[j];
      }
    }
  }
}