The Routing API function 'reachable-locations' calculates whether one or more locations can be reached from a waypoint (or the other way around: route reachable from locations).
The Routing API function 'reachable-areas' calculates the areas which can be reached from a waypoint or from a route, within given horizons (or the other way around: from destination to start).
For both calculations, the PTV Routing API considers the road network distance.
Use
The dealer search is a common use case which needs the function 'reachable-locations' in order to detect the position of dealers within a given horizon.
The 'reachable-areas' function is designed for isolines calculation. Isolines describe zones based on driving distance or travel time horizons. The polygons returned by the calculateReachableAreas feature describe specifically this kind of zones.
The polygons returned by the reachableAreasResponse can be used for a geofencing use case. The geofencing defines virtual geographical barriers around a geographical position.
Detailed Consideration
Calculate reachable locations
These are the input parameters for the calculation of the reachable locations:
- waypoint:
The Routing API triggers a search around the geographical coordinates contained in the waypoint. - routeId:
Instead of the waypoint mentioned above, a routeId of a previously calculated route or a matched track can be entered. - profile:
This parameter sets the vehicle profile to be used to calculate the reachable locations. - horizon:
This parameter sets the distance or time to determine whether locations are reachable or not. - horizonType:
This determines whether the calculation should be time ('TRAVEL_TIME') or distance ('DISTANCE') based. - options:
These are routing-relevant options like drivingDirection or trafficMode. - locations:
These are the locations which should be taken into account for the calculation of reachable locations. The locations have to be set in the body of the POST request.
Reachable locations
From the location list sent by the user, the Routing API returns two tables:
- The reachableLocations table contains the list of locations that meets the conditions of reachability. Each item contains the input index of the location, its distance and traveltime from or to the given InputWaypoint.
- The unreachableLocations table contains the list of locations that do not meet the conditions of reachability. Each item in the list contains the input index of the location not reached.
Visualisation of a reachableLocationsResponse
Calculate reachable areas
These are the input parameters for the calculation of the reachable areas:
- waypoint:
The Routing API triggers a dealer search around the geographical coordinates contained in the waypoint. - routeId:
Instead of the waypoint mentioned above, a routeId of a previously calculated route or a matched track can be entered. This parameter is only available in the asynchonous request. - profile:
This parameter sets the profile to be used to calculate the reachable areas. - horizons:
Horizons give the Routing API the distances or times which should be used to calculate the areas. - horizonType:
This determins whether the calculation should be time ('TRAVEL_TIME') or distance ('DISTANCE') based, dependent on the horizonType. - options:
These are routing-relevant options like drivingDirection or trafficMode.
Reachable areas response
The returned polygons are the reachable areas for each horizon. Those polygons can contain holes.
Visualisation of a reachableAreasResponse with 3 horizons
Multiples horizons can be requested and received in the same response. On the figure above, there are three colored polygons corresponding to each horizons.
Good to know
- The distance returned in case of a reachable location from a route is the distance to the nearest node.
- Warranty
The results obtained by isoline calculation with the calculateReachableAreas function will be the same as those obtained with the calculateReachableLocations function. For example, a RouteLocation reached by dealer or corridor search will be within the polygon returned in the ReachableLocationsResponse. However, some locations close to the polygon border may be unreached even if they belong to the polygon due to an approximation used during the polygon calculation. - Limitations
- Synchronous reachable areas calculation is limited to 25 kilometers or 20 minutes horizons depending on the horizon type. A calculation of areas from a route is not available.
- Asynchronous reachable areas/locations calculation from a waypoint is limited to 100 kilometers or 60 minutes horizons depending on the horizon type.
- Reachable areas/locations calculation from a route is limited to 50 kilometers or 45 minutes horizons depending on the horizon type and a route must not exceed 500 kilometers.
- The number of horizons is limited to 5, in case of calculation from a route the maximum is 3 horizons.
Try it in the Calculate Reachable Areas Synchronously and the Calculate Reachable Locations code samples.