Guide for migrating to the JS API v3

The guide contains examples that show the difference between the JavaScript API versions v3 and 2.1. As the APIs are fundamentally different, this guide contains only differences in their basic components and approaches.

Connecting the API

Version 2.1

<!DOCTYPE html>
  <head>
    <!-- Loading API -->
    <script src="https://api-maps.yandex.ru/2.1/?apikey=YOUR_API_KEY&lang=en_US"
   ></script>
    <script>
      // When loading the API successfully,
      // a corresponding function is run.
      ymaps.ready(function () {
         …
      });
    </script>
   </head>
  ...
</html>

Version v3

<!DOCTYPE html>
<html>
  <head>
    <!-- Loading the API -->
    <script src="https://api-maps.yandex.ru/v3/?apikey=YOUR_API_KEY&lang=en_US"
   ></script>
    <script>
      // When loading the API successfully, the `ymaps3.ready` promise is available
      ymaps3.ready.then(() => {
         …
      });
    </script>
   </head>
  ...
</html>

Required parameters:

Important.

The API v3 has no feature for loading modules separately by request. The onload parameter is missing. The only way to run the code after the API is ready is via the ymaps3.ready promise.

Creating a map

Version 2.1

// Creating a copy of the map
// and linking it to the
// container with the id="YMapsID".
const map = new ymaps.Map('YMapsID', {
  center: [37.64, 55.76],
  zoom: 10,
  type: 'yandex#satellite',
  // The created map will have no
  // controls.
  controls: []
});

Version v3

// Creating a map instance.
const map = new ymaps3.YMap(document.getElementById('YMapsID'), {
  location: {
    center: [37.64, 55.76],
    zoom: 10
  }
});

Note.

The API v3 has no layer with satellite data. If you need this layer, you can create it manually by specifying the URL to get tiles from.

Behaviors

Version 2.1

By default, the following behaviors are enabled: drag, multiTouch, dblClickZoom, rightMouseButtonMagnifier, scrollZoom.

Version v3

See the whole list of behaviors in Events.

By default, the following behaviors are activated: drag, scrollZoom, pinchZoom, dblClick, and magnifier.

Geo objects

Setting the placemark style

Version 2.1

// A placemark with a standard icon.
// See the list of the standard styles
// in the guide under
// option.preset.storage.
var placemark = new ymaps.Placemark(
  [37.6, 55.8],
  {},
  {
    preset: 'islands#greenCircleIcon'
  }
);

// Creating a placemark with a custom icon.
var placemark2 = new ymaps.Placemark(
  [37.6, 55.8],
  {},
  {
    // One of the two standard placeholder
    // templates with an image icon:
    // - default#image - without any content;
    // - default#imageWithContent - with text
    // in the icon.
    iconLayout: 'default#image',
    iconImageHref: '/path/to/icon.png',
    iconImageSize: [20, 30],
    iconImageOffset: [-10, -20]
  }
);

Version v3

const defaultMarker = new ymaps3.YMapDefaultMarker({
  title: 'Hello, world!',
  subtitle: 'Nice and kind',
  color: 'blue'
});

const content = document.createElement('div');
const marker = new ymaps3.YMapMarker(content);
content.innerHTML = '<div>Put anything here</div>';

const map = new ymaps3.YMap(document.getElementById('map-root'), {
  location: INITIAL_LOCATION
})
  .addChild(new ymaps3.YMapDefaultSchemeLayer())
  .addChild(new ymaps3.YMapDefaultFeaturesLayer({zIndex: 1800}))
  .addChild(defaultMarker)
  .addChild(marker);

The API v3 has only one default marker type: YMapDefaultMarker.

For custom markers, use YMapMarker. Inside, you can use any HTML.

Clusterization

Version v3

The API v3 has no clusterization tool.

Map controls

Version v3

By default, a map is created without the standard controls: full-screen mode, zoom buttons, geolocation. To learn how to add controls you want to the map, go to Controls.

The API v3 has only three controls: geolocation, zoom buttons, and the main button. Learn more

The API v3 has no built-in pop-up window. Instead, you can manage the content of a marker's HTML element yourself.

Previous
Events
Next
JS API Reference