Документация
Справочник JavaScript API
2.1.53 (текущая версия)
collection
interactivityModel
Интерфейсы
Следующая Ctrl 

Начало работы с API

JavaScript API Яндекс.Карт — это набор JavaScript-компонентов, позволяющий размещать на страницах сайта интерактивные карты.

Для того чтобы вставить карту на страницу и разместить на ней объект (например, метку), выполните действия:

  1. Подключите API
  2. Создайте контейнер для карты
  3. Создайте карту
  4. Добавьте метку на карту

Если не получилось отобразить карту, воспользуйтесь инструкцией.

Шаг 1. Подключите API

Прежде чем использовать функции API, необходимо загрузить в браузер JavaScript-файлы, в которых эти функции определены. Для этого добавьте в заголовок head HTML-страницы строку следующего вида:

<head>
    ...
    <script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU" type="text/javascript">
    </script>
    ...
</head>

По адресу api-maps.yandex.ru/2.1/ находится загрузчик, который при обращении к нему подключает нужные компоненты API.

Внимание! API доступен по протоколу HTTPS.

Подробнее о подключении API.

Шаг 2. Создайте контейнер для карты

Создайте видимый контейнер ненулевого размера, в котором будет размещена карта. В качестве контейнера может использоваться любой HTML-элемент блочного типа (например, элемент div с заданной шириной и высотой). Карта заполнит этот элемент полностью.

<body>
    <div id="map" style="width: 600px; height: 400px"></div>
</body>

Уникальный идентификатор (id) контейнера будет использоваться в следующем шаге для получения указателя на контейнер карты.

Шаг 3. Создайте карту

Создайте экземпляр класса карты, в конструкторе которого укажите id контейнера, ее центр и коэффициент масштабирования.

<script type="text/javascript">
    var map = new ymaps.Map("map", {
            center: [55.76, 37.64], 
            zoom: 7
        });
</script>

Совет. По умолчанию координаты принято задавать в последовательности «широта, долгота». Изменить порядок задания координат можно с помощью параметра coordorder при подключении API.

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

Создавать карту следует после того, как веб-страница загрузится целиком. Это даст уверенность в том, что контейнер для карты создан и к нему можно обращаться по id. Чтобы инициализировать карту после загрузки страницы, можно воспользоваться функцией ready().

Функция ready вызовется тогда, когда API будет загружен и DOM сформирован:

<script type="text/javascript">
    ymaps.ready(init);
    var myMap;

    function init(){     
        myMap = new ymaps.Map("map", {
            center: [55.76, 37.64],
            zoom: 7
        });
    }
</script>

Подробнее о создании карты.

Шаг 4. Добавьте метку на карту

В API метки реализуются с помощью класса Placemark. Перед тем как добавить метку на карту, создайте экземпляр этого класса. При создании метки вы можете задать текст её иконки, а также текст балуна, который откроется при нажатии кнопкой мыши на этой метке.

<script type="text/javascript">
  ymaps.ready(init);
    var myMap,
        myPlacemark;

    function init(){     
        myMap = new ymaps.Map ("map", {
            center: [55.76, 37.64],
            zoom: 7
        });

        myPlacemark = new ymaps.Placemark([55.76, 37.64], { hintContent: 'Москва!', balloonContent: 'Столица России' });
    }
</script>

После того как метка была создана, ее можно добавить на карту. Добавление объектов на карту осуществляется через их добавление в глобальную коллекцию объектов карты myMap.geoObjects:

<script type="text/javascript">
  ymaps.ready(init);
    var myMap,
        myPlacemark;

    function init(){     
        myMap = new ymaps.Map("map", {
            center: [55.76, 37.64],
            zoom: 7
        });

        myPlacemark = new ymaps.Placemark([55.76, 37.64], { 
            hintContent: 'Москва!', 
            balloonContent: 'Столица России' 
        });

        myMap.geoObjects.add(myPlacemark);
    }
</script>

Подробнее об объектах карты.

Результат

Полный текст примера:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Быстрый старт. Размещение интерактивной карты на странице</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <script src="https://api-maps.yandex.ru/2.1/?lang=ru_RU" type="text/javascript">
    </script>
    <script type="text/javascript">
        ymaps.ready(init);
        var myMap, 
            myPlacemark;

        function init(){ 
            myMap = new ymaps.Map("map", {
                center: [55.76, 37.64],
                zoom: 7
            }); 
            
            myPlacemark = new ymaps.Placemark([55.76, 37.64], {
                hintContent: 'Москва!',
                balloonContent: 'Столица России'
            });
            
            myMap.geoObjects.add(myPlacemark);
        }
    </script>
</head>

<body>
    <div id="map" style="width: 600px; height: 400px"></div>
</body>

</html>

С примерами можно ознакомиться в песочнице.

Не получилось?

Если при работе с API возникли проблемы, выполните следующие действия:

  1. Ознакомьтесь со списком часто задаваемых вопросов.
  2. Прочитайте статью из Клуба API Карт — в ней содержатся советы по отладке кода и выявлению ошибок. Поищите ответ в клубе.
  3. Если разобраться в проблеме не получилось, задайте свой вопрос в клубе или через форму обратной связи. По возможности приложите скриншот. Если ваш вопрос касается JavaScript API, приведите код, в котором возникает ошибка. Для этого загрузите код на JSFiddle и сохраните его, нажав кнопку Save в левом верхнем углу. Полученную ссылку укажите в описании проблемы.
быстрый старт
начало работы с API Карт
добавить карту на страницу
показать карту
добавить метку на карту
проблемы с API
как начать работать с API