Requests and Responses

This Technical Concept is relevant to all services

Characteristic

Short description | Requests

The SOAP SOAP (Simple Object Access Protocol) is a protocol specification for exchanging structured information in the context of Web services. XML is used for definition of the message format, and it is based on other application layer protocols, like Hypertext Transfer Protocol (HTTP) or Simple Mail Transfer Protocol (SMTP)./JSON JSON (JavaScript Object Notation) is an open standard format for which human-readable text is used to transmit information consisting of attribute–value pairs. It is the first-address data format used for asynchronous browser/server communication (AJAX). operations of PTV xServer always have exactly one parameter. Its type is derived from RequestBase.

Short description | Responses

The return type of the operations is derived from ResponseBase.

Use

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

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.

Example of fields defined in RequestBase

{
    "storedProfile": "truck11_99t",
    "requestProfile": {
        "vehicleProfile": {
            "load": {
                "hazardousGoodsTypes": "HAZARDOUS",
                "tunnelRestrictionCode": "D"
            }
        }
    },
}

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 waypoints A waypoint is a geographic location used to specify start, destination and possible stopovers for a route. which have to be connected by a route 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	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 profile 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 polyline 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	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.

Noteworthy about result lists: Empty result lists are omitted from the response. Depending on the used client technology you might have to check if a list exists before iterating over it.

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 vehicle 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.

See an example of a route response with such a result limitation

{
    "$type": "RouteResponse",
    "resultLimitations": [
        {
            "$type": "FeatureLayerMatchLimitation",
            "message": "A feature layer theme does not match the map version. The result may be inaccurate.",
            "hint": "Please update the feature layer data for this theme or the map so that both have the same version. If in doubt, contact your PTV representative for help.",
            "themeId": "PTV_TrafficIncidents",
            "countries": [
                "LU"
            ]
        }
    ],
    "distance": 18796,
    "travelTime": 1252.957
}

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 profile A stored profile is a (partial) profile persisted as an XML file. or the request profile 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..

See how a field is specified as XPath

The example XPath /profile/featureLayerProfile/themes/@id may identify one of the following fields. Note that it is a simplified XPath notation which does not consider array indexes.

Sample request profile in JSON

{
    "requestProfile": {
        "featureLayerProfile": [
            {
                "themes": {
                    "id": "PTV_SpeedPatterns"
                    "enabled": true
                }
            }
        ]
    }
}

Sample stored profile in XML

<?xml version="1.0" encoding="UTF-8"?>
        <profile version="2">
        <featureLayerProfile>
        <themes id="PTV_TruckAttributes" enabled="true"/>
        </featureLayerProfile>
</profile>

Exceptions

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.

See some examples...

An invalid request with a formatting error will result in an InvalidRequestFault like this.

{
        "message": "Can not construct instance of boolean from String value '}': only \"true\" or \"false\" recognized\n at [Source: org.apache.cxf.transport.http.AbstractHTTPDestination$1@75e6a6a0; line: 34, column: 1] (through reference chain: com.ptvgroup.xserver.xroute.RouteRequest[\"requestProfile\"]->com.ptvgroup.xserver.profile.RequestProfile[\"featureLayerProfile\"]->com.ptvgroup.xserver.featurelayerprofile.FeatureLayerProfile[\"themes\"]->com.ptvgroup.xserver.featurelayerprofile.Theme[\"enabled\"])",
        "errorLine": 34,
        "errorColumn": 1,
        "faultType": "com.ptvgroup.xserver.exceptions.InvalidRequestFault"
}

A route request with an input location somewhere in the middle of an ocean will result in an xRoute-specific WaypointNotLinkableFault like this.

{
        "waypointIndices": [
         0
        ],
        "hint": "Make sure that the coordinates of the waypoints in question are covered by the map data and are close to a road segment valid for the given vehicle.",
        "faultType": "com.ptvgroup.xserver.exceptions.WaypointNotLinkableFault",
        "message": "Some waypoints of the request could not be linked to the road network.",
        "$type": "XServerException"
}

Good to know

Enumerations

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.

Developer's Guide	Web Service Interface Principles