Section 6.3. Data Sources and CountriesRegions

6.3. Data Sources and Countries/Regions

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 nameyou can use the CommonServiceSoap class for this purpose as well.

6.3.1. 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 CountryRegionInfo object, which exposes several properties, such as EntityID, FriendlyName, Iso2, Iso3, and OfficialName. 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 the CountryRegionInfo class 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 the CommonServiceSoap.GetCountryRegionInfo method:

     //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)     {       . . .     }

The GetCountryRegionInfo method takes an array of entity IDs as integers; however, in the previous code example, I'm passing null in 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 one CountryRegionInfo object (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 a Hashtable with the entity ID as the key) in your applications to avoid round trips to the MapPoint Web Service.

6.3.2. Querying for Geographic Extent for a Data Source

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 the EntityExtent field of the DataSource object. The DataSource.EntityExtent field 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 source MapPoint.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.

6.3.3. 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 DataSourceCapability enumeration discussed in Chapter 5. Once you have the DataSourceCapability figured 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. The countryRegionsTable is a Hashtable containing cached country/region information indexed on the entity IDs. The algorithm used 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.