Show All

Article
09/10/2006

Show All

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

The Location object refers to a place on the map. A Location object can refer to a point (such as an address, a point of interest, a latitude/longitude coordinate), or an area (such as a country, state, post code, or province). Location objects are used throughout the object model, for example, to create waypoints on a route, to place Pushpins, to draw Microsoft MapPoint shapes, or to zoom and pan.

Location objects have properties that help you determine what the Location object represents. Use the Name, Type, StreetAddress, PlaceCategory, Latitude, and Longitude properties to get more information about a Location object.

Locations are used for a multitude of tasks in MapPoint, many covered in this topic. They are also used for creating Pushpins, shapes, and stops on a route (waypoints).

Finding a latitude and longitude coordinate

The simplest type of location that you can get is one that represents a latitude and longitude coordinate on the map. To get the Location object for a specific latitude, longitude, and, optionally, altitude, use the GetLocation method on the Map object.

Note Latitude is measured with north positive and runs from +90° to -90°, and longitude is measured with east positive and runs from +180° to –180°. For more information, see About latitude and longitude.

In the MapPoint object model, latitude and longitude are represented in decimal format. Altitude is measured in GeoUnits. If not specified, the altitude defaults to the current map altitude, which is how far the map is zoomed in or out. You can see the altitude in the user interface on the Zoom Slider on the Navigation toolbar, as you move the slider to change the zoom.

The following example gets the location that represents a specific latitude and longitude and then zooms to it:

  Sub ShowHelenaMontana()
    Dim oMap As MapPoint.Map
    Dim oLoc As MapPoint.Location
    Set oMap = GetObject(, "MapPoint.Application").ActiveMap
    oMap.Application.Units = geoMiles

    Set oLoc = oMap.GetLocation(46.59, -112.03, 100)
    oLoc.GoTo
End Sub

MapPoint zooms to that location and sets the current altitude to 100 miles. (The unit of measurement can be either miles or kilometers, based on the Units property of the Application object).

Using the Find methods and FindResults collection

MapPoint has several methods for finding places and addresses on the map. Each of these methods returns a list of the locations that were found. The return from all of these methods is a FindResults collection, which is a collection of Location or Pushpin objects that match your search criteria (the place name or address, for example).

Finding addresses

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."

Finding places

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.

Using the Find methods

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.

The FindResults collection

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

Finding nearby places

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.

Working with street addresses

Locations returned by the FindResults, FindAddressResults, and FindNearby methods may have a StreetAddress property. When an address is not associated with a location, the StreetAddress property will return Nothing.

By using the StreetAddress object, you can access the individual parts that make up an address. These are the Street, City, OtherCity, Region, PostalCode, and Country properties.

You can also obtain a StreetAddress object from text by calling the ParseStreetAddress method. The ParseStreetAddress method splits an address in the same way as the Find box on the Navigation toolbar. It does not determine that the address is valid, only that it would be split into an address if typed into the Find box. To find the address, use the FindResults or FindAddressResults method. Use the ParseSteetAddress method as a fast way to extract information when you know you have a valid address.

  Sub ShowPostalCode()
    Dim oMap As MapPoint.Map
    Set oMap = GetObject(, "MapPoint.Application").ActiveMap
	
    MsgBox oMap.ParseStreetAddress( _
        "1 Microsoft Way, Redmond, WA, 98052").PostalCode
End Sub

Working with screen coordinates

Location objects can be defined using screen coordinates. Not all coordinates have Location objects associated with them. If you zoom all the way out, screen locations can be in outer space.

The XYToLocation method turns a screen coordinate into a Location object. It returns nothing if the location is off the screen or in outer space.

The LocationToX and LocationToY methods will return the screen coordinates of a Location object or -1 if the location is off the screen.

The following code moves the map to the location where the user clicks:

  Dim WithEvents oMap As MapPoint.Map

Private Sub Form_Load()
    Set oMap = GetObject(, "MapPoint.Application").ActiveMap
End Sub

Private Sub oMap_BeforeClick(ByVal Button As Long, _
        ByVal Shift As Long, ByVal X As Long, _
        ByVal Y As Long, Cancel As Boolean)
    Dim oResults As MapPoint.FindResults
	
    Cancel = True ' Do not perform the usual action on click
    Dim oLoc As MapPoint.Location
    Set oLoc = oMap.XYToLocation(X, Y)
    If Not (oLoc Is Nothing) Then oLoc.GoTo
End Sub

The ObjectsFromPoint method returns all locations at a screen coordinate, which makes it possible to determine what a user is clicking. This is often called hit-detecting. There can be a number of locations (for example, both a city and a province) at a particular screen location, and the list of locations will change for the same globe position based on the map altitude. If the screen coordinate is in outer space, the FindResults collection will be empty.

The ObjectsFromPoint method creates a FindResults collection that can include both Location and Pushpin objects. The ResultsQuality property of the resulting FindResults collection will return either geoAllResultsValid or geoNoResults.

The following code example displays the names of all objects where the user double-clicked.

  Dim WithEvents oMap As MapPoint.Map

Private Sub Form_Load()
    Set oMap = GetObject(, "MapPoint.Application").ActiveMap
End Sub

Private Sub oMap_BeforeDblClick(ByVal Button As Long, _
        ByVal Shift As Long, ByVal X As Long, _
        ByVal Y As Long, Cancel As Boolean)
    Cancel = True 'Do not perform the usual action on dbl-click

    Dim oResults As MapPoint.FindResults
    Dim oResult As Object
    Set oResults = oMap.ObjectsFromPoint(X, Y)
    For Each oResult In oResults
        MsgBox oResult.Name
    Next
End Sub

Map views and the GoTo method

A map view location is used to ensure that an area is displayed on the screen or that a number of locations are displayed on the map at the same time. For example, the Location object returned by finding a country defines a map view and a point on the globe. The map view is called the "best map view" of that entity. It is a view that displays as much of the entity as possible (some entities or groups of entities may not all fit on the screen at the same time). To zoom to the map view of the country, call the GoTo method on that Location object.

Map views are returned by route segments (Direction object or Directions collection) as the Location property of that section. To zoom to a route segment, call the GoTo method on the segment's location.

Note that a Location object's position and its GoTo result can be different, as shown in the following code example.

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

    Dim locFlorida As MapPoint.Location
    Set locFlorida = oMap.FindAddressResults(, , , "Florida", , "USA")(1)
    locFlorida.GoTo
    oMap.AddPushpin(locFlorida).BalloonState = geoDisplayBalloon
End Sub

When you run this code, the entire state of Florida is visible on the screen and "Florida" appears in the Location and Scale toolbar (if visible). The screen is centered on a point in the Gulf of Mexico. This map view is the "best map view" of the area. However, the Pushpin was placed at a point on the land mass. This point is called the "representative point" or "centroid" and it is where, for example, data map icons are displayed and from which distances are calculated.

To create a map view that shows multiple locations, use the Union method. The following code example creates a map view that ensures that both New York City and Paris are on the screen at the same time.

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

    Dim locNewYork, locParis As MapPoint.Location
    Set locNewYork = oMap.FindResults("New York City")(1)
    Set locParis = oMap.FindResults("Paris, France")(1)

    oMap.Union(Array(locParis, locNewYork)).GoTo
    ' Zoom out just a little
    oMap.Altitude = oMap.Altitude * 1.2
End Sub

It is possible to ensure that the resulting view always contains all the desired points by displaying a flat map. In the object model, set the Projection property to geoFlatAtHighAltitudesProjection.

Measuring distances

In MapPoint, distances are measured in GeoUnits. Set GeoUnits to miles or kilometers by using the Units property. The following code example sets the Units property to kilometers.

  Sub MetricUnits()
    Dim oApp As MapPoint.Application
    Set oApp = GetObject(, "MapPoint.Application")
	
    oApp.Units = geoKm
End Sub

The simplest way to find the distance between two locations is to use the DistanceTo method. This is the same as the Distance method, but is slightly more convenient. Note that the distance returned is the distance along the great circle through the locations. See About using shapes in MapPoint for an explanation of the great circle.

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

    Dim locParis, locNewYork As MapPoint.Location
    Set locParis = oMap.FindResults("Paris, France")(1)
    Set locNewYork = oMap.FindResults("New York City")(1)

    MsgBox locNewYork.DistanceTo(locParis)
End Sub

You can also find the shortest distance between a Location and a route segment (Direction object or Directions collection) by using the DistanceTo method on the segment.

Highlighting

You can highlight locations on the map, just as you would by clicking Highlight on the shortcut menu for a selected point on the map. Not all locations, however, can be highlighted. You can highlight places, but you cannot highlight addresses and latitude and longitude coordinates (returned from the GetLocation method). Check the IsHighlightable property before setting the Highlight property.

  Sub LocationHighlight()
    Dim oMap As MapPoint.Map
    Set oMap = GetObject(, "MapPoint.Application").ActiveMap
	
    Dim oLoc As Location
    Set oLoc = oMap.FindResults("Space Needle, Seattle, WA")(1)
    oLoc.GoTo
    If oLoc.IsHighlightable Then oLoc.Highlight = True
End Sub

Location types

There are two ways to determine the type of location: the Type property, which tells you the type of geography of the location (for example, state or country), and the PlaceCategory property. The PlaceCategory property returns information for a location that falls into one of the categories in the Show or Hide Places dialog box, such as museum or theater.