Служба матрицы расстояний

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Обзор

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

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

Начиная

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

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

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

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

Цены

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

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

Ограничения скорости

Обратите внимание на следующие ограничения скорости дополнительных запросов:

Ограничение скорости применяется к сеансу пользователя, независимо от того, сколько пользователей совместно используют один и тот же проект. Когда вы впервые загружаете API, вам выделяется начальная квота элементов. После того, как вы используете эту квоту, API применяет ограничения скорости для дополнительных запросов на посекундной основе. Если за определенный период времени сделано слишком много запросов, API возвращает код ответа OVER_QUERY_LIMIT .

Ограничение скорости на сеанс предотвращает использование клиентских служб для пакетных запросов. Для пакетных запросов используйте веб-сервис API Distance Matrix .

Политики

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

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

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

Вы получаете доступ к службе 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 , направления между точками будут рассчитываться с использованием платных маршрутов, где это возможно.

Режимы передвижения

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

  • 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 запроса Distance Matrix. Адреса возвращаются в том виде, в каком они были отформатированы геокодером.
  • destinationAddresses — это массив, содержащий местоположения, переданные в поле destinations , в формате, возвращаемом геокодировщиком.
  • rows — это массив объектов DistanceMatrixResponseRow , где каждая строка соответствует источнику.
  • elements являются дочерними элементами rows и соответствуют паре источника строки с каждым пунктом назначения. Они содержат информацию о статусе, продолжительности, расстоянии и стоимости проезда (если имеется) для каждой пары отправления/назначения.
  • Каждый element содержит следующие поля:
    • status : См. Коды состояния для получения списка возможных кодов состояния.
    • duration : время, необходимое для прохождения этого маршрута, выраженное в секундах (поле value ) и в виде text . Текстовое значение форматируется в соответствии с unitSystem указанным в запросе (или в метрике, если предпочтение не было указано).
    • duration_in_traffic : время, необходимое для проезда по этому маршруту с учетом текущих условий движения, выраженное в секундах (поле value ) и в виде text . Текстовое значение форматируется в соответствии с unitSystem указанным в запросе (или в метрике, если предпочтение не было указано). duration_in_traffic возвращается только для клиентов с планом Премиум платформы Google Карт, для которых доступны данные о трафике, установлен mode driving , а время departureTime включено как часть поля distanceMatrixOptions в запросе.
    • Distance : Общее 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 — служба отказала вашей веб-странице в использовании службы матрицы расстояний.
  • 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];
      }
    }
  }
}