---
metadata:
  - name: generator
    content: Diplodoc Platform v5.39.1
alternate:
  - https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/dg/concepts/geocoding/geocode.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/jsapi-v2-1/doc/ru/llms.txt

# Программное геокодирование


## Общие сведения {#info}

Функция [geocode](https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/geocode.md) позволяет производить поиск топонимов по адресу или названию, либо определять их адрес по координатам. В функцию можно передать название объекта в виде строки или координаты в виде массива.

## Выполнение геокодирования {#search}

Чтобы выполнить геокодирование с помощью функции [geocode](https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/geocode.md), вызовите ее и обработайте ответ:

{% list tabs %}

- Прямое геокодирование

  ```javascript
  var myGeocoder = ymaps.geocode("Петрозаводск");
  myGeocoder.then(function(res) {
      myMap.geoObjects.add(res.geoObjects);
  });
  ```

  В песочнице можно посмотреть [интерактивный пример прямого геокодирования](https://tech.yandex.ru/maps/jsbox/2.1/direct_geocode).

- Обратное геокодирование

  ```javascript
  var myGeocoder = ymaps.geocode([61.79,34.36]);
  myGeocoder.then(function(res) {
      myMap.geoObjects.add(res.geoObjects);
  });
  ```

  В песочнице можно посмотреть [интерактивный пример обратного геокодирования](https://tech.yandex.ru/maps/jsbox/2.1/reverse_geocode).

{% endlist %}

Функция работает асинхронно. Асинхронное взаимодействие реализовано с помощью обещаний ([promises](http://wiki.commonjs.org/wiki/Promises/A)): 
- Вызов функции **geocode** приводит к созданию объекта типа [vow.Promise](https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/vow.Promise.md).
- Когда от сервера вернутся результаты геокодирования или сообщение об ошибке, они будут сохранены в объекте `promise`.
- С помощью метода [then](https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/vow.Promise.md#then) объект `Promise` передаст полученный ответ последующим функциям.

## Результат поиска {#result}

Функция может вернуть результаты поиска в двух форматах:
- в виде коллекции [GeoObjectCollection](https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/GeoObjectCollection.md). Этот объект реализует интерфейс [IGeoObject](https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/IGeoObject.md), то есть может быть размещен на карте;
- в формате JSON. Чтобы получить ответ в таком формате, задайте опции `json` значение `true`. Подробнее о формате документа можно посмотреть в статье [Ответ геокодера](https://yandex.ru/dev/maps/geocoder/doc/desc/reference/response_structure.html) документации HTTP API Геокодера.

# Решение типовых задач

{% cut "Как получить координаты в текстовом формате?" %}

Чтобы получить координаты топонима, произведите обратное геокодирование. Первый элемент в полученном объекте содержит нужный геообъект. Затем можно получить адрес геообъекта в текстовом формате с помощью метода [GeoObject.getAddressLine](https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/ref/reference/GeoObject.md).

```
// Поиск координат Красной площади.
ymaps.geocode('Красная площадь', {
    results: 1
}).then(function (res) {
        // Выбирает первый результат геокодирования.
        var firstGeoObject = res.geoObjects.get(0),
            // Координаты геообъекта.
            coords = firstGeoObject.geometry.getCoordinates(),
            // Область видимости геообъекта.
            bounds = firstGeoObject.properties.get('boundedBy');

        // Устанавливает необходимый для отображения текста пресет метки.
        firstGeoObject.options.set('preset', 'islands#darkBlueDotIconWithCaption');
        // Получает строку с адресом и выводим в иконке геообъекта.
        firstGeoObject.properties.set('iconCaption', firstGeoObject.getAddressLine());

        // Добавляет первый найденный геообъект на карту.
        myMap.geoObjects.add(firstGeoObject);
        // Масштабирует карту на область видимости геообъекта.
        myMap.setBounds(bounds, {
            // Проверяет наличие тайлов на данном масштабе.
            checkZoomRange: true
        });
    });
```

{% endcut %}

{% cut "Как ограничить область поиска?" %}

Область поиска можно ограничить с помощью опции `boundedBy`. По умолчанию, заданная область не накладывает жестких ограничений на поиск. Поиск производится по всей карте, но приоритет отдается видимым объектам.

Чтобы искать строго в указанной области, задайте опции `strictBounds` значение `true`.

```javascript
var myGeocoder = ymaps.geocode("Петрозаводск", {
   // Ограничение поиска видимой областью карты.
   boundedBy: myMap.getBounds(),
   // Жесткое ограничение поиска указанной областью.
   strictBounds: true
});
myGeocoder.then(function(res) {
    myMap.geoObjects.add(res.geoObjects);
});      
```

{% endcut %}

{% cut "Как найти ближайшие станции метро?" %}

Чтобы получить информацию о ближайшей к точке станции метро, передайте в метод geocode тип `metro` и получите первый объект из ответа:

```javascript
var myCoords = [55.754952,37.615319];
myMap.geoObjects.add(
    new ymaps.Placemark(myCoords,
        {iconContent: 'Где метро?'},
        {preset: 'islands#greenStretchyIcon'}
    )
);
var myGeocoder = ymaps.geocode(myCoords, {kind: 'metro'});
myGeocoder.then(
    function (res) {
        var nearest = res.geoObjects.get(0);
        var name = nearest.properties.get('name');
        nearest.properties.set('iconContent', name);
        nearest.options.set('preset', 'islancds#redStretchyIcon');
        myMap.geoObjects.add(res.geoObjects);
    },
    function (err) {
        alert('Ошибка');
    }
);
```


{% note info %}

Если в запросе указан тип топонима, другие типы топонимов игнорируются.

{% endnote %}


{% endcut %}

{% cut "Как определить адрес по клику на карте?" %}

Чтобы определить адрес точки когда пользователь кликает на карте, нужно отслеживать событие нажатия по карте и произвести обратное геокодирование полученных координат:

```
  // Код ждет клик на карте.
  myMap.events.add('click', function(e) {
    var coords = e.get('coords');

    getAddress(coords);
  });

  // Определение адреса по координатам (обратное геокодирование).
  function getAddress(coords) {
    ymaps.geocode(coords).then(function(res) {
        var firstGeoObject = res.geoObjects.get(0);
        // Обработка координат
        ...
      }

    )}
```

В песочнице можно посмотреть [интерактивный пример](https://tech.yandex.ru/maps/jsbox/2.1/event_reverse_geocode).

{% endcut %}

## Примеры в песочнице {#examples}

- [Прямое геокодирование и разбор ответа геокодера](https://tech.yandex.ru/maps/jsbox/2.1/direct_geocode)
  
- [Обратное геокодирование](https://tech.yandex.ru/maps/jsbox/2.1/reverse_geocode)

- [Определение адреса клика по карте](https://tech.yandex.ru/maps/jsbox/2.1/event_reverse_geocode)