Share via

Programming with the MapPoint Web Service Customer Data Service Download Methods

  • Article

 

IMPORTANT: MapPoint Web Service was retired on November 18, 2011. Please see Bing Maps for a list of current Bing Maps APIs.

Chandu Thota
Microsoft Corporation

November 2004

Applies to:
   Microsoft MapPoint Web Service, version 3.5 and later

Summary: Learn how to program with the new Customer Data Service download methods to download your custom point-of-interest data from the MapPoint Web Service Customer Services Site (CSS). (7 printed pages)

Click here to download the code sample for this article.

Contents

Introduction
Implementing a Data Download Client
About Data File Formats
Conclusion
Appendix A—Download API Reference

Introduction

The Customer Data Service, which you can use to upload your point-of-interest data to the CSS programmatically, was introduced with MapPoint Web Service, version 3.5. Now, the Customer Data Service has been enhanced so that you can also download your point-of-interest data. A new set of APIs has been added to the service to facilitate programmatic downloads.

After uploading a data source to the MapPoint Web Service servers, you can use the tools on the MapPoint Web Service Customer Services site (CSS) to correct addresses that could not be geocoded properly or to add entities to the data source. However, if you upload that data source again later, the changes that you made through the CSS will be lost. By regularly downloading your data sources and updating your local database, you can ensure that the data sources on the MapPoint Web Service servers and your local database remain synchronized.

This article describes the new download methods and how to program with them. The sample code discussed in this article is available for download from the Microsoft Download Center. This article assumes that you are familiar with the MapPoint Web Service SOAP API and the Customer Data Service API. For more information, see Developing with MapPoint Web Service and Introducing Customer Data Service in the MapPoint Web Service SDK.

Implementing a Data Download Client

When you call the new download API methods, the data is not returned directly to your application in the form of a byte array. Instead, the Customer Data Service downloads your point-of-interest data to a file, stores it on MapPoint Web Service servers, and returns a URL that you can use to access the file. This file can only be accessed by using your credentials over a secure (SSL/TLS) channel. Once you access the file, you can easily retrieve the data by using typical Web client APIs such as System.Net.WebClient in the Microsoft .NET Framework. The lifespan of the URL is two weeks.

Your data download client must communicate with the Customer Data Service Web service, whose Web Service Description Language (WSDL) document is available at the following location:

https://mappoint-css.partners.extranet.microsoft.com/CustomerData-30/CustomerDataService.wsdl

When you add the WSDL document to your project as a Web reference in Microsoft Visual Studio .NET, the proxy classes for the download methods are automatically generated for you. You can then implement the data download client in three simple steps:

  1. Create a new data download job.
  2. Poll for the status of the job.
  3. Upon successful completion of the job, download and store the data to the local hard-disk.

The following sections look at these steps in detail.

Create a New Download Job

In this step you create a new download job by using the CustomerDataService.StartDownload method. You also specify several job-specific parameters, such as environment (production or staging), entity type, data source name, and so on, by using the new DownloadSpecification object. A successful call to StartDownload returns a unique job ID that you use in subsequent steps. This step also initiates the actual download process, in which the Customer Data Service downloads your point-of-interest data to a secure location that you can access through a URL.

The following code example demonstrates how to start a new download job:

[C#]
//Define the DownloadSpecification object.
DownloadSpecification specification = new DownloadSpecification();

//Create the Customer Data Service proxy.
CustomerDataService DownloadService = new CustomerDataService();

//Set the PreAuthenticate property to true.
DownloadService.PreAuthenticate = true;

//Assign your CSS credentials to access the 
//Web service API.
DownloadService.Credentials = 
     new System.Net.NetworkCredential(userName, password);
         
//Start the download job.
string jobID = DownloadService.StartDownload(specification);

Poll for the Status of the Job

Using the job ID that you obtained in the previous step, you poll the Customer Data Service Web service to determine whether the download job completed successfully.

The following code example demonstrates how to poll for the job status until the download job is complete:

[C#]
//Get the job state.
JobState jobState = DownloadService.GetJobState(jobID);

//Call IsWaitingState to check the
//status of the job.
while(IsWaitingState(jobState))
{
    //Wait for 60 seconds before polling
    //again.
    Thread.Sleep(60 * 1000);
    //Get the job state again.
    jobState = DownloadService.GetJobState(jobID);
}

The IsWaitingState method checks the value of the JobState enumeration to determine whether the job is pending or in progress. The following code shows the implementation of the IsWaitingState method:

// Determine whether the job is still being processed.
bool IsWaitingState(JobState state)
{
   switch (state)
   {
      //If the job is in progress
                //or pending
                //IsWaitingState returns a value of true..
      case JobState.Pending:
      case JobState.InProcess:
         return true;
      default:
         return false;
   }
}

Download the Data File

When JobState is set to CompletedSuccess, you can get the URL to your data file by using the CustomerDataService.GetDownloadFileURL method. The following code shows how to invoke this method:

[C#]
//Get the URL to the download file.
string fileUrl = DownloadService.GetDownloadFileURL(jobID);

Now that you have the URL, you can download the data to a local file using the System.Net.WebClient class from the .NET Framework:

[C#]
//Define a valid local file path.
string localFile = @"C:\Downloads\data.csv";
//Create a new WebClient instance.
System.Net.WebClient client = new System.Net.WebClient();
//Assign your CSS credentials.
client.Credentials = DownloadService.Credentials;
//Download the data to a local file.
client.DownloadFile(fileUrl, localFile);

Now you have successfully downloaded your data from the CSS to a local file.

About Data File Formats

The new download methods support several file formats, both compressed and uncompressed. If no data format is specified in the DownloadSpecification object, the download service uses Microsoft Access 2003 XML format as the default. The following table lists the supported file formats.

File format Description
AccessXml2003 Microsoft Access 2003 XML format. This is the default format used by the download methods.
AccessXml2002 Microsoft Access 2002 XML format.
TabDelimitedTextLatin1 Tab-delimited text format with Latin 1 [ISO 8859-1] encoding.
TabDelimitedTextUTF8 Tab-delimited text format with UTF-8 [ISO 10646-1:2000 Annex D] encoding.
PipeDelimitedTextLatin1 Pipe-delimited text format with Latin 1 [ISO 8859-1] encoding.
PipeDelimitedTextUTF8 Pipe-delimited text format with UTF-8 [ISO 10646-1:2000 Annex D] encoding.
CommaDelimitedTextLatin1 Comma-delimited text format with Latin 1 [ISO 8859-1] encoding.
CommaDelimitedTextUTF8 Comma-delimited text format with UTF-8 [ISO 10646-1:2000 Annex D] encoding.

When you request a compressed file by using the DownloadSpecification.Compressed flag, your data will be compressed as a .zip file.

Conclusion

In this article you have learned how the download methods work and how to build a data download client by using the new download methods and the .NET Framework. With the addition of the download methods, you can now use the Customer Data Service to upload and download your point-of-interest data programmatically.

Appendix A—Download API Reference

This section contains reference documentation for the new classes added to the Customer Data Service.

DownloadSpecification Class

Contains the specifications for a data download job.

Public Fields

Name Description
DataSourceName Represents the name of the data source (the DataSource.Name property) containing the point-of-interest data to be downloaded (System.String).
EntityTypeName Representing the name of the entity type (the EntityType.Name property) of the data that is being downloaded (System.String).
Environment Indicates from which environment the data should be downloaded. The default value is Staging ([Namespace].LocationDataEnvironment).
Format The file format for the downloaded data. The default value is AccessXml2003 ([Namespace].FileFormat).
Compressed A flag that indicates whether the data should be compressed. The default value is false (System.bool).

CustomerDataService.StartDownload Method

Starts a location data download job. This method returns a unique job ID that should be used in subsequent calls.

Syntax

[Visual Basic]
Public Function StartDownload (specification As DownloadSpecification)
      _ As System.String
[C#]
public System.String StartDownload (DownloadSpecification specification);

Parameters

specification

The specifications (DownloadSpecification object) for the data download job.

Remarks

  • Calling this method creates a job with a unique ID on the MapPoint Web Service server. The job ID is used in the subsequent calls to the GetDownloadFileURL method.
  • Always set the PreAuthenticate property for your data upload proxy to true (True in Microsoft Visual Basic .NET) to prevent errors during the data upload process.

CustomerDataService.GetDownloadFileURL Method

Returns a URL that can be used to access the data file for a given job.

Syntax

[Visual Basic]
Public Function GetDownloadFileURL (jobID as string)
      _ As System.String
[C#]
public System.String GetDownloadFileURL (string jobID);

Parameters

jobID

The unique ID for the data download job.