Types
Use direct distance. This mode does not require a distance matrix or a road network.
| No fields defined. |
This type represents options of a distance matrix.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| timeConsideration | TimeConsideration | no | - | 2.8 | Set this parameter if time dependent features should be considered for the distance matrix calculation. The different scenarios of time consideration are explained in more detail in the technical concept about time consideration. If the object is NULL, all data which have time restrictions are not considered. For some scenarios a reference time is needed to match properties with a time domain against this reference time. If for this time no time zone is defined, i.e. it represents a local time, all matrix locations are checked for their time zone offsets. If a time zone cannot be determined for such a location, this location is not taken into further consideration. So, in a first step a set of locations with calculated time zones is determined. If this set contains no elements, an exception is thrown. When the time zones differ for some locations, then the time zone containing most locations is used and a result limitation is added to the result. If all locations are in the same time zone, then this time zone is used and the result is calculated as usual. Please note that the time consideration values ExactTimeConsiderationAtStart and ExactTimeConsiderationAtArrival are not available and if used an exception will be returned. |
| contentSnapshotId | String | no | - | 2.8 | Specifies the content snapshot to use. If no snapshot ID is set, the most recent content is used. |
| highPerformanceRoutingNetworkId | String | no | - | 2.18 | Specifies the high-performance routing network to use. Besides, the routing type must be explicitly set to RoutingType.HIGH_PERFORMANCE_ROUTING otherwise a ParameterConflictFault is thrown. The profile and request parameters of the high-performance routing network are used for linking and routing. The stored profile of the RequestBase will be ignored. Throws a DataNotAvailableFault if the high-performance routing network with the given id does not exist. |
| geographicRestrictions | GeographicRestrictions | no | - | 2.5 | Geographic restrictions that are considered for each routing that is done during the distance matrix calculation. |
| detourFactor | Double | no | 1.38 | 2.5 | A factor that describes the average detour an actual route on the road requires, compared to the direct distance. This factor is used to approximate a relation that could not be calculated using the road network. |
| averageSpeed | Speed (Double) | no | 60.0 | 2.5 | The average speed of the vehicle. This parameter is used to approximate a relation that could not be calculated using the road network. |
| routingType | RoutingType | no | RoutingType.HIGH_ ... | 2.5 | Strategy to decide if high-performance routing or conventional routing is used. For further explanation see the definition of RoutingType. |
| persistTollCosts | Boolean | no | false | 2.20 | Specifies whether to calculate and persist the toll costs of each relation in the distance matrix. The toll costs are persisted and returned in one currency. If no currency is set in the request, an exception is thrown. Note that the aggregated toll costs returned by the xDima service can differ slightly from the toll costs returned by the xRoute service because price calculation, currency conversion and rounding is carried out in a different order. Note that the usage of detailed toll data is required to use this feature. Otherwise an exception is thrown. |
| currency | CurrencyCode (String) | no | - | 2.20 | Specifies the currency in which the toll costs should be persisted and returned. If the option to persist the toll costs is not set, an exception is thrown. |
| binaryFeatureLayer | EncodedContent (String) | no | - | 2.19 | Specifies the binary Feature Layer to be considered in the request. |
| useDetailedToll | Boolean | no | - | (2.22) | Specifies if detailed toll data shall be used for toll calculation. If this parameter is set to false detailed toll data is ignored and only basic toll data is used. This request parameter overwrites core.tollOptions.useDetailedToll in the Server Configuration. This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
| exchangeRates | ExchangeRates | no | - | 2.26 | Specifies the exchange rates that should be used for the toll price conversion to the target currency. |
The progress for a running distance matrix calculation.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| status | ProgressStatus | yes | - | 2.1 | The action currently being performed. |
| calculationProgress | Percent (Double) | no | - | 2.1 | The progress of the action CALCULATING_MATRIX. |
| routingType | RoutingType | no | - | 2.5 | Indicates what route calculation algorithm is being used for the distances matrix calculation. |
Represents the meta information of a distance matrix.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| id | String | no | - | 2.1 | The ID of the distance matrix which is generated when the distance matrix is created. Use this ID to reference the matrix for further use. |
| numberOfStartLocations | PositiveInteger (int) | yes | - | 2.1 | The number of start locations in the distance matrix. |
| numberOfDestinationLocations | PositiveInteger (int) | yes | - | 2.1 | The number of destination locations in the distance matrix. |
| percentageOfDirectDistanceRelations | Percent (double) | yes | - | 2.1 | Percentage of relations in the distance matrix which has not been calculated successfully. It depends on the use case and the geographical region which values can be tolerated or not. |
| routingType | RoutingType | no | - | 2.5 | Indicates what route calculation algorithm was used for the distances matrix calculation. If a profile dependent high-performance routing network is configured but there is no matching high-performance graph for the called profile the routing mode will fall back to profile independent routing. |
| label | UserDefinedName (String) | no | - | 2.1 | The optional label of the distance matrix, if it was specified in the request. This label is only used for displaying the distance matrix, e.g. in the dashboard, and is not considered in any other way. |
DistanceMode (abstract)
extended by DirectDistance, ExistingDistanceMatrix, EstimateByReferenceMatrix, ExistingDistanceMatrixPerVehicle
used by CoverLocationsRequest, OptimizeVisitSequenceRequest, PlanClustersRequest, PlanVisitsRequest, PlanToursRequest
since 2.1
The abstract base type for different modes how distances can be retrieved for clustering or tour planning.
| No fields defined. |
Use an existing distance matrix, for example from a createDistanceMatrix request. The distance matrix has to contain every location that is necessary for the tour or cluster planning, otherwise an exception is returned.
Possible status values for a distance matrix progress.
| Enumeration Value | Since | Description |
|---|---|---|
| PREPROCESSING | 2.1 | Indicates that some tasks have to be done before calculating the matrix. For example loading high-performance routing networks. |
| CALCULATING_MATRIX | 2.1 | The actual progress of this state is available in DistanceMatrixProgress.calculationProgress. |
| DONE | 2.1 | Indicates that the calculation of the distance matrix is finished. |