Эта страница переведена с помощью Cloud Translation API.

Сервис Distance Matrix

Разработчики Европейской экономической зоны (ЕЭЗ)

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

Обзор

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

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

Начиная

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

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

Перейдите в консоль Google Cloud .
Нажмите кнопку Выбрать проект , затем выберите тот же проект, который вы настроили для Maps JavaScript API, и нажмите Открыть .
В списке API на панели инструментов найдите Distance Matrix API (Legacy) .
Если вы видите API в списке, все готово. Если API не указан, включите его на https://console.cloud.google.com/apis/library/distance-matrix-backend.googleapis.com

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

Ценообразование

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

Примечание : Каждый запрос, отправляемый в службу 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 . Допустимые значения описаны в разделе Driving Options .
unitSystem ( необязательно ) — Система единиц измерения, используемая при отображении расстояния. Принимаемые значения:
- google.maps.UnitSystem.METRIC (по умолчанию)
- google.maps.UnitSystem.IMPERIAL
avoidHighways ( необязательно ) — если true , маршруты между пунктами отправления и назначения будут рассчитываться таким образом, чтобы по возможности избегать автомагистралей.
avoidTolls ( необязательно ) — если true , то маршруты между точками будут рассчитываться с использованием бесплатных маршрутов, где это возможно.

Примечание: Поле durationInTraffic теперь устарело . Ранее это был рекомендуемый способ для клиентов Google Maps Platform Premium Plan указать, должен ли результат включать длительность, учитывающую текущие условия дорожного движения. Теперь вместо этого следует использовать поле drivingOptions .

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

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

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

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

Transit Service в настоящее время является «экспериментальной». На этом этапе мы будем вводить ограничения скорости для предотвращения злоупотреблений 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 запроса Distance Matrix. Адреса возвращаются в том виде, в котором они отформатированы геокодером.
destinationAddresses — это массив, содержащий местоположения, переданные в поле destinations , в формате, возвращаемом геокодером.
rows — это массив объектов DistanceMatrixResponseRow , где каждая строка соответствует началу координат.
elements являются дочерними элементами rows и соответствуют паре происхождения строки с каждым пунктом назначения. Они содержат информацию о статусе, продолжительности, расстоянии и тарифе (если доступно) для каждой пары происхождения/пункта назначения.
Каждый element содержит следующие поля:
- status : см. раздел Коды статуса для получения списка возможных кодов статуса.
- duration : Длительность времени, необходимого для прохождения этого маршрута, выраженная в секундах (поле value ) и в виде text . Текстовое значение форматируется в соответствии с unitSystem , указанным в запросе (или в метрической системе, если не было указано никаких предпочтений).
- duration_in_traffic : Продолжительность поездки по этому маршруту с учетом текущих условий дорожного движения, выраженная в секундах (поле value ) и в виде text . Текстовое значение форматируется в соответствии с unitSystem , указанным в запросе (или в metric, если предпочтение не указано). duration_in_traffic возвращается только при наличии данных о дорожном движении, mode driving , а departureTime включено как часть поля distanceMatrixOptions в запросе.
- distance : Общее расстояние этого маршрута, выраженное в метрах ( value ) и в виде text . Текстовое значение форматируется в соответствии с unitSystem , указанным в запросе (или в метрической системе, если не было указано никаких предпочтений).
- fare : Содержит общую стоимость проезда (то есть общую стоимость билета) на этом маршруте. Это свойство возвращается только для транзитных запросов и только для транзитных поставщиков, у которых доступна информация о тарифах. Информация включает:
  - currency : код валюты ISO 4217, указывающий валюту, в которой выражена сумма.
  - value : общая сумма тарифа в валюте, указанной выше.

Коды статуса

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

Коды статуса ответа

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

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

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

Следующие коды состояния применяются к определенным объектам 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];
      }
    }
  }
}