Как сделать Яндекс Карту на сайте: виджет и API

Q: Как сделать карту адаптивной?

Задайте контейнеру ширину 100% и явную высоту, затем проверьте узкий экран. Вставка не должна быть шире родительского блока.

Яндекс Карту на сайте проще всего добавить готовым виджетом через iframe. Если нужны собственные маркеры, фильтры или изменение центра по данным страницы, подключайте JavaScript API. Сначала подготовьте точный адрес или координаты, затем вставьте карту и проверьте её на телефоне.

Виджет или JavaScript API: что выбрать

Виджет подходит для адреса офиса, пункта выдачи или готового маршрута. Он вставляется как отдельный iframe и почти не требует кода. JavaScript API нужен, когда карта реагирует на действия, показывает объекты из вашей базы или меняется без ручной замены вставки.

Выберите виджет, если нужна одна организация, одна точка или готовый маршрут.
Выберите Конструктор карт, если нужно вручную нанести несколько объектов и получить готовую вставку.
Выберите JavaScript API, если маркеры приходят из базы, карта связана с фильтрами или нужна собственная логика.
Оставьте обычную ссылку на Яндекс Карты рядом с картой как запасной путь.

В официальном обзоре инструментов Яндекс Карт указано, что виджет вставляется через iframe, а код можно получить после выбора организации или маршрута через кнопку «Поделиться». Справка API поясняет: если платформа запрещает скрипты, JavaScript API не подойдёт, но виджет можно разместить в отдельном iframe. Это описано в FAQ JavaScript API.

Правило выбора: одна готовая точка без собственной логики означает виджет. Данные, фильтры и действия на карте означают API.

Теория понятна, дальше нужен ваш сайт, а не пример из статьи. На бесплатном вебинаре страницу собирают с нуля и сразу публикуют в интернете.

Собрать свой сайт

Как вставить готовый виджет

Для простого адреса не пишите карту вручную. Получите вставку у Яндекса и разместите её в HTML-блоке конструктора или в шаблоне страницы.

Откройте нужную организацию или постройте маршрут в Яндекс Картах. Проверьте название и точку до копирования.
Нажмите «Поделиться» и выберите код для вставки. Скопируйте весь iframe, не только адрес из src.
В конструкторе добавьте HTML-блок. Если платформа очищает код, найдите её штатный блок карты или виджета.
Вставьте сгенерированный код в контейнер карты. Если нужна адаптивная ширина, примените к iframe CSS width:100%;max-width:100%, а высоту задайте явно и проверьте на телефоне. Нулевая высота недопустима.
Опубликуйте страницу и откройте её в приватном окне. Нажмите на карту, проверьте адрес и переход в Яндекс Карты.

Если на странице уже есть внешние блоки, сверяйтесь с правилом выбора из статьи про виджеты на сайте. Для конструктора с HTML-блоком пригодится общий разбор, как добавить на сайт карту, форму или видео.

По теме: Как сделать сайт публичным: публикация и проверка 2026

Как подключить JavaScript API

Для JS API v3 нужен ключ пакета JavaScript API. В официальном быстром старте Яндекс требует ограничение ключа по HTTP Referer, подключение скрипта, контейнер ненулевого размера и инициализацию после готовности ymaps3.ready. Полная последовательность и актуальный пример находятся в документации быстрого старта.

Создайте ключ JavaScript API в кабинете разработчика Яндекса и укажите разрешённый домен в ограничении по HTTP Referer.
Подключите скрипт API в <head> и замените YOUR_API_KEY на свой ключ. Не отправляйте вместе с ним другие секреты проекта.
Добавьте контейнер карты с понятным id и ненулевой высотой.
Дождитесь ymaps3.ready, создайте YMap и добавьте слой схемы.
Проверьте простую карту без маркеров. Только после этого добавляйте объекты и обработчики.

<script src="https://api-maps.yandex.ru/v3/?apikey=YOUR_API_KEY&lang=ru_RU"></script>
<div id="map" style="width:100%;height:420px"></div>
<script>
async function initMap() {
  await ymaps3.ready;
  const { YMap, YMapDefaultSchemeLayer } = ymaps3;
  const map = new YMap(document.getElementById("map"), {
    location: { center: [37.588144, 55.733842], zoom: 10 }
  });
  map.addChild(new YMapDefaultSchemeLayer());
}
initMap();
</script>

Это минимальный каркас без метки. Он отдельно проверяет ключ, загрузку API, контейнер и центр. Маркеры добавляйте следующим изменением. В справочнике Яндекса объект для DOM-маркера называется YMapMarker, это указано в разделе объекты карты.

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

Собрать сайт с ИИ

Диагностика: карта не отображается

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

Проверьте контейнер. Временно задайте ему фон и высоту. Если блока не видно, проблема в разметке или CSS, а не в карте.
Откройте консоль и вкладку Network. Убедитесь, что скрипт api-maps.yandex.ru загрузился без блокировки.
Проверьте ключ и разрешённый домен. Для локальной проверки отдельно разрешите localhost, как указано в быстром старте.
Убедитесь, что инициализация идёт после ymaps3.ready, а document.getElementById("map") находит элемент.
Верните минимальный пример без маркеров. Если он работает, добавляйте слой, маркер и события по одному.
Проверьте публичную страницу, а не только предпросмотр. Домен и политика безопасности в нём могут отличаться.

Справка Яндекса перечисляет те же базовые причины для ветки API 2.1: неверный ключ, неправильный идентификатор элемента, нулевой размер контейнера и запуск до готовности API. Используйте официальный список диагностики как контроль, но не смешивайте синтаксис версий 2.1 и v3 в одном коде.

По теме: Как сделать ссылку на документ на сайте: открыть или скачать

Проверяемый чек-лист результата

Карта показывает нужный адрес, а не только нужный город.
Название организации и подпись рядом совпадают с карточкой в Яндекс Картах.
На телефоне карта не растягивает страницу по ширине.
Прокрутка не застревает на карте, рядом есть ссылка «Открыть в Яндекс Картах».
Карта загружается в приватном окне после публикации.
При отключённом JavaScript остаётся текстовый адрес и обычная ссылка.
В консоли нет ошибок ключа, ограничения домена или отсутствующего контейнера.

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

Когда карта на странице не нужна

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

Не прячьте важные контакты внутрь карты. Адрес, режим работы и способ связи должны оставаться обычным текстом: его можно скопировать, прочитать без JavaScript и использовать, если внешний сервис временно недоступен.

Частые вопросы

Можно ли вставить Яндекс Карту без API-ключа?

Для готового виджета используйте код, который выдаёт Яндекс. Для JavaScript API v3 нужен ключ и ограничение по HTTP Referer согласно официальному быстрому старту.

Почему вместо карты пустой белый блок?

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

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

Да. Для нескольких вручную заданных точек подходит Конструктор карт, для данных из вашей системы используйте JavaScript API.

Как сделать карту адаптивной?

Задайте контейнеру ширину 100% и явную высоту, затем проверьте узкий экран. Вставка не должна быть шире родительского блока.

На бесплатном вебинаре вы соберёте сайт с помощью ИИ, добавите нужные внешние блоки и проверите, что страница работает после публикации.

Записаться на вебинар