ФронтендJavaScriptHTML / CSS

2ГИС API на JavaScript: строим маршрут между двумя точками на карте

Подключаем MapGL JS API и Directions 2ГИС: показываем карту, ставим две точки, строим автомобильный маршрут и обрабатываем ошибку ключа.

Кодик

Автор

6 мин чтения

2ГИС MapGL можно освоить на одном небольшом проекте, если сразу видеть вход, действие и результат. MapGL JS API рисует интерактивную карту, а Directions plugin строит и сразу отображает автомобильный или пешеходный маршрут. Ниже вы соберёте работающий пример и проверите обычный и граничный сценарии.

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

1Соберите минимум

создать mapgl.Map с center, zoom и key. Не расширяйте проект до первого успешного запуска.

2Увидьте данные

обе координаты видны. Проверяйте значение, а не отсутствие ошибки.

3Измените правило

После успеха добавьте третью точку и кнопку выбора типа маршрута. Так копирование станет практикой.

Как устроен учебный проект 2ГИС MapGL

MapGL создаёт карту, Marker показывает начало и конец, Directions получает тот же map и отдельный directionsApiKey, затем рисует путь между координатами. Держите ввод, логику и отображение раздельно: тогда каждый этап можно проверить отдельно.

ЭтапДействиеПроверяемый результат
Картасоздать mapgl.Map с center, zoom и keyподложка 2ГИС загружена
Точкидобавить Marker для старта и финишаобе координаты видны
Маршрутсоздать Directions с directionsApiKeycarRoute рисует оптимальный путь
Повторвызвать clear перед новым запросомна карте остаётся одна актуальная линия

Контрольные точки: карта, точки, маршрут и повтор. Следующий шаг начинается после совпадения с ожидаемым результатом.

Путь данных в проекте 2ГИС MapGL
От входных данных до видимого результата. Сначала проверяется вход, затем действие и только потом интерфейс.

Зафиксируйте первый успех Сначала загрузите только карту и одну метку. Если подложка не появилась, Directions ещё не имеет смысла отлаживать. Сохраните команду запуска и ожидаемый вывод.

Собираем рабочий пример шаг за шагом

Материал сверялся с официальной документацией 2 ноября 2026 года. Получите отдельные ключи MapGL и Directions, подключите официальные скрипты API и задайте контейнеру карты явную высоту. Проверьте текущую папку через pwd или Get-Location. Вставьте пример целиком, выполните один раз, затем разбирайте по частям.

const start = [37.6176, 55.7558]
const finish = [37.6487, 55.7416]

const map = new mapgl.Map('map', {
  center: start,
  zoom: 12,
  key: window.MAPGL_KEY,
})

new mapgl.Marker(map, { coordinates: start, label: { text: 'Старт' } })
new mapgl.Marker(map, { coordinates: finish, label: { text: 'Финиш' } })

const directions = new mapgl.Directions(map, {
  directionsApiKey: window.DIRECTIONS_KEY,
})

document.querySelector('#route').addEventListener('click', async () => {
  const status = document.querySelector('#status')
  status.textContent = 'Строим маршрут...'
  try {
    directions.clear()
    await directions.carRoute({ points: [start, finish] })
    status.textContent = 'Маршрут построен.'
  } catch (error) {
    console.error(error)
    status.textContent = 'Не удалось построить маршрут. Проверьте ключи.'
  }
})
Что должно произойти после запуска
  • После загрузки видны карта и две подписанные точки с координатами в порядке longitude, latitude.
  • Кнопка строит одну линию маршрута, а ошибка API превращается в сообщение рядом с картой.
  • Повторный запуск даёт тот же предсказуемый результат.
  • Пустой ввод получает понятное сообщение вместо падения.

Главная функция принимает явный вход и возвращает результат, который можно проверить отдельно от интерфейса. Найдите в примере вход, проверку и место формирования результата.

Хрупкий и проверяемый вариант 2ГИС MapGL
Что отличает устойчивый проект от случайного запуска. Явные границы делают ошибку локальной и понятной.

Что происходит внутри и почему это работает

Координаты MapGL передаются в порядке долгота, широта. Directions plugin получает список точек и сам добавляет слои маршрута на существующую карту. Логику держите отдельно от вывода: функция получает аргумент и возвращает значение, а интерфейс показывает его. Ключи для клиентского API ограничивайте разрешёнными доменами в кабинете. Не используйте один секретный серверный ключ во фронтенде.

ЧастьЗа что отвечаетЧто проверить
Mapрисует подложку и управляет камеройконтейнер имеет высоту и корректный key
Markersпоказывают входные координатыточки не перепутаны местами
Directionsзапрашивает и рисует маршрутошибка Promise обработана

Маршрут является результатом внешнего API, поэтому интерфейс должен иметь loading, success и error. Не считайте пустую карту доказательством отсутствия пути: сначала проверьте ключ, сеть и координаты. Не прячьте поток в одном обработчике: сохраните вход, проверьте его, вызовите операцию и только затем обновите интерфейс.

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

Проверяем проект и добавляем свою функцию

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

Проверка своими руками
  1. Сохраните ожидаемый результат: карта загружается, две точки видны, carRoute рисует линию, а повторный запуск сначала очищает старый маршрут.
  2. Измените правило: добавьте третью точку и кнопку выбора типа маршрута. Сначала предскажите итог.
  3. Передайте граничное значение и убедитесь, что приложение не падает.
  4. Верните корректные данные и объясните роли трёх основных частей.
Готово, если выполняются все пункты
  • подложка 2ГИС загружена
  • обе координаты видны
  • carRoute рисует оптимальный путь
  • на карте остаётся одна актуальная линия

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

Четыре контрольные точки 2ГИС MapGL
Четыре проверки перед следующим шагом. Каждый следующий этап начинается после наблюдаемого результата.

Что запомнить и куда двигаться дальше

Для портфолио вынесите координаты в форму, ограничьте число точек и добавьте доступный текстовый статус, который работает без цвета. Для закрепления откройте в статье про Яндекс Карты, в подсказках адреса DaData и в приложении погоды.

Как изучить тему в Кодике

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

ШагЧто разобратьМини-проверка
1. ОсноваМассивы, DOM-события и async/await JavaScriptОбъясните вход и выход функции.
2. ИнструментMapGL Map, Marker и Directions pluginПовторите команду по памяти.
3. ПроектМаршрут с loading, success и errorПроверьте два сценария.
4. РефакторингФорму координат, доменные ограничения ключей и UX картыРазделите ввод, логику и вывод.

Закрепите проект, восстановив ключевую функцию по памяти и добавив собственный граничный случай. Базовый синтаксис закрепите через курс JavaScript.

Перепутан порядок координат

MapGL ждёт долготу, затем широту. Точка улетает в другую часть мира.

Один ключ для всего

MapGL и Directions используют свои параметры доступа.

Нет высоты контейнера

Карта загружена, но div имеет нулевой размер.

Ошибка Promise не обработана

Пользователь видит вечную загрузку. Добавьте try/catch и статус.

Сверяйтесь с первичной документацией. Команды и ограничения примера проверены по официальному источнику 1. Если версия инструмента изменилась, официальный источник важнее старого скриншота.

Что получится в итоге

Готовый результат проекта: 2ГИС API на JavaScript: строим маршрут между двумя точками на карте
Финальный экран показывает результат, состояние операции и понятное сообщение об ошибке без раскрытия секретов.

Короткие ответы
В каком порядке передаются координаты?

Сначала долгота, затем широта: longitude, latitude.

Зачем вызывать directions.clear()?

Чтобы перед новым запросом удалить старые линии и не смешивать маршруты.

Что проверять первым, если 2ГИС MapGL не запускается?

Версию среды, текущую папку, команду запуска и первую строку ошибки.

Как понять, что проект 2ГИС MapGL работает?

Проверьте основной сценарий, неверный ввод, повторный запуск и один граничный случай.

Можно ли начать с готового кода?

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

Сделайте один осознанный шаг дальше

Выберите одно улучшение и проведите его от ввода до результата.

Если не хватает основы, перейдите курс JavaScript, затем восстановите ключевую функцию без подсказки.