geocode

Static function.

Processes geocoding requests. The request result can be provided in JSON format or as a GeoObjectCollection object. The geocoder's response format is described in Geocoding.

See GeocodeResult

Returns Promise object.

{ vow.Promise } geocode(request[, options])

Parameters:

Parameter

Default value

Description

request*

Type: String|Number[]

The address for which coordinates need to be obtained (forward geocoding), or the coordinates for which the address needs to be determined (reverse geocoding).

options

Type: Object

Options.

options.boundedBy

Type: Number[][]

A rectangular area on the map, where the object being searched for is presumably located.

options.json

false

Type: Boolean

If true, JSON is passed to the handler function. Otherwise, the handler function is passed an object containing the geoObjects field with the geocoding results as GeoObjectCollection. When geocoding using the 'yandex#map' geocoder, the collection contains GeocodeResult objects.

options.kind

'house'

Type: String

Type of toponym (only for reverse geocoding).

List of acceptable values:

  • house - House or building.
  • street - Street.
  • metro - Subway station.
  • district - City district.
  • locality - City, town, village, etc.

options.provider

'yandex#map'

Type: IGeocodeProvider|String

Geocoding provider. One of the standard providers can be used:

  • 'yandex#map' - Search on the map.

options.results

10

Type: Integer

Maximum number of results to be returned.

options.searchCoordOrder

Type: String

Determines how to interpret the coordinates in the request.

options.skip

0

Type: Integer

Number of results that must be skipped.

options.strictBounds

false

Type: Boolean

Search only inside the area defined by the "boundedBy" option.

* Mandatory parameter/option.

Examples:

1.

// Performs a search for an object named "Moscow".
// The result is immediately displayed on the map.
var myGeocoder = ymaps.geocode("Moscow");
myGeocoder.then(
    function (res) {
        map.geoObjects.add(res.geoObjects);
        // Taking the data resulting from geocoding the object
        // and outputting it to the console.
        console.log(res.geoObjects.get(0).properties.get('metaDataProperty').getAll());
    },
    function (err) {
        // error handling
    }
);

2.

// Implements the IGeocodeProvider interface.
var randomPointProvider = {
    geocode: function (request, options) {
        var deferred = ymaps.vow.defer(),
            geoObjects = new ymaps.GeoObjectCollection(),
            results = options.results || 10;

        for (var i = 0; i < results; i++) {
            geoObjects.add(new ymaps.GeoObject({
                geometry: {
                    type: "Point",
                    coordinates: [(Math.random() - 0.5) * 180, (Math.random() - 0.5) * 360]
                },
                properties: {
                    name: request + ' ' + i,
                    description: request + '\'s description ' + i,
                    balloonContentBody: '<p>' + request + ' ' + i + '</p>'
                }
            }));
        }

        var response = {
            geoObjects: geoObjects, // search output geo objects
            // Response metainformation.
            metaData: {
                geocoder: {
                    request: request, // processed request string
                    found: results, // number of results found
                    results: results, // number of results returned
                    skip: options.skip || 0 // number of results skipped
                }
            }
        };

        // Asynchronous processing.
        setTimeout(function () {
            deferred.resolve(response);
        }, 0);

        return deferred.promise();
    }
};
var myGeocoder = ymaps.geocode("Moscow", { provider: randomPointProvider });

myGeocoder.then(
    function (res) {
        map.geoObjects.add(res.geoObjects);
    },
    function (err) {
        // handling errors
    }
);