Section 5.4. Understanding MapPoint Web Service Object Model

5.4. Understanding MapPoint Web Service Object Model

MapPoint Web Service consists of four core services (or engines) that work with an array of map data sources. The core services depend on the data sources for location-oriented tasks, such as finding a place, finding an address, and so on. The data sources provide the necessary data to perform location-based tasks. In MapPoint Web Service, the data sources are organized based on geographic coverage; for example, the data source that contains the map data for all North American regions is MapPoint.NA. Figure 5-7 summarizes this discussion pictorially.

Along with the predefined MapPoint data sources, you can also add your business-specific data as custom data source. With this introduction, let's look at services and data sources in detail. If you recall from our earlier discussion, MapPoint Web Service consists of four integral service components, including:

Common service
Find service

Figure 5-7. MapPoint Web Service core services
Render service
Route service

Let's look at each service in detail to understand more.

5.4.1. Common Service

The common service contains classes, methods, and properties that are common to the other three services (find, route, and render) or are basic utility functions, such as getting the version of the MapPoint Web Service, obtaining data source information, and calculating great circle distance.

This service is programmatically represented by the CommonServiceSoap class.

5.4.2. Find Service

The find service offers core find functionality, such as finding places, addresses, nearby points of interests, latitude/longitude coordinates, and geographic entities (such as parks, airports, and so on).

Some of the find methods only work with MapPoint Web Service data, and a few methods in the find service are designed to work only with your business-specific data (I will discuss this more later).

This service is programmatically represented by the FindServiceSoap class.

5.4.3. Render Service

The render service allows you to render maps of found places or addresses and routes, using your custom business data as pushpins. You can also use it to customize the map visualization, size, label font size, and so on.

This service is programmatically represented by the RenderServiceSoap class.

5.4.4. Route Service

The route service offers methods to calculate driving directions, routes, and route map views. Using this service, you can calculate the driving directions among any given waypoints.

This service is programmatically represented by the RouteServiceSoap class.

I will discuss these core services in detail in Chapters 6, 7, and 8, but for now let's look at another important concept in programming with MapPoint Web Service: data sources .

5.4.5. MapPoint Web Service Data Sources

Data sources are the essential building blocks on which the MapPoint Web Service functionality largely depends. At a macro level, data sources are simply stores that contain map data, geographic entity information, and point of interest information; this data is made accessible to the MapPoint Web Service via several APIs.

Data sources in MapPoint Web Service can be broadly categorized into two categories: MapPoint data sources and customer data sources. MapPoint data sources are compiled (created), hosted, and maintained by Microsoft; an example would be the geographic coverage map data source for North America, MapPoint.NA. A customer data source contains business specific data (such as Company A's 40 store locations in North America) compiled and maintained by customers (your company or you) but hosted by MapPoint Web Service. Next, let's look at each one of these data source types in detail.

5.4.5.1. MapPoint data sources

MapPoint Web Service makes more than 45 data sources available for you to program with. These 45 data sources can be broadly categorized into three types of data sources:

Map data sources
Point of interest data sources
Icon data sources

Let's look at each data source type in detail.

Map data sources Map data sources contain the geographic data used to perform location-oriented tasks, such as finding places and addresses, calculating routes, and rendering maps. All these data sources support entities, which represent the physical existing "things" in the real world, such as airports, coffee shops, libraries, roads and so forth. Table 5-2 shows the Map Data Sources available in MapPoint Web Service.

Table 5-2. Data sources and coverage areas
Data source name	Geographic coverage
`MapPoint.NA`	North America
`MapPoint.EU`	Europe
`MapPoint.BR`	Brazil
`MapPoint.AP`	Asia Pacific
`MapPoint.World`	World
`MapPoint.Moon`	Moon

For a detailed list of entities supported by these data sources, check Microsoft's online documentation at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/mappointsdk/html/index.asp.

Point of interest data sources MapPoint Web Service provides more than 35 point of interest data sources containing information about millions of businesses and organizations in several countries and regions in Europe and North America. The data contained in these data sources is organized by Standard Industry Code (SIC) and includes properties such as location and contact information. You can use these data sources to find businesses either by searching attributes (such as store names, cities, etc.) or by performing a proximity search around a given latitude and longitude (such as a store-locator).

Almost all point of interest data are provided by external data vendors (such as NavTeq or Acxiom) to Microsoft, so these data sources are named after their vendor's name. For example, if you want to use the point of interest data in the North American region provided by NavTeq, use the NavTeq.NA data source.

Along with the vendor-supplied point of interest data sources, MapPoint Web Service also provides one sample point of interest database for a fictitious company called Fourth Coffee Company. The data source for this company, MapPoint.FourthCoffeeSample, contains fictitious coffee shops across North America and Europe. This data source can be used as an example of how your business data can be uploaded as point of interest data to the MapPoint Web Service servers.

For a full list of point of interest data sources and the entity types supported by them, check Microsoft's online documentation at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/mappointsdk/html/index.asp.

Icon data sources MapPoint Web Service provides one icon data source, MapPoint.Icons, which contains over 900 icon images that you can use with the Pushpin object when rendering a map. Each icon image in the icon data source is indexed with either text or numbers that can be used in your application to indicate to use of a pushpin. Identify the icon data source for the pushpin image, and then render that pushpin using one of the map data sources.

You can see a full list of icons in Microsoft's online documentation at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/mappointsdk/html/mpn35devTablesIcons.asp

Now that you know what MapPoint data sources are, let's look at customer data sources in detail.

5.4.5.2. Customer data sources

Customer data sources are created and maintained by customers that use MapPoint Web Service; however, the actual data is hosted on MapPoint Web Service servers. For example, if your company wants to show your office locations on MapPoint Web Service-rendered maps, you need to upload your office location data to MapPoint Web Service servers. The uploaded data is geo-coded and stored in a data source specifically associated with your MapPoint Web Service account. This data source is only accessible by you, and no other MapPoint Web Service customer can read or write to this data source.

You will be automatically assigned a custom data source with a pre-assigned name when you sign up for the MapPoint Web Service, but you can also create your own data sources apart from the pre-assigned one. For example, if your company name that is registered with MapPoint Web Service account is CompanyXyz, and your MapPoint Web Service ID is 6909, your default data source name will be CompanyXyz.6909, and any new data sources that you create will contain this name as their first part. If you want to create a new data source to store only your office locations with the name Office, the data source name will be CompanyXyz.6909.Office.

You can create new data sources either manually by using the Customer Services web site (https://mappoint-css.partners.extranet.microsoft.com/cscv3/) or programmatically by using the Customer Data Service API (see Chapter 8 for more details).

MapPoint Web Service currently supports only point of interest data and icon data for customer data sources , which means that you can only upload points of interests and your own icons to use in your MapPoint Web Service applications.

With so many data sources available in MapPoint Web Service, if you are wondering how to remember which data source performs each location-oriented task, you can find out the capabilities of any data source programmatically in MapPoint Web Service.

5.4.5.3. MapPoint Web Service data source capabilities

Each data source in the MapPoint Web Service environment supports certain location-oriented and non-oriented tasks. The data source capabilities define which data source supports each task.

The data source capabilities are the metadata defined for each data source, which you can use to find out which tasks that data source can support. For example, to find out what all the tasks that can be performed by the data source MapPoint.NA are, query the capabilities metadata using the CommonServiceSoap API. The data source capabilities are programmatically represented as the DataSourceCapability flagged-enumeration whose values are shown in Table 5-3.

Table 5-3. Data source capabilities enumeration
Name	Flag	Function
`CanDrawMaps`	1	Used to render maps
`CanFindAddress`	16	Used to find addresses
`CanFindNearby`	4	Used for proximity searching and attribute searching
`CanFindPlaces`	2	Used for finding places
`CanRoute`	8	Used for calculating driving directions and creating routes
`HasIcons`	32	Used for setting pushpin icons

Data source capabilities can be grouped by their basic functionality, such as find, render, and route, which we will look at in detail in the next couple of chapters; also remember that one single data source can support more than one of these capabilities. For example, the MapPoint.NA data source supports CanDrawMaps, CanFindAddress, CanFindPlace, and CanRoute.

Finally, before we wrap up our discussion on data sources, you need to be familiar with which languages these data sources support .

5.4.5.4. Language support in data sources

Although MapPoint Web Service currently supports 10 languages, not every data source currently supports all 10 languages. The core geographic coverage data sources, MapPoint.NA, MapPoint.EU, MapPoint.BR, and MapPoint.AP, support the nine languages shown in Table 5-4.

Table 5-4. Languages supported in data sources
Language (Country/Region)	Language code	LCID
Dutch	nl	19
English	en	9
EnglishUnited States	en-US	1033
French	fr	12
German	de	7
Italian	it	16
Portuguese	pt	22
Spanish	es	10
Swedish	sv	29

The data sources MapPoint.Moon and MapPoint.World support all of these languages as well as Japanese (language code ja and LCID 1041).

It is also important to note that the MapPoint.Icons data source and all MapPoint point of interest data sources are available only in United States English.

Language preference in MapPoint Web Service is exposed via the CultureInfo object using the UserInfoHeader class, which you can use to set a desired culture Name or Lcid value from the previous table. The following code shows how to request a culture specific setting during a FindService call:

     //Create a Find Service proxy class instance     FindServiceSoap find = new FindServiceSoap();     //Assign Credentials     . . .     //Set culture specific settings     //Create the user info header instance     find.UserInfoFindHeaderValue = new UserInfoFindHeader();     //Initialize culture value and set italian     find.UserInfoFindHeaderValue.Culture = new CultureInfo();     find.UserInfoFindHeaderValue.Culture.Name = "it";     //Assign data source name and invoke find method     . . .

When you set a specific culture for the Find Service, the find results returned by the service are expressed in the culture requested. For example, if you try finding Redmond, WA with "en-US" as your culture information, you get Redmond, Washington, United States as the display name of the found entity, but the same find request returns the "Redmond, Washington, Stati Uniti d'America" when you set the culture info as "it" to get return results in Italian culture format.