Developer's Guide > API Documentation > API Documentation PTV xMapmatch > Request

Component xmapmatch

Diagrams

Request

Response

Exceptions

Operations

matchTrack

DEPRECATED: Please use matchPositions instead. Matches a given sequence of input coordinates to the map.

Parameter Name Type Description
trackPositions TrackPosition[] An array holding the input positions. For using "stable matching", at least six positions have to be provided (see the profiles).
mapName String Deprecated as of release 1.14.0.0. The name of the map to choose for matching, for example "deu_", "dnk_d". This is purely optional since release 1.14.0.0. This parameter will be removed in future versions.
Return Type Description
MatchResult Returns the found matches.
XServiceException Thrown if a PTV xServer framework exception occurs.
XMapmatchException Thrown if an PTV xMapmatch Server exception such as an invalid request parameter occurs.

matchTrackExtended

DEPRECATED: Please use matchPositions instead. Match LocationReferencePoints to the network.
Parameter Name Type Description
trackPositions TrackPosition[] Array holding input positions. For using "stable matching" (see the profiles), at least six positions have to be provided.
mapName String Name of the map to choose for matching (e.g. "deu_", "dnk_d". Note that this is purely optional since 1.14.0.0. This parameter is deprecated and will be removed in future versions.
returnSpeedClass boolean If true, the speed class per segment is returned.
returnPolyline boolean If true, the rendered polyline is returned (per segment and as a complete line).
Return Type Description
MatchResult Returns the found matches.
XServiceException Thrown if a PTV xServer framework exception occurs.
XMapmatchException Thrown if an PTV xMapmatch Server exception such as an invalid request parameter occurs.

matchPositions

Matches a given sequence of input coordinates to the map. The returned result is configurable via ResultListOptions, allowing for certain attributes to be turned on or off in the result.

Parameter Name Type Description
trackPositions TrackPosition[] An array holding the input positions. For using "stable matching", at least six positions have to be provided (see the profiles).
details ResultListOptions The detail of the matched route. Use this for e.g. getting back special attributes for segments.
Return Type Description
MatchResult Returns the found matches.
XServiceException Thrown if a PTV xServer framework exception occurs.
XMapmatchException Thrown if an PTV xMapmatch Server exception such as an invalid request parameter occurs.

Classes

MatchResult

The result type, specified by an array of all individual matched locations as well as an aggregated path.
Attribute Name Type Description
completePath MatchedSegment[]

An array holding all segments on matched route. Each segments only appears once in this array (as long as there is no loop in the matched track).

overallLength double

The overall length of the matched route in meter.

matchedLocations MatchedLocation[]

An array holding all individual matches.

overallTime long

The overall time of the matched route in seconds.

MatchedLocation

Contains all information about a single match.
Attribute Name Type Description
angleDifference float

The angle difference between the match and the segment.

coveredDistance double

This value gives the position relative to the last segment of the path. It is defined as the distance on the segment from its start node to the point of the matched location. Hence, this value is at least zero and at most the length of the segment.

drivenDistance double

The driven distance since the previous match in meter.

heading float

The current heading in degrees clockwise relative to true north.

linkingDistance float

Linking distance between the matched coordinate on a segment and the coordinate given by the input object.

localMatching boolean

If true, this match was calculated by a local matching.

localRating float

This value rates the quality of this match and tells how good the regarded street segment fits to the current position input. The rating is given as a value between 1 and 0.

probability float

The probability of a segment is a value between 0.0 and 1.0. The sum of all probabilities for all candidates in a history element is 1.0. The probability depends on the rating of the match relative to other matches at this point of time.

An invalid probability is specified by a value of -1.

stable boolean

A match is stable if it is the only candidate at this point of time. Hence, there are no alternative candidates, so this match can not be corrected.

timestamp Calendar

Returns the set timestamp.

transitionRating float

This value rates the quality of driven distance of this match relative to the driven distance given by the input. The rating is given as a value between 1 and 0.

path MatchedSegment[]

A match stores the path to the previous match in form of a list of segments. The segment order is from the segment which contains the previous match to the segment which contains the current match.

This array holds at least one entry - the segment for the current match.

inputId long

A reference to the input position used for this match.

lon Double

Longitude of this match. The attributes lon and lat belongs together.

The actual representation of lon/lat is in the CoordFormat OG_GEODECIMAL. The CoordFormat in the CallerContext will be ignored.

lat Double

Latitude of this match. The attributes lon and lat belongs together.

The actual representation of lon/lat is in the CoordFormat OG_GEODECIMAL. The CoordFormat in the CallerContext will be ignored.

coordinate Point

The coordinate of this match. The actual representation is defined by the CallerContext CoordFormat property.

MatchedSegment

Contains the network data of a matched position.
Attribute Name Type Description
tileId long

The tileID of this segment. Together with the rtgSegIdx this segment can be identified.

rtgSegIdx int

The rtgSegIdx of this segment. Together with the tileID this segment can be identified.

networkClass int

The networkClass of the segment.

speedLimitBackward int

The speedLimit in backward direction. Usually the same as in forward direction.

speedLimitForward int

The speedLimit in forward direction. Usually the same as in backward direction.

endXYN int[]

The XYN-coordinates of the end point of this segment. These coordinates are local to the current tile.

startXYN int[]

The XYN-coordinates of the start point of this segment. These coordinates are local to the current tile.

length int

The length of the segment in meter.

countryCode int

The countryCode on this segment.

speedClass Integer

The speed class of the route segment. This value will be returned if returnSpeedClass of the method matchTrackExtended() is true.

The map data comprises a network class and a speed class for each segment. The network class indicates the level of a road segment (dependent on the functional road class, form of way, number of lanes, etc.). There are eight network class levels. The speed class is derived from the network class and speed information like speed restrictions or maximum speeds on different roads (highway, trunk road, rural road, city road). The same type of road can have different maximum speeds, e.g. wide or narrow roads, steep or even roads, mostly empty or congested roads, roads with or without many traffic lights.

polyline Point[] The rendering polygon of the segment. This value will be returned of the method matchPositions if the attribute polyline of the ResultListOptions is true.
vendorId String

This is the vendor id consisting of a list of provider's segment ID's (for example TomTom).

The syntax for this description is:
LINESTRINGSEG(<segID> <dir> <countryCode>)

<segID> = provider ID
<dir> = the digitalization direction
<countryCode> = the countryCode representing the country the segment belongs to

Example:
LINESTRINGSEG(78620413 0 49)

The SegmentIDs of certain countries will only be taken into account when the corresponding IDMapping layer could be initialized. See the list of countries in the logging, initialized when xMapmatch Server is started.

ResultListOptions

Select which additional attributes should be returned by the mapmatcher.
Attribute Name Type Description
speedClass Boolean

If true, the speed class is returned per segment.

polyline Boolean

If true, the polyline per segment is returned. Also, the polyline of the complete path is returned.

vendorId Boolean

If true, the vendor id per segment is returned. The vendor id is the id of a segment that was used by the raw map data provider. The id is a string consisting of a segment id, a flag for the direction of the segment and the country code separated by spaces (e.g. "123456789 0 49").

TrackPosition

A single input position as it might be derived from NMEA-Tracks or other GPS signal representations.

The input coordinate can be specified as a pair of two double values: lon and lat. Or as a Point value: coordinate. For the calculation use either the attributes lon and lat or the attribute coordinate only. The response follows the same policy.

Attribute Name Type Description
id long The unqiue key to identify the signal - must not be null.
heading float The heading of the input.
speedInMps float The speed at the given position in meters per second.
timestamp Calendar The time stamp indicating the occurance of the positioning event.

Warning! Even though this parameter is marked optional in the WSDL (due to technical reason in the generation process), this parameter is required.

lon Double Longitude part of the input coordinate. The attributes lon and lat belongs together. Please only use coordinate or the lat/lon attributes as input coordinate for all TrackPositions of a request. The actual representation of lon/lat is in the CoordFormat OG_GEODECIMAL. This is the condition to use this!
lat Double Latitude part of the input coordinate. The attributes lon and lat belongs together. Please only use coordinate or the lat/lon attributes as input coordinate for all TrackPositions of a request. The actual representation of lon/lat is in the CoordFormat OG_GEODECIMAL. This is the condition to use this!
coordinate Point

The input coordinate as a Point. Please only use coordinate or the lat/lon attributes as input coordinate for all TrackPositions of a request. The actual representation is defined by the CallerContext CoordFormat property (CoordFormat).

Exceptions

XMapmatchException

Thrown if an PTV xMapMatch Server exception such as an invalid request parameter occurs.

Component common

Diagrams

basetypes

opengis-geometry

Exceptions

Asynchronous Requests

Classes

BoundingBox

A bounding box, definded by its left top corner point and right bottom corner point.
Attribute Name Type Description
leftTop Point

The left top corner point.

rightBottom Point

The right bottom corner point.

BulkProgress

Extends JobProgress

Default implementation for bulk jobs.
Attribute Name Type Description
remaining int

Specifies how many requests have still to be calculated.

successful int

The number of successful calculations so far.

failed int

The number of failed computations so far.

ClusterProgress

Extends JobProgress

Implementation of JobProgress for cluster planning.
Attribute Name Type Description
action String

The current action being executed. For more information on progress see About Asynchronous Protocol.

distanceMatrixProgress DistanceMatrixProgress

The progress of the distance matrix calculation, available only if action equals "DistanceMatrix.Calculation".

optimizationProgress OptimizationProgress

The progress of the optimization, available only if action starts with "Optimization.".

DistanceMatrixCalculationProgress

Progress information of the currently active distance matrix calculation
Attribute Name Type Description
dimaId int

The unique key to identify the distance matrix currently being calculated.

currentDimaIndex int

The 1-based index of the distance matrix currently being calculated. Depending on the number of different vehicles in the request the number of distance matrices to be calculated can be greater than

lastDimaIndex int

The index of the last distance matrix to be calculated, that is the total number of distance matrices.

currentDistanceMatrixProgress DistanceMatrixProgress

The progress of the distance matrix currently being processed, available only if action equals "DistanceMatrix.Calculation".

DistanceMatrixProgress

Extends JobProgress

Default implementation for distance matrix calculation jobs.
Attribute Name Type Description
currentRowIndex int

The 1-based index of the current row of the current distance matrix being calculated.

lastRowIndex int

The index of the last row of the current distance matrix to be calculated.

EncodedGeometry

Extends EncodedGeometryBase

The abstract base class for geometry objects used in a geographical PTV xServer. Contains the attributes to represent openGIS conform encodings with a specific coordinate format. The actual representation is defined by the CallerContext ResponseGeometry property (GeometryEncoding) and the CallerContext CoordFormat property (CoordFormat).

Attribute Name Type Description
wkb byte[]

If not null, this attribute contains the well-known binary encoded form of the geometry

wkt String

If not null, this attribute contains the well-known text encoded form of the geometry

kml KML

If not null, this attribute contains the well-known text encoded form of the geometry

EncodedGeometryBase

The abstract base class for geometry objects.
No attributes defined.

GeometryCollection

Extends EncodedGeometry

A geometry collection as specified by the openGIS standard.
Attribute Name Type Description
geometryCollection PlainGeometryCollection

If not null, this attribute contains the explicit form of the geometry

ImprovementProgress

Progress information of the currently active improvement step of the optimization.
Attribute Name Type Description
availableMachineTime int

The available machine time stated in the request in [s]. This value is 0 if available machine time is not set in the request.

usedMachineTime int

The machine time already used in [s].

iterationIndex int

The index of this iteration. Index 0 denotes the initial plan directly after construction or the input plan.

numberOfImprovements int

The number of improvements the algorithm has already achieved. In other words, this is the number of tour plans with a smaller value of costOfObjectiveFunction than the best one at that time.

currentPlan KeyFigures

The key figures characterizing the current tour plan.

bestPlan KeyFigures

The key figures characterizing the currently best tour plan.

initialPlan KeyFigures

The key figures characterizing the initial tour plan. The initial tour plan is the input plan, if available, or the first tour plan after the construction step.

Job

Reference to jobs running in the background.
Attribute Name Type Description
id String

This id references the background job on the server.

status JobStatus

The current status of the job.

progress JobProgress

The current progress of the job. Can be null at the very beginning or very end of the request execution.

elapsedTime int

Elapsed time since this job has been queued.

JobProgress

Abstract base class for progresses. An individual PTV xServer might define its own implementations.
No attributes defined.

KML

Represents a KML geometry.
Attribute Name Type Description
kml String

The KML string itself.

placemarks String[]

The placemarks of the KML. If empty, all placemarks will be used. This will result in a GeometryCollection, if more than one exists.

KeyFigures

These key figures characterize a tour plan.
Attribute Name Type Description
costOfObjectiveFunction int

The optimization aims at minimizing the objective function. This value contains its arithmetical cost.

The significance of this value is not the value itself, but rather if and how fast it decreases during the calculation. The faster the value decreases the better the tour plans become according to the GoalImportance which defines what "better" means, at all.

numberOfScheduledOrders int

The number of orders already being scheduled.

numberOfUnscheduledOrders int

The number of orders not being scheduled, yet. These orders are feasible and can be scheduled during further improvement iterations.

numberOfInfeasibleOrders int

The number of orders not being scheduled. These orders are infeasible and will not be scheduled during further improvement iterations.

numberOfScheduledVehicles int

The number of vehicles being scheduled.

totalTourCount int

The number of all planned tours.

totalTourPeriod int

The sum of the tour periods for all planned tours ([sec]).

totalTourDrivingPeriod int

The sum of the tour driving periods for all planned tours ([sec]).

totalTourWaitingPeriod int

The sum of the tour waiting periods for all planned tours ([sec]).

totalTourDistance int

The sum of the tour distances for all planned tours ([m]).

totalTourCost int

The sum of the tour costs for all planned tours ([MU]). The costs per chain will not be included, see attribute totalChainCosts.

totalChainCost int

The sum of the costs per chain of all planned chains ([MU]). See VehicleCosts.

totalChainPeriod int

The sum of the chain periods of all planned chains ([sec]). The chain period is defined as the period between the start of the first tour and the end of the last tour. This period is greater than the sum of the periods of all tours if two subsequent tours do not start right after the other.

LineString

Extends EncodedGeometry

A line string as specified by the openGIS standard.

See EncodedGeometry for possible representations.

Attribute Name Type Description
lineString PlainLineString

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

LinearRing

Extends EncodedGeometry

A linear ring as specified by the openGIS standard.

See EncodedGeometry for possible representations.

Attribute Name Type Description
linearRing PlainLinearRing

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

MultiLineString

Extends EncodedGeometry

A multi line string as specified by the openGIS standard.

See EncodedGeometry for possible representations.

Attribute Name Type Description
multiLineString PlainMultiLineString

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

MultiPoint

Extends EncodedGeometry

A multi point as specified by the openGIS standard.

See EncodedGeometry for possible representations.

Attribute Name Type Description
multiPoint PlainMultiPoint

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

MultiPolygon

Extends EncodedGeometry

A multi polygon as specified by the openGIS standard.

See EncodedGeometry for possible representations.

Attribute Name Type Description
multiPolygon PlainMultiPolygon

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

OptimizationProgress

The progress information of the currently active step of the optimization.
Attribute Name Type Description
currentLoopIndex int

The index of the current loop being calculated.

lastLoopIndex int

The index of the last loop being calculated. The calculation will automatically be finished by the algorithm before reaching this index when no improvement could be reached, anymore. The total number of loops can be set for the improvement step, only (see Params).

progress int

The progress in % of the current loop being calculated.

PlainGeometryBase

The abstract base class for the structured representation of geometry objects.
No attributes defined.

PlainGeometryCollection

Extends PlainGeometryBase

A plain structured polygon consisting of a set geometries.
Attribute Name Type Description
geometries PlainGeometryBase[]

The set of geometries making up the geometry collection.

PlainLineString

Extends PlainGeometryBase

A plain structured line string consisting of a set of points.

Attribute Name Type Description
points PlainPoint[]

The set of points defining the line string.

PlainLinearRing

Extends PlainGeometryBase

A plain structured linear ring consisting of a set of points

Attribute Name Type Description
points PlainPoint[]

The set of points defining the linear ring.

PlainMultiLineString

Extends PlainGeometryBase

A plain structured polygon consisting of a set of line strings.
Attribute Name Type Description
lineStrings PlainLineString[]

The set of line strings making up the multi line string.

PlainMultiPoint

Extends PlainGeometryBase

A plain structured polygon consisting of a set of points.
Attribute Name Type Description
points PlainPoint[]

The set of points making up the multi point.

PlainMultiPolygon

Extends PlainGeometryBase

A plain structured polygon consisting of a set of polygons.
Attribute Name Type Description
polygons PlainPolygon[]

The set of polygons making up the multi polygon.

PlainPoint

Extends PlainGeometryBase

A plain structured point consisting of two floating point attributes for the coordinates. In contrast to Point it is never transformed.

Attribute Name Type Description
x double

The x coordinate

y double

The y coordinate

z Double

The z coordinate (optional, only if requested)

PlainPolygon

Extends PlainGeometryBase

A plain structured polygon consisting of a set of linear rings.

Attribute Name Type Description
linearRings PlainLinearRing[]

The set of linear rings making up the polygon.

PlanProgress

Extends JobProgress

Implementation of JobProgress for tour planning.
Attribute Name Type Description
action String

The current action being executed. For more information on progress information see About Asynchronous Protocol.

distanceMatrixCalculationProgress DistanceMatrixCalculationProgress

The progress of the distance matrix calculation, available only if action starts with "DistanceMatrix.".

improvementProgress ImprovementProgress

The progress of the improvement step during the tour plan optimization, available only if action equals "Optimization.Improvement".

Point

Extends EncodedGeometry

Represents a single coordinate (point). Do not use this type for other points (e.g. pixel in an image), the coordinates are automatically transformed. Instead use PlainPoint.

See EncodedGeometry for possible representations.

Attribute Name Type Description
point PlainPoint

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

Polygon

Extends EncodedGeometry

A polygon as specified by the openGIS standard.

See EncodedGeometry for possible representations.

Attribute Name Type Description
polygon PlainPolygon

If not null, this attribute contains the explicit form of the geometry.

ATTENTION: Filled with requested EncodedGeometry representation (not necessarily a plain geometry).

RequestOptions

General options for requests

Attribute Name Type Description
coordFormat CoordFormat

The coordinate format used in the request/response.

responseGeometry GeometryEncoding[]

The geometry encoding for the response.

profile String

The name of the parameter profile to be used.

profileXMLSnippet String

For internal use only.

srId String

If the coordFormat equals to 'OG_SRID', this attribute contains the Spatial Reference Identifier as specified by the Open Geospatial Consortium (OGC), otherwise it is null. All codes of the EPSG Geodetic Parameter Dataset V7.9 maintained by the EPSG.

TerritoryProgress

Extends JobProgress

Implementation of JobProgress for territory planning.

Attribute Name Type Description
action String

The current action being executed. For more information on progress with territory planning see the use case documentation.

distanceMatrixProgress DistanceMatrixProgress

The progress of the distance matrix calculation, available only if action equals "DistanceMatrix.Calculation".

optimizationProgress int

The progress of the optimization, available only if action starts with "TerritoryOptimization.".

WatchOptions

This class includes options to control job status and progress updates. All parameters are optional.
Attribute Name Type Description
progressUpdatePeriod Integer

If defined this optional parameter enables additional progress updates with the specified interval. If no new progress update arrives during the specified period, watchJob will wait for and return with the next available progress update. Important updates such as terminal states will always return immediately. The minimum period must be at least 250ms. If no progress waiting period is defined, progress will only be sent as part of status updates.

maximumPollingPeriod Integer

Specifies the timeout after which watchJob will report the last status even if no further updates are available.If not specified a configured default is used.

ZoneLoadingProgress

Extends JobProgress

Attribute Name Type Description
action String

The current action being executed.

optimizationProgress int

The progress of the optimization, available only if action starts with "LoadingSpaceOptimization.".

Enumerations

CoordFormat

The CoordFormat enumeration contains all coordinate types supported by the PTV xServer. All examples represent the same geographic location.

Enumerator Name Value Description
OG_GEODECIMAL None

OpenGIS representation of WGS 84 coordinates. Example x=8.2505556, y=48.7627778.

PTV_MERCATOR None Mercator projection. Example x=917420, y=6227729.
PTV_GEOMINSEC None

PTV representation of coordinates by degree, minute, and second. Example x=815020, y=4845460.

PTV_GEODECIMAL None

PTV representation of WGS 84 coordinates. Example x=825056, y=4876278.

PTV_CONFORM None

PTV representation of conform coordinates. Example x=1672358, y=1620743.

PTV_SUPERCONFORM None

PTV representation of super-conform coordinates. Example x=5072358, y=3320743.

PTV_SMARTUNITS None

PTV internal coordinate format. Example x=4352286, y=5456405.

OG_SRID None

This format is set implicitly, if a Spatial Reference Identifier as specified by the Open Geospatial Consortium (OGC) is set in the CallerContext. All codes of the EPSG Geodetic Parameter Dataset V7.9 maintained by the EPSG..
Note: The coordinate format 'OG_GEODECIMAL' and the SRID code 'EPSG:4326' are equivalent.

ErrorCode

Enumerator Name Value Description
REQUEST_INVALID_WKT 10

The specified WKT in the request is invalid. It should a well-known text representation of a geometry from a string (see the OpenGIS simple features specification).

REQUEST_INVALID_WKB 11

The specified WKB in the request is invalid. It should be a geometry from a byte stream in well-known binary format.

REQUEST_INVALID_KML 12

The specified KML in the request is invalid.

KML_PLACEMARK_NOT_FOUND 13

Thrown, if requested placemark name is not found in the KML

CONVERT_GEOMETRY_OBJECT 20

One or more geometry objects in the request are invalid. There are problems to convert a geometry object to a plain geometry object. Also used for retrieving the plain geometry object from a geometry object.

CONVERT_COORDINATE_FORMAT 21

There are problems to convert a CoordFormat of the request to a coordinate type.

GEOMETRY_ENCODING 22

Geometry objects cannot be encoded.

GeometryEncoding

Defines encoding options for geometry parameters and results.

Plain indicates that geometry objects should be transmitted in plain object form, WKB indicates that openGIS well-known binary format should be used, WKT represents the openGIS well-known text format. KML represents the Keyhole Markup Language.

Enumerator Name Value Description
PLAIN None

Plain geometry encoding using structured objects and according network presentation.

WKB None

Geometry should be represented by well-known binaries.

WKT None

Use well-known texts to encode geometry objects.

KML None

Use Keyhole Markup Language to encode geometry objects.

JobStatus

Specifies different job status values.
Enumerator Name Value Description
QUEUING None

Job has been enqueued.

RUNNING None

Job is currently running.

STOPPING None

Stop has been requested, the job will terminate its calculation as soon as possible.

SUCCEEDED None

Job has completed successfully.

FAILED None

Job has failed with an exception.

DELETED None

The job was deleted by the user.

UNKNOWN None

The job is in an unknown state. For example a given id is unknown or the job has already been fetched and has thus been deleted from the underlying persistent store.

Exceptions

XServiceException

XServiceException is used for all exceptions which can occur in the PTV xServer framework.

SystemException (from package com.ptvag.jabba.core.exception)

This is the base class for all system relevant exceptions. It is thrown for example if a request has timed out or if a request has been rejected.