FAQ

Commercial version of the Yandex.Maps API

General questions

How can I add a map to my website?

You can use any of the tools listed below to add a Yandex map to your website:

Tool Description

Map Constructor

A visual editor for creating interactive or static maps. You can mark objects on the map such as placemarks, lines, and polygons. You can configure the style of objects (for instance, change the placemark icon or set the color for lines).

You do not need any programming skills to use this tool.

Map Widget

Displays an interactive map on a website with the results of your actions on Yandex.Maps. For example, if you created a route to your office on Yandex.Maps, the embedded map will also show this route. The route will be updated according to the current traffic conditions.

You do not need any programming skills to use this tool.

Geolink

Selects an address or business name on the page that opens Yandex.Maps with the location when clicked.

You do not need any programming skills to use this tool.

JavaScript API

Embeds a map on your website with the ability to search for place names and businesses, build routes, view panoramas, and use other features of Yandex.Maps.

Review the documentation and examples. Write the JavaScript code and insert it on pages of your website. This will allow your users to see the map on the page.

Static API

An HTTP API that returns a static map image in response to an API request.

CMS modules

Open programming modules that extend the API features. Note that not all modules are free of charge.

Can I use the Yandex.Maps API on my website for free?

You can use the Yandex.Maps API free of charge if you meet all the requirements listed in the section Terms of use for the API. If you can't meet one or more of the requirements, you will need to purchase the commercial version of the API.

Does the Yandex.Maps API have any restrictions?

The free version of the API has the following restrictions:

  • The limit on the total number of requests to the Yandex geocoding, routing, and panorama services is 25,000 requests per day. Keep this limit in mind if you are using the JavaScript API or the Geocoder HTTP API. More about limits.
  • The maximum number of requests to the Places API is 500 requests per day.

If you need to increase the limits, you can purchase the commercial version of the API.

I want to monitor my request limit. Is there a special tool for this in the free version of the API?

No. The free version of the API doesn't provide a monitoring tool. In order to track your total requests to various services, you will need to set up request monitoring on your own.

Users of the commercial version of the Yandex.Maps API have special keys they can use to see statistics in the personal dashboard.

How will I know if I exceed the limits in the free version of the Yandex.Maps API?

If you exceed the daily request limit, the geocoding and routing services return the 429 request status. If you access the geocoding, routing, and panorama services via the JavaScript API, you will receive an error message.

Which browsers are supported by the Yandex.Maps API?

There is a list of supported browsers in the documentation (this list is updated regularly). The full functionality of all JavaScript API features is guaranteed only in the latest versions of the supported browsers.

Note that the commercial version of the JavaScript API does not support Internet Explorer 8.

My site doesn't work correctly in IE browsers.

IE11 is the only supported version of IE browser. Browsers IE8, IE9 and IE10 are partially supported. In these browsers, you can only access the Yandex.Maps API features that are technically possible to implement on the given platform. For example, Microsoft Internet Explorer does not have full SVG support, so it does not allow setting custom colors for placemarks.

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.

How can I get a key for the free version of the JavaScript API?

You don't need a key to access the free version of the JavaScript API. If you received the error "Invalid key", just delete the key from the connection link and continue using the API.

Do I need a key for the free version of the Geocoder HTTP API?

No. You don't need a key to use the free version of the Geocoder HTTP API.

Do I need a key for the free version of the Static API?

No. You don't need a key to use the free version of the Static API.

I wanted to get free access to the Yandex.Maps API, but I requested the commercial version of the API version. What should I do now?

You don't need a key to use the free version of the API. If your project meets the terms of use, just continue using the API normally, without the key. There is no need to delete the key in the dashboard.

Can I use the API to get data without showing it on the map?

According to the terms of use for the service, all data received via the API must be shown on the map. This includes information about traffic, routes, user location, and other data.

If you need to use data from the API without displaying it on the map, purchase the commercial version of the Yandex.Maps API.

Can I use the Yandex.Maps API for displaying my own maps?

Yes. You can use the Yandex.Maps API to display your own maps or maps from third-party services.

Examples: creating your own map and displaying a map in the polar azimuth projection.

Can I display Yandex maps via a third-party API?

No. This is not allowed.

Can I store the response from the Geocoder HTTP API?

No. The response from the Geocoder HTTP API must not be stored (see point 4 in the terms of use). However, you are allowed to cache the response for up to 30 days.

If you need to store geocoding results for some reason, write to us.

Are specific versions of the Yandex.Maps JavaScript API ever deleted?

Yes. We may eventually deprecate an outdated minor version of the JavaScript API. If you were using this version in your project, you will be automatically connected to the newest version of the API. Note that the change in versions might cause your application to stop working correctly. For this reason, we recommend that you keep track of API updates and switch to newer versions as soon as possible. More about API versions.

Is the search for businesses available in the JavaScript API?

To enable the search for businesses in the JavaScript API, set the search provider to 'yandex#search'. Open example

You can also use the Places HTTP API. Note that the maximum number of requests to this service is 500 requests per day. If you exceed this limit, access to data will be blocked until the beginning of the next day. If you need to increase the daily limit, you can purchase the commercial version of the API.

What types of businesses are included in the Places API?

You can see the available types of businesses in this file (.xlsx format).

Technical questions

How can I use a specific version of the JavaScript API?

To do this, specify the version number in the connection link. For example:

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

How can I insert a map in a blog if it doesn't allow scripts?

If your blog hosting service does not allow the use of scripts, you won't be able to embed an interactive map using the JavaScript API. However, you can use the Map Widget to embed an interactive map. When you add the Map Widget to the site, the map is placed in a separate iframe.

You can also use a static map image. To get the map image, use the Map Constructor or the Static API.

Can I use the Yandex.Maps API on a website with CSP?

Yes, you can. For more information, read Enabling the API when using CSP in the documentation.

I am using the JavaScript API to show a map on my site, but the map doesn't display. What am I doing wrong?

  1. Make sure that you specified the correct ID of the DOM element when creating the map instance.
  2. Check whether the size is set for the map container (it can't have a zero size).
  3. The map isn't displayed if the API code wasn't loaded yet when the map was created. To guarantee that the API code is loaded when working with the map, we recommend putting it in the ymaps.ready() function. For more information, see the section API readiness.

Can I store the map state in the URL?

Yes, you can. See the example.

How can I add my own map layer to the map?

See the example.

Why did geolocation stop working (or can't show an accurate location) on my site?

Most likely, your service is located in an HTTP domain. Google has prohibited using the browser to detect location on non-HTTPS domains. In this case, the browser console outputs this information: https://sites.google.com/a/chromium.org/dev/Home/chromium-security/deprecating-powerful-features-on-insecure-origins

When I set properties or options for map objects, they aren't applied. What could be the reason for this problem?

It's possible that you are not using the prefixes correctly when setting properties or options. For example, to set properties for a placemark icon, you need to use the 'icon' prefix (iconLayout). But to set properties for a cluster icon, you need to use the 'clusterIcon' prefix (clusterIconLayout). In addition, the correct use of prefixes depends on the level of the property – whether you are setting it for the object itself, for its collection, or on the map level. For more information, see Using prefixes in option names.

Can I change the appearance of route points?

Yes, you can. Example in the sandbox: Configuring the view of a multiroute.

Why aren't placemarks shown on the map when clustering is used?

You might be adding both a cluster and separate placemarks in this cluster at the same time. You should only add the cluster. For more information, see Placemark clustering.

I want to calculate the area of a polygon/rectangle/circle on the geodesic surface. Is there a special tool for this in the API?

You can use an external module to calculate the geodesic area of shapes: https://github.com/yandex/mapsapi-area. You can use this module in conjunction with the API.

Why do I sometimes get the 429 error code in response to requests to the Geocoder HTTP API?

This means that you have exceeded the daily request limit for the free version of the API. The limit on the total number of requests to the Yandex geocoding, routing, and panorama services is 25,000 requests per day (see Limits on API requests). You should either optimize the number of API requests you are sending, or increase your daily limit by using the commercial version of the API.

The geocoder returns an empty response or the wrong type of result. What should I do?

  1. If you are using reverse geocoding, make sure that the coordinates are listed in the correct order in the request. By default, the geocoder accepts coordinates in “longitude, latitude” order. You can change the coordinate order in the sco parameter.
  2. Make sure that you specified the correct borders for the search area (the bbox or ll+spn parameters). The object you are searching for might be located outside of the set search area.
  3. If the object you are searching for doesn't exist on the Yandex map, you can add it by drawing it in the Map Editor, or report an error on the Yandex.Maps page.

Map Constructor

Can I edit a map that was created in the Map Constructor?

Yes, you can. Note that only the person who created the map can edit it.

Can other users see a list of my maps?

The list of maps created in the Map Constructor is not visible to anyone except the person who created them.

Can I collaborate with other users and edit the same map?

The Map Constructor does not currently have a collaboration feature, since each map is linked to the account it was created in. If necessary, you can use a shared account.

Who can see my map?

You are the only person who can see your map – until you place the map code on your website and share a public link to it.

When I open the CSV file in Microsoft Excel, I get an encoding error. What should I do?

Encoding problems are related to issues with Microsoft Excel. To view the CSV file, we recommend using any other editor.

You can also export map objects in XSLX format. Files in this format will open correctly in Microsoft Excel. More about exporting map objects.

How can I move a map to a different account?

  1. Log in to Yandex, then export the map that you want to move to a different account. We recommend using KML format for the export, because it preserves more properties and data compared to other formats.
  2. Log in under the account that you are moving the map to.
  3. Import the map.

Commercial version of the Yandex.Maps API

How does the commercial version of the Yandex.Maps API differ from the free version?

The differences are as follows:

  • The commercial version of the Yandex.Maps API removes the restrictions of the free version. For example, the commercial version can be used in commercial projects, in applications with restricted access, and in tracking systems.
  • The Satellite and Hybrid layers are not available in the commercial version of the JavaScript API and the Static API. This is because the licensing restrictions of the data providers do not allow use of the satellite layers in third-party commercial projects.
  • The commercial version does not support Internet Explorer 8.

Which services are available in the commercial version of the Yandex.Maps API?

The Yandex.Maps API includes multiple separate services and programmatic libraries. For convenience in counting requests, the services are grouped into three packages:

Requests that are sent to the API from different packages are not totaled together, and are priced separately. This means that if you are planning to use the Geocoder API and the Places API, you need to choose a pricing plan for each of the appropriate packages.

How do I know whether I can use the free version of the API or whether I need to purchase the commercial version of the API?

Read the terms of use for the free version, and also review the request limits. If your project can't meet one of the requirements (for instance, you are planning to use the Yandex.Maps API in your company's intranet), you should purchase the commercial version of the API.

Which operations incur fees in the commercial version of the JavaScript API?

In the JavaScript API, all operations that send requests to the geocoding, routing, and panorama search services are counted. For example, if you need to add a placemark at some address on the map (so this will use the geocoder), this request will be counted. If you just need to add a placemark at some geographical coordinates, this operation will not be counted. More about how requests are counted.

How are requests counted when totaling the daily use of the service?

The Yandex.Maps API includes multiple separate services and programmatic libraries. For convenience in counting requests, the services are grouped into three packages:

For the JavaScript API and Geocoder HTTP API packages, the total number of requests is calculated using the formula:

  • <number of Geocoder requests> + <number of Router requests> + 5 × <number of Panorama requests>.
For the Places API and the Static API, requests are simply totaled:
  • one request to the service over HTTP is equal to one request in the limit counter.

The daily limit on requests for each service depends on the selected pricing plan. Requests that are sent to the API from different packages are not totaled together, and are priced separately. This means that if you are planning to use the Geocoder API and the Places API, you need to choose a pricing plan for each of the appropriate packages.

I want to purchase the commercial version of the Yandex.Maps API. What should I do?

  1. Decide which services you are going to use in your project: JavaScript API, Geocoder HTTP API, Places API, or Static API.
  2. Choose the packages to enable: For each package, review the terms of use, limits, and pricing. Assess the load for your project and choose an appropriate plan.
  3. Log in to Yandex and go to the developer's dashboard. Click “Get key”. In the window that opens, create a name for the key (for instance, use the name of the project), and choose the package you want.

    When choosing the package, you will see a form where you need to fill in information about the project and specify your pricing plan. After you submit the form, instructions will be sent to the email address you specified.

What is the correct way to specify the key in the code in order to use the commercial version of the Yandex.Maps API?

  • Link for enabling the commercial version of the JavaScript API:

    https://enterprise.api-maps.yandex.ru/<version number>/?lang=<language ID>&apikey=<API key>&<additional parameters>
  • Link for accessing the commercial version of the Static API:

    https://enterprise.static-maps.yandex.ru/1.x/?key=<API key>&<additional parameters>
To access the commercial version of the Geocoder HTTP API and the Places API, use the same links as for the free version.
  • Link for accessing the commercial version of the Geocoder HTTP API:
    https://geocode-maps.yandex.ru/1.x/?lang=<language ID>&apikey=<API key>&<additional parameters> 
  • Link for accessing the commercial version of the Places API:
    https://search-maps.yandex.ru/v1/?apikey=<key>&<additional parameters> 

I am using the same key for different services. Are my requests to these services added together, or totaled separately?

The services are grouped into three packages:

Requests that are sent to the services from different packages are not totaled together, and are priced separately. For example, if you are using the same key for accessing the Geocoder and the Places API, the requests will still be totaled separately according to the pricing plans you selected for each of these two packages.

What will happen if I exceed the purchased amount?

At the end of the month, you will receive a bill for excess usage. The cost for each 1000 requests over the limit depends on the selected pricing plan. For more information, see Pricing and terms of use.

Where can I view the pricing information and overcharges?

See Pricing and terms of use.

Can I get a trial key to the commercial version of the JavaScript API?

The commercial version of the JavaScript API includes the same functionality as the free version. To test the API features, use the free version. You don't need to get a key for this purpose.

Attention. You do need to consider the restrictions when using the free version of the JavaScript API.

If you need to test the JavaScript API outside of the terms of use (for instance, you need to test it in a closed system), write to us. In your email, tell us what project you need the key for and what the time period is for testing. Also include the anticipated number of requests to the geocoding, routing, and panorama services. A manager will contact you after we receive your request.

Can I get a trial key to the commercial version of the Places API?

You can try out the features of the Places API in the free version. To get a key for the free version, go to the developer's dashboard and select “Get key”. Fill in the required fields and leave “I need the commercial version” empty. After you submit the application, a key is generated. It is activated automatically when you receive it, so you can begin using it in your project right away. To switch to the commercial version of the API later, write to us and make sure that your email includes the key that you received.

Attention. The free version of the Places API is limited to 500 requests per day. In addition, you must comply with a number of restrictions.

If you need to use a test key without complying with the restrictions (for instance, you need to test it in a closed system), write to us. In your email, describe your project and tell us how long you need to use the test key. Also include the anticipated number of requests to the API. A manager will contact you after we receive your request.

The pricing plans only show the price per year. Is there an option for paying by the month?

The only purchasing option is a yearly plan.

Where can I monitor request statistics? How often are statistics updated?

To view request statistics:

  1. Go to the developer's dashboard.
  2. Select the appropriate key in the menu on the left.
  3. On the right side of the page, enter the day or time period to get statistics for, and click “Show”.

The statistics show both the total number of API requests and the number of requests to each separate service (such as the Geocoder, the Router, and the panoramas). There is a one-hour delay in updating the statistics.

Can I transfer a key to a different account (for instance, if my employee leaves)?

No. You can't transfer a key to a different account. We recommend obtaining keys for a shared corporate account.

I forgot the password to the account that the key is registered to. What should I do?

Follow the instructions for restoring the password.

Why doesn't the commercial version support Satellite and Hybrid layers? The free version has them.

The satellite images are subject to licensing restrictions by the data providers. This data can't be used in commercial third-party products. This is why we can't sell this data or access to it. As a result, the Satellite and Hybrid layers are only available in the free version of the API in accordance with the license agreement.

I am using the free version of the Yandex.Maps API, but my site/app is experiencing an increase in traffic. How can I monitor the number of API requests so that I know when to switch to the commercial version of the API?

The free version of the API does not provide a tool for tracking the number of requests to the services. Our recommendation is to set up request logging on your own and use your logs to track the number of requests. For information about requests that incur a fee, see the section Limits on API requests.

My project is not going to use the geocoder, router, or panorama search services. How much will the license cost for just the JavaScript API?

In this case, the price of the license for the JavaScript API is 120,000 rubles per year.

I have a question that isn't listed

If you didn't find the answer to your question here, you can send us a message using the contact form. Select the subject of the message and describe the problem in detail. We'll try to respond as quickly as possible.