VEMap.Find Method

Find Method

VEMap.Find Method

Performs a what (business) search or a where (location) search. At least one of these two parameters is required.

VEMap.Find(what, where, findType, shapeLayer, startIndex, numberOfResults, showResults, createResults, useDefaultDisambiguation, setBestMapView, callback);

Parameters

Parameter	Description
what	The business name, category, or other item for which the search is conducted. This parameter must be supplied for a pushpin to be included in the results.
where	The address or place name of the area for which the search is conducted. This parameter is overloaded; see the Remarks section for more information.
findType	A VEFindType Enumeration value that specifies the type of search performed. The only currently supported value is VEFindType.Businesses.
shapeLayer	A reference to the VEShapeLayer Class object that contain the pins that result from this search if a what parameter is specified. Optional. If the shape layer is not specified, the pins are added to the base map layer. If the reference is not a valid VEShapeLayer reference, an exception is thrown.
startIndex	The beginning index of the results returned. Optional. Default is 0.
numberOfResults	The number of results to be returned, starting at startIndex. The default is 10, the minimum is 1, and the maximum is 20.
showResults	A Boolean value that specifies whether the resulting pushpins are visible. Optional. Default is true.
createResults	A Boolean value that specifies whether pushpins are created when a what parameter is supplied. Optional. If true, pushpins are created. If false, the arguments sent to the function specified by the callback parameter are set as follows: The VEShapeLayer argument is . The array of VEFindResult Class objects is still present, but no pushpin layer is created. Each VEFindResult object's corresponding Shape property is .
useDefaultDisambiguation	A Boolean value that specifies whether the map control displays a disambiguation box when multiple location matches are possible. If true, the map control displays a disambiguation box. Optional. The default is true. To ensure no messages appear when useDefaultDisambiguation is false, set the VEMap.ShowMessageBox Property to false.
setBestMapView	A Boolean value that specifies whether the map control moves the view to the first location match. If true, the map control moves the view. Optional. Default is true.
callback	The name of the function that the server calls with the search results. If this parameter is not and useDefaultDisambiguation is true, this function is not called until the user has made a disambiguation choice. Optional.

Return Value

This method does not return a value. The function defined by the callback parameter receives the following arguments, in the order shown, from the server:

A VEShapeLayer Class object. If shapeLayer was supplied, it should be the same object.
An array of VEFindResult Class objects.
An array of VEPlace Class objects.
A Boolean value indicating whether there are more results after the current set.
A String containing a possible error message.

Remarks

The callback function for this method is not re-entrant. If an application calls Find before a previous Find call has returned the search results to the callback function, the first set of arguments are destroyed and are no longer available.

A Find call must include a non-null what parameter or non-null where parameter (or both).

If the Find call contains a non-null what parameter:

The map control returns a VEShapeLayer Class object as the first argument to the callback function. If the search is unsuccessful, this argument is . Otherwise, the pushpins that are returned as the second argument are all on this layer.
The map control returns an array of VEFindResult Class objects as the second argument to the callback function. If the search is unsuccessful, this argument is . Otherwise, each VEFindResult object contains a reference to a corresponding VEShape Class pushpin.
If a what parameter is specified, but the where parameter is , the current map view is used, even if the setBestMapView parameter is true.
If the numberOfResults parameter is set, it will limit the number of locations returned.

If the Find call provides a non-null where parameter:

The where parameter is overloaded. It can be either a String, representing a place such as "London" or "123 Main Street," a VEPlace Class object, or a VELatLongRectangle Class object. If it is a VEPlace object or a VELatLongRectangle object, then the what parameter must be non-null.
If the where parameter is a String, it is used to geocode a place name or an address.
The map control returns an array of VEPlace objects as the third argument to the callback function. If the search is unsuccessful, this argument is . Otherwise, these objects represent the possible location matches.
If more than one location matches the where search string, and the useDefaultDisambiguation parameter is true, the map control displays a disambiguation dialog box. The user must select a location from this dialog before the map control completes the search and calls the callback function.
If a where parameter is specified, the what parameter is null, and at least one of the VEPlace objects returned as the third argument to the callback function has a MatchConfidence property value of VEMatchConfidence.High, the map control does not display a disambiguation dialog box, even if the useDefaultDisambiguation parameter is true, but displays the first VEPlace object in the array. However, since all of the possible places are returned in the array, an application could build its own disambiguation dialog and query the user.

Localized search results can be returned by adding a mkt attribute to the map control reference. Information about returning localized results including supported cultures can be found in the Returning Localized Results topic.

Example

JScript

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
   <head>
      <title></title>
      <meta http-equiv="Content-Type" content="text/html; charset=utf-8">

      <script type="text/javascript" src="http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.2"></script>

      <script type="text/javascript">
         var map = null;
         var index = 0;
         var results = null;

         function GetMap()
         {
            map = new VEMap('myMap');
            map.LoadMap();
         }
          
         function FindLoc(numResults)
         {
            try
            {
               results = map.Find(document.getElementById('txtWhat').value,
                                  document.getElementById('txtWhere').value,
                                  null,
                                  null,
                                  index,
                                  numResults,
                                  true,
                                  true,
                                  true,
                                  true,
                                  MoreResults);
                index = parseInt(index)+9;
            }
            catch(e)
            {
               alert(e.message);
            }
         }
        
         function MoreResults(layer, resultsArray, places, hasMore, veErrorMessage)
         {
            if(hasMore)
            {
               var r = "<a href='#' onclick='javascript:FindLoc(parseInt(document.getElementById('txtNumResults').value));'>" +
                       "Click for More Results</a>";
               document.getElementById('results').innerHTML = r;
            }
            else
            {
               index=0;
               number=Number(document.getElementById('txtNumResults').value); 
               document.getElementById('results').innerHTML = "";
               document.getElementById('results').innerHTML = "No More Results Available";
            }
         }
      </script>
   </head>
   <body onload="GetMap();" style="font-family:Arial">
      <div id='myMap' style="position:relative; width:400px; height:400px;"></div>
      What:
      <input id="txtWhat" type="text" name="txtWhat" value="Pizza"/>
      <br />
      Where:
      <input id="txtWhere" type="text" name="txtWhere" value="Toledo, OH"/>
      Number of Results:
      <input id="txtNumResults" name="txtNumResults" type="text" maxlength="2" style="width: 37px" value="10" />
      <input id="find" type="button" value="Find" name="find" onclick="FindLoc(document.getElementById('txtNumResults').value);"/>
      <div id="results"></div>
   </body>
</html>

Concepts

VEPlace Class
VEFindResult Class
VEShapeLayer Class
Returning Localized Results