Accessing the MapPoint Web Service SOAP API

Accessing the MapPoint Web Service SOAP API

MapPoint Web Service is an XML Web service with a SOAP API that comprises four constituent services: finding locations, creating routes, rendering maps, and providing a set of utility function objects and methods that are common to the previous three. To call the service, you need to reference the Web Services Description Language (WSDL) for MapPoint Web Service.

MapPoint Web Service Production and Staging Environments

The MapPoint Web Service staging and production environments are two functionally-identical, yet separate, service environments that are available 24 hours a day, seven days a week.

Staging Environment

The MapPoint Web Service staging environment is a set of testing services that is separate from and complementary to the production services you use when your application goes live. You can use the staging environment to prototype, develop, and test new applications. You can also use the staging environment to test the completeness and accuracy of point-of-interest data and icons you have uploaded to the staging environment through the MapPoint Web Service Customer Services site (https://mappoint-css.live.com/CSCV3/) before uploading your data to the production environment.

Note The staging environment is not scaled for the extraordinary volumes that the production environment is designed to provide. Any application stress or performance testing is limited to a certain number of requests per second and time of day. For more information, see the help topic Developer Resources on the MapPoint Web Service Customer Services site (https://mappoint-css.live.com/CSCV3/).

The staging enviroment is used in the following situations:

  • Developing or testing prototypes and applications

  • Testing custom point-of-interest and icon data uploaded for use with MapPoint Web Service

  • Testing application performance

Production Environment

The MapPoint Web Service production environment is fully scaled for all MapPoint Web Service customers. You use this environment when your application is made available to the public through the Internet, including live, beta, evaluation, and prerelease types of applications.

The production environment is used in the following situations:

  • Conducting final application testing before launch; limited to expected transaction activity levels

  • Releasing your application for customer access; releases include beta, hidden launch, evaluation, prerelease, and full-release versions

Note Activity in the production environment is billable. Do not use the production environment for performance and stress testing beyond your expected volumes.

Referencing the MapPoint Web Service WSDL

The WSDL is an XML document that defines the format of messages that MapPoint Web Service uses. The WSDL serves as an agreement that defines the behavior of MapPoint Web Service and instructs potential clients how to interact with it. Your development project must reference mappoint.wsdl to access the MapPoint Web Service SOAP API.

You can reference the WSDL by using either the standard HTTP protocol or the HTTPS Secure Sockets Layer (SSL) protocol. Using the SSL protocol adds latency for each call to the MapPoint Web Service API. The latency duration depends on how the SSL infrastructure is implemented on your servers; the minimum additional latency is five milliseconds.

As shown in the following table, there are two mappoint.wsdl files: one for staging and one for production. You can access each file through two URLs; one is for standard HTTP access and the other for secure HTTPS access. When your application is ready to move from staging to production, you must delete the Web reference to the staging version of mappoint.wsdl, and then add a Web reference to the production version.

Environment

HTTP URL

HTTPS URL

Staging

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

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

Production

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

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

Using the Constituent Services

The MapPoint Web Service WSDL file describes four services (CommonServiceSoap, FindServiceSoap, RenderServiceSoap, and RouteServiceSoap) within a single WSDL file. However, some development tools, including Microsoft Visual Studio 2005, expect a WSDL file to only describe a single service. To ensure proper functionality of your code, you should always provide the Url property when instatiating each of the service classes. The URL you should use for each service depends on the environment you are using. Each URL is listed in the WSDL file in a soap:address location element. The following code example shows how to set this property:

[C#]

RenderServiceSoap render = new RenderServiceSoap();
render.PreAuthenticate=true;
render.Credentials=myCredentials;
render.Url="https://renderv3.staging.mappoint.net/Render-30/RenderService.asmx";


[Visual Basic]

Dim render As New RenderServiceSoap
render.PreAuthenticate = True
render.Credentials = myCredentials
render.Url = "https://renderv3.staging.mappoint.net/Render-30/RenderService.asmx"


For more information about the Url property, see WebClientProtocol.Url Property in the MSDN Library.

Example

Fourth Coffee has just acquired a number of new businesses that it is not yet ready to share with the public. The company's application development team uploads the new location data and icons to the staging server on the MapPoint Web Service Customer Services site. The team codes the application to reference the staging version of mappoint.wsdl to test the data sources that contain the new store locations and special icons. When intitial testing is complete and the application is ready to beta test, the team uses the MapPoint Web Service Customer Services site to submit the tested data to the production environment, and changes the application code to reference the production version of mappoint.wsdl.

Note For information about how to access the MapPoint Web Service Customer Services site, check the customer information that you received when you enrolled in the service. For information on becoming a customer, visit the MapPoint Web Service Web site at https://www.microsoft.com/mappoint/webservice.