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

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

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

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

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

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

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

Передайте два списка точек: откуда и куда нужно ехать. Для двух складов и трёх заказов Вы получите шесть расстояний и шесть оценок времени. По этой таблице Ваше приложение может выбрать подходящий вариант. [Пример на главной](https://mmapps.ru/#distance-matrix).

## Доступ

Разрешите `matrix` в [настройках ключа](https://mmapps.ru/app/projects). Для матрицы по текстовым адресам нужно также `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](https://mmapps.ru/gateway.openapi.yaml).

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

| `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](https://mmapps.ru/app/usage). [Общие правила расходов](https://mmapps.ru/docs/billing).