find

var existingShape = $( map or service selector ).geomap( "find", { type: "Point", coordinates: [ -71.098709, 42.330322 ] }, 8 )

var allShapes = $( map or service selector ).geomap( "find", "*" )

The find method allows you to search for shapes appended to the map and/or services. There are two distinct ways to call this method.

geometry search

The find method can take a single GeoJSON map point and return all shapes within a pixel radius of the given location that have been added with append. If there are no shapes at the location, this method returns an empty array.

The pixelTolerance argument is always in pixels. This allows for pixel-based searches regardless of the map's current zoom. A high-zoom search is finer than a low-zoom one because at lower zoom levels, i.e., the map is zoomed out more, the Earth-size of a pixel is greater causing this search to reach out farther from the supplied position.

Duplicate shape references are included in the return value. For example, if you have appended the same GeoJSON object to both the map and a specific service, and then call find at that location, the returned array will contain two, identical shape references.

selector search

The find method can also take a single string. The string is in CSS selector syntax but currently only one selector is supported: *. Use the * selector to return an array of all shapes that have been appended to the map or service. If there are no shapes on the map or service, this method returns an empty array. Searching for all shapes at the map level will return all shapes that have been appended to the map or any service.

Duplicate shape references are included in the return value. For example, if you have appended the same GeoJSON object to both the map and a specific service, and then call find( "*" ) at the map level, the returned array will contain two, identical shape references.

The shape selector cannot include service ids or classes. To search for shapes within a specific service, see below.

service-level shapes

Similar to how you can append shapes to specific services, you can find shapes in specific services as well.

You do this by targeting a service inside a map instead of the map itself for your call to geomap's find method. For example, the default map service has the CSS class: osm. We can find a shape from that service specifically by using jQuery to target the service:

var osmShapes = $( "#map .osm" ).geomap( "find", [ -71, 42 ], 8 );

However, unlike the other three shape methods, shapes appended to a specific service will be returned by calling find on the map itself. In this way, calling find on the map is a deep search for shapes on all services. For example, after this sequence the shapes variable will contain the shape even though it was appended to a service specifically:

var point = {
      type: "Point",
      coordinates: [ -71, 42 ]
    };

// add the shape to the osm service
$( "#map .osm" ).geomap( "append", point );

// use the original point to search for shapes on the map widget
var shapes = $( "#map" ).geomap( "find", point, 3 );

Another difference between the find method and the append, remove, and empty methods, is that the find method cannot currently be used on multiple targets simultaneously. For example, the return value of the following is undefined:

// attempt to search the osm service and a second service at the same time
var shapes = $( "#map .osm,#map .massgis" ).geomap( "find", point, 8 );

To find shapes in two specific services without searching all services you should use two find calls:

// find shapes on the default service and a second service
var osmShapes = $( "#map .osm" ).geomap( "find", point, 8 ),
    massgisShapes = $( "#map .massgis" ).geomap( "find", point, 8 );

The selector-based version also follows this requirement. You cannot target more than one element with the initial selector and you cannot use the shape selector to search services. A multi-service selector-based search would be the same as above but with "*" instead of: point, 8.

// the following are invalid and their return value is undefined
var multiTarget = $( "#map .massgis,#map .osm" ).geomap( "find", "*" );
var shapeSubSelector = $( "#map" ).geomap( "find", ".massgis *" );

// proper way to get all shapes from multiple services
var osmShapes = $( "#map .osm" ).geomap( "find", "*" ),
    massgisShapes = $( "#map .massgis" ).geomap( "find", "*" );