routing

Types

CountryIgnoredLimitation

extends ResultLimitation
since 2.23

This result limitation indicates that GeographicRestrictions.allowedCountries or GeographicRestrictions.prohibitedCountries contains a country code that cannot be used like this due to the available data, and that it was ignored.

Field Name Type Required Default Since Description
ignoredCountryCode String yes - 2.23 The country code that was requested in allowedCountries or prohibitedCountres, but was ignored.

DistanceBasedHorizon

extends Horizon
since 2.1

Represents a geographical horizon that is described by a distance. Every point or road segment that is reachable from the source within the specified distance is included in the horizon.

Field Name Type Required Default Since Description
distance NonZeroDistance (double) yes - 2.1 A distance that specifies the range of the horizon.

Defines the geographic restrictions to be applied for route calculation. The effective routable area is determined by the intersection of the effective country list and the search space bounds.

Field Name Type Required Default Since Description
searchSpaceBounds SearchSpaceBounds no - 2.18 The area to which the search space should be restricted.
allowedCountries CountryCode[] (String[]) 0..* - 2.3

Specifies a list of country codes that are allowed for a routing.

Unsupported country codes, i.e. codes representing a country not contained in the configured map or codes not assigned to any country, are ignored. The response will contain a CountryIgnoredLimitation. Unsupported subdivision codes for supported countries will be ignored, instead the whole country will be allowed. The response will contain a SubdivisionFallbackLimitation. Without any country code defined in this parameter, the list of allowed countries is set by default to the list of those contained in the configured map. When this list is not empty but contains only unsupported codes, route calculation will fail.

The effective list of countries authorized in the routing is computed as following:

prohibitedCountries CountryCode[] (String[]) 0..* - 2.3 Specifies a list of country codes that are prohibited for a routing. Unsupported country codes will be ignored, supported country codes with unsupported subdivision codes will also be ignored. The response will contain a CountryIgnoredLimitation. For further explanation see the definition of GeographicRestrictions.allowedCountries.
prohibitedSegmentsByIntersectingPolylines EncodedGeometry[] 0..* - 2.26 Specifies a list of polylines which causes all segments intersected by these polylines to be prohibited for the route calculation. Only geometries of type Polyline are allowed. In contrast to the other geographic restrictions the prohibited segments specified here can be violated if the violations are enabled in the routing profile. Such violations are reported also when a PathWaypoint is used.
If these polylines intersect more than 5000 segments, the request is rejected with an exception.

GeographicRestrictionsIgnoredLimitation

extends ResultLimitation
since 2.24

This result limitation indicates that a GeographicRestrictions parameter was ignored due to an other parameter.

Field Name Type Required Default Since Description
ignoredParameter String yes - 2.24 Identifies the geographic restrictions parameter (as an xPath path expression) which was ignored.
relatedParameter String yes - 2.24 Identifies the parameter (as an xPath path expression) which caused the geographic restrictions parameter to be passed over.
ignoredValue String yes - 2.24 The ignored geographic restrictions parameter value.
relatedValue String no - 2.24 The value which caused the geographic restrictions parameter to be passed over. Not present if the conflict is independent of the value.

The abstract base type for geographical horizons like the reachable circle around a point.

No fields defined.

MonetaryCostOptions

used by RouteOptions
since 2.21

Specifies parameters for calculating monetary costs of a route. The parameters are explained in more detail in the section "Route Selection by Monetary Costs" of the technical concept on route selection.

Field Name Type Required Default Since Description
costPerKilometer Double no - 2.21 Specifies the monetary cost per kilometer.
If no value is provided a default of 1.2 EUR or the corresponding amount in the provided currency is used.
workingCostPerHour Double no - 2.21 Specifies the monetary cost per hour. It is applied to segments of types LINK_SEGMENT, NETWORK_SEGMENT and COMBINED_TRANSPORT. It is not applied to segments that represent service times or breaks and rests.
If no value is provided a default of 20.5 EUR or the corresponding amount in the provided currency is used.
costPerFuelUnit Double no - 2.27 Specifies the cost per fuel unit (that means per liter Diesel or per kg CNG). The Engine.fuelConsumption and Engine.consumptionFactorsPerSpeed are used to determine the actual fuel consumption on a road segment and then the cost per fuel unit is applied on this fuel consumption to calculate the energy costs.
If no value is provided no energy cost is used and the reported energy cost is zero.
costPerElectricityUnit Double no - 2.27 Specifies the cost per electricity unit (that means per kWh). The Engine.electricityConsumption and Engine.consumptionFactorsPerSpeed are used to determine the actual electricity consumption on a road segment and then the cost per electricity unit is applied on this electricity consumption to calculate the energy costs.
If no value is provided no energy cost is used and the reported energy cost is zero.

OffRoadRouteLocation

extends RouteLocation
used by OffRoadWaypoint
since 2.0

Specifies a route location based on a coordinate that is usually located off the road network. A route actually reaches this coordinate, and the distance and the assumed travel time from that location to the road network is included in the route totals. Optionally another coordinate on the road network can be given to specify more precisely to which road the coordinate off the road shall be connected. The behavior which road will be chosen in such a case is influenced by the violations parameters. See route locations documentation for details.

Field Name Type Required Default Since Description
offRoadCoordinate Coordinate yes - 2.0

Specifies the coordinate off the road that the route actually reaches. If OffRoadRouteLocation.roadAccessCoordinate is not specified then this coordinate is used to determine the nearest road on the road network.

When using the PTV xLocate service, enter the Location.referenceCoordinate here.

roadAccessCoordinate Coordinate no - 2.0

Specifies an optional coordinate to specify to which road the OffRoadRouteLocation.offRoadCoordinate is connected to. This is especially useful if location is not connected to the geographically closest road but to some road further away.

When using the PTV xLocate service, enter the Location.roadAccessCoordinate here.

sideOfStreetRestriction SideOfStreetRestriction no SideOfStreetRestr ... 2.20

Specifies how the street at which the location is located can be used. With this parameter it's possible to use the side of the street on which the OffRoadRouteLocation.offRoadCoordinate is located.

Will be ignored when used with calculateReachableAreas or calculateReachableLocations.

OnRoadRouteLocation

extends RouteLocation
used by OnRoadWaypoint
since 2.0

Specifies a route location based on a coordinate will be treated as if it was located on the road network. The route actually reaches its link point on the road network, but usually not the given coordinate. The behavior which road will be chosen is influenced by the violations parameters. See route locations documentation for details.

Field Name Type Required Default Since Description
coordinate Coordinate yes - 2.0

Specifies the coordinate which is used to determine the nearest road on the road network.

When using the PTV xLocate service, enter the Location.referenceCoordinate here

considerAlternativeNearByRoads Boolean no false 2.19 If true, roads within a radius of 500 meters around the location are considered as alternative start/end points of the route. Otherwise, the route always starts/ends at the nearest road. Note that this feature is currently available only for the xRoute calculateRoute service for the first and last waypoint. If it is set to true for an intermediate xRoute via waypoint this parameter is ignored and always the nearest road is used. All other services return an exception if this parameter is set to true.
sideOfStreetRestriction SideOfStreetRestriction no SideOfStreetRestr ... 2.26

Specifies how the street at which the location is located can be used. With this parameter it's possible to use the side of the street on which the OnRoadRouteLocation.coordinate is located.

Will be ignored when used with calculateReachableAreas or calculateReachableLocations.

SearchSpaceBounds

used by GeographicRestrictions
since 2.18

The search space bounds can be used to restrict the route calculation or high-performance routing networks to a custom excerpt of the map. This is particularly useful when you know in advance the area in which your routes will take place and can help to improve the performances.

Field Name Type Required Default Since Description
restrictionMode RestrictionMode no RestrictionMode.NONE 2.18 The restriction mode.
customBounds Bounds no - 2.18 The minimum bounds to which the search space should be restricted, their coordinate format is specified by RequestBase.coordinateFormat. The effective bounds may be a bit larger due to alignment with the data source.

SubdivisionFallbackLimitation

extends ResultLimitation
since 2.23

This result limitation indicates that GeographicRestrictions.allowedCountries contains a country subdivision code that cannot be used like this due to the available data, and that instead the enclosing country code was used. In such cases, routes are constrained to the country, rather than only the subdivision.

Field Name Type Required Default Since Description
requestedSubdivisionCode String yes - 2.23 The country subdivision code that was requested in allowedCountries, but cannot be used.
fallbackCountryCode String yes - 2.23 The enclosing country that is used as a fallback instead.

TravelTimeBasedHorizon

extends Horizon
since 2.1

Represents a geographical horizon that is described by a travel time. Every point or road segment that is reachable from the source within the specified travel time is included in the horizon.

Field Name Type Required Default Since Description
travelTime NonZeroDuration (double) yes - 2.1 A travel time that specifies the range of the horizon.
Enumeration

RestrictionMode

used by SearchSpaceBounds
since 2.18

Defines the restriction mode how to restrict the route calculation using a bounding box.

Enumeration Value Since Description
NONE 2.18 No restriction by bounding box.
AUTOMATIC 2.18 Use a bounding box automatically calculated from the route locations to restrict the search space.
CUSTOM 2.18 Use the custom bounding box to restrict the search space.
Enumeration

RouteCalculationCriteria

used by RouteOptions
since 2.21

Specifies what the routing algorithm should optimize for.

Enumeration Value Since Description
ABSTRACT_COSTS 2.21 Calculate the route according to the best abstract costs based on distance time weighting and penalties.
MONETARY_COSTS 2.21 Calculate the route according to the best monetary costs based on the parameters in the monetary cost options and including toll costs.
If set, it is required to specify a currency in the route options.

Represents the type of the route calculation algorithm. It can be used as input parameter or the type is reported, for instance as part of a distance matrix calculation.

Enumeration Value Since Description
CONVENTIONAL 2.5 Route calculation based on a standard algorithm. Heuristic elements are used to improve performance. If this element is used as input it the routing is forced to use the conventional algorithm.
HIGH_PERFORMANCE_ROUTING_WITH_FALLBACK_CONVENTIONAL 2.5 This element is used only as input. It indicates that the service tries to use a high-performance routing network, and if no adequate data is found conventional routing is used instead.
HIGH_PERFORMANCE_ROUTING 2.5 High-performance route calculation based on pre-calculated, profile-dependent additional routing networks. If it is used as input and no such network which fits the current profile settings is available an exception is thrown.
Enumeration

SideOfStreetRestriction

used by OffRoadRouteLocation, OnRoadRouteLocation
since 2.20

Specifies how the street at which the location is located can be used.

Enumeration Value Since Description
ANY_SIDE 2.20 No restrictions on the side of the street, both sides can be used.
SAME_SIDE_AS_LOCATION 2.20 The street side on which the location is situated should be used.

Diagrams

Geographic Restrictions

Route Location