General Information
This chapter provides general information on the MapTP Web Services. It covers the environment in which the MapTP Web Services are running, authentication, and session management.
Environments
NAVTEQ provides several MapTP environments. Each MapTP environment provides MapTP Web Services and MapTP servers. MapTP servers provide the map data and route service requests between clients and Web services.
After registering as a customer of MapTP products you receive a MapTP ID (Authentication) and a URL to a MapTP staging environment that you can use for development and testing purposes. When you are done with implementation and tests a MapTP production environment will be assigned to you.
The example URLs in this document use the MapTP staging environment with NAVTEQ map data (maptp12.map24.com).
Authentication
Every MapTP Web Service request must be authenticated. Authentication is done with a MapTP ID. The MapTP ID is a customer identification and provided to you by NAVTEQ when registering as customer. For SOAP requests the MapTP ID has to be included in the RequestHeader (see section RequestHeader / ResponseHeader). For HTTP GET requests the MapTP ID has to be passed with the mid parameter.
Throughout this document a dummy MapTP ID is used in example requests. Replace this with your MapTP ID. Some examples also show the string sequence *** in the place of a MapTP ID. An authentication service on the server is capable of matching a given session ID to a MapTP ID. As long as the client session is valid on the server it is therefore possible to use the sequence *** as MapTP ID for subsequent Web services requests. Only the first request has to specify both, MapTP ID and session ID.
Section Sending Requests to the MapTP Web Services, shows how to set the MapTP ID in the request URL.
Session Management
The state of mapping clients is stored on the server. The server uses a user-defined session ID to identify clients. The server-side representation of a mapping client is also called MapTP session. For example, you can retrieve an image of the current map view of a mapping client by sending a renderBitmapImage request to the MGI Service, passing the session ID of the mapping client in the request. Another example: You can "remote control" a mapping client such as changing its current map view by sending an MRC command to the MRC Service, passing the session ID of the mapping client in the request.
With every MRC command the state of a MapTP session is changed. For example, a SetMapView command changes the state of the map view (center point, clipping width) in a MapTP session.
You must set a session ID for each mapping client. A session ID must be unique within a server environment. Therefore you have to ensure that each session ID is assigned to only one mapping client. When starting two clients with the same session ID the second client hides the first so that for example MRC commands would not reach the first client anymore.
A session ID can contain alphanumeric characters and the underscore (_). No other special characters are allowed. A session ID must contain at least five characters and at most 40 characters.
The following listing shows how to set a session ID "12345" in the applet tag of a MapTP Applet:
<applet width="650" height="520"
...
<param name="sid" value="12345">
...
</applet>
Note: The session ID has to be passed in the URL of SOAP and HTTP GET requests with the sid parameter. In a load balanced environment this ensures that subsequent requests from the same client session are serviced by the same service instance where the session information is stored.
Sending Requests to the MapTP Web Services
All MapTP Web Services provide a SOAP interface. Some of these Web services also offer the possibility to send HTTP GET requests. The syntax of HTTP GET requests is described in the documentation of the respective services.
The following URL is an example for sending SOAP requests to the MapTP Web Services:
http://maptp12.map24.com/map24/webservices1.5?action=soap&mid=***&sid=12345
The current and recommended version of the MapTP Web Services is 1.5. Throughout this document we refer only to this version.
The request parameters:
| Parameter |
Description |
| action |
The action. For SOAP requests the value is "soap". If an HTTP GET interface is available for a particular MapTP Web Service, the action parameter identifies the operation. Those are described in the respective HTTP GET interface descriptions of the service. |
| mid |
A MapTP ID used to authenticate the request. (see section Authentication). |
| sid |
The session ID for identifying the mapping client on the server (see section Session Management). |
RequestHeader / ResponseHeader
The RequestHeader element is mainly used for authenticating the request. Every request to the MapTP Web Services must include a RequestHeader element.
A response from the MapTP Web Services may contain a ResponseHeader element. The ResponseHeader element contains the same structure and contents as the RequestHeader element of the corresponding request.
| Field |
Description |
| Map24ID |
A mandatory MapTP ID used to authenticate the request. |
| ClientID |
An optional ID for identifying the mapping client on the server. Note that this ID is the session ID as described in section Session Management. |
| RequestID |
An optional ID that can be used for logging and debugging of requests. |
| AuthenticationKey |
An optional key that may contain some encrypted code that will be evaluated depending on the customers settings (MD-5, RSA, etc.). |
| CustomerHashtable |
Optionally, this hashtable can contain customer defined key-value pairs. This data will be returned with the ResponseHeader, but it will not be used for any operations within the MapTP Web Services. |
|
