How to avoid LinkingErrors

[Bernd Welter]

Hey ho,

these days a customer asked me about some issues within routing. Some of his waypoints are locate far away from the regular street network and he wanted to know how to deal with this. So here are some basics of linking that should enable you to optimize your requests

The flags on this map show the input coordinates (green=start, red=destination) of a route. As the close environment of these coordinates is not allowed for the vehicle (e.g. because of pedestrian zone, tollroads forbidden, trucks forbidden...) we have to investigate which other segments within a given radius are allowed. In this plot we finally find the segments near the yellow crosses. Those are the closest segments that match our routing options (malus values) and our vehicles properties.

It is possible to request some details about this linking process. Just use the RoutingOption.GENERATE_EXTWAYPOINTS and the server returns info such as airline distance between Waypoint input coordinates and the linking points.

The output info for the Waypoints / Linking points

If necessary you can reduce or enlarge the search tolerance for the linking points search by using the snippet or profile:
The following code reduces the search range to a limit of 50m.

Code: Select all

<?xml version="1.0" encoding="utf-8"?>
<Profile xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Routing majorVersion="2" minorVersion="0">
    <Waypoint maximumDistanceToSegment="50">
    </Waypoint>
  </Routing>
</Profile>

As you can see in the example one of the waypoints is located more than 200m away (linkingDistance). So this is why this reduction raises a well known linking error:

Code: Select all

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
	<soap:Body>
		<soap:Fault>
			<faultcode>soap:2530</faultcode>
			<faultstring>linking to waypoint (zero-based index list: 0,1) failed</faultstring>
			<detail>
				<ns3:XRouteException xmlns:ns6="http://exception.core.jabba.ptvag.com" xmlns:ns4="http://types.xroute.xserver.ptvag.com" xmlns:ns3="http://xroute.xserver.ptvag.com" xmlns:ns2="http://baseservices.service.jabba.ptvag.com" xmlns:ns1="http://common.xserver.ptvag.com" xmlns:ns0="http://wrappertypes.service.jabba.ptvag.com">
					<ns6:stackElement className="com.ptvag.xserver.xroute.XRouteException" errorKey="2530" message="linking to waypoint (zero-based index list: 0,1) failed">
						<ns6:cause xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
						<ns6:wrappedContext xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
					</ns6:stackElement>
				</ns3:XRouteException>
			</detail>
		</soap:Fault>
	</soap:Body>
</soap:Envelope>

Update 4.8.2021:
In xRoute 2 the error message looks like this (JSON style):

Code: Select all

{"faultInfo":
{"$type":"WaypointNotLinkableFault",
"hint":"Make sure that the coordinates of the waypoints in question are covered 
by the map data and are close to a road segment valid for the given vehicle.",
"waypointIndices":[0] ... 
},
"message":"Some waypoints of the request could not be linked to the road network."
}

The default value for the search distance is 5000m. In most cases this is a sufficient distance. In the given scenario the route is successfully computed and looks like this:

The proper route

The linking distance is just one out of several parameters that have impact on this scenario. Feel free to get back to us if you have some challenges dealing with such plots. And be aware that there is always a message behind a linking error - therefore do not increase the radius if it is important for you to recognize whether you are far of!

Update 4.8.2021 (xRoute2):
In xRoute 2 you can specify the Linking parameters via the RequestProfile.RoutingProfile

Best regards
Bernd

[Tom]

Hi Bernd,

thanks for the details on the linking-process.
Unfortunateley it does not explain what the title promises, that is how to avoid this type of error

In a real world scenario (like mine) you don't deal with single routes where you know, when it fails, one of both is wrong. Rather we have roughly 150.000 customer addresses (already geocoded) which we need to link to the street network and calculate the routes to 80 depots. About 1% of the geo-locations is wrong for several reasons. I would like to generate a list of these "wrong" (that is not to the street network linkable) addresses in order to investigate the reasons and to decide whether to drop them or correct them.

The problem ist neither calculateExtendedRoute nor calculateMatrixInfo comes back to me with information on which of the waypoints fails. It simply causes the mentioned execption for the whole request. Of course for efficiency reasons I send hundrets of waypoints in one request. So which of them caused the error???

So how can I find out which of the locations are unlinkable without sending them 2-by-2 with calculateExtendedRoute (that would run endless...)?

Or do you suggest making a "dry-run" with all locations involved having maximumDistanceToSegment set to 10.000 km in order to analyze the resultung linkingDistance and searching for everything longer than in the real vehicle-profile?

But then what about

The linking distance is just one out of several parameters that have impact on this scenario

This all does not sound like a real solution to me. Or do you have a different approach?

Thanks for any ideas...

regards
Tom

[Joost]

Actually the response does tell you which link points failed. Unfortunate is a text message which you have to parse for automatic recognition.

{
"errorMessage": "linking to waypoint (zero-based index list: 1,2) failed",
"errorKey": "2530",
"exceptionType": "com.ptvag.xserver.xroute.XRouteException"
}

For avoiding Linking errors, please have a look at an older blog topic (but still relevant):

http://devblog.ptvgroup.com/2014/01/10/ ... -vehicles/

[Tom]

I would be happy, if the server would tell me that too, but unfortunately the message says in my case:

linking to waypoint (zero-based index list: unknown) failed

Anyone has an idea whay is that difference?

[Joost]

I did some small experiments to see if I can reproduce the behavior you are encountering. I was able to reproduce this behavior. In my case It happens when I'm using coordinates that are not on this world. This caused internally a different error then coordinates that are just not close enough to a network. Maybe this is also the case with your data. I would recommend you raise a ticket via our email support so they can check this and process it back to development if needed. If you do so please include a sample request for further investigation and details about the xRoute and map versions you are using.

[Tom]

Hi Joost,

thanks a lot for this hint, in fact, I can narrow down "not on this world" to "not in the region where the xServer has a map". Because if I take the coordinates of a very rough rectangle around Europe (I use the central europe map) and filter out the failing coordinates (which still are on this world, just somewhere in the indean ocean...), then I get back a correct error message for those coordinates that simply cannot be bound to the road network, which I can put on a list for further investigation.

So, finally I got it. Thanks a lot for the help here!

Best regards,
linuzer