GeoQueryResult

Extends IPromiseProvider.

Geo query result.

Constructor | Methods

Constructor

GeoQueryResult(source)

Parameters:

Parameter

Default value

Description

source*

Type: Object

Source of geo objects:

  • IGeoObject - Object that implements the corresponding interface.
  • IGeoObject[] - Array of objects that implement the corresponding interface.
  • ICollection - Collection of objects that implement the IGeoObject interface.
  • ICollection[] - Array of object collections that implement the IGeoObject interface.
  • IPromiseProvider - A promise object that passes the data source for geoQuery to the handler function. The handler function can also be passed an object with the geoObjects field containing the data source for geoQuery.
  • GeoQueryResult - Object of the GeoQueryResult class.
  • String|Object - String or object with a JSON description of objects.
  • Object[] - Array of JSON descriptions of geometries. An array item is an object with the "type" and "coordinates" fields. When describing a circle, the "radius" field is also mandatory. When describing a polygon, the optional "fillRule" field may also be specified.
    JSON object descriptions are formed using the following approach (see the example below). An object may be an entity or a collection of entities. A collection of entities is made up of an object with the following fields:
  • type - Type of object. The value of the field must be "FeatureCollection".
  • features - Array of child entities in the collection. Child objects may be entities or nested collections of entities.
    An entity is made up of an object with the following fields:
  • type - Type of object. The value of the field must be "Feature".
  • geometry - Object geometry. Contains the "type" and "coordinates" fields. Corresponds to the parameter passed to the constructor for the ymaps.GeoObject object.
  • options - Options for the geo object.
  • properties - Geo object data.

* Mandatory parameter/option.

Examples:

1.

// Creating GeoQueryResult from a single geo object.
var placemark = new ymaps.Placemark([34, 56]);
ymaps.geoQuery(placemark).addToMap(myMap);

2.

// Creating GeoQueryResult from an array of geo objects.
var objects = [
    new ymaps.Placemark([34, 56]),
    new ymaps.Rectangle([[34, 56], [36, 57]])
];
ymaps.geoQuery(objects).addToMap(myMap);

3.

// Creating GeoQueryResult from a collection of geo objects.
var result = ymaps.geoQuery(myMap.geoObjects).searchIntersect(myMap);
alert("Number of geo objects in the visible map area: " + result.getLength());

4.

// Creating GeoQueryResult from vow.Deferred.
var result = ymaps.geoQuery(ymaps.geocode('Siromyatnicheskiy lane')).searchInside(myGeoBounds);
// Because the data source is asynchronous, we must wait for result processing.
result.then(function () {
    alert('Number of objects located inside the specified area: ' + result.getLength());
});

5.

// Creating GeoQueryResult from JSON.
var result = ymaps.geoQuery({
    type: 'FeatureCollection',
    features: [
        {
            type: 'Feature',
            geometry: {
                type: 'Circle',
                coordinates: [15, 15],
                radius: 100
            }
        },
        {
            type: 'Feature',
            geometry: {
                type: 'LineString',
                coordinates: [[15, 16], [66, 23]]
            }
        },
        // Object collections can be nested.
        {
            type: 'FeatureCollection',
            features: [
                {
                    type: 'Feature',
                    geometry: {
                        type: 'Point',
                        coordinates: [12, 41]
                    },
                    properties: {
                        name: 'point'
                    },
                    options: {
                        preset: 'islands#yellowIcon'
                    }
                }
            ]
        }
    ]
});
// Adding non-point objects to the map as-is.
result.search('geometry.type != "Point"').addToMap(myMap);
// Adding point objects to the map via the clusterer.
myMap.geoObjects.add(result.search('geometry.type == "Point"').clusterize());

Methods

Name

Returns

Description

add(source)

GeoQueryResult

Adds objects from the source to objects in the result. It does not change the source object; it creates a new object containing a combined set of geo objects.

addEvents(events, callback, context)

GeoQueryResult

Assigns event handlers to selection items.

addTo(collection)

GeoQueryResult

Method for adding objects to a collection of geo objects.

addToMap(map)

GeoQueryResult

Method for adding objects to the map.

applyBoundsToMap(map[, options])

GeoQueryResult

Method for setting the visible area of the map so that all the objects in the selection are visible.

clusterize([options])

Clusterer

This method creates a clusterer and adds objects from the selection to it. If the selection data are not ready yet, they will be added to the clusterer immediately after processing, and the returned clusterer will be empty at first. Only objects with the "Point" geometry will be added to the clusterer.

each(callback, context)

GeoQueryResult

Returns self-reference.

get(index)

IGeoObject

Returns a selection item by index.

getBounds()

Number[][]|null

Returns geographical coordinates of the area that includes all the result objects.

getCenter(map)

Number[]

Method that returns the center of the area that covers all the result objects, in geographical coordinates.

getCentralObject(map)

IGeoObject|null

Method for getting the object that is closest to the center of the visible area of the map.

getClosestTo(object)

IGeoObject|null

Method that returns the selection object that is closest to the one specified. If an object that is already in the selection is given as input, it returns a different object from the selection that is closest to the one specified. Note that many of the geo objects must be added to the map for correct calculations.

getExtreme(key)

Number

Returns the maximum and minimum coordinate values among the coordinates of objects in the selection.

getExtremeObject(key)

IGeoObject

Method that returns the object with the minimum or maximum coordinates among the coordinates of objects in the selection.

getGlobalPixelBounds(map)

Number[][]|null

Method that returns global pixel coordinates of the area for the current map zoom.

getGlobalPixelCenter(map)

Number[]

Returns coordinates of the center of the area, that covers all the result objects, in global pixel coordinates for the current map zoom.

getIterator()

IIterator

Returns iterator for objects in the result.

getLength()

Number

Returns number of items in the result.

getMaxZoom(map[, options])

Number

Method that calculates the maximum zoom level at which all the objects fall within the visible area of the map.

getParent()

GeoQueryResult|null

Returns reference to the parent selection, if the current selection was created as the result of changing another GeoQueryResult object.

indexOf(item)

Number

Returns index of the item in the selection. If the item was not found, it returns -1.

intersect(result)

GeoQueryResult

This method creates a new selection containing common items for two different selections.

isReady()

Boolean

Returns whether the selection results are ready or are still being processed.

map(callback[, context])

GeoQueryResult

Method that calls the "callback" method for all the selection items and forms a new selection based on the results received.

remove(objects)

GeoQueryResult

Deletes objects from the result. It does not change the source object; it creates a new object containing the resulting set of geo objects.

removeEvents(events, callback, context)

Deletes the subscription to events from an object. Note that in order to unsubscribe correctly, the arguments passed must be exactly the same as the ones for subscribing via the "addEvents" method.

removeFrom(collection)

GeoQueryResult

Method for deleting objects from a collection.

removeFromMap(map)

GeoQueryResult

Method for deleting objects from the map.

reverse()

GeoQueryResult

Rearranges the selection items in reverse order and returns the new selection.

search(condition)

GeoQueryResult

Method for searching for selection objects that meet the conditions.

searchContaining(object)

GeoQueryResult

Method that creates a new selection from objects containing the specified object. Note that many of the geo objects must be added to the map for correct calculations.

searchInside(object)

GeoQueryResult

Method that creates a new selection from objects that are completely included in the specified object. Note that many of the geo objects must be added to the map for correct calculations.

searchIntersect(object[, options])

GeoQueryResult

Method that creates a new selection from objects intersecting the specified object. Note that many of the geo objects must be added to the map for correct calculations.

setOptions(key[, value])

GeoQueryResult

Method for setting option values for all the selection items.

setProperties(path, value)

GeoQueryResult

Method for setting the value of the "properties" field for all the selection items.

slice(begin[, end])

GeoQueryResult

Method that returns a slice of the selection.

sort(comparator)

Method for sorting selection objects. It does not change the original selection; it creates a new one containing sorted objects.

sortByDistance(object)

GeoQueryResult

Method for getting a selection containing objects sorted by their distance from the specified object. Note that many of the geo objects must be added to the map for correct calculations. It does not change the original selection.

then([onFulfill[, onReject, context)

GeoQueryResult

Subscription to the promise.

unsetOptions(keys)

GeoQueryResult

Method for nullifying option values for all the selection items.

unsetProperties(path)

GeoQueryResult

Method for nullifying the value of the "properties" field for all the selection items.

Methods details

add

{GeoQueryResult} add(source)

Adds objects from the source to objects in the result. It does not change the source object; it creates a new object containing a combined set of geo objects.

Returns a new object with the combined set of geo objects.

Parameters:

Parameter

Default value

Description

source*

Type: Object

Source of geo objects:

  • IGeoObject - Object that implements the corresponding interface.
  • IGeoObject[] - Array of objects that implement the corresponding interface.
  • ICollection - Collection of objects that implement the IGeoObject interface.
  • ICollection[] - Array of object collections that implement the IGeoObject interface.
  • vow.Promise - A promise object that passes the data source for geoQuery to the handler function. The handler function can also be passed an object with the geoObjects field containing the data source for geoQuery.
  • GeoQueryResult - Object of the GeoQueryResult class.
  • String|Object - String or object with a JSON description of objects.
  • Object[] - Array of JSON descriptions of geometries. An array item is an object with the "type" and "coordinates" fields. When describing a circle, the "radius" field is also mandatory. When describing a polygon, the optional "fillRule" field may also be specified.
    JSON object descriptions are formed using the following approach (see the example below). An object may be an entity or a collection of entities. A collection of entities is made up of an object with the following fields:
  • type - Type of object. The value of the field must be "FeatureCollection".
  • features - Array of child entities in the collection. Child objects may be entities or nested collections of entities.
    An entity is made up of an object with the following fields:
  • type - Type of object. The value of the field must be "Feature".
  • geometry - Object geometry. Contains the "type" and "coordinates" fields. Corresponds to the parameter passed to the constructor for the ymaps.GeoObject object.
  • options - Options for the geo object.
  • properties - Geo object data.

* Mandatory parameter/option.

Examples:

1.

// Adding a single geo object to GeoQueryResult.
var placemark = new ymaps.Placemark([34, 56]);
myGeoQueryResult.add(placemark);

2.

// Adding an array of geo objects to GeoQueryResult.
var objects = [
    new ymaps.Placemark([34, 56]),
    new ymaps.Rectangle([[34, 56], [36, 57]])
];
// Note that a different GeoQueryResult object will be obtained in the result,
// while the old one remains unchanged.
var newResult = myGeoQueryResult.add(objects);

3.

// Adding collections of geo objects to GeoQueryResult.
// Note that a different GeoQueryResult object will be obtained in the result,
// while the old one remains unchanged.
var newResult = myGeoQueryResult.add(myMap.geoObjects).searchIntersect(myBounds);
alert("Number of geo objects in the specified area: " + myGeoQueryResult.getLength());

4.

// Adding geocoding results to GeoQueryResult.
// Note that a different GeoQueryResult will be obtained in the result,
// while the old one remains unchanged.
var newResult = myGeoQueryResult.add(ymaps.geocode('Siromyatnicheskiy lane'));
newResult.searchInside(myGeoBounds);
// Because the data source is asynchronous, we must wait for the result to be processed.
result.then(function () {
    // The source object still exists.
    alert('Before adding objects, the number of objects was:' + myGeoQueryResult.getLength());
    // The new object has both the old geo objects and the ones that were added.
    alert('After adding objects, the number of objects is: ' + result.getLength());
});

5.

// Adding objects from a JSON string.
var result = ymaps.geoQuery(myMap.geoObjects);
var extendedResult = result.add('{"type": "Feature", "geometry": { "type": "Point", "coordinates": [15, 64] }}');
extendedResult.addToMap(myMap);

addEvents

{GeoQueryResult} addEvents(events, callback, context)

Assigns event handlers to selection items.

Returns self-reference.

Parameters:

Parameter

Default value

Description

events*

Type: String|String[]

Event type or array of event types that the subscription ends on.

callback*

Type: Function

Handler function.

context*

Type: Object

Context for the handler function.

* Mandatory parameter/option.

Example:

ymaps.geoQuery(map.geoObjects).search('geometry.type="Circle"').addEvents('click', function () {
    alert('You clicked a circle!');
});

addTo

{GeoQueryResult} addTo(collection)

Method for adding objects to a collection of geo objects.

Returns self-reference.

Parameters:

Parameter

Default value

Description

collection*

Type: ICollection

The collection that objects will be added to.

* Mandatory parameter/option.

Example:

// Showing objects in the northern hemisphere on the map.
var result1 = ymaps.geoQuery(placemarks).search('lat > 0').addTo(myMap.geoObjects);

addToMap

{GeoQueryResult} addToMap(map)

Method for adding objects to the map.

Returns self-reference.

Parameters:

Parameter

Default value

Description

map*

Type: Map

The map that objects will be added to.

* Mandatory parameter/option.

Example:

// Showing objects in the northern hemisphere on the map.
var result1 = ymaps.geoQuery(placemarks).search('lat > 0').addToMap(myMap);

applyBoundsToMap

{GeoQueryResult} applyBoundsToMap(map[, options])

Method for setting the visible area of the map so that all the objects in the selection are visible.

Returns self-reference.

Parameters:

Parameter

Default value

Description

map*

Type: Map

Map.

options

Type: Object

Options.

options.checkZoomRange

false

Type: Boolean

Checks whether the specified zoom level can be set. If the value of this option is "true", the method is called asynchronously. A request is sent to the server, which returns the range of acceptable zoom values for the given center. After this, the specified center and appropriate zoom are applied.

options.duration

0

Type: Number

Animation duration, in milliseconds.

options.preciseZoom

false

Type: Boolean

The ability to use fractional zoom levels.

options.timingFunction

'linear'

Type: String

Timing function. The same as the value of the CSS property transition-timing-function. Full list of values: http://www.w3.org/TR/css3-transitions/#transition-timing-function_tag

options.useMapMargin

true

Type: Boolean

Whether to account for map margins map.margin.Manager.

options.zoomMargin

0

Type: Number|Number[]

Offset from the borders of the visible area of the map. If a single number is set, it is applied to each side. If two numbers are set, they are the horizontal and vertical margins, respectively. If an array of four numbers is set, they are the top, right, bottom, and left margins. When the "useMapMargin" option is enabled, the "zoomMargin" value is combined with the values that were calculated in the margins manager map.margin.Manager.

* Mandatory parameter/option.

Examples:

1.

// Making a geocoding request and setting the visible area of the map
// so that all the results will be visible on it immediately.
var result = ymaps.geoQuery(ymaps.geocode('Lenin street')).applyBoundsToMap(myMap);
// Note that the request to the server is asynchronous and we need to wait for results.
result.then(function () {
    alert("Got results and adjusted the visible area of the map.");
}, function () {
    alert("An error occurred.");
});

2.

// For synchronous requests, the new map area is set immediately.
var result = ymaps.geoQuery(objects).applyBoundsToMap(myMap);
alert('The visible area of the map changed.');

clusterize

{Clusterer} clusterize([options])

This method creates a clusterer and adds objects from the selection to it. If the selection data are not ready yet, they will be added to the clusterer immediately after processing, and the returned clusterer will be empty at first. Only objects with the "Point" geometry will be added to the clusterer.

Returns clusterer.

Parameters:

Parameter

Default value

Description

options

Type: Object

Options passed to the object constructor Clusterer.

Example:

// Selecting only cafes and adding them to the clusterer.
var clusterer = ymaps.geoQuery(objects).search('properties.type="Cafe"').clusterize();
myMap.geoObjects.add(clusterer);

each

{GeoQueryResult} each(callback, context)

Returns self-reference.

Parameters:

Parameter

Default value

Description

callback*

Type: Function

Handler function. Called for each of the selection items and gets the item as input.

context*

Type: Object

Context for the handler function.

* Mandatory parameter/option.

Example:

// Hiding red placemarks in the visible area of the map.
ymaps.geoQuery(placemarks).searchIntersect(myMap).each(function(pm) {
    if (pm.options.get('preset') == 'islands#redIcon') {
        myMap.geoObjects.remove(pm);
    }
});

get

{IGeoObject} get(index)

Returns a selection item by index.

Parameters:

Parameter

Default value

Description

index*

Type: Number

Index of items.

* Mandatory parameter/option.

Examples:

1.

// Example with synchronous processing.
var result = ymaps.geoQuery(placemarks).sort('lat');
// The southernmost object.
var southObject = result.get(0);
// The northernmost object.
northObject = result.get(result.getLength() - 1);

2.

// Example with asynchronous processing.
var result = ymaps.geoQuery(ymaps.geocode('Moscow cafe')).sort('lat');
// We have to wait for the result to be ready before processing further.
result.then(function () {
    // Southernmost object.
    var southObject = result.get(0);
    // Northermost object.
    var northObject = result.get(result.getLength() - 1);
});

getBounds

{Number[][]|null} getBounds()

Returns geographical coordinates of the area that includes all the result objects.

Examples:

1.

// Example of adding the objects synchronously.
// Setting the map center and zoom so that all the objects added to the map are displayed.
var myResult = ymaps.geoQuery(myMap.geoObjects);
myMap.setBounds(myResult.getBounds(), { checkZoomRange: true });

2.

// Example of adding the objects asynchronously.
// Waiting for the data and only then call the getBounds method.
var myResult = ymaps.geoQuery(ymaps.geocode(' Zveronozhka river')).then(function () {
     myMap.setBounds(myResult.getBounds(), { checkZoomRange: true });
});

getCenter

{Number[]} getCenter(map)

Method that returns the center of the area that covers all the result objects, in geographical coordinates.

Returns coordinates of the center of the area, in geographical coordinates.

Parameters:

Parameter

Default value

Description

map*

Type: Map

The map to make calculations for.

* Mandatory parameter/option.

Example:

// Moving the map center to the center of the area that covers the objects.
myMap.setCenter(ymaps.geoQuery(objects).getCenter());

getCentralObject

{IGeoObject|null} getCentralObject(map)

Method for getting the object that is closest to the center of the visible area of the map.

Returns reference to a geo object, or null if the selection is empty.

Parameters:

Parameter

Default value

Description

map*

Type: Map

Map.

* Mandatory parameter/option.

Examples:

1.

// Example of working with synchronous operations.
// Opening a balloon at the object closest to the center of the visible area of the map.
ymaps.geoQuery(objects).getCentralObject(myMap).balloon.open();

2.

// Usage example with asynchronous operations.
var result = ymaps.geoQuery(ymaps.geocode('Ulitsa Stroiteley'));
// We just sent the geocoding request so we need to wait for
// the result.
result.then(function () {
    result.getCentralObject(myMap).balloon.open();
});

getClosestTo

{IGeoObject|null} getClosestTo(object)

Method that returns the selection object that is closest to the one specified. If an object that is already in the selection is given as input, it returns a different object from the selection that is closest to the one specified. Note that many of the geo objects must be added to the map for correct calculations.

Returns the selection object closest to the one specified, or null if the object cannot be found.

Parameters:

Parameter

Default value

Description

object*

Type: Object

The object that the search will be relative to. Accepts the following values:

  • IGeoObject - Object that implements the IGeoObject interface.
  • IGeometry - Object that implements the IGeometry interface.
  • Map - The map. In this case, the reference object is the rectangular border of the map.
  • Number[] - Coordinates of a point.
  • Object - JSON description of a geometry. Contains the "type" and "coordinates" fields. When describing a circle, the "radius" field is also mandatory. When describing a polygon, the optional "fillRule" field may also be specified.

* Mandatory parameter/option.

Examples:

1.

// Examples of using the method with various input data.
var result = ymaps.geoQuery(objects).addToMap(myMap);

// 1. IGeoObject.
// A search can be made relative to an outside object.
var polyline = new ymaps.Polyline([[35, 65], [35, 66], [34, 62], [34, 63]]);
myMap.geoObjects.add(polyline);
var closestObject = result.getClosestTo(polyline);
// The search can be based on an object from the same selection.
var closestToFirst = result.getClosestTo(result.get(0));

// 2. IGeometry.
var closestToGeometry = result.getClosestTo(placemark.geometry);

// 3. Map.
// Finding the object closest to the border of the visible area of the map.
var edgeObject = result.getClosestTo(myMap);

// 4. Object nearest a point.
var closestObject = result.getClosestTo([34, 53]);

2.

// Example with asynchronous operations.
var result = ymaps.geoQuery(ymaps.geocode('Paris')).addToMap(myMap);
// Waiting for the server response and getting the object nearest the point.
result.then(function () {
    var closestObject = result.getClosestTo([34, 65]);
    // If the response is empty, the nearest object will not be found.
    if (closestObject) {
        closestObject.balloon.open();
    }
});

getExtreme

{Number} getExtreme(key)

Returns the maximum and minimum coordinate values among the coordinates of objects in the selection.

Parameters:

Parameter

Default value

Description

key*

Type: String

Key for receiving data. Accepts the following values:

  • top
  • right
  • bottom
  • left

* Mandatory parameter/option.

Examples:

1.

// Example with synchronous operations.
alert('Northernmost coordinate: ', ymaps.geoQuery(myMap.geoObjects).getExtreme('top'));

2.

// Example with asynchronous operations.
var result = ymaps.geoQuery(ymaps.geocode('Novgorod'));
// Waiting for the server response and getting the northernmost coordinate.
result.then(function () {
    alert('Northernmost coordinate in the response: ' + result.getExtreme('top'));
});

getExtremeObject

{IGeoObject} getExtremeObject(key)

Method that returns the object with the minimum or maximum coordinates among the coordinates of objects in the selection.

Returns object with the required coordinate.

Parameters:

Parameter

Default value

Description

key*

Type: String

Key for searching for an object. Accepts the following values:

  • top
  • right
  • bottom
  • left

* Mandatory parameter/option.

Examples:

1.

// Example with synchronous operations.
// Opening a balloon on the northernmost object.
var topObject = ymaps.geoQuery(myMap.geoObjects).getExtremeObject('top');
topObject.balloon.open();

2.

// Example with asynchronous operations.
var result = ymaps.geoQuery(ymaps.geocode('Laptev Sea'));
// Waiting for the server response in order to work with data.
result.then(function () {
    var topObject = result.getExtremeObject('top');
    // If the response is empty, the object will not be found.
    if (topObject) {
        topObject.balloon.open();
    }
});

getGlobalPixelBounds

{Number[][]|null} getGlobalPixelBounds(map)

Method that returns global pixel coordinates of the area for the current map zoom.

Returns global pixel coordinates of the area that includes all objects in the result.

Parameters:

Parameter

Default value

Description

map*

Type: Map

The map that calculations are being made for.

* Mandatory parameter/option.

Example:

var result = ymaps.geoQuery(placemarks).search('properties.type="shop"').getGlobalPixelBounds(myMap);
if (Math.abs(result[0][0] - result[1][0]) > myMap.container.getSize()[0]) {
   alert('Objects are too wide to fit on the map!');
}

getGlobalPixelCenter

{Number[]} getGlobalPixelCenter(map)

Returns coordinates of the center of the area, that covers all the result objects, in global pixel coordinates for the current map zoom.

Parameters:

Parameter

Default value

Description

map*

Type: Map

The map to make calculations for.

* Mandatory parameter/option.

Example:

// Calculating the tile number that contains the center of the area that spans the result.
var globalPixelCenter = ymaps.geoQuery(objects).getGlobalPixelCenter(myMap);
var tileNumber = [
    Math.floor(globalPixelCenter[0] / 256),
    Math.floor(globalPixelCenter[1] / 256)
];
alert('Number of the center tile: ' + tileNumber[0] + ' ' + tileNumber[1]);

getIterator

{IIterator} getIterator()

Returns iterator for objects in the result.

Examples:

1.

// Using the iterator with synchronous operations.
// Searching for elements that match the click coordinates.
myMap.events.add('click', function (event) {
    var iterator = ymaps.geoQuery(myMap.geoObjects)
        .searchContaining(event.getCoordinates())
        .getIterator();
    var   obj;
    while ((obj = iterator.getNext()) != iterator.STOP_ITERATION) {
        // Performing the necessary actions on a geo object.
    }
});

2.

// Using an iterator with asynchronous operations.
// Creating a result from the geocoder query.
var result = ymaps.geoQuery(ymaps.geocode("Starokolpakskiy street")).search("lat > 20");
// Note that we only sent the request to the server, and the response will come later.
// Because the request is asynchronous, we need to wait for it to be ready before getting the result.
result.then(function () {
    var iterator = result.getIterator();
    var obj;
    while ((obj = iterator.getNext())  != iterator.STOP_ITERATION) {
        // Performing the necessary actions on the geo object.
    }
});

getLength

{Number} getLength()

Returns number of items in the result.

Examples:

1.

var result = ymaps.geoQuery(myMap.geoObject).searchIntersect(myPolygon);
alert('The number of geo objects that intersect with the polygon: ' + result.getLength());

2.

var result = ymaps.geoQuery(ymaps.geocode('Ivanovo')).searchInside(myMap);
// Because we sent the request to the server, we cannot immediately count
// the number of elements in the result. We have to wait for the response.
result.then(function () {
    alert('Number of objects in the visible area of the map: ' + result.getLength());
});

getMaxZoom

{Number} getMaxZoom(map[, options])

Method that calculates the maximum zoom level at which all the objects fall within the visible area of the map.

Returns maximum map zoom level.

Parameters:

Parameter

Default value

Description

map*

Type: Map

The map that the calculation is being made for.

options

Type: Object

Options.

options.useMapMargin

true

Type: Boolean

Whether to account for map margins map.margin.Manager.

* Mandatory parameter/option.

Example:

// Calculating the maximum zoom level
// at which all the selection objects are visible
// and setting a restriction for the map.
var maxZoom = ymaps.geoQuery(objects).getMaxZoom();
myMap.options.set('maxZoom', maxZoom);

getParent

{GeoQueryResult|null} getParent()

Returns reference to the parent selection, if the current selection was created as the result of changing another GeoQueryResult object.

Example:

ymaps.geoQuery(objectsArray)
    // Selecting only objects of the type "cafe" and defining their styles.
    .search('properties.type == "cafe"')
    .setOptions('preset', 'islands#yellowDotIcon')
    // Then, without interrupting the chain of calls,
    // getting back to the original selection and defining styles for another group of objects.
    .getParent()
    .search('properties.type == "shop"')
    .setOptions('preset', 'islands#greenDotIcon');

indexOf

{Number} indexOf(item)

Returns index of the item in the selection. If the item was not found, it returns -1.

Parameters:

Parameter

Default value

Description

item*

Type: IGeoObject

The required object.

* Mandatory parameter/option.

Example:

// Sorting the selection by the "name" field.
var result = ymaps.geoQuery(polygons).sort('properties.name');
alert('New position of the first item: ' + result.indexOf(polygons[0]));

intersect

{GeoQueryResult} intersect(result)

This method creates a new selection containing common items for two different selections.

Returns the new selection that contains the intersection result.

Parameters:

Parameter

Default value

Description

result*

Type: GeoQueryResult

The selection to intersect the first one with.

* Mandatory parameter/option.

Examples:

1.

// Example of intersection with synchronous operations.
var result = ymaps.geoQuery(placemarks);
var greenObjects = result.search('properties.color="green"');
var roundObjects = result.search('properties.shape="round"');
var greenRoundObjects = greenObjects.intersect(roundObjects);
alert('Number of round green objects: ' + greenRoundObjects.getLength());

2.

// Example of intersection with asynchronous operations.
var result = ymaps.geoQuery(ymaps.geocode('Ivanovka'));
var filteredByLat = result.search('lat > 56');
var filteredByLong = result.search('long > 36');
var intersectedResult = filteredByLat.intersect(filteredByLong);
// Because the original request is asynchronous, we must wait for data to be ready.
intersectedResult.then(function () {
    alert('Number of objects with the name "Ivanovka" +
        'with coordinates higher than [56, 36]: ' +
        intersectedResult.getLength());
});

isReady

{Boolean} isReady()

Returns whether the selection results are ready or are still being processed.

Example:

var result = ymaps.geoQuery(ymaps.geocode('Ivanovo'));
if (!result.isReady()) {
    result.then(function () {
        // Processing data.
    });
} else {
    // Processing data.
}

map

{GeoQueryResult} map(callback[, context])

Method that calls the "callback" method for all the selection items and forms a new selection based on the results received.

Returns the new selection.

Parameters:

Parameter

Default value

Description

callback*

Type: Function

Handler function. Takes a selection item as input. Returns an instance of IGeoObject.

context

Type: Object

Context for the handler function.

* Mandatory parameter/option.

Example:

// Adding only circle objects to the map.
var circlesResult = ymaps.geoQuery(objects).search('geometry.type="Circle"').addToMap(myMap);
// We'll also add placemarks that indicate the circle centers.
var centers = circlesResult.map(function (object) {
    return new ymaps.Placemark(object.geometry.getCenter());
}).addToMap(myMap);

remove

{GeoQueryResult} remove(objects)

Deletes objects from the result. It does not change the source object; it creates a new object containing the resulting set of geo objects.

Returns new object with the resulting set of geo objects.

Parameters:

Parameter

Default value

Description

objects*

Type: Object

Objects can be presented in various forms:

  • IGeoObject - Object that implements the corresponding interface.
  • IGeoObject[] - Array of objects that implement the corresponding interface.
  • ICollection - Collection of objects that implement the IGeoObject interface.
  • ICollection[] - Array of object collections that implement the IGeoObject interface.
  • GeoQueryResult - Object of the GeoQueryResult class. Note that with asynchronous operations, the result has to be prepared before it can be deleted correctly.
  • vow.Promise - Object of the vow.Deferred class. Must be resolved by an array of geo objects or an object with the "geoObjects" field.

* Mandatory parameter/option.

Examples:

1.

var objects = [
    new ymaps.Placemark([34, 56]),
    new ymaps.Rectangle([[34, 56], [36, 57]])
];
var result = ymaps.geoQuery(objects);
// Note that a different GeoQueryResult object will be obtained in the result,
// while the old one remains unchanged.
var newResult = result.remove(objects[1]);

2.

// Deleting an array of geo objects from GeoQueryResult.
var objects = [
    new ymaps.Placemark([34, 56]),
    new ymaps.Rectangle([[34, 56], [36, 57]]),
    new ymaps.Placemark([35, 64])
];
var result = ymaps.geoQuery(objects);
// Note that a different GeoQueryResult object will be obtained in the result,
// while the old one remains unchanged.
var newResult = result.remove([objects[1], objects[2]]);

3.

// Deleting collections of geo objects from GeoQueryResult.
// Adding objects to the map that aren't on it yet.
myGeoQueryResult.remove(myMap.geoObjects).addToMap(myMap);

4.

// Deleting data of a different GeoQueryResult from GeoQueryResult.
var result1 = ymaps.geoQuery(placemarks).search('properties.color="green"');
var result2 = ymaps.geoQuery(placemarks).search('properties.shape="circle"');
var result3 = result1.remove(result2);
alert('Number of green non-round shapes: ' + result3.getLength());

removeEvents

{} removeEvents(events, callback, context)

Deletes the subscription to events from an object. Note that in order to unsubscribe correctly, the arguments passed must be exactly the same as the ones for subscribing via the "addEvents" method.

Parameters:

Parameter

Default value

Description

events*

Type: String|String[]

Event type or array of types that a subscription was made to.

callback*

Type: Function

Handler function that was specified when subscribing.

context*

Type: Object

Context that was specified when subscribing.

* Mandatory parameter/option.

Example:

var callback = function () {
    alert('You clicked a circle!');
};
ymaps.geoQuery(map.geoObjects).search('geometry.type="Circle"').addEvents('click', callback);
// ...
ymaps.geoQuery(map.geoObjects).search('geometry.type="Circle"').removeEvents('click', callback);

removeFrom

{GeoQueryResult} removeFrom(collection)

Method for deleting objects from a collection.

Returns self-reference.

Parameters:

Parameter

Default value

Description

collection*

Type: ICollection

The collection to delete objects from.

* Mandatory parameter/option.

Example:

// Showing all objects on the map.
var result1 = ymaps.geoQuery(placemarks).addTo(myMap.geoObjects);
// Then hiding objects in the northern hemisphere.
var result2 = result1.search('lat > 0').removeFrom(myMap.geoObjects);

removeFromMap

{GeoQueryResult} removeFromMap(map)

Method for deleting objects from the map.

Returns self-reference.

Parameters:

Parameter

Default value

Description

map*

Type: Map

The map to delete objects from.

* Mandatory parameter/option.

Example:

// Showing all objects on the map.
var result1 = ymaps.geoQuery(placemarks).addToMap(myMap);
// Then hiding objects in the northern hemisphere.
var result2 = result1.search('lat > 0').removeFromMap(myMap);

reverse

{GeoQueryResult} reverse()

Rearranges the selection items in reverse order and returns the new selection.

Returns the new selection with items in reverse order.

Examples:

1.

// Usage with synchronous requests.
var result = ymaps.geoQuery(myMap.geoObjects).sort('x'),
    invertedResult = result.reverse();

2.

// Usage with asynchronous requests.
var result = ymaps.geoQuery(ymaps.geocode('Friendly Bees village')).sort('x');
var invertedResult = result.reverse();
invertedResult.then(function () {
    // Got the result. Ready to use.
});
{GeoQueryResult} search(condition)

Method for searching for selection objects that meet the conditions.

Returns a new selection containing search results.

Parameters:

Parameter

Default value

Description

condition*

Type: String|Function

String template for search or a filter function. A string template has the structure "<fieldname> <condition> <expression>". Acceptable values for <fieldname>:

  • 'lat' - Latitude. Supported only for point objects.
  • 'lng', 'long' - Longitude. Supported only for point objects.
  • 'x' - Global pixel coordinates on the X axis. Supported only for point objects.
  • 'y' - Global pixel coordinates on the Y axis. Supported only for point objects.
  • 'geometry.type' - Type of geometry. Result of executing the geometry.getType() method.
  • 'geometry.coordinates.<index>' - Coordinates. Result of executing the geometry.getCoordinates() method. To get access to a coordinate, specify its indexes after a dot - 'geometry.coordinates.0.1'.
  • 'properties.<path>' - Value of the data field.
  • 'options.<key>' - Value of options.
    Acceptable values for <condition>:
  • '>'
  • '>='
  • '==', '='
  • '!='
  • '<='
  • '<'
  • 'rlike', 'regexp' - Matches the <fieldname> value to a regular expression.
    Acceptable values for <expression>:
  • Number
  • String (must be put in quotation marks)
  • true
  • false
  • null
  • undefined
    The filter function takes a selection object as input and returns true/false. True means the object is in the resulting selection, and false means it is not.

* Mandatory parameter/option.

Examples:

1.

// Example of searching for objects with synchronous operations.
var result = ymaps.geoQuery(myMap.geoObjects);

         // Searching for objects with a specific type of geometry. Note that
// the field value shown in quotes is a string.
result.search('geometry.type = "Circle"')
// Searching by a coordinate.
    .search('geometry.coordinates.0 > 100')
// Searching by latitude.
    .search('lat < 0')
// Searching by pixel coordinates.
    .search('x >= 100')
// Searching by the field value in "properties".
    .search('properties.name != null').search('properties.name rlike "(.) \\""')
    .search('properties.author.name = "Stepan"')
// Searching by option value.
    .search('options.visible = true');

2.

// Using the method with asynchronous operations.
var result = ymaps.geoQuery(ymaps.geocode('Moose'));
// Waiting for the result to be ready before working with it.
result.then(function () {
    result.search('properties.description regExp "*village*"')
        .addToMap(myMap)
        .applyBoundsToMap(myMap);
});

searchContaining

{GeoQueryResult} searchContaining(object)

Method that creates a new selection from objects containing the specified object. Note that many of the geo objects must be added to the map for correct calculations.

Returns a new selection containing the desired objects.

Parameters:

Parameter

Default value

Description

object*

Type: Object

The object that the search will be relative to. Accepts the following values:

  • IGeoObject - Object that implements the IGeoObject interface.
  • IGeometry - Object that implements the IGeometry interface.
  • Map - The map. In this case, the reference object is the rectangular border of the map.
  • Number[] - Coordinates of a point. If one parameter is passed, it is interpreted as a point. If two arguments are passed, it is interpreted as a circle.
  • Number[][] - Coordinates of a rectangular area.
  • Object - JSON descriptions of a geometry.

* Mandatory parameter/option.

Examples:

1.

// Examples of using the method with various input data.
var result = ymaps.geoQuery(objects).addToMap(myMap);

// 1. IGeoObject.
var polygon = new ymaps.Polygon([[[35, 65], [35, 66], [34, 62], [34, 63], [35, 65]]]);
myMap.geoObjects.add(polygon);
var objectsContainingPolygon = result.searchContaining(polygon);

// 2. IGeometry.
var objectsContainingGeometry = result.searchContaining(polygon.geometry);

// 3. Map.
var objectsContainingMapBounds = result.searchContaining(myMap);

2.

// Example of usage with asynchronous operations.
var result = ymaps.geoQuery(ymaps.geocode('cafe'))
        .addToMap(myMap);
// Waiting for the server response before processing results.
result.then(function () {
    var areas = result.map(function (object) {
        return new ymaps.Circle(object.geometry.getCoordinates(), 100);
    })
        .setOptions('visible', false)
        .addToMap(myMap);
    myMap.events.add('click', function (event) {
        if (areas.searchContaining(event.getCoordinates()).getLength()) {
            alert('You clicked near a cafe.');
        }
    });
});

searchInside

{GeoQueryResult} searchInside(object)

Method that creates a new selection from objects that are completely included in the specified object. Note that many of the geo objects must be added to the map for correct calculations.

Returns a new selection containing the desired objects.

Parameters:

Parameter

Default value

Description

object*

Type: Object

The object that the search will be relative to. Accepts the following values:

  • IGeoObject - Object that implements the IGeoObject interface.
  • IGeometry - Object that implements the IGeometry interface.
  • Map - The map. In this case, the reference object is the rectangular border of the map.

* Mandatory parameter/option.

Examples:

1.

// Examples of using the method with various input data.
var result = ymaps.geoQuery(objects).addToMap(myMap);

// 1. IGeoObject.
var polygon = new ymaps.Polygon([[[35, 65], [35, 66], [34, 62], [34, 63], [35, 65]]]);
myMap.geoObjects.add(polygon);
var objectsInsidePolygon = result.searchInside(polygon);

// 2. IGeometry.
var objectsInsideGeometry = result.searchInside(polygon.geometry);

// 3. Map.
// We'll find objects that fit entirely inside the visible area of the map.
var visibleObject = result.searchInside(myMap);

2.

// Example of usage with asynchronous operations.
var result = ymaps.geoQuery(ymaps.geocode('Ivanovo'))
        .setOptions('visible', false)
        .addToMap(myMap);
// Waiting for the server response and then showing objects that fit inside the visible area of the map.
result.then(function () {
    result.searchInside(myMap).setOptions('visible', true);
});

searchIntersect

{GeoQueryResult} searchIntersect(object[, options])

Method that creates a new selection from objects intersecting the specified object. Note that many of the geo objects must be added to the map for correct calculations.

Returns a new selection containing the desired objects.

Parameters:

Parameter

Default value

Description

object*

Type: Object

The object that the search will be relative to. Accepts the following values:

  • IGeoObject - Object that implements the IGeoObject interface.
  • IGeometry - Object that implements the IGeometry interface.
  • Map - The map. In this case, the reference object is the rectangular border of the map.

options

Type: Object

Options.

options.considerOccurance

true

Type: Object

Flag indicating whether we consider it an intersection when one figure is completely contained inside another.

* Mandatory parameter/option.

Examples:

1.

// Examples of using the method with various input data.
var result = ymaps.geoQuery(objects).addToMap(myMap);

// 1. IGeoObject.
var polygon = new ymaps.Polygon([[[35, 65], [35, 66], [34, 62], [34, 63], [35, 65]]]);
myMap.geoObjects.add(polygon);
var objectsIntersectPolygon = result.searchIntersect(polygon);

// 2. IGeometry.
var objectsIntersectGeometry = result.searchIntersect(polygon.geometry);

// 3. Map.
// We will only search for objects that directly intersect
// the map border. In other words, objects that are entirely inside the visible area of the map
// will not be in the final selection.
var objectsIntersectMapBounds = result.searchIntersect(myMap, {considerOccurance: false});

2.

// Example of usage with asynchronous operations.
var result = ymaps.geoQuery(ymaps.geocode('cafe'))
        .setOptions('visible', false)
        .addToMap(myMap);

// Waiting for the server response and then showing objects that fall within the map viewport.
result.then(function () {
    result.searchIntersect(myMap).setOptions('visible', true);
});

setOptions

{GeoQueryResult} setOptions(key[, value])

Method for setting option values for all the selection items.

Returns self-reference.

Parameters:

Parameter

Default value

Description

key*

Type: String|Object

Option name or hash with options and their values.

value

Type: Object

Option value.

* Mandatory parameter/option.

Example:

var result = ymaps.geoQuery(placemarks);
// Making elements visible if they fall within a rectangular area.
result.searchIntersect(myBounds).setOptions('visible', true);

// Setting options using a hash.
result.setOptions({zIndex: 10, fillColor: '#ff0005'});

setProperties

{GeoQueryResult} setProperties(path, value)

Method for setting the value of the "properties" field for all the selection items.

Returns self-reference.

Parameters:

Parameter

Default value

Description

path*

Type: String

Name of the field that the value is assigned to. It may contain ".".

value*

Type: Object

Field value.

* Mandatory parameter/option.

Example:

var result = ymaps.geoQuery(objects);
// Marking elements that fall inside the area.
result.searchIntersect(myBounds1).setProperties('intersectBounds', true);
result.searchIntersect(myBounds2).setProperties('intersectBounds', true);
// ...
result.search('properties.intersectBounds = true').addToMap(myMap);

slice

{GeoQueryResult} slice(begin[, end])

Method that returns a slice of the selection.

Returns the new selection containing items in the slice.

Parameters:

Parameter

Default value

Description

begin*

Type: Number

Index of the first item in the slice.

end

Type: Number

Index of the selection item that ends the slice. However, the last item in the new slice will be the item with the index end-1.

* Mandatory parameter/option.

Examples:

1.

// Making a slice with asynchronous processing.
var result = ymaps.geoQuery(map.geoObjects).slice(0, 10);
alert('Number of items in new selection:' + result.getLength());

2.

// Getting a slice with asynchronous processing.
var result = ymaps.geoQuery(ymaps.geocode('cafe Moscow')).slice(0, 10);
// The result is not ready immediately after the request.
alert('The selection is still empty. Number of items in selection: ' + result.getLength());
// Waiting for the result to be ready and then we will see how many items will be in the selection.
result.then(function () {
    alert('Response received. Amount of data in the selection: ' + result.getLength());
});

sort

{} sort(comparator)

Method for sorting selection objects. It does not change the original selection; it creates a new one containing sorted objects.

Parameters:

Parameter

Default value

Description

comparator*

Type: String

Function

String with a sorting template or a compare function. The template string can be in the format '<fieldname> [=asc]'. Acceptable values for <fieldname>:

  • 'lat' - Latitude. Supported only for point objects.
  • 'lng', 'long' - Longitude. Supported only for point objects.
  • 'x' - Global pixel coordinates on the X axis. Supported only for point objects.
  • 'y' - Global pixel coordinates on the Y axis. Supported only for point objects.
  • 'geometry.type' - Type of geometry. Result of executing the geometry.getType() method.
  • 'geometry.coordinates.<index>' - Coordinates. Result of executing the geometry.getCoordinates() method. To get access to a coordinate, specify its indexes after a dot - 'geometry.coordinates.0.1'.
  • 'properties.<path>' - Value of the data field.
  • 'options.<key>' - Value of options.
    Acceptable values for the optional <order>: parameter:
  • 'asc' - Sort in ascending order.
  • 'desc' - Sort in descending order.
    The compare function takes two selection items as input. Returned values: If the first object is larger than the second, the function returns the value > 0. If the first object is equal to the second, the function returns 0. If the first object is smaller than the second, the function returns < 0.

* Mandatory parameter/option.

Example:

// Example with synchronous operations.
var result = ymaps.geoQuery(myMap.geoObjects);
result.sort('lat').sort('x')
    .sort('properties.name desc')
    .sort('options.preset')
    .sort(function (a, b) {
        if (a.properties.get('name') == b.properties.get('name')) {
            return a.geometry.getCoordinates()[0] - b.geometry.getCoordinates()[0];
        } else {
            return (a.properties.get('name') > b.properties.get('name')) ? 1 : -1;
        }
    });

sortByDistance

{GeoQueryResult} sortByDistance(object)

Method for getting a selection containing objects sorted by their distance from the specified object. Note that many of the geo objects must be added to the map for correct calculations. It does not change the original selection.

Returns the new ordered selection.

Parameters:

Parameter

Default value

Description

object*

Type: Object

The object that the distance will be calculated to. Accepts the following values:

  • IGeoObject - Object that implements the IGeoObject interface.
  • IGeometry - Object that implements the IGeometry interface.
  • Map - The map. In this case, the reference object is the rectangular border of the map.
  • Number[] - Coordinates of a point.
  • Number[][] - Coordinates of a rectangular area.
  • Object - JSON description of a geometry. Contains the "type" and "coordinates" fields. When describing a circle, the "radius" field is also mandatory. When describing a polygon, the optional "fillRule" field may also be specified.

* Mandatory parameter/option.

Examples:

1.

// Examples of using the method with various input data.
var result = ymaps.geoQuery(objects).addToMap(myMap);

// 1. IGeoObject.
var polyline = new ymaps.Polyline([[35, 65], [35, 66], [34, 62], [34, 63]]);
myMap.geoObjects.add(polyline);
var sortedByPolyline = result.sortByDistance(polyline);

// 2. IGeometry.
var sortedByGeometry = result.sortByDistance(placemark.geometry);

// 3. Map.
var sortedByMapBounds = result.sortByDistance(myMap);

// 4. The selection sorted by a point.
var sortedByPoint = result.sortByDistance([34, 53]);

2.

// Example with asynchronous operations.
var result = ymaps.geoQuery(ymaps.geocode('Paris')).addToMap(myMap).sortByDistance([45, 64]);
// Waiting for the result from the server and getting the nearest and furthest
// object relative to the point.
result.then(function () {
    alert('The nearest object has the coordinates ' + result.get(0).geometry.getCoordinates());
    alert('The furthest object has the coordinates ' + result.get(result.getLength() - 1).geometry.getCoordinates());
});

then

{GeoQueryResult} then([onFulfill[, onReject, context)

Subscription to the promise.

Returns self-reference.

Parameters:

Parameter

Default value

Description

onFulfill

Type: Function

Handler function that is called if the promise was fulfilled.

onReject

Type: Function

Handler function that is called if the promise was not fulfilled (an error occurred).

context*

Type: Object

Context for the handler function.

* Mandatory parameter/option.

Example:

var result = ymaps.geoQuery(ymaps.geocode('Lena river'));
result.then(function () {
    alert('Number of objects found: ' + result.getLength());
}, function () {
    alert('Error occurred.');
});

unsetOptions

{GeoQueryResult} unsetOptions(keys)

Method for nullifying option values for all the selection items.

Returns self-reference.

Parameters:

Parameter

Default value

Description

keys*

Type: String|String

Name or array of names of options that should be canceled.

* Mandatory parameter/option.

Example:

result.unsetOptions('visible');

unsetProperties

{GeoQueryResult} unsetProperties(path)

Method for nullifying the value of the "properties" field for all the selection items.

Returns self-reference.

Parameters:

Parameter

Default value

Description

path*

Type: String

Name of a field to cancel the value for. It may contain ".".

* Mandatory parameter/option.

Example:

var result = ymaps.geoQuery(objects);
// Marking items that fall inside the first area, but do not fall inside the second one.
result.searchIntersect(myBounds1).setProperties('intersectBounds', true);
result.searchIntersect(myBounds2).unsetProperties('intersectBounds', true);
// ...
result.search('properties.intersectBounds = true').addToMap(myMap);