Getting started with the API

The Yandex.Maps JavaScript API is a set of JavaScript components for publishing interactive maps on website pages.

To embed a map on a page and put an object on it (for example, a placemark), follow the steps below.

Step 1. Get the API key

Go to the Developer's Dashboard and press “Get key”. In the popup window, select the “JavaScript API, Geocoding API” option.

After you select the service, the form appears. In this form, you need to provide your contact information. After you fill in the form, the “Service successfully connected” text appears. The created key is now available in the “Keys” section. Use it when you enable the API.

Step 2. Enable the API

Before using the API features, you must make sure your browser loads the JavaScript files that define these features. To do this, add the following string to the HTML page's head header:

<head>
    ...
    <script src="https://api-maps.yandex.ru/2.1/?apikey=<your API key>&lang=en_US" type="text/javascript"></script>
    ...
</head>

The address api-maps.yandex.ru/2.1/ is the location of the loader that enables the necessary API components on request.

Note that The API is accessed over the HTTPS protocol.

Attention. Users who are working in browsers IE8, IE9 and IE10 will be automatically switched to the API version 2.1.oldie.1. This version has the same functionality as version 2.1.59 and doesn't include the latest updates.

If you need to support the browsers IE8, IE9 and IE10, develop your code using the reference guide for version 2.1.59. If you use functionality from later versions, it may cause the API to work incorrectly in IE8, IE9 and IE10.

More information about enabling the API.

Step 3. Create a map container

Create a nonzero-size visible container where the map will be placed. Any block type of HTML element can be used as the container (for example, the div element with a set height and width). The map will completely fill this element.

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

The container's unique ID (id) will be used in the next step for getting a reference to the map container.

Step 4. Create a map

Create an instance of the map class; in its constructor, specify the container id, the map center, and the zoom level.

<script type="text/javascript">
    var map = new ymaps.Map("map", {
            center: [55.76, 37.64], 
            zoom: 7
        });
</script>
Tip. By default, coordinates are set in the order “latitude, longitude”. When enabling the API, you can use the coordorder parameter to change the order for setting coordinates.

The map should be created after the web page has completely loaded. This will ensure that the map container has been created and can be accessed by its id. To initialize the map after loading the page, you can use the ready() function.

The "ready" function will be called when the API is loaded and the DOM is generated:

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

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

More information about creating a map.

Step 5. Add a placemark to the map

In the API, placemarks are implemented using the Placemark class. Before adding a placemark to the map, create an instance of this class. When creating a placemark, you can set its icon text, as well as the text of the balloon that opens when clicking the 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: 'Moscow!', balloonContent: 'Capital of Russia' });
    }
</script>

After the placemark has been created, it can be added to the map. Objects are added to the map by adding them to the global collection of map objects 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: 'Moscow!', balloonContent: 'Capital of Russia' 
        });

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

More information about map objects.

Result

Full text of the example:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Quick start. Showing an interactive map on a page</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <script src="https://api-maps.yandex.ru/2.1/?apikey=<your API key>lang=en_US" 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: 'Moscow!', balloonContent: 'Capital of Russia'
            });
            
            myMap.geoObjects.add(myPlacemark);
        }
    </script>
</head>

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

</html>

You can play with examples in the sandbox.