Working with locations and finding places and address in the MapPoint object model

To find an address or intersection on the map, use the FindAddressResults method. The FindAddressResults method is similar to using the Address tab of the Find dialog box in the user interface. Note that not all parameters apply to every address. For example, the OtherCity parameter is used in many addresses in Europe but is not used in any addresses in North America.

Note  In the following examples, it is assumed that the first result found is correct. For more information about viewing multiple results, see the "The FindResults collection" section in this topic.

	Sub FindAddresses()
	    Dim oMap As MapPoint.Map
	    Dim oLoc As MapPoint.Location
	    Dim oPin As MapPoint.PushPin
	    Set oMap = GetObject(, "MapPoint.Application").ActiveMap
	    oMap.FindResults("Seattle")(1).GoTo

	    Set oLoc = oMap.FindAddressResults( _
	        "1 Microsoft Way", "Redmond", , "WA")(1)
	    Set oPin = oMap.AddPushpin(oLoc)
	    oPin.BalloonState = geoDisplayBalloon
	    oMap.AddPushpin(oMap.FindAddressResults( _
	        "Bellevue Ave. E. & E. Roy St.", "Seattle", , _
	        "WA")(1)).BalloonState = geoDisplayName
	End Sub

You can also use the FindResults method to find an address by passing the address as a single line:

	Sub FindAddressFromText()
	    Dim oMap As MapPoint.Map
	    Set oMap = GetObject(, "MapPoint.Application").ActiveMap

	    oMap.AddPushpin oMap.FindResults( _
	        "1 Microsoft Way, Redmond, WA, 98052")(1)
	End Sub

For more information about addresses and how to parse them, see the section titled "Working with street addresses" in this topic. For more information about the FindResults method, see "Using the Find methods."

To find a place, use the FindPlaceResults method. This will return the list of places whose names match the search text. You can use this to find cities, points of interest, and other locations. For more information about finding places in general, see Find a place on the map. You can also use the FindResults method to find places.

	Sub FindPlaces()
	    Dim oMap As MapPoint.Map
	    Set oMap = GetObject(, "MapPoint.Application").ActiveMap

	    oMap.AddPushpin oMap.FindPlaceResults("Washington, D.C.")(1)
	    oMap.AddPushpin oMap.FindPlaceResults("Mount Rushmore")(1)
	    oMap.AddPushpin oMap.FindResults("I-5 exit 137")(1)
	    oMap.AddPushpin oMap.FindResults( _
	        "Space Needle, Seattle, WA")(1)
	End Sub

If you know the specific type of place that you are looking for (such as a city or ZIP Code) and it is part of an address, you can use the FindAddressResults method to find places with more accuracy. To use this method, fill in only the relevant information from the address:

	Sub FindPlacesFromFields()
	    Dim oMap As MapPoint.Map
	    Set oMap = GetObject(, "MapPoint.Application").ActiveMap
	
	    oMap.AddPushpin _
       		oMap.FindAddressResults(PostalCode:="98104")(1)
	    oMap.AddPushpin oMap.FindAddressResults(, _
	        "Kansas City", , "MO")(1)
	End Sub

Note that locations found in this way will have a StreetAddress property of Nothing.

The FindPlaceResults method finds a place, such as "Washington State" or "Pioneer Square." The FindAddressResults method is used when you know that you are searching for an address and have separate strings for the different parts of the address. If you do not have separate strings for the different parts of the address but know that it is an address, you can generate the separate strings by calling the ParseStreetAddress method. For more information about addresses, see the section titles "Working with street addresses" in this topic.

The FindResults method is a mixture of both the FindPlaceResults and FindAddressResults methods and is similar to using the Find box on the Navigation toolbar in the user interface. By using it, you can reduce some code, although understanding exactly what it is doing is important.

The FindResults method takes a string and tries to parse it into an address (the same way the ParseStreetAddress method does). If it can parse it, it performs a FindAddressResults method; otherwise, it performs a FindPlaceResults method. Because it first attempts to treat the string as an address, place names that look like street names to MapPoint (such as "Pioneer Square," because "Square" can be a street type as well as a place name) will not be found with the FindResults method, but will be found with the FindPlaceResults method.

All of the Find methods discussed so far do not return a single location, but instead return a collection of possible matches. It has been assumed in all of these cases that the first returned object is the one that you are looking for, but in practice, you will find that, just as in the MapPoint user interface, there are times that the correct object must be disambiguated from the list of objects. For example, if you search for "France," MapPoint understands that you are looking for the country. However, if you search for "Washington," it does not know whether you are looking for Washington, D.C., the capital or Washington State. In cases such as "Washington," you must disambiguate for MapPoint by choosing the result that you want to use.

MapPoint will almost always return more than one location, even for a (so-called) exact match, such as "France." The reason for this is that even though MapPoint interprets that you are looking for the country, you may have typed the name incorrectly and meant "Frances," a river in Canada. How can you decide which result to return? There are several points of understanding that help.

First, MapPoint always returns the results in "best match order." This means that the first item in the list is the one that MapPoint determined was the most likely choice. In the case of "France," the best match order will get you the country and you are done. However, in the case of "Washington," MapPoint really can't tell which is better between the state and the city. In that case, you can use the ResultsQuality property of the FindResults collection.

Remember that the Find methods all return a collection of possible matches. The return value is actually an object called the FindResults collection. You can use the Count and Item properties to access the list of locations returned, but to know the quality of the results, you use the ResultsQuality property. This property returns one of five GeoFindResultsQuality values:

geoFindResultGood  This value indicates that the first result is considered a good result and the other results are probably not good. This is the case when searching for "France," where it is probably safe to return the first item in the collection.

geoAmbiguousResults  In this case, at least the first two results are good, but MapPoint cannot automatically decide what to do. This applies when searching for "Washington," where you must investigate further or possibly show your user a list of choices before you decide which item to return. You may still simply choose the first one, but it is less ambiguous when there is only a single good result.

geoNoGoodResult  This value indicates that although there are results, MapPoint does not consider any to be a good match. If you search for "Franze" (misspelling "France"), you will get this result. In this case, one of the items in the list may or may not be the correct return value (here, "France" will be the second item in the collection). You should allow your user to disambiguate the results; otherwise, choosing any item in this collection could have unintended results.

geoNoResults  This is returned when nothing is found or if you search for an empty or nonsense string, such as "!!;;"

geoAllResultsValid  This is returned when every one of the results is valid for the query. It is not returned for any of the Find methods that you have seen so far but is returned in the case of the FindNearby method, described later in this topic.

If you know that you must disambiguate the objects, you can use several properties of the Location object to choose the correct location. Specifically, if you know the type of location you are looking for (for example, a city, not a state), then the PlaceCategory and Type properties of the Location object can be useful. If you want to enable your user to disambiguate the results, the Name property of the locations returned will be useful. If you are searching for an address, you can also use the StreetAddress property to get more information about the location.

FindResults may also return Pushpin objects (as described in Working with Pushpins in the MapPoint object model ), so you may need to get the type of object that is returned. (The Microsoft Visual Basic TypeName function will return either "Pushpin" or "Location"). If you want to always use the location type, even in the case where the return value may be a Pushpin, you can use the Location property of the result. Pushpin objects have a Location property that returns the Location objects associated with them, and Location objects have a Location property that simply returns itself, as shown in the following code example.

	Sub EnsureLocation()
	    Dim oMap As MapPoint.Map
	    Set oMap = GetObject(, "MapPoint.Application").ActiveMap
	
	    oMap.AddPushpin oMap.Location, "Seattle"
	    ' Use the Location object of whatever was found
	    oMap.AddPushpin oMap.FindResults("Seattle")(1).Location
	End Sub

The FindNearby method enables you to find points of interest near a Location object or near a route section (Direction object or Directions collection). For a route segment, places are found along the portion of the route represented by that segment.

The FindNearby method returns all points of interest or Pushpins that are within a specified distance from the location or route segment. They are returned in distance order, with the closest listed first. All returned objects are valid, so the ResultsQuality property will be either geoAllResultsValid or geoNoResults. The points of interest are also filtered by the PlaceCategories collection (which is the equivalent to selections made in the Show Or Hide Places dialog box in the user interface).

The following example hides all categories except museums and displays the name of the closest museum within walking distance of an attraction (if any).

	Sub NearbyMuseums()
	    Dim oMap As MapPoint.Map
	    Set oMap = GetObject(, "MapPoint.Application").ActiveMap
	
	    Dim oLoc As MapPoint.Location
	    Dim oFound As MapPoint.FindResults
	    ' Hide all
	    oMap.PlaceCategories.Visible = geoFalse
	    oMap.PlaceCategories("Museums").Visible = True
	    Set oLoc = oMap.FindResults("Space Needle, Seattle, WA")(1)
	    ' Find all museums within half a mile
	    Set oFound = oLoc.FindNearby(0.5)
	    If oFound.Count > 0 Then MsgBox oFound(1).Name
	End Sub

Note  The FindNearby method will also return any Pushpins that are within the specified search radius. In the previous example, to ensure that only museums are returned, you must check the Type property of the returned object. For more information, see the section titled "The FindResults collection" in this topic.