Getting Started with MapPoint Web Service Version 3.5

  • Article

 

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

Paula Flanders
Microsoft Corporation

February 2004

Applies to:
    Microsoft® MapPoint® Web Service version 3.5

Summary: Learn how to get started with MapPoint Web Service version 3.5, whether you are a new customer or are upgrading from a previous version of MapPoint Web Service. (9 printed pages)

Contents

Introduction
Developing Your MapPoint Web Service Application
Preparing Your Custom Data
Preparing Your Custom Icons
Putting Your Application into Production
Managing Your MapPoint Web Service Application and Account
Conclusion

Introduction

Microsoft® MapPoint® Web Service is an XML-based Web service that companies can use to integrate location-based services, such as maps, driving directions, and proximity searches, into applications and business processes. MapPoint Web Service also provides an extensive set of map-related content, such as business listings, points-of-interest, and other types of data that can be used within applications along with your own custom data.

Microsoft MapPoint Web Service version 3.5 is the latest version of MapPoint Web Service. New MapPoint Web Service customers can develop applications based on this platform. Customers using earlier versions of MapPoint Web Service to power their location-based applications are automatically upgraded to MapPoint Web Service 3.5 and can take advantage of the many new features in this fully backward-compatible release.

Implementing MapPoint Web Service in an enterprise requires a number of tasks, including developing an application, preparing custom data and icons, monitoring your application's usage, and ongoing data management. Depending on your organization's size and needs, these tasks might be the responsibility of one person or a team. Many of these tasks, such as developing the application and preparing your custom data, can be completed in parallel. This article provides an overview of the tasks necessary to get started with MapPoint Web Service.

Developing Your MapPoint Web Service Application

If you are a new customer building your first MapPoint Web Service application, you must decide what your customers will be able to do with the application before you or your developer begins building it. Do you want to render maps with your locations marked on them? Provide driving directions? Allow your customers to search for nearby locations? If you have an existing MapPoint Web Service application, review the MapPoint Web Service 3.5 features and enhancements to see which ones might be of use in your applications.

The MapPoint Web Service API consists of four services:

  • Common service Provides utility classes, methods, and properties that are used by the other services.
  • Find service Provides the capability to locate addresses, points of interest, and get location information about specific pairs of latitude and longitude coordinates. You can also use the find service to find locations near a specific point or along a route. Developers familiar with MapPoint Web Service may be interested in two new find methods, FindByID and FindByProperty, that allow you to find your locations by entity ID or by property. Also, version 3.5 includes FindNearRoute for finding your locations within a specified distance along a route.
  • Render service Provides the capability to render maps showing your routes and locations. You can set map size, view, and controls and add pushpins. If you use the Customer Services Web site to upload custom icons, you can display those on maps as well. New with this release is the ability to render maps targeted for small-screen devices with the Phone and PhoneBW map styles.
  • Route service Provides the capability to create driving directions and routes, set waypoints, and generate map views of the routes.

In addition, MapPoint Web Service 3.5 includes a new API, Customer Data Service, a Web service that is accessible through the MapPoint Web Service Customer Services site (CSS). With this SOAP API, you can upload your custom location data to the MapPoint Web Service servers programmatically. A data upload client that is included as a sample in the SDK shows how you can use the Customer Data Service to execute a batch file from the command line to upload your custom data on a schedule.

If you will be developing the application with the Microsoft® .NET Framework, you can download a version of the MapPoint Web Service SDK that is integrated with the Microsoft Visual Studio® .NET documentation. (Visual Studio .NET and the .NET Framework version 1.1 must be installed before downloading the SDK.) Developers are not required to use the .NET Framework to develop the application, however. Because MapPoint Web Service is based on SOAP, you can develop your application with any SOAP-compliant language, such as Java 1.4 using the Axis Library. For that reason, the SDK is available in HTML format for developers who are not using Visual Studio .NET. For more information about the MapPoint Web Service API, developers can review the MapPoint Web Service Software Development Kit (SDK), Version 3.5.

MapPoint Web Service provides two identical, but separate, environments. You can use the staging environment to develop and test your applications. When your application is ready for release to your customers, move it to the production environment.

Test your application in the staging environment by accessing the staging MapPoint Web Service Description Language (WSDL) file. There is a standard (HTTP) URL and an encrypted (HTTPS) URL for staging:

The WSDL URLs are the same for MapPoint Web Service 3.5 as they were for MapPoint Web Service 3.0. To take advantage of the new API features, refresh the WSDL files in your development environment. The WSDL file for the new Customer Data Service API is accessed with your Customer Services site credentials, not your Web Service credentials. The URL for that WSDL file is as follows:

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

For more information about testing, see the CSS Help topic, "About Testing Your Application."

If you are a new customer, while your application is being developed, make sure that you can log on to the Customer Services site (CSS) using the credentials supplied to you in the welcome e-mail message that you received when you set up your MapPoint Web Service account. On the Home page, click Verify Credentials, and then follow the instructions on the Verify Credentials page. Because MapPoint Web Service 3.5 is backward-compatible release, existing customers can continue to use their MapPoint Web Service 3.0 credentials.

Note  Evaluation account customers cannot access the MapPoint Web Service production environment. If you try to access MapPoint Web Service using the production Web Services Description Language (WSDL) file, your application will fail with a 401 error, even if your credentials are valid on the Verify Credentials page.

Preparing Your Custom Data

MapPoint Web Service maintains a number of different public data files, called data sources, with geographic and point-of-interest data that you can use with the find, render, and route services to display maps. Most likely, you will also want to use your own data so that you can render your locations on maps and include them as beginning or end points in driving directions. You can do this by uploading your data source files to the MapPoint Web Service servers.

Data source files are made up of records, which are called entities. Each record, or entity, consists of the information associated with one physical location. For example, an automobile manufacturer might have a data source containing the names, addresses, and other details about all of their dealerships. Each dealership and its associated information is an entity.

With MapPoint Web Service 3.5, you can have up to 25 data sources on the MapPoint Web Service servers (in the staging and production environments) at a given time. You can use the staging environment to keep data sources that are under development separate from those in the production environment that are accessed by your end-users.

A new, task-based Home page on the CSS lists your data sources in both environments and includes icons, shown in Figure 1, for quick access to Web pages for common tasks, such as uploading, downloading, and modifying the entities in a data source. If you already have a MapPoint Web Service custom data source for a MapPoint Web Service 3.0 application, you can still use it with MapPoint Web Service 3.5. The first time you log on to the CSS, your data source will be listed in the production environment table on the Home page.

Click here for a larger image.

Figure 1. Data source list with icons (click the image to enlarge it)

Data Source Requirements

At minimum, your data sources must meet the following requirements:

  • Total size The combined size of all your data sources cannot exceed 2 gigabytes. A file that you upload (either through the CSS or the API) cannot exceed 100 megabytes (compression is allowed).

  • File format Your file must be in either Microsoft® Access 2002 or 2003 XML file format with an embedded schema or in delimited flat-file format. Either file type can be compressed into .zip format. If you use a flat-file format, the first row defines the schema. Valid delimiters are commas, tabs, or pipes ( | ). You must use a single delimiter consistently throughout the file.

    If any values in the first row of data are not valid, the upload operation will fail. If the values in the first row are valid, errors in subsequent rows will not cause an upload operation to fail, but the values that are not valid are either truncated or cleared.

  • Schema Your file's schema cannot exceed 300 columns, including required columns. The columns must be of the types described in Table 1.

    Table 1. Column data types

    Data type Description
    keyword Up to 10 fields with the type keyword and 350 keywords per field are allowed. The maximum number of characters for a single keyword is 50, and the maximum number of characters in one keyword field or across all keyword fields per entity is 2000.
    info Up to 25 fields with the type info are allowed. The maximum number of characters in one info field or across all info fields per entity is 2,560.
    string Up to 50 searchable string fields are allowed. The maximum number of characters in one string field is 256 and the maximum number of characters in all string fields for each entity is 2,560.
    double Up to 20 fields with the type double are allowed. The Latitude and Longitude fields count toward this maximum. The maximum number of characters in one double field is 30.
    long Up to 20 fields with the type long are allowed. The EntityID field counts toward this maximum. The maximum number of characters in one long field is 20.
    Boolean Up to 200 fields with the type Boolean allowed.

    Note  The maximum number of characters per entity is 2,560.

  • Required columns Your data source file must contain Latitude and Longitude columns; however, these fields can be empty. If these fields contain entries for particular entities, the values are accepted as correct, and those entities are not geocoded as part of the upload process. Values in the Latitude column must be floating point numbers representing decimal degrees that range from -90 to 90. Values in the Longitude column must be floating point numbers representing decimal degrees that range from -180 to 180. For an Access XML file, the Access data type must be Number and the Access field size must be double for each of these columns.

    Your data source file must also have an EntityID column that contains a unique integer identifier for each entity. For an Access XML file, the Access data type must be Number or AutoNumber and the field size must be integer or long Integer. For a delimited flat file, the data type must be long (the range is -2147483648 to 2147483647).

    **Note  **If your data source does not have a CountryRegion column that contains values, the geocoder uses the MapPoint.World data source for geocoding, and cannot geocode addresses to the street level.

  • Column names Each column must have a name. Optionally, the name can be followed by the data type in parentheses (no spaces are allowed). Valid data types are long, double, Boolean, string, info, and keyword. If you omit the data type, the data type for the EntityID column defaults to long, the data types for the Latitude and Longitude columns default to double, and all others default to string. Column names must be XML-compliant; that is, they must not contain spaces or reserved characters. In addition, column names must be unique and no longer than 50 characters.

  • File size Each data source must contain at least one entity, and the file cannot exceed 100 megabytes (MB). A data source can contain a maximum of 8.75 million searchable non-Boolean cells. This limit includes cells in the columns that are required (EntityID, Latitude, and Longitude) and cells in the columns that are added to the data source file by MapPoint Web Service during the uploading and geocoding process (MatchCode, MatchedMethod, MatchedAddress, EditedLocationUTC, EditedPropertyUTC, and InputModified). The total does not include cells with the type info or keyword. Therefore, the number of entities contained in a single data source cannot exceed 972,222 (8.75 million cells divided by 9 non-Boolean, searchable properties per row).

Uploading a Data Source

While previous releases required separate processes for geocoding (assigning latitude and longitude coordinates) and uploading your custom data source, MapPoint Web Service 3.5 streamlines the process. Your custom data is geocoded as part of the upload process. For more information about geocoding, see the CSS Help topic, "About Geocoded Data."

Note  You can re-geocode a data source by downloading the data source, clearing the entries from the Latitude and Longitude columns, and then uploading the data source again.

When you upload a data source to the CSS, your upload job is listed in the Recent Jobs section of the CSS Home page. When the job is complete, you can click View Details to review the results of the upload and geocoding processes. Once uploaded, your data source is listed on the CSS Home page. You can click the edit icon next to the name of the data source to access a set of Web pages that you can use to edit individual entities in the data source and correct any entities that were not geocoded properly.

For more information about using the new Customer Data Service API to upload data sources or downloading the sample data upload client application, see the MapPoint Web Service SDK, Version 3.5. For information about using the data upload client and the CSS to upload your data source files, see the CSS Help topics, "Uploading a Data Source Using the Command Line" and "Uploading a Data Source Using the CSS."

Preparing Your Custom Icons

MapPoint Web Service provides a wide variety of stock icons that you use with the maps generated by your application, and you can also use your own custom icons. You can review the stock icons available from MapPoint Web Service by clicking Stock Icon Images on the CSS Home page. If you have custom icons (such as company logos), you can upload them to the MapPoint Web Service servers by clicking Upload Custom Icons from the menu on the Home page. The icons you upload must meet specific requirements. For more information, see the CSS Help topic, "Requirements for Custom Icons." Custom icons that you upload to the MapPoint Web Service servers must meet the following requirements:

  • File format Graphics files must be in bitmap (.bmp) format.

  • Size The maximum size for an image is 50,000 pixels, with no individual dimension of a bitmap exceeding 2000 pixels. The recommended size is 16 by 16 pixels.

  • Color The color must be 8-bit (256 colors).

    Note  The background of custom icons (except for rectangular icons) should be transparent so as not to obscure the area of the map on which the icon is placed. The transparency color of maps rendered by MapPoint Web Service is pure green (RGB=0,255,0). Set the background color of your custom icons to this color. For example, if a custom icon is an oval, fill the corner areas of the frame background with pure green.

  • File name Icon file names must be unique. Check the Stock Icon Images page to ensure that your images don't have the same file names as the stock icons. Give the image a file name that uses only alphanumeric characters with a 64-character limit.

    Use the following format for the name:

    name,[space]x,y.bmp

    where name is a unique name for the icon and x,y defines the pixel coordinates of the hotspot (the point of the image that is matched to a location on a map). For example, if an icon that is 16 by 16 pixels has a file name of 0,7,15.bmp, the icon name is 0 and the hotspot is located at 7,15 (7 pixels over and 15 pixels down from the upper-left corner).

Custom icons uploaded by MapPoint Web Service 3.0 customers remain available for use with MapPoint Web Service 3.5. No changes are necessary to your application or to the icons.

Putting Your Application into Production

If you are a new customer, you must perform the following tasks prior to releasing your application to production:

Managing Your MapPoint Web Service Application and Account

Managing your account, monitoring application usage, and maintaining your custom data and icons are ongoing tasks. MapPoint 3.0 customers will find a number of enhancements and new features available for managing custom data and monitoring usage data. The following sections describe each task in more detail.

Managing Your Custom Data

As stated earlier, each data source listed on the CSS Home page has a row of clickable icons that provide quick access to common tasks. Click an icon in the same row as the data source you want to work with to complete to upload, download, copy, edit, or delete the data source. When you click the edit icon, you access a set of Web pages for managing the entities in a data source. The first page displayed is the Manage Locations page, as shown in Figure 2. On this page, you can view a list of entities in the data source, sort those entities in a variety of ways, and filter the entities to display only the ones you plan to work with. Because of size constraints, the number of entities listed on the Manage Locations page has been reduced in this illustration. Normally, the minimum number of entities listed on the page is 10.

Click here for a larger image.

Figure 2. Manage Locations page (click the image to enlarge it)

Click the ID of an entity to view or modify detailed information about that entity, including the address information, its properties, and its location on a map. You can also add new entities or delete ones no longer needed.

Note  If you make changes to a data source through the CSS, you must also make the same changes to your local source file if you intend to upload the file again.

Modifying Your Custom Icons

Click Manage Custom Icons to change the name of an icon, delete icons, or change an icon's hotspot.

Managing Your Account

New customers receive an e-mail message containing one user name and password for the extranet portal, which you use to access the CSS. If you want to, you can create additional accounts. For more information, see the CSS Help topic, "Adding Extranet User Accounts."

You also need to keep your account and technical contact information up-to-date using the Manage Accounts page on the CSS.

**Note  **On that page, you can indicate whether you want to be contacted by Microsoft marketing and sales personnel. If you have an evaluation account and indicate that you do not want to be contacted, MapPoint Web Service will not contact you with licensing information. You must request the information if you want to license the product when the evaluation period ends.

Viewing Your Usage Reports

MapPoint Web Service provides a variety of usage reports available through the CSS. Click View Reports to access reports about your application and the way your customers are using it. Customers upgrading from the previous version will notice a new category of reports—business locations. These six reports, such as Most Popular Business Locations and Most Popular Subdivisions, help you see which locations your customers are searching for most frequently.

Data available for reports is updated once a day. The length of time needed for your reports to have enough data to be meaningful depends on the amount of traffic generated by your application.

Note  The business locations reports will not contain data unless you give MapPoint Web Service permission to log data about the searches performed with your application.

Using the available filters, you can customize your reports to get reports about certain date ranges, about one data source or a group of data sources, about a particular environment, or even about a specific API service.

Conclusion

An enhanced API, support for multiple data sources and larger data sources, and an updated Customer Services site for managing your applications make MapPoint Web Service 3.5 the ideal platform on which to develop location-based Web services. Once your application is in production, you can perform ongoing management tasks through the CSS. For more information about MapPoint Web Service, see the MapPoint Web Service SDK, Version 4.0.