Служба Distance Matrix

Обзор

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

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

Начало работы

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

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

  1. Войдите в Google Cloud Console.
  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 г. для API Maps, Routes и Places действует новый тарифный план с оплатой по мере использования. Узнайте больше о новых ценах и лимитах на использование сервиса JavaScript Distance Matrix из статьи Статистика использования и оплата Distance Matrix API.

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

Ограничение частоты запросов

Учитывайте описанные ниже ограничения по частоте дополнительных запросов.

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

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

Правила

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

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

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

Для доступа к службе Distance Matrix служит объект конструктора google.maps.DistanceMatrixService. Метод DistanceMatrixService.getDistanceMatrix() инициирует отправку запроса к службе, передавая ей литерал объекта 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 – запрашивает пеший маршрут по пешеходным дорожкам и тротуарам (в регионах, где это возможно).

Параметры маршрутов на общественном транспорте

Служба 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. Допускаются следующие значения:
    • FEWER_TRANSFERS – указывает, что в предпочтительном маршруте должно быть как можно меньше пересадок.
    • LESS_WALKING – указывает, что в предпочтительном маршруте должно быть как можно меньшим расстояние, преодолеваемое пешком.

Параметры автомобильных маршрутов

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

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

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Назначение полей:

  • Переменная departureTime, без которой литерал объекта drivingOptions не будет действителен, задает время отправления в объекте Date. Для этого значения должно быть установлено текущее время или момент времени в будущем. Время в прошлом указать нельзя. Чтобы избежать ошибок с часовыми поясами, API преобразует все даты в формат UTC. Если включить в запрос departureTime, API вернет оптимальный маршрут с учетом прогнозируемой загруженности дорог и рассчитает потерянное в пробках время (duration_in_traffic). Если время отъезда не указывать (запрос без поля drivingOptions), API вернет подходящий маршрут без учета дорожной обстановки.

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

  • 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

В результате успешного вызова службы 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"
      }
    } ]
  } ]
}

Результаты Distance Matrix

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

  • 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 возвращается, только если оформлен план Premium платформы Google Карт, в качестве mode выбран driving и в поле запроса distanceMatrixOptions включен параметр departureTime.
    • distance – общее расстояние маршрута в метрах (value) и в формате text. Текстовое значение меняется в соответствии с системой измерения, заданной в запросе параметром unitSystem (по умолчанию используется метрическая).
    • fare – общая стоимость билетов по маршруту. Возвращается только при запросе маршрутов на общественном транспорте операторов, которые предоставили информацию о стоимости проезда. Содержит:
      • currency – код валюты ISO 4217, в которой приведена стоимость проезда;
      • value – общую стоимость проезда в этой валюте.

Коды статуса

В ответ службы Distance Matrix включается код статуса ответа на запрос в целом и статусы для каждого из элементов.

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

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

  • OK – запрос действителен. Этот статус может возвращаться, даже если не найдено никаких маршрутов между любой парой точек отправления/прибытия. Подробнее о статусах на уровне элементов читайте ниже.
  • INVALID_REQUEST – переданный запрос недействителен. Этот статус обычно связан с отсутствием обязательных полей (см. список поддерживаемых полей выше).
  • MAX_ELEMENTS_EXCEEDED – результат умножения числа пунктов отправления и назначения в запросе превышает установленное ограничение.
  • MAX_DIMENSIONS_EXCEEDED – запрос содержит более 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];
      }
    }
  }
}