Матрица расстояний

Получите автомобильные расстояния и расчётное время для всех пар двух списков точек.

SDK 1.0.0-rc.9 Эта страница в Markdown Вся документация одним файлом

На этой странице

Что возвращает матрица

POST /v1/matrix принимает sources и targets. Ответ cells[i][j] описывает путь от источника i к назначению j. Например, 2 источника × 3 назначения — один запрос и 6 элементов.

Матрица помогает сравнить расстояния между складами, магазинами и адресами доставки. Направления A→B и B→A могут отличаться. Автомобильный профиль car не учитывает пробки и дату выезда; время является оценкой. Матрица не выбирает порядок посещения и не возвращает линию маршрута.

Где пригодится

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

Передайте два списка точек: откуда и куда нужно ехать. Для двух складов и трёх заказов Вы получите шесть расстояний и шесть оценок времени. По этой таблице Ваше приложение может выбрать подходящий вариант. Пример на главной.

Доступ

Разрешите matrix в настройках ключа. Для матрицы по текстовым адресам нужно также geocode, для выбранных ссылок — resolve.

Матрица должна быть доступна в текущем тарифе аккаунта. Проверить это можно серверным ключом с правом status: GET /platform/v1/capabilities, поле matrix.enabled. В matrix.limits возвращаются ограничения конкретного подключения.

Запрос по координатам

bash

curl --request POST 'https://mmapps.ru/v1/matrix' \
  --header "Authorization: Bearer ${MMAPPS_SERVER_KEY}" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: matrix-example-operation-001' \
  --data '{"sources":[{"latitude":55.75,"longitude":37.61}],"targets":[{"latitude":55.76,"longitude":37.62}],"profile":"car"}'

В SDK RC9:

javascript

const operationKey = crypto.randomUUID();
const result = await geo.routes.matrix({
  sources: selectedSources,
  targets: selectedTargets,
  profile: 'car',
}, { operationKey });

Каждый список содержит объекты {latitude, longitude}. Текущий запрос может содержать до 25 пар; каждая пара должна находиться в пределах 200 км по прямой. Дорожное расстояние в результате может быть больше. Точные ограничения — в OpenAPI.

Чтение результата

`cells[i][j].status`	Расстояние и время
`ok`	`distance_m` в метрах, `duration_s` в секундах
`no_route`	Оба значения `null`; путь между этой парой не найден

Не превращайте null в ноль: это создало бы ложный результат «рядом». При ошибке сервиса завершённая матрица не возвращается, элементы матрицы не оплачиваются.

Матрица по адресам

POST /v1/matrix/geocode и geo.routes.matrixGeocode() принимают те же списки, но каждая позиция — {q: 'адрес'}, {ref: selectedRef} или {point: selectedPoint}.

Текстовый поиск возвращает кандидатов в waypoints.sources и waypoints.targets; matrix остаётся null. Покажите варианты пользователю, замените каждый текст подтверждённой ссылкой или координатой и отправьте новый запрос с новым ключом операции. Даже единственный кандидат требует подтверждения.

Тариф и повторы

Матрица учитывается по элементам, а не по запросам. 2 000 элементов в месяц входят в бесплатную квоту; затем — 39 ₽ за 1 000 элементов (0,039 ₽ за элемент). Применимый тариф и доступность проверяйте в кабинете.

Если осталось 3 бесплатных элемента, запрос на 25 элементов использует 3 бесплатных и 22 платных: 0,858 ₽. Повторяющиеся пары, диагональ и завершённые no_route также учитываются. Выполненный поиск текстовых адресов оплачивается отдельно; resolve бесплатен.

Idempotency-Key обязателен. Повторяйте тот же запрос с прежним ключом; другое тело с тем же ключом даст 409. Количество элементов, расход квоты и стоимость видны в статистике и CSV. Общие правила расходов.