Waypoints

The Routing API supports different waypoint types and attributes in order to support different use cases.

Waypoint Types

By choosing the appropriate waypoint type the route will actually reach the location off the road, stop on the road close to the location or just pass by a location at a given distance.

Off-road waypoints

The route from or to an off-road waypoint starts or ends at the given location, and the distance to the match point on the nearest possible road will be included in the route as well as in its polyline. The travel time for this part is calculated using an average vehicle-specific speed.

This waypoint type should be used when the route ends rather at the front door than at the road, for example for routings from house to house or for delivery services. Use this waypoint type when recalculating a route from the Route Optimization API.

https://api.myptv.com/routing/v1/routes?waypoints=49.612936,6.108476;includeLastMeters&waypoints=49.613063,6.109887;includeLastMeters

For several exact addresses with street and house number, the Geocoding API provides an additional roadAccessPosition which is on that road from which the house can be accessed. This is not necessarily the nearest road.

https://api.myptv.com/routing/v1/routes?waypoints=51.540508,0.003530;roadAccessPosition=51.540611,0.003830&waypoints=49.4404499,6.4970397;includeLastMeters

On-road waypoints

The route from or to an on-road waypoint starts or ends on the road which is nearest to the given location and which can be used by the selected vehicle.

This waypoint type should be used when the distance from the given location to the match point on the road is not significant, for example when calculating the distance between city centers or click-points on the map.

https://api.myptv.com/routing/v1/routes?waypoints=49.612936,6.108476&waypoints=49.613063,6.109887

Route-manipulation waypoints

The route will pass the route-manipulation waypoint within the given radius, but it will not necessarily reach that position. The part of the route from or to a route-manipulation waypoint will not form a leg.

This waypoint type should be used to force the route to pass a certain position such as a city or a click-point on the map. It can be used when dragging the route on the map.

https://api.myptv.com/routing/v1/routes?waypoints=49.005447,8.408660&waypoints=48.782493,9.018230;radius=5000&waypoints=49.145783,9.220275

Combined transport waypoints

A combined transport waypoint is defined by a set of two coordinates as the start and destination of a ferry or rail shuttle connection. Connections are automatically searched within a 5 km radius around the two coordinates matching the nearest port or station. Please note that ferries and rail shuttles are also used on a route without specifying the connection explicitly if it is advantageous compared to road.

This waypoint type should be used to force the route using a specific ferry or rail shuttle. It is treated like a route-manipulation waypoint, so the part of the route from or to a combined transport waypoint will not form a leg or appear in waypoint events.

If no connection between the given coordinates is available, the combined transport waypoint will be ignored and the warning ROUTING_COMBINED_TRANSPORT_WAYPOINT_IGNORED will be returned. If multiple connections are available, the warning ROUTING_COMBINED_TRANSPORT_WAYPOINT_AMBIGUOUS and a list of the available connections will be returned.

https://api.myptv.com/routing/v1/routes?waypoints=53.5406134,9.9645996&waypoints=combinedTransport=54.4981782,11.2249374,54.6564319,11.3612365&waypoints=55.6741360,12.5463867

Waypoint Attributes

Prevent the driver from crossing the street

In some use cases, the driver shall not cross the street to reach the destination for delivery or pickup, e.g. for safety reasons. Therefore, it is possible to take into account the side of the street of the route location during the route calculation, in order to start or arrive on the same side of the road as the route location.

In this example, the left route has been calculated using a waypoint without the matchSideOfStreet parameter. It is allowed to cross the street in order to reach the destination as fast as possible.

The right route has been calculated considering the side of the street at which the waypoint is located. Therefore, it is forbidden to cross the street. The vehicle has to take a detour to be able to reach the destination.

https://api.myptv.com/routing/v1/routes=waypoints=49.5915,6.1232;matchSideOfStreet&waypoints=49.5915,6.1244;matchSideOfStreet

Service time (POST only)

The service time specifies the time needed at a waypoint to provide a service (e.g. pickup and deliver goods). This time will be added to the travelTime and will also be taken into consideration when using the driver's working hours.

Opening intervals (POST only)

Opening intervals specify the periods during which the waypoint is open. Leaving this parameter empty means that the waypoint is always open. Service can only start within one of the opening intervals.

Route IDs

When the RouteID was requested with a previously calculated route, it can be used instead of the waypoint list in a subsequent request to recalculate results. The path of the route will never change nor the distance or the polyline, only results such as the travel time, toll, emissions or events may change according to the specified parameters.

This feature can be used to find out the travel time for the same route at a different date and time. When using options[trafficMode]=REALISTIC the travel time may change with every request. The route may even become violated when a road on the route is blocked for the specified vehicle at that date and time.

To find out the toll prices for the same route with a different vehicle, specify the vehicle parameters or the vehicle profile accordingly. The route may become violated when a road on the route is blocked for the specified vehicle, e.g. a weight or a height violation. When changing the profile the route calculation may even fail, e.g. when calculating a truck route for a bicycle using highways.

The parameters options[allowedCountries] and options[prohibitedCountries] will be ignored, and a warning is issued.

Limitations

The total number of waypoints in a request is limited to 25.

For bicycle and pedestrian routes, the air-line distance of all waypoints in a request is limited to 1000 km.

Try it in the Waypoints code sample.