Section A.2. Using Customer Data Web Service

A.2. Using Customer Data Web Service

The Customer Data Service enables you to upload and download your point of interest data to the MapPoint servers programmatically. Even though Microsoft hosts it as part of MapPoint Web Service, Customer Data Service is only used in customer data management, whereas MapPoint Web Service offers a core mapping platform for location based application development.

You can access the Customer Data Service WSDL at: https://mappoint-css.partners.extranet.microsoft.com/CustomerData-30/CustomerDataService.wsdl.

To access Customer Data Service Web Service , you need to use your MapPoint Web Service Customer Services Site credentials.

A.2.1. A Look at Customer Data Service APIs

As I said earlier, Customer Data Service supports both upload and download of your entity data programmatically. If you are developing with Customer Data Service, the main class that you need to use is the CustomerDataService class. Depending on the task (upload or download) you need to invoke the StartUpload or StartDownload methods on the CustomerDataService class. Table A-1 shows the methods exposed on the CustomerDataService class.

Table A-1. CustomerDataService methods

Method	Description
StartUpload	Starts a location data upload job. This method returns a unique job ID that should be used in subsequent calls.
UploadData	Uploads the point-of-interest data. You can use this method to upload data in multiple chunks. This method returns the number of bytes that were uploaded in the current call.
GetJobState	Returns the state of the data upload job represented by the jobID parameter.
FinishUpload	Marks the data upload job represented by the job ID as complete and submits the uploaded data for geocoding.
StartDownload	Starts a location data download job. This method returns a unique job ID that should be used in subsequent calls.
GeTDownloadFileURL	Returns a URL that can be used to access the data file for a given job.

So, how does the data upload/download work with Customer Data Service? Let's look in detail in the following two sections.

A.2.1.1. Uploading data using Customer Data Service

The upload process using Customer Data Service has the following three steps:

A.2.1.1.1. Create a new upload job

During this step, you create a new upload job using the CustomerDataService.StartUpload method. This method takes a specification object of type UploadSpecification, which specifies several job-specific parameters such as environment (production versus staging), geocoding match level (street, city, Zip Code, subdivision, or country/region), whether to ignore ambiguous records after geocoding, etc. Table A-2 shows the fields exposed on the UploadSpecification class.

Table A-2. UploadSpecification class fields

Field	Notes
DataSourceName	Represents the name of the data source that the point-of-interest data is being uploaded to.
EntityTypeName	Represents the name of the entity type of the data that is being uploaded.
Environment	Indicates which MapPoint Web Service environment should be used for the data upload. This field is of type LocationDataEnvironment enumeration. The default value is Staging.
MaximumGeocodingLevel	Indicates the maximum geocoding level (GeocodingLevel enumeration) to be used to geocode the point-of-interest data. The default geocoding level is street name and number.
RejectAmbiguousGeocodes	Indicates whether ambiguous addresses should be skipped or whether they should be assigned the latitude and longitude of the first address that matches the record.
GeometryType	Specifies whether the data is point data or polygon data (GeometryType enumeration).

Tables A-3, A-4, and A-5 provide possible values for various enumerations used with the UploadSpecification object.

Table A-3. LocationDataEnvironment enumeration

Item	Notes
Service	Indicates that the data upload is performed in the production environment
Staging	Indicates that the data upload is performed in the staging environment

Table A-4. GeoCodingLevel enumeration

Item	Notes
City	Indicates that the city level of geocoding is allowed. If this geocoding level is selected, all ambiguous addresses at street and postal code levels are geocoded against their city names.
CountryRegion	Indicates that the country/region level of geocoding is allowed. If this geocoding level is selected, all ambiguous addresses at street, postal code, and city levels are geocoded against their country names.
PostalCode	Indicates that the postal code level of geocoding is allowed. If this geocoding level is selected, all ambiguous addresses at the street level are geocoded against their postal codes.
Street	Indicates that the point of interest data will be geocoded at the street name and number level. When an ambiguous address is found with this geocoding level, that record will not be marked as ambiguous and will not be geocoded at other levels, such as postal code or city.
Subdivision	Indicates that the subdivision/state level of geocoding is allowed. If this geocoding level is selected, all ambiguous addresses at street, postal code, and city levels are geocoded against their state/subdivision.

Table A-5. GeometryType enumeration

Item	Value
Point	Indicates that the data being uploaded is the point data
Polygon	Indicates that the data being uploaded is polygon data

Next, look at the following code to see how to start a data upload job:

     //Create an instance of the customer data service proxy.     CustomerDataService cds = new CustomerDataService( );     //Assign your credentials.     . . .     //Set PreAuthenticate to true     cds.PreAuthenticate = true;     //Define an upload specification object     //and assign all required fields.     UploadSpecification uploadspec = new UploadSpecification( );     uploadspec.DataSourceName = myDataSourceName;     uploadspec.EntityTypeName = myEntityTypeName;     uploadspec.Environment = LocationDataEnvironment.Staging;     uploadspec.MaximumGeocodingLevel = GeocodingLevel.City;     uploadspec.RejectAmbiguousGeocodes = false;     uploadspec.GeometryType = GeometryType.Point;     //Start an upload job and obtain the job ID.     string jobID = cds.StartUpload(uploadspec);

A successful call to this method returns a unique job ID used in subsequent steps.

A.2.1.1.2. Upload your data

Using the job ID that you obtained in the first step, upload your custom point of interest data to the MapPoint servers with the CustomerDataService.UploadData method; this method takes a valid job ID, point of interest data as a memory buffer, and the bytes uploaded in previous upload calls for this job. The last parameter is useful if you are uploading small chunks of data instead of uploading all of the data at once. You have to upload your data in chunks if your data file is bigger than 1 MB. This method returns the number of bytes uploaded once you have successfully uploaded the data.

Assuming that your location data is contained in a simple text file, the following code shows how to use this method:

     //String buffer to hold the poi data     string poidata = string.Empty;     //Get the contents from the poi file     System.IO.StreamReader sr = new StreamReader(@"C:\poi.txt");     poidata = sr.ReadToEnd( );     sr.Close( );     //Convert the string content into an array of bytes.     byte[] buffer = System.Text.Encoding.UTF8.GetBytes(poidata);     //Now upload the POI data.     long uploadedbytes = cds.UploadData(jobID, buffer, 0);

If you are uploading data in one call, set bytesPreviouslyUploaded to zero; if you are uploading the data in multiple chunks, this parameter value must match the cumulative sum of all individual uploads for the current job. For example, if you have 10 KB of data that you want to upload, the value of the bytesPreviouslyUploaded is zero if you upload all 10 KB in one CustomerDataService.UploadData method call. However, if you decide to upload the same 10 KB of data in five chunks of 2 KB each, then the values of the bytesPreviouslyUploaded parameter should be 0, 2,000, 4,000, 6,000, and 8,000 in corresponding consecutive CustomerDataService.UploadData method calls.

Here is an example of a text file with custom location data:

     EntityID    Latitude    Longitude    nat_importance    Region    Name    street_     number    street_name    AddressLine    PrimaryCity    Subdivision    PostalCode     CountryRegion    Phone     6    42.720266    -87.870073    N    CHI    Knights Court    1149    Oakes Rd    1149     Oakes Rd    Racine    WI    53406    United States    262-8866667     7    42.719011    -87.859109    N    CHI    Fairfield Inn-Racine    6421     Washington Ave    6421 Washington Ave    Racine    WI    53406    United States     262-8865000     8    42.720513    -87.866756    N    CHI    Comfort Inn-Racine    1154    Prairie Dr     1154 Prairie Dr    Racine    WI    53406    United States    262-8866055     9    42.719168    -87.864424    N    CHI    Frank Gentile Oldsmobile    6801     Washington Ave    6801 Washington Ave

A.2.1.1.3. Submit your data for processing

Upon completing the second step, submit your points of interest data for processing by calling the CustomerDataService.FinishUpload method. If you do not call this method, your data will not be processed; in other words, your data will not be loaded into your data source. This method takes the job ID and the total number of byes uploaded as input parameters.

The following code shows the CustomerDataService.FinishUpload method call:

     //Finish the data upload     cds.FinishUpload(jobID, 10000);

After the CustomerDataService.FinishUpload method is invoked, the services on MapPoint Web Servers upload your data to your data sources, but how do you know when an upload job is done? You can use the CustomerDataService.GetJobState method for that purpose.

A.2.1.2. Polling for an upload job status

You can use the CustomerDataService.GetJobState method to get the status of your data upload job. This method takes a valid job ID and returns the JobState enumeration to indicate the job status. The following code shows how to use the CustomerDataService.GetJobState method:

     //Get job state by calling the GetJobState method.     JobState jobStatus = cds.GetJobState(jobID);     //Check the state     switch(jobStatus)     {         case JobState.Pending:         //Still Pending         break;         case JobState.Loading:         //Still Loading         break;         default:         //None of the above two         break;     }

Now that you know how to upload data programmatically, let's look at how you can use Customer Data Service to download your data.

A.2.1.3. Downloading data using Customer Data Service

Using the Customer Data Service, you can also download your point of interest data; like the data upload process, the download process also has three basic steps.

A.2.1.3.1. Create a new download job

In this step, you create a new download job using the CustomerDataService.StartDownload method. You also have to specify several job-specific parameters, such as environment (production or staging), entity type, data source name, and so on, using the DownloadSpecification object. Table A-6 shows the fields defined in the DownloadSpecification object.

Table A-6. DownloadSpecification class fields

Field	Description
DataSourceName	Represents the name of the data source containing the point of interest data to be downloaded.
EntityTypeName	Represents the name of the entity type of the data that is being downloaded.
Environment	Indicates from which environment the data should be downloaded (of type LocationDataEnvironment enumeration). The default value is Staging.
Format	Indicates the file format (FileFormat enumeration) for the downloaded data. The default value is AccessXml2003.
Compressed	Indicates whether the data should be compressed. The default value is false.

A successful call to StartDownload method 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 demonstrates how to initiate a download process:

     //Create the Customer Data Service proxy     CustomerDataService cds = new CustomerDataService( );     //Set the PreAuthenticate property to true     DownloadService.PreAuthenticate = true;     //Assign your Customer Services Site credentials     . . .     //Define the DownloadSpecification object     DownloadSpecification specification = new DownloadSpecification( );     //Assign download settings for my data source     specification.DataSourceName = "MyCompany.6909.ATM";     specification.EntityTypeName = "ATM";     //Set staging environment - this is default     specification.Environment = LocationDataEnvironment.Staging;     //Assign the desired file format     specification.Format = FileFormat.CommaDelimitedTextUTF8;     //Compress the file for faster downloads     specification.Compressed = true;     //Start the download job     string jobID = cds.StartDownload(specification);

The download specification takes the desired file format and supports compressed file formats as well (for example, a Zip file). Table A-7 shows the supported file formats for the data download.

Table A-7. 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.

AccessXml2003 is the default format for the downloaded file. Finally, when the Compressed flag is set to true on the download specification, the data is downloaded in compressed format as a Zip file.

A.2.1.3.2. Poll for the status of the job

Calling the StartDownload method initiates the actual download process, so you have to keep checking the job status using the GetJobState method until the download process is complete.

The following code shows how to poll for the job status to find out whether the download is complete or not:

     //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);     }     // 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;        }     }

I have added a small method, IsWaitingState, which checks the value of the JobState enumeration to determine whether the job is pending or in progress. Once the job state is returned as CompletedSuccess, it indicates that the download process is complete, and you can save the downloaded data to your local hard disk.

A.2.1.3.3. Download the data file and save it to your hard drive

When the download job is completed successfully, your point of interest data are downloaded to a secure location. You have to use the CustomerDataService.GetDownloadFileURL method to obtain the location of the file so that you can download it to your local hard drive.

The following code shows how to obtain the downloaded file URL and save it to your local disk:

     //Get the URL to the download file     string fileUrl = DownloadService.GetDownloadFileURL(jobID);     //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 Customer Services Site credentials     . . .     //Download the data to a local file     client.DownloadFile(fileUrl, localFile); 

Also, it is important to remember that if you set the Compressed flag to TRue in the DownloadSpecifications, the data is downloaded as a Zip file.