Сервис Distance Matrix

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

Обзор

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

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

Начиная

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

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

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

Цены и политика

Цены

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

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

Политики

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

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

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

Виды путешествий

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

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

Варианты транспорта

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

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

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

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

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

Ниже приведено описание этих полей:

  • arrivalTime ( необязательно ) указывает желаемое время прибытия в виде объекта Date . Если указано время прибытия, время отправления игнорируется.
  • departureTime ( необязательный ) указывает желаемое время отправления в виде объекта Date . Параметр departureTime будет проигнорирован, если указано arrivalTime . По умолчанию используется текущее время (то есть текущее время), если значение для 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 указанной в запросе (или в метрической системе, если предпочтения не были указаны). Значение duration_in_traffic возвращается только в том случае, если доступны данные о дорожной ситуации, mode установлен на driving , а поле distanceMatrixOptions в запросе содержит поле departureTime .
    • distance : Общая протяженность данного маршрута, выраженная в метрах ( value ) и в text . Текстовое значение форматируется в соответствии с unitSystem указанной в запросе (или в метрической системе, если предпочтения не были указаны).
    • fare : содержит общую стоимость проезда (то есть общую стоимость билета) по данному маршруту. Эта информация возвращается только для запросов на проезд в общественном транспорте и только для тех транспортных компаний, у которых доступна информация о стоимости проезда. Информация включает в себя:

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

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

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

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

  • OK — Запрос действителен. Этот статус может быть возвращен, даже если маршруты между пунктами отправления и назначения не были найдены. Информацию о статусе на уровне элементов см. в разделе «Коды состояния элементов» .
  • INVALID_REQUEST — Предоставленный запрос недействителен. Это часто происходит из-за отсутствия обязательных полей. См. список поддерживаемых полей выше.
  • MAX_ELEMENTS_EXCEEDED — Произведение адресов отправления и назначения превышает лимит для каждого запроса .
  • MAX_DIMENSIONS_EXCEEDED — Ваш запрос содержал более 25 пунктов отправления или более 25 пунктов назначения.
  • OVER_QUERY_LIMIT — Ваше приложение запросило слишком много элементов в течение допустимого периода времени. Запрос должен быть успешно выполнен, если вы повторите попытку через разумное время.
  • REQUEST_DENIED — Сервис отклонил запрос на использование матрицы расстояний вашей веб-страницей.
  • 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];
      }
    }
  }
}