Enabling MapPoint Web Service to use your custom data with find
service methods such as FindNearby
and FindById
is possible by uploading
your data to MapPoint servers. There are two ways to upload/download
your data to/from the MapPoint Customer Services site: you can use
either the MapPoint Customer Services site itself or the Customer Data
Web Service.
In both cases, you can upload new data or update existing data. However, to delete uploaded data, you have to use the MapPoint Customer Services Site Web UI. It is also important to note that neither one of these two options support incremental updates. If you upload a data source, modify it using the CSS, and then re-upload the same data source, your changes will be lost, so it is essential to back up your data before uploading each time to the MapPoint Servers.
Now, let’s take a look at these two options in detail.
You can upload custom points of interest data using the MapPoint Web Service Customer Services site (https://mappoint-css.partners.extranet.microsoft.com/cscV3/) web interface. The user interface for this functionality is available on the home page of the site under the data sources section shown in Figure A-1.
Location data files that you upload to MapPoint Web Service must be in either Access XML file format or flat file format and must meet specific requirements. To find out more about the specific requirements, refer to the Formatting MapPoint Web Service Data Source Files topic on MSDN http://msdn.microsoft.com/library/default.asp?url=/library/en-us/mappointsdk/HTML/mpn35FormattingDataSources.asp?frame=true.
You can perform a maximum of 50 location data uploads within a 24-hour period. This restriction includes uploading new data as well as updating existing data. To upload your data using the UI, follow these steps:
On the home page, scroll down to the data sources section for the environment that you want, and click Create.
In the “Data source name” field, type a name for the new data source. The name you type is appended to the customer’s name and the account ID assigned to you by MapPoint Web Service, which is displayed to the left of the text box.
In the “Entity type” field, assign an entity type for the data source. The entities in a data source require an entity type, and all entities within the data source must be of the same type. The entity type is the category you want associated with your data, such as Stores, Distributors, or ATMs. The entity type can be anything you want as long as it is a valid XML name (which contains no spaces or reserved characters).
Type the filename and path of the data file, or click Browse to locate the file on your computer.
From the Geocoding level (matched method) drop-down list, choose a geocoding level. The geocoder works through the geocoding hierarchy in the order shown in the drop-down list (Street, PostCode, City, Subdivision, CountryRegion) seeking a match for each entity either below or at the level you select. If the latitude and longitude columns in the data source file are empty for any of the entities, they will be geocoded as part of the upload process. Sometimes the geocoder returns multiple results for an address. Select the “Reject ambiguous matches” checkbox to leave the latitude and longitude fields blank for any entity for which multiple matches are returned. Otherwise, the latitude and longitude coordinates for the first match are used.
Click Create.
The MapPoint Customer Services site home page includes a section for recently uploaded data jobs. Refresh the page to see the status of your upload job. You can click on the “View details” link to see additional information about the job or to see whether the job has successfully completed, along with the number of entities that are successfully uploaded and the number of entities that failed to load.
Now that you know how to upload data using the Customer Services Site UI, let’s look at how you can programmatically upload the data using the 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.
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.
Method | Description |
| Starts a location data upload job. This method returns a unique job ID that should be used in subsequent calls. |
| 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. |
| Returns the state of the data upload job represented by the jobID parameter. |
| Marks the data upload job represented by the job ID as complete and submits the uploaded data for geocoding. |
| Starts a location data download job. This method returns a unique job ID that should be used in subsequent calls. |
| 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.
The upload process using Customer Data Service has the following three steps:
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.
Field | Notes |
| Represents the name of the data source that the point-of-interest data is being uploaded to. |
| Represents the name of the entity type of the data that is being uploaded. |
| Indicates which MapPoint Web
Service environment should be used for the data upload.
This field is of type |
| Indicates the maximum
geocoding level ( |
| 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. |
| Specifies whether the data is
point data or polygon data ( |
Tables A-3,
A-4, and A-5 provide possible
values for various enumerations used with the UploadSpecification
object.
Item | Notes |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
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.
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.
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.
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.
Field | Description |
| Represents the name of the data source containing the point of interest data to be downloaded. |
| Represents the name of the entity type of the data that is being downloaded. |
| Indicates from which
environment the data should be downloaded (of type
|
| Indicates the file format
( |
| Indicates whether the data
should be compressed. The default value is |
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.
3.16.79.65