Notice that this list includes all kinds of entities, such as city halls, parks, libraries, and schools in the result list. Imagine for now that you need only a list of cities named after Redmond—you need to tell MapPoint Web Service that you are only looking for city entity matches to your query. You can do this using the FindSpecification.EntityTypeNames field. The EntityTypeNames field is an array of strings that represents the entity type names that the Find method needs to look for. Since you are only interested in cities named Redmond, pass the entity type name PopulatedPlace :
//Assign entities to search fndspec.EntityTypeNames = new string[] {"PopulatedPlace"};
A call to the Find method with this addition returns the following nine cities named Redmond:
Redmond, Washington, United States Redmond, Oregon, United States Redmond, Western Australia, Australia Redmond, Larimer, Colorado, United States Redmond, Butler, Pennsylvania, United States Redmond, Sevier, Utah, United States Redmond, Mason, West Virginia, United States Redmond Corner, Oneida, New York, United States Redmondville, Iron, Missouri, United States
Even though your threshold score is 0 and there are 500 returned results requested, by assigning specific entity type, the find is narrowed down to 9 results from the original 32 results.
Limiting search to a geographic area
Notice that the above list contains cities from both the United States and Australia. If you are looking only for cities in the United States and need to instruct MapPoint Web Service to limit the search within a geographic boundary, using the FindOptions.SearchContext field you can limit the search to a particular geographic area. The SearchContext field is an integer value that represents the entity ID of a spe cific geographic area. Since you are specifically looking for cities named Redmond in the United States, the context ID should be set to the United States country entity ID 244 . The following code shows the addition of search context to the find request:
//Assign country context for United State s findspec.Options.SearchContext = 244;
With this addition, the search now only returns the following 8 results:
Redmond, Washington, United States Redmond, Oregon, United States Redmond, Larimer, Colorado, United States Redmond, Butler, Pennsylvania, United States Redmond, Sevier, Utah, United States Redmond, Mason, West Virginia, United States Redmond Corner, Oneida, New York, United States Redmondville, Iron, Missouri, United States
The list now includes only cities in the United States.
Finding geographic entities with no input place name
The Find method is very powerful because it allows you to find geographic entities without actually specifying a place name. Example queries include: “Find all states in the United States” and “Find all airports in Australia.” You can perform these queries based on entity type names, geographic contexts, or by assigning the input place name a null value. The following code shows how to get all state names in the United States:
//Create find service soa p FindServiceSoap findsoap = new FindServiceSoap(); //Assign credentials . . .
//Create FindSpecification FindSpecification findspec = new FindSpecification(); //Assign data source findspec.DataSourceName = "MapPoint.NA";
//Assign null to input place findspec.InputPlace = null;
//Create find options findspec.Options = new FindOptions(); //Set result count findspec.Options.Range = new FindRange(); //Set to the maximum count findspec.Options.Range.Count = 500;
//Set threshold score to zero findspec.Options.ThresholdScore = 0;
//Assign state entity type to search fndspec.EntityTypeNames = new string[] {"AdminDivision1"};
This search results in 51 entities (50 states and Washington D.C.).
To explore more on data sources, entity types, and entity based finds, I have included an application, MapPoint Web Service Data Source Browser, on the com panion material as part of the Chapter06 sample solution. Figure 6-2 shows a screen-shot of the application with results for the query “Find all airports in Australia.”
Finally, it is important remember that, due to performance reasons, for any find query, the maximum number of results returned ( FindResult objects) is 500; you cannot issue a find query such as “Find all cities in the world,” but if you do have such a requirement, I recommend breaking down the query to get a manageable result set that is less than or equal to 500 each time. An example of such implementation would be to provide a browse functionality where your customers can select a country first, a state second, a county third, and then find all cities within that county without hitting any maximum result count issues, since you are confining your query to a smaller, limited geographic area.
While the FindServiceSoap.Find method works well for finding places and geographic entities in general, it doesn’t offer any help to find addresses; use the FindServiceSoap.FindAddress method for that purpose.
Like any FindServiceSoap.Find method, the FindServiceSoap.FindAddress method takes a specification object of type FindAddressSpecification and inputs a data
Figure 6-2. MapPoint Web Service data source browser
source name field of type String and an Options field of type FindOptions as input fields to expose an InputAddress field of type Address . Table 6-3 shows the fields exposed on the FindAddressSpecification object.
Table 6-3. Fields exposed in the FindAddressSpecification class
Field
Description
DataSourceName
A string representing the name of the data source in which to search for the address. Example: MapPoint.NA .
InputAddress
The input address to be found. This field is of type Address class.
Options
The search options ( FindOptions object), which include the range of results, the threshold score of results returned, and a flag to identify which objects are desired in the returned results.
To use a data source to find addresses, it must have the CanFindAddress capability. An address in MapPoint Web Service is always represented as a valid instance of the Address object; the Address class provides fields such as AddressLine , PrimaryCity , SecondaryCity , Subdivision , PostalCode , and CountryRegion to represent a valid address for all countries/regions. When used as input, the address line information of an address is optional. When an address is returned as an output, the address object also provides a formatted address string via the FormattedAddress field.
Say you want to find the following address:
1 Microsoft Wa y Redmond, WA 98052 US
First, you need to create an Address object:
//Create an address object //And assign address values Address address = new Address(); address.AddressLine = "1 Microsoft Way"; address.PrimaryCity = "Redmond"; address.Subdivision = "WA"; address.PostalCode = "98052"; address.CountryRegion = "US";
Once the Address object is ready, you can find the address information (such as latitude/longitude, best map view information, etc.) using the FindServiceSoap.FindAddress method:
//Create a find address specification object FindAddressSpecification findAddressSpec = new FindAddressSpecification(); //Assign input address findAddressSpec.InputAddress = address; findAddressSpec.DataSourceName = "MapPoint.NA";
//Call the find address method FindResults foundAddressResults = findService.FindAddress(findAddressSpec);
//Process found results if (foundAddressResults.NumberFound > 0) { if(foundAddressResults.Results[0].FoundLocation.LatLong != null) { //Process latitude/longitude information . . . } }
The previous code snippet assumes that you have the FindService object available with proper credentials assigned.
The FindAddressSpecification also exposes the Options field so that you can control the behavior of the locations returned by this method using the FindOptions class; the FindOptions behavior that we have looked at in the Find method still holds true for this method except that you can only get a maximum of 100 results instead of 500.
To find points of interest around a given location, use the FindServiceSoap.FindNearby method. The FindNearby method works only with data sources that have the CanFindNearby capability. As a general rule of thumb, only the point of interest data sources supplied by data vendors such as NavTeq and Acxiom have this capabil ity; data sources such as MapPoint.NA and MapPoint.EU do not support the FindNearby method.
Like any other find service method, the FindNearby method also takes a specification of type FindNearbySpecification class. The FindNearbySpecification object takes information such as the data source name, input location around which you want to find points of interest (as a latitude/longitude), distance to be covered around the original location to find points of interest, and entity types you want to find. Table 6-4 gives an idea of the fields presented in the FindNearbySpecification object.
Table 6-4. Fields in a FindNearbySpecification object
Field
Description
DataSourceName
Data source name as a string.
Distance
The distance from the LatLong property.
Filter
The filter ( FindFilter object) to apply to the results. In other words, it is the specific entity type, properties, and values that the returned results must match.
LatLong
The latitude and longitude coordinate ( LatLong object) of the point around which the search is made.
Options
The search options ( FindOptions object), which include the range of results and a flag to identify which objects are desired in the returned results.
To find all ATMs around the address 1 Microsoft Way, Redmond, WA, get the latitude and longitude information using the FindServiceSoap.FindAddress method, and call FindServiceSoap.FindNearby with one of the point of interest data sources (in this case, I chose to use NavTech.NA ) and the entity type name for ATM, SIC3578 :
//Create find service soap instanc e FindServiceSoap findService = new FindServiceSoap(); //Assign credentials . . .
//Define findnearby specification FindNearbySpecification findNearbySpec = new FindNearbySpecification(); //Assign a data source findNearbySpec.DataSourceName = "NavTech.NA"; //Since you are looking for ATMs, assign ATMs entity type findNearbySpec.Filter = new FindFilter(); //Assign entity type for ATMs findNearbySpec.Filter.EntityTypeName = "SIC3578"; //Set the distance in miles findNearbySpec.Distance = 1; //Assign the location around which you want to find ATMs findNearbySpec.LatLong = new LatLong(); findNearbySpec.LatLong.Latitude = 47.6; findNearbySpec.LatLong.Longitude = -122.33;
//Call findnearby method FindResults foundResults; foundResults = findService.FindNearby(findNearbySpec); //Process the results foreach(FindResult fr in foundResults.Results) { . . . }
The previous code finds ATMs around the specified address within one mile using the NavTech.NA data source; of course you could have also used other points of inter est data sources from Acxiom .
Next, say that you are working for a banking company and building an ATM locator application; obviously you would display your company’s ATMs around any specified address. It is possible to display your ATMs with the FindNearby method, but since none of the MapPoint data sources or vendor data sources (NavTech, Acxiom, and so on) know about your bank’s ATMs specifically, you need to provide a data source for MapPoint Web Service to use with the FindNearby method. That’s when the customer data sources come into the picture.
If you do not want to upload your data to MapPoint servers due to security reasons, you can implement your own FindNearby functionality using SQL Server—see Appendix C for more details.
Customer data sources—displaying your data
When you sign up for MapPoint Web Service, you are assigned space on MapPoint servers to upload your business data (such as points of interest and icons) to use with the FindNearby method. Using this space, you can create a maximum of 25 data sources on the MapPoint Web Service servers. For example, if your company has banks and ATMs, you would create two data sources with one assigned to each entity type. So, with multiple data sources, you can use different data source files for different types of data. Having said that, there are certain requirements for creating your own data sources:
The combined size of all your data sources cannot exceed 2 gigabytes.
Each data file that you upload (that contains a number of location records) cannot exceed 100 megabytes.
Each data source and the entities it contains must have an entity type, which is a user-defined alphanumeric string, and an entity id, which is an integer.
The total number of searchable non-Boolean cells (or entity properties) per data source cannot exceed 8.75 million.
Every entity (or location record) has three required properties (EntityID, latitude, and longitude) and six additional properties created by the MapPoint Geocoder sevice, including MatchCode, MatchedAddress, MatchedMethod, EditedLocationUTC, EditedPropertyUTC, and InputModified. All of these properties are treated as searchable non-Boolean cells, so the number of entities contained in a single data source cannot exceed 972,222 (8.75 million cells divided by 9 non-Boolean, searchable properties per row). The number of Boolean cells per entity in a data source cannot exceed 200.
There are additional requirements applicable for entity property types in MapPoint Web Service, such as number of characters per field and type of characters per field.
For more information on the customer data formatting requirements, see the “Requirements for Custom Location Data” section from the MapPoint Web Service Customer Services site help documentation.
There are two options for uploading and downloading your entities to and from the customer services site: you can either use the Customer Services site web UI, or programmatically upload and download using the Customer Data Service Web Service, which is discussed in detail in Appendix A. Once you upload your custom data, you can use the FindServiceSoap.FindNearby method to use it against your own data.
To find points of interest along a given route, use the FindServiceSoap.FindNearRoute method. The FindNearRoute method works only with data sources that have the CanFindNearby capability. As with the FindNearby method, only the point of interest data sources supplied by data vendors such as NavTeq and Acxiom have this capability; data sources such as MapPoint.NA and MapPoint.EU do not support the FindNearRoute method.
You can read more about calculating routes using RouteServiceSoap in Chapter 7.
Like any other find service method, the FindNearRoute method also takes a specification of type FindNearRouteSpecification class. The FindNearRouteSpecification object takes information, such as the data source name, input route (as a Route object) around which you want to find points of interest, and distance to be covered along the route, and uses it to find points of interest and entity types you want to find. Table 6-5 gives an idea of the fields presented in the FindNearRouteSpecification object.
Table 6-5. Fields in a FindNearRouteSpecification object
Field
Description
DataSourceName
The data source name as a string
Distance
The distance from the Route property
Filter
The filter ( FindFilter object) to apply to the results; that is, the specific entity type, properties, and values that the returned results must match
Route
The route from which the points of interest are searched
Options
The search options ( FindOptions object), which include the range of results and a flag to identify which objects are desired in the returned results
Say you want to find all the coffee shops along the route that you are planning for a road trip. First, calculate your route using the RouteServiceSoap class; next, call the FindServiceSoap.FindNearRoute with one of the point of interest data sources (I chose to use MapPoint.FourthCoffeeSample ) and the entity type name for coffee shops, FourthCoffeeShops , as follows:
FindServiceSoap findService = new FindServiceSoap(); findService.Credentials = new System.Net.NetworkCredential(myMapPointUserId, mySecurePassword);
RouteServiceSoap routeService = new RouteServiceSoap(); routeService.Credentials = new System.Net.NetworkCredential(myMapPointUserId, mySecurePassword);
//Route between two locations LatLong[] latLongs = new LatLong[2]; latLongs[0] = new LatLong(); latLongs[1] = new LatLong(); latLongs[0].Latitude = 52.5; latLongs[0].Longitude = 13.1; latLongs[1].Latitude = 52.51; latLongs[1].Longitude = 13.11;
This code finds the coffee shops around the specified route within 20 miles from the beginning of the route using the MapPoint.FourthCoffeeSample data source; you could use different point of interest data sources from Acxiom or NavTech or even your own data source.
Finally, note that the distance must always be greater than 0.1 miles (0.160934 kilo meters) and less than 25 miles (40.2336 kilometers).
Please check back next week for the continuation of this article.
BrainDump 
Parsing Addresses and More with the MapPoint Web Service Find APIs
