Requests and Responses


Short description | Responses

The return type of the operations is derived from ResponseBase.


This setup guarantees that basic information, such as the coordinate format of input coordinates, are always available. Furthermore, requests and responses are built up in a common way for all operations. This diagram shows the contents of these base types.

Detailed Consideration | Requests


 RequestBase contains fields that are shared among all SOAP/JSON requests, e.g. storedProfile, requestProfile, coordinateFormat, and geometryOptions. All fields are optional and have proper default values. See the article on RequestBase for additional information.

Request structure

All request types implement a similar structure, which consists of the following main parts in the following order.

Input data

This is the main input for a request. Required content depends on the request type. Examples include the waypointsClosed A waypoint is a geographic location used to specify start, destination and possible stopovers for a route. which have to be connected by a routeClosed A route corresponds to a path of a vehicle through the underlying transport network. The main attributes of a route are the distance and the time that the vehicle travels along the path. (mandatory for routing requests) or the bounding box of a map to be rendered (needed for map requests). It may be represented by one or more fields within the request.


Options define parameters which are request specific such as the reference time of a route calculation or map rendering. Options define also parameters which apply to several result fields such as whether or not to calculate the elevation for each response coordinate. In contrast to profileClosed A profile is a collection of parameters used to configure the request. Full profiles consist of a number of specialized sub-profiles like the VehicleProfile which describes the properties of a vehicle. parameters these options define not only how to calculate the response but also what to calculate. Thus, options may change both the structure of the response and its values.

Options are optional, but if present, they may be represented by one or more fields in the request type.

Result fields

Result fields specify which fields of the response are to be calculated. They define what to calculate, therefore result fields always change the structure of the response by switching parts of the response on or off. By default most result fields are switched off, only the most important result fields are switched on. As an example, distance and travel time of a route are always switched on, but further result fields, such as the polylineClosed A polyline is a continuous line composed of one or more line segments given as a set of tuples with x,y and optional z coordinates., the segment list, or toll must be switched on explicitly.

Result fields are optional, but if present, they are represented by exactly one field in the request.


Profiles contain parameters which control the algorithm behind an xServer request. They define how to calculate the response. Changing a profile parameter never changes the structure of the response, only its values. Profiles are described in detail in a separate technical concept.

Detailed Consideration | Responses

Response structure

The response types do not follow a specific structure. They present the results to the caller in a comprehensible way and are designed to ensure that their content or at least parts of it can be used as an input to other requests. As an example, the result of a geocoding using the PTV xLocate service can easily be used as an input to route calculation using PTV xRoute.

Detailed Consideration | Error handling

When an error occurs while processing the request, it does not always cause the request to fail with an exception. If possible, the error will be ignored and processing may continue when a meaningful response can still be calculated. In that case the response contains one or more instances of ResultLimitation, which contain information about the error. As an example requesting elevations for an area within the map which is not covered by the elevations data in the map would result in a ResultLimitation. Further examples can be found in the documentation of the service-specific result limitations.

As a rule of thumb, exceptions are thrown when the request contains invalid parameters, required input is missing, or required data are missing to fulfill the request. Examples are entering a string value for a numeric field, referencing a vehicleClosed The term vehicle describes what is being routed or planned for. Vehicles are used in route calculation, distance matrix calculation and effectively also in tour planning. In route calculation, vehicle properties like overall size, weight and speed are in focus. In tour planning, it is vehicle properties like capacity and availability. Commonly a vehicle is motorized, like a truck - including its trailer or a car. However also a bike or even a pedestrian are included in this definition. by its id but not defining this vehicle, or requesting elevations for a map which does not contain elevations data at all.

Result limitations

This diagram shows some general result limitations, but each service may have its own result limitations. See their documentation to learn more about when they will be returned.

The FeatureLayerMatchLimitation is an example of a result limitation common to several services. It will be returned if one or more feature layers corresponding to a requested feature layer theme do not exactly fit to the currently used map. For example, newer feature layer data may be used with an older map, but then some road segments may not be identified correctly and the results may be inaccurate.

The ElevationsNotAvailableLimitation is an example of a result limitation specific to the PTV xRoute service. It will be returned if elevation data are present but do not cover the entire map. Currently, available data only cover the map up to a latitude of ±60°.

Every result limitation contains at least a message and a hint. Many of them carry additional information, e.g. a field and its invalid value as shown in the example above. Fields are specified in an XPath-like notation. If it is located in a profile, the XPath begins with /profile, no matter whether it was taken from a stored profileClosed A stored profile is a (partial) profile persisted as an XML file. or the request profileClosed The request profile is a partial profile provided in object form for a specific request. Any parameter which is not set in the request profile will be taken from the stored profile..


Fatal errors cause an XServerException to be thrown which contains a message and an abstract fault which in turn contains a specific instance specifying the error in detail. See the exceptions documentation to learn more. It contains all faults, the common and the service-specific ones.

Good to know


Enumeration values are represented by string values, see for example EncodedGeometryType. Although clients languages might use integral values to represent enumerations, only the string representation is supported within an xServer request.