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;includeLastMetersOn-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.109887Route-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.220275Combined 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.
To avoid these warnings, it is recommended to search as a pre-step for all available combined transports around a coordinate, e.g. in a large port, using getCombinedTransports in the Data API. Besides the exact coordinates of start and destination, additional information like name, duration or allowed vehicles of the combined transports are provided to simplify a selection. These coordinates could directly be used with the combined transport waypoints.
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.5463867Waypoint 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 first 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 second 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;matchSideOfStreetService 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 of the route and the leg which starts at this waypoint, and it will also be taken into consideration when using the driver's working hours.
If the driver does not have to perform the service himself, but instead a break or rest can be scheduled during that time, set useServiceTimeForRecreation to true. The corresponding schedule events will contain both SERVICE and BREAK. If the service time is shorter than the break to be scheduled, the remaining break will be appended to the service. If the service time is longer than the break, the service time after finishing the break will be marked as WAITING.
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. It may happen that the vehicle has to wait for the waypoint to open. In such cases this waiting time will be added to the travelTime of the route and the leg which starts at this waypoint.
Vehicle parameters at waypoint (POST only)
Vehicle parameters defines the changes to be applied from this waypoint. If no vehicle parameter is set at a specific waypoint, the next leg is calculated using the last modified vehicle profile. For example, it is possible to set the weight of the load inside the vehicle for each waypoint. This can lead to changes in the final route, and better calculation of emissions.
Route IDs
A route can be represented by a route ID which can be requested when calculating a route. It can also be the representation of an alternative route returned by a route calculation.
This route ID can then be used in subsequent requests to refer to that route. The route ID will automatically be deleted after 12 hours.
Recalculate the route with different parameters
When the route ID is requested with a route calculation, it can be used instead of the waypoint list in subsequent requests to recalculate results. The path of the route will not 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 will be issued.
Fetch the route results once again
Using getRouteByRouteId the results of the initial route calculation can be fetched again. The result will contain all results of the initial route calculation and use the same parameters. The path of the route will not change nor the distance or the polyline, but other results may be slightly different as some data may have changed, in particular live traffic but also exchange rates, custom road attributes or even map data when being updated.
Calculate the estimated time of arrival and reachable areas and locations
The route ID can also be used to refer to a route path when calculating the estimated time of arrival as well as reachable areas and reachable locations. For these operations only the path of the route will be used. All other results of the route represented by the route ID will be ignored.
Note
The route represented by a route ID will automatically be updated when being used for the first time after the map has been updated. A new map may mean in some cases that the route will be different from the initial one, for example, when roads used by the route have changed or were deleted in the new map. The request which updates the route will issue a warning ROUTING_UPDATED_ROUTE_ID in order to notify on update of the route.
Limitations
The total number of waypoints in a request is limited to 25 for GET requests using calculateRoute and 250 for POST requests using calculateRoutePost.
For bicycle and pedestrian routes, the air-line distance of all waypoints in a request is limited to 1000 km. For other routes, the air-line distance of all waypoints in a request is limited to 50000 km.
Try it in the Waypoints code sample.