VEMap.Find Method

You are not viewing the latest version of the AJAX control. Bing Maps AJAX V7 is the recommended JavaScript control for Bing Maps. If you need this documentation, it is available in as a CHM or PDF download.

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 array of VEFindResult Class objects is still present, but no pushpin layer is created.

  • Each VEFindResult object's corresponding Shape property is null.

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 null 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 null. 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 null. Otherwise, each VEFindResult object contains a reference to a corresponding VEShape Class pushpin.

  • If a what parameter is specified, but the where parameter is null, 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 null. 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

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://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="https://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.3"></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>

See Also

Concepts

VEPlace Class
VEFindResult Class
VEShapeLayer Class
Returning Localized Results