Position Matching

Position matching tries to find the best matching road segment in the map for a given position. Therefor all segments within a radius around the position are taken into account. For the calculation mode QUALITY the radius is larger than for PERFORMANCE. If no other information is given then the nearest non-blocking segment within this radius is taken as result. If additionally also the heading of the position is given, then the difference between the heading and the angle of the road segment is taken in account, too.

Input

The input of the position matching entry point are latitude and longitude (WGS84) of the query point which are given as path parameters. This endpoint also considers a heading for the position and the calculation mode as query parameter. The heading is the direction in which the vehicle (resp. the device from which the position is delivered) is traveling. It is measured clockwise in degrees from north.

The last parameter is the results parameter. Three values are supported:

  • If the value GEOMETRY is set the polygon line of the matched road segment is provided in the response.
  • If the value SEGMENT_LOCATION_DESCRIPTORS is set the address of the match position is provided in the response. Getting the address for a position causes additional runtime costs which leads to reduced performance. Thus it is recommended to query this result only if it is really needed.
  • If the value SEGMENT_ATTRIBUTES is set additional segment attributes are added to the response.

The following request matches a position with a given heading and the calculation mode QUALITY:

https://api.myptv.com/mapmatch/v1/positions/49.620790/6.121673?heading=109&calculationMode=QUALITY&results=GEOMETRY,SEGMENT_LOCATION_DESCRIPTORS,SEGMENT_ATTRIBUTES&apiKey=YOUR_API_KEY;
Output

If the request succeeds, the response consists of details about the match:

  • Latitude and longitude (WGS84) of the match position. The match position is the closest point on the matched road segment.
  • The polygon line of the matched road segment as GeoJSON. This response attribute is only provided if the results parameter of the request contains the GEOMETRY value.
  • The distance between the input position and the match position in meters.
  • If a heading was given, the angle difference to the matched road segment in degrees.
  • The address of the match position. This response attribute is only provided if the results parameter of the request contains the SEGMENT_LOCATION_DESCRIPTORS value.
  • Additional information of the matched segment. This response attribute is only provided if the results parameter of the request contains the SEGMENT_ATTRIBUTES value.

The response for the example request above looks like this:

{
   "latitude":  49.620835566,
   "longitude":  6.1217594858,
   "segmentGeometry":  "{\"type\":\"LineString\",\"coordinates\":[[6.1216710953,49.620906044],[6.1222333876,49.620457701]]}",
   "matchDistance":  8,
   "angleDifference":  31.91,
   "segmentLocationDescriptors": {
      "countryName": "Luxemburg",
      "city": "Luxemburg",
      "postalCode": "1750",
      "street": "Avenue Victor Hugo"
   },				
   "segmentAttributes": {
      "bridge": false,
      "tunnel": false,
      "ramp": false,
      "frontage": false,
      "paved": true,
      "requiresFourWheelDrive": false,
      "privatelyManaged": false,
      "publicAccess": true,
      "parkingLot": false,
      "priorityRoad": false,
      "builtUpArea": true,
      "speedLimit": 30
   }
}

The following picture illustrates this response:

Position matching response

As you can see in the picture above the distance between the input position and the left road is nearly the same as the distance to the matched segment on the right road. In this case the heading and the segment angle of the right road are almost identical (the angle difference is only about 32°). This leads to the match on the right. Thus giving a heading for the input increases the match quality significantly.