Все готово!

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

Активация Google Maps JavaScript API

Чтобы помочь вам освоиться, мы покажем, как выполнить некоторые необходимые действия в консоли разработчика Google:

  1. Создание или выбор проекта
  2. Активация Google Maps JavaScript API и связанных служб
  3. Создание соответствующих ключей

Служба Distance Matrix

Обзор

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

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

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

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

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

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

Правила и ограничения на использование

Квоты

Для службы Distance Matrix действуют следующие ограничения на использование:

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

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

  • 2 500 бесплатных элементов в день, рассчитывается как сумма обращений на стороне клиента и на стороне сервера; разрешите тарификацию ( разрешить тарификацию), чтобы получить больший размер квоты по цене 0,50 долларов США за 1 000 дополнительных элементов. Максимальный размер квоты составляет 100 000 элементов в день.
  • Не более 25 исходных точек или 25 точек назначения на запрос.
  • Не более 100 элементов на запрос.
  • Не более 100 элементов в секунду, рассчитывается как сумма запросов на стороне клиента и на стороне сервера.

Использование службы Distance Matrix в рамках премиум-плана

  • Общая ежедневная бесплатная квота – 100 000 элементов каждые 24 часа; дополнительные запросы оплачиваются ежегодно приобретаемыми кредитами Maps API.
  • Не более 25 исходных точек или 25 точек назначения на запрос.
  • Не более 625 элементов на запрос. Примечание. Запросы с необязательным параметром departure_time в режиме mode=driving могут включать не более 100 элементов на запрос.
  • Без ограничений элементов на стороне клиента в секунду на каждый проект. Обратите внимание, что API на стороне сервера ограничен 1 000 элементами в секунду.

Лимит частоты применяется к сеансу каждого пользователя независимо от количества пользователей проекта.

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

Политики

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

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

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

Для доступа к службе 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.
}

Просмотр примера (distance-matrix.html)

DistanceMatrixRequest содержит следующие поля:

  • origins (обязательное) – массив, содержащий одну или несколько строк адресов, объектов google.maps.LatLng или объектов google.maps.Place, на основании которых рассчитываются расстояние и время.
  • destinations (обязательное) – массив, содержащий одну или несколько строк адресов, объектов google.maps.LatLng или объектов google.maps.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-интерфейсом по умолчанию. Значение для этого поля можно задавать, только если в запрос входит ключ API-интерфейса. Допускаются следующие значения:
    • FEWER_TRANSFERS – указывает, что в рассчитанном маршруте следует отдать приоритет уменьшению количества пересадок.
    • LESS_WALKING – указывает, что в рассчитанном маршруте следует отдать приоритет уменьшению расстояния, которое нужно пройти пешком.

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

Конкретные параметры автомобильного маршрута можно задать с помощью объекта DrivingOptions. Если вы хотите включить поле drivingOptions в запрос DistanceMatrixRequest, при загрузке API нужно указать идентификатор клиента Google Maps APIs Premium Plan.

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

{
  departureTime: Date,
  trafficModel: TrafficModel
}

Назначение этих полей объясняется ниже.

  • departureTime (обязательное для того, чтобы литерал объекта drivingOptions был корректным) – указывает желаемое время отъезда в виде объекта Date. Для этого значения должно быть установлено текущее время или определенный момент времени в будущем. Прошедший момент времени является недопустимым. (API преобразует все даты в формат UTC, чтобы обеспечить единообразную интерпретацию часовых поясов.) Если пользователь Google Maps APIs Premium Plan включит в запрос поле 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) и в виде текста. Текстовое значение форматируется в соответствии со значением параметра unitSystem, указанным в запросе (или использует метрические единицы измерения, если этот параметр не был задан).
    • duration_in_traffic: длительность поездки по этому маршруту с учетом текущей дорожной обстановки, выраженная в секундах (поле value) и в виде текста. Текстовое значение форматируется в соответствии со значением параметра unitSystem, указанным в запросе (или использует метрические единицы измерения, если этот параметр не был задан). Значение duration_in_traffic возвращается только пользователям Google Maps APIs Premium Plan при наличии данных о дорожной обстановке, когда установлен режим driving и в запросе содержится параметр departureTime в поле distanceMatrixOptions.
    • distance: общее расстояние этого маршрута, выраженное в метрах (value) и в виде текста. Текстовое значение форматируется в соответствии со значением параметра unitSystem, указанным в запросе (или использует метрические единицы измерения, если этот параметр не был задан).
    • fare: содержит информацию об общей стоимости (т. е. общей стоимости билетов) этого маршрута. Это свойство возвращается только для запросов маршрутов на общественном транспорте и только для тех транспортных операторов, которые предоставили информацию о стоимости проезда. Эта информация включает следующие сведения:
      • currency: код валюты ISO 4217, указывающий валюту отображаемой суммы.
      • value: общая стоимость проезда в указанной выше валюте.

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

Ответ Distance Matrix включает код состояния для ответа в целом и для состояния каждого элемента.

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

Коды состояния, относящиеся к 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 содержит одну строку для каждой исходной точки, переданной в запросе. Каждая строка содержит поле 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];
      }
    }
  }
}

Оставить отзыв о...

Текущей странице
Google Maps JavaScript API
Google Maps JavaScript API
Нужна помощь? Обратитесь в службу поддержки.