Section 5.2. Getting Started with MapPoint Web Service

5.2. Getting Started with MapPoint Web Service

In this section, let's look at a step-by-step approach to getting started with MapPoint Web Service. If you have already signed up for MapPoint Web Service, are waiting to receive your credentials, and can't wait to start programming with MapPoint Web Service, use the evaluation credentials provided with the companion material; however, remember that these credentials are shared among all readers of this book and may expire at some point in the future.

5.2.1. Requesting MapPoint Web Service Credentials

The first step in programming with MapPoint Web Service is getting your own credentials to access the MapPoint Web Service APIs. Fill in the account request form available on the MapPoint web site at http://www.microsoft.com/mappoint/evaluation/default.aspx. Once you complete and submit the form, you will receive an email containing your MapPoint Web Service account information that includes a user ID and password to access the MapPoint Web Service APIs and another user ID and password to manage your MapPoint Web Service account. Managing your MapPoint Web Service account is done using their Customer Services site, (also known as the Extranet), details of which are included in the email. The customer services site can be considered an administrative console where you can manage your account user IDs and passwords, check your MapPoint Web Service usage (i.e., how many requests you have submitted so far), manage your custom data, and so on. Details on the Customer Services site are discussed later in this chapter.

It is important to remember that the credentials you receive via email only give you access to the staging version of the MapPoint Web Service. The production version of the MapPoint Web Service is accessible only to the customers who actually sign the MapPoint Web Service contract.

The evaluation credentials you have received in the email are only valid for 45 days; after 60 days, these credentials expire, and your application can no longer communicate with MapPoint Web Service. If you are in still in the development phase at that time, however, you can ask the MapPoint Web Service Support to extend the evaluation period.

5.2.2. Accessing the MapPoint Web Service APIs

Now that you have your own set of MapPoint Web Service credentials, let's look at how to access the APIs. The formal WSDL document for the MapPoint Web Service APIs can be found at the following locations:

Staging MapPoint Web Service

http://staging.mappoint.net/standard-30/mappoint.wsdl

https://staging.mappoint.net/secure-30/mappoint.wsdl

Production MapPoint Web Service

http://service.mappoint.net/standard-30/mappoint.wsdl

https://service.mappoint.net/secure-30/mappoint.wsdl

If you are new to the world of web services, WSDL documents are the "contracts" that publish the web service interfaces, methods, and arguments in XML format. WSDL documents also express the types and their wire formats by defining them in XSD simple and complex types.

You might have noticed that MapPoint Web Service offers a staging environment and a production environment; however, the APIs offered by both environments are exactly the same. So why do you need two different environments? The staging environment is primarily targeted for development and testing purposes, while the production environment should be used for live applications. Moreover, the staging and production environments are physically isolated to ensure the Service Level Agreement (SLA) compliance in terms of availability (99.9%) and API response times. For the staging environment, the SLAs are not applicable (the staging Web Service access is free!); however, the SLAs are fully applicable to the production environment. Again, I recommend that you read the EULA for more details on SLAs related to availability and response time.

If you are either prototyping your MapPoint Web Service application or are still in the development phase, you should use the staging environment; once you are done with the development and testing, move your application to production environment. Note that if you are performing large-scale stress testing , it should be scheduled and worked out with the MapPoint operations team in advance. Moving your application is as simple as changing the service URL within your MapPoint Web Service proxy class, which I'll explain later in this chapter. Finally, MapPoint Web Service APIs are available on both normal (http) and secured (https) channels.

5.2.3. Accessing the Customer Services Site

When you request evaluation credentials to access MapPoint Web Service, you also receive a set of credentials to the Customer Services site, where you can manage your web service account. Figure 5-2 shows the Customer Services site reports page.

Figure 5-2. Customer Services site

I will discuss managing your custom data later in this chapter.