Сервис Distance Matrix

Обзор

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

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

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

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

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

1. Войдите в Google Cloud Console.
2. Нажмите кнопку Select a project (Выбрать проект), затем выберите тот же проект, который вы используете для Maps JavaScript API, и нажмите Open (Открыть).
3. В списке API на панели управления найдите Distance Matrix API.
4. Если этот API есть в списке – все готово к работе. Если API в списке нет, включите его:
   1. Вверху страницы нажмите Enable API (Включить API), чтобы перейти на вкладку Library (Библиотека). Вы также можете выбрать в меню слева пункт Library (Библиотека).
   2. Найдите Distance Matrix API и выберите его из списка результатов.
   3. Нажмите Enable (Включить). Когда процесс завершится, Distance Matrix API появится в списке API на панели управления.

Цены и правила

Цены

С 16 июля 2018 г. для API Maps, Routes и Places действует новый тарифный план с оплатой по мере использования. Узнайте больше о новых ценах и лимитах на использование сервиса JavaScript Distance Matrix из статьи Статистика использования и оплата Distance Matrix API.

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

Правила

Использование сервиса 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 – запрашивает пеший маршрут по пешеходным дорожкам и тротуарам (в регионах, где это возможно).

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

Сервис "Транспорт" является экспериментальным. Сейчас мы вынуждены ограничивать частоту запросов к нему, чтобы предупредить чрезмерную нагрузку на 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];
      }
    }
  }
}