Just as each data source in MapPoint Web Service supports different entity types, there is country/region level mapping to each MapPoint data source. The geographic extent (or the geographic coverage) of each data source is predefined by MapPoint Web Service. For example, the data source MapPoint.NA has a geographic extent of the United States, Canada, Mexico, and Puerto Rico. In the same way, other data sources have different supported country listings. You don’t need to remember which data source needs to be used for each country name—you can use the CommonServiceSoap class for this purpose as well.
Countries/Regions and Their Entity IDs
Before we get into the details of how to query data source geographic extents and how to map a country to a supported data source programmatically, you need to understand how the countries/regions are managed in MapPoint Web Service Data sources. Each country/region is given an entity ID, which is a unique integer number. Each country/region also holds an ISO2- and ISO3-compatible code associated with that country. All of this information is represented as the CountryRegionInfoobject, which exposes several properties, such asEntityID,FriendlyName,Iso2,Iso3, andOfficialName. If you take the United States, for example, the country region information is organized as follows:
Entity ID 244 FriendlyName United States Iso2 US Iso3 USA OfficialName United States of America
An instance of theCountryRegionInfoclass that represents a valid country/region also includes the centroid latitude/longitude of the country. The entity ID for the United States is 244, and it does not change across different versions of the MapPoint Web Service, so you can safely hardcode this ID into your applications for any United States–specific find queries.
To get the country/region information using MapPoint Web Service, use theCommonServiceSoap.GetCountryRegionInfomethod:
//Create Common Service SOAP Class instance CommonServiceSoap commonsoap = new CommonServiceSoap(); //Assign credentials . . .
//Get country region info CountryRegionInfo[] countryregioninfos = commonsoap.GetCountryRegionInfo(null);
//Do some processing foreach(CountryRegionInfo crinfo in countryregioninfos) { . . . }
TheGetCountryRegionInfomethod takes an array of entity IDs as integers; however, in the previous code example, I’m passingnullin order to get country/region information for all the countries listed in MapPoint Web Service. Similarly, if you want only country/region information for the United States, your call would look like this with 244 entity ID as an input argument:
//Get country region info CountryRegionInfo[] countryregioninfos = commonsoap.GetCountryRegionInfo(new int[] {244});
You get only oneCountryRegionInfoobject (that corresponds to the United States) back from this method.
Note that since the list of county/region information does not change that frequently, it is good idea to store it in an in-memory data structure (such as aHashtablewith the entity ID as the key) in your applications to avoid round trips to the MapPoint Web Service.
Now that you know how the country/region information is organized in MapPoint Web Service, let’s look at how to get a list of countries supported by different data sources.
The geographic extent of the countries supported by a particular data source is defined using theEntityExtentfield of theDataSourceobject. TheDataSource.EntityExtentfield is an array of integers that represent the corresponding country entity IDs. The following code snippet shows how to get the geographic extent of the data sourceMapPoint.NA:
//Create Common Service SOAP Class instance CommonServiceSoap commonsoap = new CommonServiceSoap(); //Assign credentials . . .
//Get Data Source Info for MapPoint.NA DataSource[] datasources = commonsoap.GetDataSourceInfo(new string[] {"MapPoint.NA"}); //Get entity extent int[] extents = datasources[0].EntityExtent;
The geographic extent is expressed using the country/region entity IDs discussed in the previous section. To get the name of the country that each entity ID corresponds to, call the CommonServiceSoap.GetCountryRegionInfo method.
Programmatically Mapping a Country/Region to a Data Source
So far, I have shown how to get supported countries given a MapPoint Web Service data source. A common application scenario would be the other way around: choosing an appropriate data source for a given country. To programmatically map a country/region to a data source, you need to identify the task for which you need the data source, deciding whether you want a data source to find a place, find an address, calculate a route, or render a map. You can use the DataSourceCapabilityenumeration discussed in Chapter 5. Once you have theDataSourceCapabilityfigured out, you can get an appropriate MapPoint Web Service data source name using the following code:
private string[] GetDataSources(string countryRegionName, DataSourceCapability capability) { if(countryRegionName == null || countryRegionName.Length <= 0) throw new Exception( "Invalid country/region name; country/region name cannot be null or empty.");
ArrayList datasourceList = new ArrayList();
//Now loop through the list of data sources and //see what data source fits the purpose foreach(DataSource datasource in datasources) { if(((int)datasource.Capability & (int)capability) != 0) { //OK, this data source has the capability, but does it support the //entity extent (the country that we need a data source for?) int[] entityextent = datasource.EntityExtent; //Now loop through each entity extent and compare the input name foreach(int entityid in entityextent) { //Now look up using the entity id to see if the input //country/region name matches any entity extent //in this case I'm country region information //cached in a Hastable if(this.countryRegionsTable[entityid] as string == countryRegionName.Trim()) { //Found a match for both requirements //Return the name datasourceList.Add(datasource.Name); break; } } } } if(datasourceList.Count <= 0) throw new Exception( "No data source found to match your needs for this country.");
//Return a sorted list datasourceList.Sort();
return datasourceList.ToArray(typeof(String)) as string[]; }
The previous function returns an array of suitable MapPoint Web Service data source names. ThecountryRegionsTableis aHashtable containing cached country/region information indexed on the entity IDs. Thealgorithmused in this function is pretty simple: first, find a data source with matching capability, and then get the geographic extent for that data source and see whether there is a match with the input country/region name. You can also find the code for this function, along with other functionalities discussed in this section, in the Chapter 6 solutions on the companion material.
With this introduction to find methods, entity types, and data source relationships, let’s look at how to perform various spatial queries using Find Service.
MapPoint Web Service Find Service is programmatically exposed as part of the FindServiceSoap class, which has many find methods including Find, FindAddress, FindNearby, andFindById. Choose an appropriate find method based on your application’s requirements. In this section, let’s look in detail at each find method offered by the MapPoint Web Service Find Service.
Finding Places
To find geographic entities and places by their names, use the FindServiceSoap.Find method. This method takes the FindSpecificationas an input argument and returns theFindResultsobject as a return value. TheFindSpecificationwraps several values, including the input place name as a string, the data source to be used for searching the place, and an array of entity type names to find. Table 6-2 shows the fields of theFindSpecificationclass.
Table 6-2. Fields of the FindSpecification class
Field
Description
DataSourceName
A string representing the name of the data source in which to search for a place. For example, MapPoint.NA is the data source used for finding places in North America.
EntityTypeNames
An array of strings representing the names of the entity types to find.
InputPlace
The place name to find.
Options
The search options (FindOptionsobject), which includes the range of results, the threshold score of results returned, the search context, and a flag to identify which objects are desired in the returned results.
The data source used for theFindmethod must have theCanFindPlacescapability. TheFindResultsreturn value indicates the number of matches for the input place query using theFindResults.NumberFoundfield; when no results match your query, theNumberFoundfield is set to zero. All matches are exposed via the FindResults.Resultsfield as a collection ofFindResultobjects; eachFindResultobject returned as a match contains aLocationobject that wraps the location information and a score indicating the level of confidence in the match. A validLocationobject provides one or all of the following: address information, entity information, latitude/longitude information, and best map view information.
Next, let’s look at theFindmethod details: the following code shows how the Find API can be used to find all places named Redmond:
//Create find service soap FindServiceSoap findsoap = new FindServiceSoap(); //Assign credentials . . .
//Create FindSpecification FindSpecification findspec = new FindSpecification(); //Assign data source findspec.DataSourceName = "MapPoint.NA";
//Assign input place to search findspec.InputPlace = "Redmond";
//Assign found count foreach(FindResult findresult in findresults.Results) { //Display results . . . }
With options set at their defaults, this query returns the following seven places 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
These results include places from both the United States and Australia. By default, the find threshold score is set to 0.85, which means that any find match with a confidence score of less than 0.85 is not returned. So, to get more results for this query, you can simply decrease the threshold score using the FindOptions.ThresholdScore field:
//Create find options findspec.Options = new FindOptions();
//Set threshold score to zero findspec.Options.ThresholdScore = 0;
With the threshold score set to zero, the same query for Redmond yields 32 results of which only the following first 25 are returned:
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 Fall City Road Park (park), Washington, United States Redmond Park (park), Cedar Rapids, Iowa, United States Redmond Park (city park), Yonkers, New York, United States Redmond Branch Library (library), Redmond, Oregon, United States Redmond Chamber of Commerce (tourist information office), Redmond, Oregon, United States Redmond Chamber of Commerce (tourist information office), Redmond, Washington, United States Redmond City Hall (city hall), Redmond, Oregon, United States Redmond City Hall (city hall), Redmond, Washington, United States Redmond Community Cemetery (cemetery), Redmond, Washington, United States Redmond Corner, Oneida, New York, United States Redmond Cut (pass), California, United States Redmond District Court (courthouse), Redmond, Washington, United States Redmond Elementary School (school), Redmond, Washington, United States Redmond High School (school), Redmond, Washington, United States Redmond Junior High School (school), Redmond, Washington, United States Redmond Memorial Cemetery (cemetery), Redmond, Oregon, United States Redmond Municipal Court (courthouse), Redmond, Oregon, United States Redmond Municipal Court (courthouse), Redmond, Washington, United States
Returning more find results
By default, MapPoint Web Service always returns only 25 results at once, but you can get a maximum of 500 results using the FindOptions.Range field:
//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;
After adding this code to the Find code, you get all 32 results returned by theFindmethod.
Please check back next week for the continuation of this article.
BrainDump 
MapPoint Web Service Find APIs
