Matrix API

Mapbox GL JS тесно интегрируется с платформой Mapbox, однако Matrix API относится к серверной части Mapbox и используется совместно с фронтендом для решения задач пространственного анализа. Matrix API предназначен для вычисления матриц расстояний и времени между множеством точек с учётом дорожной сети и выбранного режима передвижения.

Matrix API решает задачу вычисления попарных расстояний и длительности маршрутов между наборами координат. Вместо построения отдельных маршрутов для каждой пары точек, система возвращает компактную матрицу значений, где каждая ячейка соответствует стоимости перемещения от точки A к точке B.

Основные характеристики:

  • вычисление времени в пути (travel time)
  • вычисление расстояний (distance)
  • поддержка различных профилей передвижения
  • работа с координатными массивами

Матрица используется в задачах оптимизации маршрутов, логистике, кластеризации точек интереса и построении пользовательских интерфейсов навигации.

Типы входных данных

Matrix API принимает массив координат в формате:

[longitude, latitude]

Порядок важен: сначала долгота, затем широта.

Пример набора точек:

[
  [69.5901, 42.3171],
  [69.6012, 42.3205],
  [69.5803, 42.3109]
]

Каждая точка участвует как источник и как цель, формируя квадратную матрицу.

Профили маршрутизации

Matrix API использует транспортные профили:

  • driving — автомобильный маршрут
  • walking — пешие маршруты
  • cycling — велосипедные маршруты

Каждый профиль учитывает собственную дорожную сеть и ограничения. Например, driving учитывает односторонние дороги, а walking игнорирует автомобильные ограничения.

Формат запроса

Типичный HTTP-запрос выглядит так:

GET https://api.mapbox.com/directions-matrix/v1/mapbox/{profile}/{coordinates}

Где:

  • {profile} — выбранный профиль маршрутизации
  • {coordinates} — список координат через ;

Пример:

/driving/69.5901,42.3171;69.6012,42.3205;69.5803,42.3109

Дополнительные параметры:

  • access_token — ключ доступа
  • annotations — какие данные возвращать (duration, distance или оба)
  • sources — индексы точек-источников
  • destinations — индексы точек назначения

Структура ответа

Ответ содержит две основные матрицы:

  • durations — время в секундах
  • distances — расстояние в метрах

Пример структуры:

{
  "durations": [
    [0, 120, 240],
    [110, 0, 180],
    [200, 170, 0]
  ],
  "distances": [
    [0, 800, 1500],
    [750, 0, 1200],
    [1400, 1100, 0]
  ]
}

Каждая строка соответствует точке-источнику, каждый столбец — точке назначения.

Интерпретация матрицы

Матрица представляет собой ориентированный граф:

  • диагональ всегда равна 0 (точка в саму себя)
  • значения не обязаны быть симметричными
  • маршрут A → B может отличаться от B → A

Несимметричность возникает из-за:

  • одностороннего движения
  • дорожных ограничений
  • различий в маршрутизации

Ограничения и оптимизация

Matrix API имеет ограничения по количеству точек. Обычно допускается до 25 координат в одном запросе, что формирует матрицу 25×25.

Для оптимизации:

  • уменьшается количество точек через кластеризацию
  • используется выборочный расчет (sources, destinations)
  • разделяются большие задачи на подмассивы

Пример ограничения выборки:

sources=0;1;2
destinations=3;4;5

Это снижает вычислительную нагрузку и ускоряет ответ.

Использование в JavaScript

Интеграция с фронтендом часто выполняется через fetch.

Пример запроса:

const coordinates = [
  [69.5901, 42.3171],
  [69.6012, 42.3205],
  [69.5803, 42.3109]
];

const coordsString = coordinates
  .map(c => c.join(','))
  .join(';');

const url = `https://api.mapbox.com/directions-matrix/v1/mapbox/driving/${coordsString}?annotations=duration,distance&access_token=YOUR_TOKEN`;

fetch(url)
  .then(res => res.json())
  .then(data => {
    const matrix = data.durations;
    console.log(matrix);
  });

Обработка ошибок

Типичные ошибки:

  • неверный токен доступа
  • превышение лимита координат
  • некорректный формат координат
  • отсутствие маршрута между точками

Пример обработки:

fetch(url)
  .then(res => {
    if (!res.ok) {
      throw new Error("Matrix API request failed");
    }
    return res.json();
  })
  .then(data => {
    if (!data.durations) {
      throw new Error("No route data available");
    }
  })
  .catch(err => {
    console.error(err.message);
  });

Практическое применение в навигационных системах

Matrix API используется как вычислительный слой для задач:

1. Оптимизация маршрутов доставки

Матрица позволяет вычислить кратчайшие пути между складом и множеством точек доставки, после чего применяется алгоритм коммивояжёра или его эвристики.

2. Ближайшая точка интереса

Для пользователя выбирается минимальное значение в строке матрицы:

const nearestIndex = matrix[0]
  .reduce((minIdx, val, idx, arr) =>
    val < arr[minIdx] ? idx : minIdx, 0);

3. Кластеризация объектов

Матрица расстояний служит входом для алгоритмов кластеризации (например, DBSCAN или k-means), где расстояние выступает метрикой близости.

4. ETA-сервисы

В системах оценки времени прибытия используются значения durations, агрегируемые по нескольким точкам назначения.

Параметры annotations

Параметр annotations управляет содержимым ответа:

  • duration — время в пути
  • distance — расстояние
  • комбинированный режим возвращает обе матрицы

Выбор влияет на объём данных и скорость ответа.

Работа с частичными матрицами

Matrix API позволяет запрашивать не всю матрицу, а её подмножество, что важно для масштабируемых систем.

Пример:

  • источники: склады
  • назначения: точки клиентов

Это снижает сложность с O(n²) до O(n·m).

Особенности интерпретации в реальных условиях

Данные Matrix API зависят от:

  • дорожного трафика (при включённых параметрах профиля)
  • времени суток
  • дорожных ограничений
  • качества картографических данных

Поэтому значения являются оценочными, а не абсолютными.

Использование совместно с визуализацией на карте

В связке с Mapbox GL JS результаты Matrix API часто визуализируются:

  • точки отображаются как маркеры
  • маршруты строятся через Directions API
  • матрица используется для выделения активных связей между объектами

Типичный сценарий:

  1. загрузка карты
  2. отрисовка точек
  3. запрос матрицы
  4. подсветка ближайших связей

Масштабирование вычислений

При увеличении количества точек применяется стратегия:

  • предварительная фильтрация точек
  • географическое разбиение на зоны
  • кэширование результатов
  • батчинг запросов

Это позволяет сохранять производительность при работе с сотнями объектов.

Геометрическая интерпретация

Матрица расстояний представляет собой полное взвешенное ориентированное графовое пространство, где:

  • вершины — координаты
  • рёбра — маршруты
  • веса — время или расстояние

Такая модель используется в задачах теории графов, логистики и пространственного анализа.

Оглавление