XMatch Operations
SOAP/JSON
Synchronous API
since 2.21
| Operation Name | Request Type | Response Type | Since | Description |
|---|---|---|---|---|
| matchTrack | MatchTrackRequest | TrackResponse | 2.21 | Matches a complete track and returns the path(s) driven by the vehicle |
| matchPositions | MatchPositionsRequest | PositionsResponse | 2.21 | Matches positions which do not necessarily belong together |
SOAP/JSON
Asynchronous API
since 2.21
| Operation Name | Request Type | Response Type | Since | Description |
|---|---|---|---|---|
| startMatchTrack | MatchTrackRequest | Job | 2.21 |
This is the asynchronous version of matchTrack. 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 fetchTrackResponse. If the job ended with status FAILED, fetchTrackResponse throws the exception that occurred during calculation. |
| fetchTrackResponse | JobRequest | TrackResponse | 2.21 |
Fetches results of type TrackResponse for the given job. If the calculation ended with an exception, fetchTrackResponse will rethrow it. If the id of the job is unknown, a XServerException with message 'unknown id' is thrown. |
| watchJob | WatchRequest | Job | 2.21 |
Returns the status of the given job. This operation behaves exactly like the watchJob operation of the xRuntime service. |
| stopJob | JobRequest | Job | 2.21 |
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.21 |
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
Allows to influence the position matching algorithm.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| calculationMode | CalculationMode | no | CalculationMode.S ... | 2.21 | Defines the calculation mode of the position matching algorithm. |
| customCalculationModeConfiguration | EncodedContent (String) | no | - | 2.21 | Defines a specific configuration for calculation mode CUSTOM in an encoded form. |
Request to match unrelated positions on a map.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| positions | Position[] | 1..* | - | 2.21 | The positions to be matched (independent of each other). |
| resultFields | MatchPositionsResultFields | no | - | (2.23) | Specifies which fields of the PositionsResponse shall be returned.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
| matchPositionsOptions | MatchPositionsOptions | no | - | 2.21 | Allows to influence the position matching algorithm. |
Request to match unrelated positions on a map.
This type is experimental. Before using it, make sure you understand the implications of Experimental features.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| providerId | Boolean | no | false | (2.23) | Specifies if the MatchedSegment.providerId shall be returned.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
Allows to influence the track matching algorithm.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| calculationMode | CalculationMode | no | CalculationMode.S ... | 2.21 | Defines the calculation mode of the track matching algorithm. |
| customCalculationModeConfiguration | EncodedContent (String) | no | - | 2.21 | Defines a specific configuration for calculation mode CUSTOM in an encoded form. |
Request to match positions describing a track on a map.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| trackPositions | TrackPosition[] | 1..* | - | 2.21 | The positions to be matched to a track (ordered). -- |
| resultFields | MatchTrackResultFields | no | - | 2.21 | Specifies which fields of the TrackResponse shall be returned. |
| matchTrackOptions | MatchTrackOptions | no | - | 2.21 | Allows to influence the track matching algorithm. |
Request to match positions on a map which belong to a track.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| matchedPaths | Boolean | no | false | 2.21 | Specifies if the TrackResponse.matchedPaths shall be returned for the track. |
| geometry | Boolean | no | false | 2.21 | Specifies if the TrackResponse.geometry shall be returned for the track. |
| matchedTrackPositions | Boolean | no | false | 2.21 | Specifies if the TrackResponse.matchedTrackPositions shall be returned for the track. |
| encodedPath | Boolean | no | false | 2.21 | Specifies if the MatchedPath.encodedPath shall be returned. |
| providerId | Boolean | no | false | (2.23) | Specifies if the MatchedSegment.providerId shall be returned.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
Detailed information about a continuous part of a matched track.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| distance | Distance (double) | yes | - | 2.21 | The distance of the complete path. It is the sum of distances of all TrackResponse.matchedPaths and hence is a whole number without decimal places. |
| encodedPath | EncodedContent (String) | no | - | 2.21 | Encoded string describing a complete track. Use this string as an input of a route request to calculate routing related information like toll prices or emissions. It is available only if the encodedPath is requested by MatchTrackResultFields.encodedPath. |
| startTrackPositionIndex | Index (Integer) | no | - | 2.21 | The index in the list of TrackResponse.matchedTrackPositions of the start position of this path. It is available only if the list of matchedTrackPositions is requested by MatchTrackResultFields.matchedTrackPositions. |
| endTrackPositionIndex | Index (Integer) | no | - | 2.21 | The index in the list of TrackResponse.matchedTrackPositions of the end position of this path. It is available only if the list of matchedTrackPositions is requested by MatchTrackResultFields.matchedTrackPositions. |
Detailed information about a position matched on a map
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| detail | MatchDetail | yes | - | 2.21 | Gives information on the result of this match, i.e. whether the position was matched successfully or not. NOT_CONSIDERED will not occur here. |
| matchedSegment | MatchedSegment | no | - | 2.21 | The segment to which the input position matches. It is available only if MatchedPosition.detail is MATCH_SUCCESSFUL. |
| matchedCoordinate | Coordinate | no | - | 2.21 | The coordinate on the segment to which the input position matches. It is available only if MatchedPosition.detail is MATCH_SUCCESSFUL. |
| quality | PositionQuality | no | - | 2.21 | Some information on the quality of the match. It is available only if MatchedPosition.detail is MATCH_SUCCESSFUL. |
Describes details on how and which segment a position was matched to.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| id | SegmentId (String) | yes | - | 2.21 | The Id of the matched segment. |
| polyline | EncodedGeometry | yes | - | 2.21 | The polyline of the matched segment |
| providerId | String | no | - | (2.23) | The provider id of the matched segment
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
Detailed information about a position on a track matched on a map
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| detail | MatchDetail | yes | - | 2.21 | Gives information on the result of this match, i.e. whether the position was matched successfully or whether the position is considered as part of the track or not. |
| distanceFromPreviousMatch | Distance (Double) | no | - | 2.21 | The travel distance from the MatchedPosition.matchedCoordinate of the previous matched position to the MatchedPosition.matchedCoordinate of this matched position. It is available only if MatchedTrackPosition.detail is MATCH_SUCCESSFUL. |
| matchedSegment | MatchedSegment | no | - | 2.21 | The segment to which the input position matches. It is available only if MatchedTrackPosition.detail is MATCH_SUCCESSFUL. |
| matchedCoordinate | Coordinate | no | - | 2.21 | The coordinate on the segment to which the input position matches. It is available only if MatchedTrackPosition.detail is MATCH_SUCCESSFUL. |
| quality | PositionQuality | no | - | 2.21 | Some information on the quality of the match. It is available only if MatchedTrackPosition.detail is MATCH_SUCCESSFUL. |
Describes a position in terms of a coordinate and additional attributes to help matching it on a map.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| coordinate | Coordinate | yes | - | 2.21 | The coordinate of the position to be matched |
| heading | AbsoluteDirection (Double) | no | - | 2.21 | The angle of the direction of travel |
Describes the quality of the position match.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| matchDistance | Distance (double) | yes | - | 2.21 | The straight-line distance (Euclidean distance) from the input position to the matching segment |
| angleDifference | AngleDifference (Double) | no | - | 2.21 | The difference between the angle of the heading of the input position and the angle of the matching segment |
Response of a matchPositions request which contains all matched segments.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| matchedPositions | MatchedPosition[] | 0..* | - | 2.21 | Detailed information about the matches of the input positions. There is one matched position for every input position. |
Describes a position which belongs to a track by additional track related attributes.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| distanceFromPreviousPosition | Distance (Double) | no | - | 2.21 | The travel distance from the previous position to this position. This value can be provided to improve the quality of the track matching. |
Response of a matchTrack request.
| Field Name | Type | Required | Default | Since | Description |
|---|---|---|---|---|---|
| distance | Distance (double) | yes | - | 2.21 | The distance of the complete track. It is the sum of distances of all TrackResponse.matchedPaths and hence is a whole number without decimal places. |
| matchedPaths | MatchedPath[] | 0..* | - | 2.21 | The matched paths the track consists of. -- |
| geometry | EncodedGeometry | no | - | 2.21 | the geometry of the paths (i.e. a collection of polylines). -- |
| matchedTrackPositions | MatchedTrackPosition[] | 0..* | - | 2.21 | Detailed information on the matches of the input track positions -- |
Enumeration to define the calculation behaviour of the algorithm, i.e. if the focus of calculation is on performance, quality or both.
| Enumeration Value | Since | Description |
|---|---|---|
| PERFORMANCE | 2.21 | The algorithm's focus is on performance. This means to take into account a higher count of failed matches and in the case of track matching that the matched track may be split into several paths. |
| STANDARD | 2.21 | The algorithm chooses a standard trade-off between quality and performance. |
| QUALITY | 2.21 | The algorithm's focus is on high solution quality. This means that as much as possible of the input positions are matched and taken into account. Though the processing time of the request can be high. |
| CUSTOM | 2.21 | The algorithm's focus is adapted to the customer's needs. It is necessary to define the MatchTrackOptions.customCalculationModeConfiguration or MatchPositionsOptions.customCalculationModeConfiguration accordingly. |
Describing the result of a match operation for a single position.