The Routing API method calculateReachableAreas calculates the areas which can be reached from a waypoint or along a route within given horizons. Please note that along a route is only possible in the asynchronous method startAndCreateReachableAreas.
The Routing API method startAndCreateReachableLocationsAreas calculates whether one or more locations can be reached from a waypoint or along a route within given horizons. Of course, this is also possible the other way around, so from the locations to the waypoint or route.
For both calculations, the PTV Routing API considers the road network distance.
Use Cases
The synchronous method calculateReachableAreas or the asynchronous method startAndCreateReachableAreas is designed for isolines calculation. Isolines describe zones based on driving distance or travel time horizons. The polygons returned describe specifically this kind of zones. These polygons can be used for a geofencing use case. The geofencing defines virtual geographical barriers around a geographical position.
The dealer search is a common use case which needs the asynchronous method startandCreateReachableLocations in order to detect the position of dealers within a given horizon.
Detailed Consideration
Calculate reachable areas
These are the input parameters for the calculation of the reachable areas:
- 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. This parameter is only available in the asynchronous request. See Route IDs for information on using the routeId after a map update has been updated. - 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 determines 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
The returned polygons are the reachable areas for each horizon. Those polygons can contain holes. Multiples horizons can be requested and received in the same response.
Visualization of a reachable areas response with a horizon of 5 kilometers along a route
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 travel time 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.
Visualization of a reachable locations response
Good to know
- Distance
The distance returned in case of a reachable location from a route is the distance to the nearest node of the route.
- Warranty
The results obtained by isoline calculation with the method startAndCreateReachableAreas will be the same as those obtained with the method startAndCreateReachableLocations. For example, a location reached by dealer or corridor search will be within the polygon returned in the reachable locations response. 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 or the Reachable Areas showcase.