GeoQueryResult
- Constructor
- Methods
- Methods details
- add
- addToMap
- applyBoundsToMap
- clusterize
- each
- get
- getBounds
- getCenter
- getCentralObject
- getClosestTo
- getExtreme
- getExtremeObject
- getGlobalPixelBounds
- getGlobalPixelCenter
- getIterator
- getLength
- getMaxZoom
- getParent
- indexOf
- intersect
- map
- remove
- removeFromMap
- reverse
- search
- searchContaining
- searchIntersect
- setProperties
- sort
- sortByDistance
- then
- unsetProperties
Extends IPromiseProvider.
Geo query result.
Constructor
GeoQueryResult(source)
Parameters:
Parameter |
Default value |
Description |
— |
Type: Object Source of geo objects:
|
* 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 |
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. |
||
Assigns event handlers to selection items. |
||
Method for adding objects to a collection of geo objects. |
||
Method for adding objects to the map. |
||
Method for setting the visible area of the map so that all the objects in the selection are visible. |
||
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 self-reference. |
||
Returns a selection item by index. |
||
Number[][]|null |
Returns geographical coordinates of the area that includes all the result objects. |
|
Number[] |
Method that returns the center of the area that covers all the result objects, in geographical coordinates. |
|
IGeoObject|null |
Method for getting the object that is closest to the center of the visible area of the map. |
|
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. |
|
Number |
Returns the maximum and minimum coordinate values among the coordinates of objects in the selection. |
|
Method that returns the object with the minimum or maximum coordinates among the coordinates of objects in the selection. |
||
Number[][]|null |
Method that returns global pixel coordinates of the area for the current map zoom. |
|
Number[] |
Returns coordinates of the center of the area, that covers all the result objects, in global pixel coordinates for the current map zoom. |
|
Returns iterator for objects in the result. |
||
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. |
GeoQueryResult|null |
Returns reference to the parent selection, if the current selection was created as the result of changing another GeoQueryResult object. |
|
Number |
Returns index of the item in the selection. If the item was not found, it returns -1. |
|
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. |
Method that calls the "callback" method for all the selection items and forms a new selection based on the results received. |
||
Deletes objects from the result. It does not change the source object; it creates a new object containing the resulting set of geo objects. |
||
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. |
||
Method for deleting objects from a collection. |
||
Method for deleting objects from the map. |
||
reverse() |
Rearranges the selection items in reverse order and returns the new selection. |
|
Method for searching for selection objects that meet the conditions. |
||
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. |
||
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. |
||
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]) |
Method for setting option values for all the selection items. |
|
Method for setting the value of the "properties" field for all the selection items. |
||
Method that returns a slice of the selection. |
||
Method for sorting selection objects. It does not change the original selection; it creates a new one containing sorted objects. |
||
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. |
||
Subscription to the promise. |
||
Method for nullifying option values for all the selection items. |
||
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 |
— |
Type: Object Source of geo objects:
|
* 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 |
— |
Type: String|String[] Event type or array of event types that the subscription ends on. |
|
— |
Type: Function Handler function. |
|
— |
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 |
— |
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 |
|
— |
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 |
|
— |
Type: Map Map. |
— |
Type: Object Options. |
|
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. |
|
0 |
Type: Number Animation duration, in milliseconds. |
|
false |
Type: Boolean The ability to use fractional zoom levels. |
|
'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 |
|
true |
Type: Boolean Whether to account for map margins map.margin.Manager. |
|
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 |
— |
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 |
— |
Type: Function Handler function. Called for each of the selection items and gets the item as input. |
|
— |
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 |
— |
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 |
|
— |
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 |
|
— |
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 |
— |
Type: Object The object that the search will be relative to. Accepts the following values:
|
* 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 |
|
— |
Type: String Key for receiving data. Accepts the following values:
|
* 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 |
|
— |
Type: String Key for searching for an object. Accepts the following values:
|
* 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 |
|
— |
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 |
|
— |
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 |
|
— |
Type: Map The map that the calculation is being made for. |
— |
Type: Object Options. |
|
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 |
|
— |
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 |
— |
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 |
— |
Type: Function Handler function. Takes a selection item as input. Returns an instance of IGeoObject. |
|
— |
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 |
— |
Type: Object Objects can be presented in various forms:
|
* 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 |
— |
Type: String|String[] Event type or array of types that a subscription was made to. |
|
— |
Type: Function Handler function that was specified when subscribing. |
|
— |
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 |
— |
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 |
|
— |
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.
});
search
{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 |
— |
Type: String|Function String template for search or a filter function. A string template has the structure "<fieldname> <condition> <expression>". Acceptable values for <fieldname>:
|
* 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 |
— |
Type: Object The object that the search will be relative to. Accepts the following values:
|
* 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 |
— |
Type: Object The object that the search will be relative to. Accepts the following values:
|
* 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 |
— |
Type: Object The object that the search will be relative to. Accepts the following values:
|
|
— |
Type: Object Options. |
|
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 |
|
— |
Type: String|Object Option name or hash with options and their values. |
— |
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 |
|
— |
Type: String Name of the field that the value is assigned to. It may contain ".". |
— |
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 |
— |
Type: Number Index of the first item in the slice. |
|
— |
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 |
|
— |
Type: String |
Function String with a sorting template or a compare function. The template string can be in the format '<fieldname> [
|
* 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 |
— |
Type: Object The object that the distance will be calculated to. Accepts the following values:
|
* 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 |
— |
Type: Function Handler function that is called if the promise was fulfilled. |
|
— |
Type: Function Handler function that is called if the promise was not fulfilled (an error occurred). |
|
— |
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 |
|
— |
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 |
|
— |
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);
Mandatory parameter/option.