Краткий справочник по Distance Matrix API

Distance Matrix API (устаревший) – это веб-сервис, который возвращает расстояние и время в пути для матрицы пунктов отправления и назначения на основе рекомендуемого маршрута между каждой парой. Вы можете задать способ передвижения (на автомобиле, пешком, на велосипеде, на общественном транспорте), виды транспорта, единицы измерения и время отправления для расчета длительности поездки с учетом загруженности дорог. Возвращает данные в формате JSON или XML.

Distance Matrix API: основные факты

  • Продукт: Distance Matrix API.
  • Другие названия: Distance Matrix API (устаревший), Distance Matrix (устаревший).
  • Категория: маршруты.
  • Платформа: веб-сервис (REST).
  • Где выполняется: на сервере (код бэкенда).
  • Стадия запуска: GA
  • Жизненный цикл: устаревший
  • Замена: Routes API.
  • Обзор: Обзор Distance Matrix API

Когда использовать Distance Matrix API

Используйте Distance Matrix API, если:

  • У вас есть проект, в котором уже включен Distance Matrix API (Legacy) и вызывается /maps/api/distancematrix.
  • Вам нужно получить с сервера расстояние и время в пути между несколькими пунктами отправления и назначения.
  • Вам нужно получить время в пути с учетом пробок для поездки на автомобиле, используя departure_time и необязательный параметр traffic_model.

Когда не следует использовать Distance Matrix API

  • Вы создаете новый проект Google Cloud. С октября 2026 г. Distance Matrix API (Legacy) нельзя будет включить для новых проектов. Используйте Routes API.
  • Вам нужны новые функции или матрица маршрутов, содержащая до 625 элементов с потоковыми ответами (computeRouteMatrix). Используйте Routes API.
  • Вам нужен полный маршрут с пошаговыми инструкциями и ломаными линиями между точками, а не только значения расстояния и продолжительности. Используйте Routes API.

Distance Matrix API: настройка

Distance Matrix API: распространенные ошибки

  • Проблема. Каждый запрос на стороне сервера ограничен 100 элементами (пункты отправления × пункты назначения) и 25 пунктами отправления или 25 пунктами назначения. Если запрос больше, возвращается ошибка MAX_ELEMENTS_EXCEEDED или MAX_DIMENSIONS_EXCEEDED. Решение. Разделите матрицу на запросы, содержащие не более 100 элементов и 25 пунктов отправления или назначения. Подробнее /maps/documentation/distance-matrix/usage-and-billing#usage-limits…
  • Проблема. Если не указать departure_time, маршрут и время в пути будут рассчитаны на основе средней загруженности дорог, а поле duration_in_traffic не будет возвращено. Результаты могут меняться со временем. Решение. Чтобы получить длительность с учетом трафика, задайте для параметра departure_time значение now или время в будущем с помощью параметра mode=driving. Обратите внимание, что запросы с информацией о трафике стоят дороже. /maps/documentation/distance-matrix/distance-matrix.
  • Проблема. Параметр units изменяет только текст в полях расстояния. Значение расстояния всегда указывается в метрах. Решение. Читайте distance.value как "метры" или используйте distance.text для отображения. /maps/documentation/distance-matrix/distance-matrix.
  • Проблема. При вызове Distance Matrix API (Legacy) из проекта, в котором он не включен, возвращается REQUEST_DENIED в status и error_message со ссылкой на LegacyApiNotActivatedMapError. ИИ-помощники часто по умолчанию генерируют код устаревшего API. Решение. Перейдите на Routes API computeRouteMatrix (с заголовком X-Goog-FieldMask). Активируйте устаревший API с помощью формы только в качестве краткосрочной меры. Подробнее: /maps/legacy#LegacyApiNotActivatedMapError.