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.

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

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.

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

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.

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.

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.

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.

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.

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:Downloadsdata.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.