xdima

XDima Operations

SOAP/JSON

Synchronous API

since 2.1
Operation Name Request Type Response Type Since Description
createDistanceMatrix CreateDistanceMatrixRequest DistanceMatrixResponse 2.1 Creates a distance matrix by calculating road distances and travel times between given locations. An InvalidValueFault is returned if the Feature Layer theme PTV_RestrictionZones is activated. PTV_RestrictionZones cannot be used for distance matrices. Returns a summary of this distance matrix calculation.
listDistanceMatrices ListDistanceMatricesRequest DistanceMatrixListResponse 2.1 Lists available distance matrices including their meta data considering user privileges and concurrent usage. See technical concept about multitenancy how to list matrices for all available tenants or scopes.
updateDistanceMatrix UpdateDistanceMatrixRequest DistanceMatrixResponse 2.5 Updates an existing distance matrix by extending it with new locations or overwriting existing entries. Returns a summary of this distance matrix calculation.
deleteDistanceMatrix DeleteDistanceMatrixRequest VoidResponse 2.1 Deletes a distance matrix with a given ID considering user privileges and concurrent usage.
getDistanceMatrix GetDistanceMatrixRequest DistanceMatrixResponse 2.5 Gets the distance matrix contents for specific matrix elements specified as relations between route locations or specified as an array of start and destination locations. Returns arrays representing the matrix contents for the requested part of the matrix.
SOAP/JSON

Asynchronous API

since 2.1
Operation Name Request Type Response Type Since Description
startCreateDistanceMatrix CreateDistanceMatrixRequest Job 2.1

This is the asynchronous version of createDistanceMatrix.

Calling this operation will not block until the result has been calculated. Instead of a result object, a Job object is returned which identifies the started calculation. To get status updates on a running job, use the operation watchJob. If it changes to SUCCEEDED, the calculation was successful and the result can be obtained using fetchDistanceMatrixResponse. If the job ended with status FAILED, fetchDistanceMatrixResponse throws the exception that occurred during calculation.
startUpdateDistanceMatrix UpdateDistanceMatrixRequest Job 2.5

This is the asynchronous version of updateDistanceMatrix.

Calling this operation will not block until the result has been calculated. Instead of a result object, a Job object is returned which identifies the started calculation. To get status updates on a running job, use the operation watchJob. If it changes to SUCCEEDED, the calculation was successful and the result can be obtained using fetchDistanceMatrixResponse. If the job ended with status FAILED, fetchDistanceMatrixResponse throws the exception that occurred during calculation.
fetchDistanceMatrixResponse JobRequest DistanceMatrixResponse 2.1

Fetches results of type DistanceMatrixResponse for the given job. If the calculation ended with an exception, fetchDistanceMatrixResponse will rethrow it. If the id of the job is unknown, a XServerException with message 'unknown id' is thrown.

watchJob WatchRequest Job 2.1

Returns the status of the given job.

This operation behaves exactly like the watchJob operation of the xRuntime service.
stopJob JobRequest Job 2.1

Attempts to stop a running job. If the status of the job changes to SUCCEEDED, preliminary results can be fetched, if available.

This operation behaves exactly like the stopJob operation of the xRuntime service.
deleteJob JobRequest Job 2.1

Attempts to delete a running job. If successful, the returned job will have state DELETED.

This operation behaves exactly like the deleteJob operation of the xRuntime service.

Types

CreateAndGetDistanceMatrixRequest

extends CreateDistanceMatrixRequest
since 2.15

This type represents settings for the creation and immediate retrieval of the contents of a new distance matrix. The matrix is not persisted. The id field of the summary is not filled. Be aware that the default settings of the DistanceMatrixContentsResultFields are that only the travel time is returned. If other contents like distance or violation flags should be returned a specific setting of the DistanceMatrixContentsResultFields are required. Note the following limitations for this request type:

In case the toll costs are of interest, it is sufficient to set the the result field DistanceMatrixContentsResultFields.tollCosts. As the distance matrix is not persisted, the field DistanceMatrixOptions.persistTollCosts is ignored.

Field NameTypeRequiredDefaultSinceDescription
resultFields DistanceMatrixContentsResultFields no- 2.15 Specifies the result fields available in the response.
contentsOptions DistanceMatrixContentsOptions no- 2.20 Specifies how to return the distance matrix contents.

CreateDistanceMatrixRequest

extends RequestBase
extended by CreateAndGetDistanceMatrixRequest, ImportDistanceMatrixRequest
used by XDima
since 2.1

This type represents settings for the creation of a new distance matrix.

Field Name Type Required Default Since Description
startLocations RouteLocation[] 1..* - 2.1 The list of start locations.
destinationLocations RouteLocation[] 0..* - 2.1 The list of destination locations. If this list is empty, the destination locations are equal to the start locations.
label UserDefinedName (String) no - 2.1 The label or description of this distance matrix. This is especially useful if the distance matrices should be listed in the PTV xServer dashboard.
distanceMatrixOptions DistanceMatrixOptions no - 2.5 Calculation options for the distance matrix.

DeleteDistanceMatrixRequest

extends RequestBase
used by XDima
since 2.1

This type represents settings for deleting a distance matrix.

Field Name Type Required Default Since Description
id String yes - 2.1 The ID of the distance matrix to be deleted.

DistanceMatrixContents (abstract)

extended by DistanceMatrixContentsArrays, DistanceMatrixContentsEncodedArrays
used by DistanceMatrixResponse, ExtendDistanceMatrixWithContentsRequest, ImportDistanceMatrixRequest
since 2.5

This type represents the contents of a distance matrix. It contains for each element corresponding to a pair of locations (start/destination) computed properties like road distance, travel time or additional data. This data is arranged in arrays. Please check the documentation of the associated requests for the data organization in the response.

No fields defined.

DistanceMatrixContentsArrays

extends DistanceMatrixContents
since 2.5

This type represents the distance matrix contents using normal arrays. For the mapping of distances/travel times/flags to pairs of locations or relations see the documentation of the corresponding GetDistanceMatrixByLocationsRequest and GetDistanceMatrixByRelationsRequest.

Field Name Type Required Default Since Description
distances Distance[] (Double[]) 0..* - 2.5 The distances of the requested matrix elements.
travelTimes Duration[] (Double[]) 0..* - 2.5 The travel times of the requested matrix elements.
violated Boolean[] 0..* - 2.5 The violated flags of the requested matrix elements.
estimatedByDirectDistance Boolean[] 0..* - 2.5 The estimated by direct distance flags of the requested matrix elements.
tollCosts Double[] 0..* - 2.20 The toll costs of the requested matrix elements in the currency that has been provided in the options of the corresponding CreateDistanceMatrixRequest.

DistanceMatrixContentsEncodedArrays

extends DistanceMatrixContents
since 2.20

This type represents the distance matrix contents. It encodes the array of each attribute of a matrix element as byte arrays. For a detailed description of the byte arrays format see distance matrices.

Field Name Type Required Default Since Description
distances byte[] no - 2.20 The distances of the requested matrix elements expressed in meters.
travelTimes byte[] no - 2.20 The travel times of the requested matrix elements expressed in milliseconds.
violated byte[] no - 2.20 The violated flags of the requested matrix elements.
estimatedByDirectDistance byte[] no - 2.20 The estimated by direct distance flags of the requested matrix elements.
tollCosts byte[] no - 2.20 The toll costs of the requested matrix elements in the currency that has been provided in the options of the corresponding CreateDistanceMatrixRequest.
travelTimeProfiles byte[] no - (2.29) The travel time profiles of the requested matrix elements..

This field is experimental. Before using it, make sure you understand the implications of Experimental features.

DistanceMatrixContentsOptions

used by CreateAndGetDistanceMatrixRequest, GetDistanceMatrixRequest
since 2.20

Specifies how to fill distance matrix contents.

Field Name Type Required Default Since Description
returnEncodedArrays Boolean no false 2.20 Indicates if the contents arrays shall be return encoded as byte arrays or as normal arrays.
startTime XMLGregorianCalendar no - (2.10) Provide the date/time to estimate the travel time in case of Multiple Travel Times Distance Matrix. If not provided, an exception is thrown.

This field is experimental. Before using it, make sure you understand the implications of Experimental features.

DistanceMatrixContentsResultFields

used by CreateAndGetDistanceMatrixRequest, DistanceMatrixResultFields
since 2.5

The type represents settings for the result fields for retrieving distance matrix relations.

Field Name Type Required Default Since Description
distances Boolean no false 2.5 Indicates if distances should be included in the result.
travelTimes Boolean no true 2.5 Indicates if travel times should be included in the result.
violated Boolean no false 2.5 Indicates if violated flags should be included in the result.
estimatedByDirectDistance Boolean no false 2.5 Indicates if estimated by direct distance flags should be included in the result.
tollCosts Boolean no false 2.20 Indicates if toll costs should be included in the result.
travelTimeProfiles Boolean no false (2.29) Indicates if travel time profiles should be included in the result. It is only applicable if the distance matrix is created with the time-consideration scenario MultipleTravelTimesConsideration. Please note that querying travel time profiles is only allowed in combination with the option returnEncodedArrays set to true and that the startTime must be left empty.

This field is experimental. Before using it, make sure you understand the implications of Experimental features.

DistanceMatrixDescription

used by DistanceMatrixInformation
since 2.1

This type represents meta data about a distance matrix.

Field Name Type Required Default Since Description
summary DistanceMatrixSummary yes - 2.1 The summary of this distance matrix.
startLocations RouteLocation[] 0..* - 2.1 The start locations of this distance matrix.
destinationLocations RouteLocation[] 0..* - 2.1 The destination locations of this distance matrix.
directDistanceRelations Relation[] 0..* - 2.1 The list of relations in this distance matrix that could not be calculated without error. Relations are approximated by direct distance if an error occurred during route calculation, for example that a location could not be linked to the road network or no route could be found for the current vehicle profile.
distanceMatrixOptions DistanceMatrixOptions no - 2.5

The options used for calculation of this distance matrix.

Warning: Options are removed from the response if they cannot be represented using the requested API version. This situation might occur if a more recent API version was used for the creation of the distance matrix than for this list request. In general, it is not recommended to mix different API versions.
profile RequestProfile no - 2.5

The profile used for calculation of this distance matrix.

Warning: Profile elements are removed from the response if they cannot be represented using the requested API version. This restriction also applies to elements of the stored profile used for calculation of this distance matrix. If the returned profile should be used as a request profile in a subsequent request (e.g. for creating another distance matrix or for a route calculation), it is recommended to specify the same stored profile as in the original create request. In general, it is not recommended to mix different API versions.
tenant String no - 2.4 The tenant is returned only for administrators.
scope ScopeName (String) no - 2.4 The user defined scope.
lastUsedAt XMLGregorianCalendar no - 2.4 Indicates the date the distance matrix was used the last time.

DistanceMatrixInformation

used by DistanceMatrixListResponse
since 2.1

The result that lists a description of a single distance matrix or the exception that was returned querying the distance matrix ID.

Field Name Type Required Default Since Description
distanceMatrixDescription DistanceMatrixDescription no - 2.1 Meta information that describes the current distance matrix.
listException SuppressedXServerException no - 2.5 Exception in case a requested distance matrix ID is not existing on the server.

DistanceMatrixListResponse

extends ResponseBase
used by XDima
since 2.1

This type represents a list of meta information on distance matrices.

Field Name Type Required Default Since Description
distanceMatrixInformation DistanceMatrixInformation[] 0..* - 2.1 The result list containing information about each distance matrix. If specific distance matrix IDs have been requested there is one entry in the list for each requested ID in the same order.

DistanceMatrixResponse

extends ResponseBase
used by XDima
since 2.1

This type represents a summary of the meta information on a distance matrix and also contains contents of the distance matrix if requested.

Field Name Type Required Default Since Description
summary DistanceMatrixSummary no - 2.1 The summary of this distance matrix.
contents DistanceMatrixContents no - 2.5 The contents of the distance matrix.

DistanceMatrixResultFields

used by GetDistanceMatrixRequest
since 2.5

Settings for the result fields of the contents of a distance matrix.

Field Name Type Required Default Since Description
summary Boolean no false 2.5 Indicates if the summary should be included in the result.
distanceMatrixContentsResultFields DistanceMatrixContentsResultFields no - 2.5 Further possibilities to customize the result of the contents of the distance matrix.

ExtendDistanceMatrixRequest

extends UpdateDistanceMatrixRequest
since 2.5

This request can be used to extend an existing distance matrix by new locations. At least one start location or one destination location must be specified. All new matrix elements introduced by the new locations are calculated by this request. It is allowed that some or even all of the given start and destination locations already exist in the distance matrix, such locations are just ignored and have no effect.

Field Name Type Required Default Since Description
startLocations RouteLocation[] 0..* - 2.5 Array of start locations to be added to the current distance matrix.
destinationLocations RouteLocation[] 0..* - 2.5 Array of destination locations to be added to the current distance matrix.

ExtendDistanceMatrixWithContentsRequest

extends UpdateDistanceMatrixRequest
since 2.30

This request can be used to extend an existing distance matrix by new locations. This request allows to extend by row or by column. Therefore, either the startLocations (or destinationLocations) should contain all the startLocations (or all the destinationLocations). The other array of locations should contain only the new locations to add. All new matrix elements introduced by the new locations are not calculated, but should be set in the contents attribute. Overwritten of existing elements is forbidden.

Field Name Type Required Default Since Description
startLocations RouteLocation[] 0..* - 2.30 Array of start locations. This list should contain either all the start locations of the extended matrix, or only the new ones to be added.
destinationLocations RouteLocation[] 0..* - 2.30 Array of destination locations. This list should contain either all the destination locations of the extended matrix, or only the new ones to be added.
contents DistanceMatrixContents yes - 2.30 The distance matrix contents for the start locations and destination locations that have been provided.
The size of the arrays has to match the product of the number of start locations multiplied with the number of destination locations.
TravelTimes and distances are imported with a default value of 0 if the array is not provided.
Violated and estimatedByDirectDistance are imported with a default value of false if the array is not provided.
Toll costs cannot be imported.

GetDistanceMatrixByLocationsRequest

extends GetDistanceMatrixRequest
since 2.20

With this request, it is possible to query slices of matrices. If m start locations and n destination locations are requested, the first n elements of the array correspond to the relations between the first start location given in the request and all n destination locations in the same order as the destination locations are given in the request. The next n elements of the array correspond to the relations between the second start location given in the request and all n destination locations, and so on.
The maximum number of relations (i.e. the number of start locations times the number of destination locations) is limited to 250000. See xdima.get.maximumNumberOfRelations in the Server Configuration how to increase this limit..

Field Name Type Required Default Since Description
startLocations RouteLocation[] 1..* - 2.20 Specifies the start locations to be retrieved from the matrix.
destinationLocations RouteLocation[] 1..* - 2.20 Specifies the destination locations to be retrieved from the matrix.

GetDistanceMatrixByRelationsRequest

extends GetDistanceMatrixRequest
since 2.5

This request can be used to query specific relations. The output order in the response corresponds to the input order of the relations.
The maximum number of relations (i.e. the number of start locations times the number of destination locations) is limited to 250000. See xdima.get.maximumNumberOfRelations in the Server Configuration how to increase this limit..

Field Name Type Required Default Since Description
relations Relation[] 1..* - 2.5 Specifies for which relations the distance matrix data should be returned.

GetDistanceMatrixRequest (abstract)

extends RequestBase
extended by GetDistanceMatrixByLocationsRequest, GetDistanceMatrixByRelationsRequest
used by XDima
since 2.5

The service method getDistanceMatrix accommodates several use-cases. This abstract type is the common denominator of the corresponding request objects.

Field Name Type Required Default Since Description
id String yes - 2.5 The ID of the distance matrix to be used.
resultFields DistanceMatrixResultFields no - 2.5 Specifies the result fields available in the response.
contentsOptions DistanceMatrixContentsOptions no - 2.20 Specifies how to return the distance matrix contents.

ImportDistanceMatrixRequest

extends CreateDistanceMatrixRequest
since 2.27

This type represents settings for the import of a new distance matrix.
The locations provided as start locations and as destination locations have to be unique. If no destination locations are provided, the start locations are also taken as destination locations.
The size of the arrays has to match the product of the number of start locations multiplied with the number of destination locations.
TravelTimes and distances are imported with a default value of 0 if the array is not provided.
Violated and estimatedByDirectDistance are imported with a default value of false if the array is not provided.
Be aware of the following limitations:

  • The maximum number of relations (i.e. the number of start locations times the number of destination locations) is limited to 250000. See xdima.get.maximumNumberOfRelations in the Server Configuration how to increase this limit.
  • Toll costs cannot be imported.

Field Name Type Required Default Since Description
contents DistanceMatrixContents yes - 2.27 The distance matrix contents for the start locations and destination locations that have been provided.
The size of the arrays has to match the product of the number of start locations multiplied with the number of destination locations.
TravelTimes and distances are imported with a default value of 0 if the array is not provided.
Violated and estimatedByDirectDistance are imported with a default value of false if the array is not provided.
Toll costs cannot be imported.

ListDistanceMatricesRequest

extends RequestBase
used by XDima
since 2.1

This type represents settings for listing meta information of distance matrices.

Field Name Type Required Default Since Description
ids String[] 0..* - 2.1 The IDs of all distance matrices that should be listed. If the list is null or empty, all available distance matrices will be listed.
resultFields ListDistanceMatricesResultFields no - 2.1 Specifies the result fields that will be available in the response.

ListDistanceMatricesResultFields

used by ListDistanceMatricesRequest
since 2.1

Settings for the result fields of the meta information of distance matrices.

Field Name Type Required Default Since Description
startLocations Boolean no false 2.1 Indicates if a list of start locations should be included in the result.
destinationLocations Boolean no false 2.1 Indicates if a list of destination locations should be included in the result.
directDistanceRelations Boolean no false 2.1 Indicates if a list of relations that are approximated by direct distance should be included in the result.
distanceMatrixOptions Boolean no false 2.5 Indicates if the options of the distance matrices should be included in the result.
profiles Boolean no false 2.5 Indicates if the profiles should be included in the result.

Relation

used by DistanceMatrixDescription, GetDistanceMatrixByRelationsRequest
since 2.1

A relation between an start location and a destination location.

Field Name Type Required Default Since Description
startLocation RouteLocation yes - 2.1 The start location.
destinationLocation RouteLocation yes - 2.1 The destination location.

UpdateDistanceMatrixRequest (abstract)

extends RequestBase
extended by ExtendDistanceMatrixRequest, ExtendDistanceMatrixWithContentsRequest
used by XDima
since 2.5

The service method updateDistanceMatrix accommodates several use-cases. This abstract type for the requests is the common denominator.

Field Name Type Required Default Since Description
id String yes - 2.5 The ID of the distance matrix to be used.

Diagrams

Operations Overview

Job Progress

Create Requests

Data Retrieval Requests

Update Requests

Responses