Description
The PointToPointRoute UDF helps extract the routing information required for traveling between two distinct points. It takes the starting and ending locations, then returns the total distance and duration of a route that is either the fastest or the shortest (as best calculated by the algorithm used).
mapreduce.task.timeout
property.Function Registration
create function PointToPointRoute as 'com.pb.bigdata.spatial.routing.hive.PointToPointRoute';Syntax
PointToPointRoute(WriteableGeometry startPoint, WriteableGeometry endPoint,
Map<String, String> options)Parameters
| Parameter | Type | Description |
|---|---|---|
| startPoint | WriteableGeometry | starting location. This must be a point for those UDFs that require it. |
| endPoint | WriteableGeometry | ending location. This must be a point for those UDFs that require it. |
| options | Map | options that affect the calculation of the route and engine options that affect the operation of the routing engine |
Syntax
PointToPointRoute(Number|String startX, Number|String startY, Number|String endX,
Number|String endY, Map<String, String> options)Parameters
| Parameter | Type | Description |
|---|---|---|
| startX | Number or String | x ordinate of the starting location in WGS 84 |
| startY | Number or String | y ordinate of the starting location in WGS 84 |
| endX | Number or String | x ordinate of the ending location in WGS 84 |
| endY | Number or String | y ordinate of the ending location in WGS 84 |
| options | Map | options that affect the calculation of the route and engine options that affect the operation of the routing engine |
Options
The options keys cannot be derived from a column in the table that the UDF is executed on. The keys of the options map must also be of type String or convertible to String, and the values should be convertible to a type appropriate for the key’s value (typically this means that all values must be of type String). Keys and values of any type can be enclosed in either double or single quotes; a number or Boolean value will be processed correctly with or without quotes. For information on options that affect the calculation of the route, see Engine Options.
| Key | Type | Description |
|---|---|---|
| pb.routing.historicSpeedBucket | String | Specifies whether the routing calculation uses the historic traffic speeds.
These speeds are based on different time-of-day buckets. The data must have historic
traffic speeds included in order to use this feature. The data for each
country/region has the same bucket definitions, where the speeds for these bucket
values may vary. The available values are:
|
| pb.routing.majorRoads | Boolean | Whether to include all roads in the calculation or just major roads. If you choose to include only major roads (that is, set the value to true), performance will improve but accuracy may decrease. The default value is false. |
| pb.routing.optimizeBy | String | The type of optimizing to use for the route. Valid values are time or distance. The default value is time. |
| pb.routing.returnDistanceUnit | String |
The unit to return distance. If not specified then this value is meter. Available
linear units are:
|
| pb.routing.returnTimeUnit | String | The unit to return time. If not specified, the default value is minute.
Available time unit values are:
|
| pb.routing.avoidTollRoads | Boolean | To exclude toll roads from the route calculation, set this value to true. The default is false, which includes toll roads in the route calculation. |
| pb.routing.error.limit | Number | The number of routing errors to allow before failing a task for "too many
errors". This prevents a task (and thus the job) from continuing in the case of a
likely configuration error. The default value is 10. Optionally you can use the
equivalent Hive variable, |
| pb.routing.error.limit.disabled | Boolean | Disables the error limit. All errors will be logged but will not cause the task
or job to fail. Optionally you can use the equivalent Hive variable,
|
|
Commercial Vehicle Restrictions
Commercial Vehicle Restrictions (CVR) are composed of directives to the routing engine that guide the behavior and attributes of commercial vehicles making trips along the route. Depending upon the vehicle attributes provided (such as height, width, length, weight) and the commercial vehicle restriction attributes present in the road network, a decision is made whether to allow to route a particular vehicle over a segment or not. If there is no commercial vehicle restriction attribute present in the road network, the input restriction properties will not affect the resultant route. The vehicle attributes specify the details of the vehicle on which the restrictions are applied. The attributes can be vehicle type, height, weight, length, or width when determining the route. Commercial vehicles are divided into different types ranging from short trailers to long triples. The Commercial Vehicle Restrictions attribution is organized on a per-vehicle type basis. This means it is entirely possible for a segment to be preferred for one vehicle type and the same segment have a restriction for another type of vehicle. |
||
| pb.routing.cvr.vehicleType | String | Choose either ALL or one of the types of vehicles:
|
| pb.routing.cvr.linearUnit | String | The unit to be used when specifying the maximum length, height, and width of
the vehicle:
|
| pb.routing.cvr.height | Number | Specifies the maximum height of a vehicle. Any vehicles over this value will be restricted when determining the route. |
| pb.routing.cvr.length | Number | Specifies the maximum length of a vehicle. Any vehicles over this value will be restricted when determining the route. |
| pb.routing.cvr.width | Number | Specifies the maximum width of a vehicle. Any vehicles over this value will be restricted when determining the route. |
| pb.routing.cvr.weight | Number | Specifies the maximum weight of a vehicle. Any vehicles over this value will be restricted when determining the route. |
|
pb.routing.cvr.weightUnit
|
String | Specifies the unit to be used for specifying the maximum weight of the vehicle.
The units of weight are:
|
| pb.routing.cvr.looseningBarrierRestrictions | Boolean | Optional. Specifies that barriers will be ignored when determining the route.These restrictions most often occur when a commercial vehicle is prohibited from traversing a segment due to local ordinance, or a commercial vehicle is allowed on the segment but only when it must (for example, last mile access, local delivery, and so on). Routes where a barrier has been removed will still have a higher route cost even if the route it shorter/faster than a route with no barrier. |
Return Values
This function returns values described in the table below:
| Return Field | Description |
|---|---|
| Distance | The total distance of the shortest path between two points in meters. |
| Time | The shortest duration of time it takes to travel between two points in minutes. |
| Error | Any error that occurs; if none, then null. |
Examples
SELECT PointToPointRoute(-77.750333, 38.736103, -77.693102, 38.677640);SELECT PointToPointRoute(ST_Point(-77.750333, 39.736103), ST_Point(-77.693102, 38.677640), map('pb.routing.majorRoads', 'false')).distance;SELECT PointToPointRoute(Geocode('485A Watervliet Shaker Rd, Latham, NY 12110','usa').geometry, Geocode('204-240 Jordan Rd, Troy, NY 12180','usa').geometry);SELECT PointToPointRoute(-77.750333, 38.736103, -77.693102, 38.677640, map('pb.routing.engine.timeout', 300)) FROM <table_name>;The previous example had the time-out specified as an number. It can also be specified as a string:
SELECT PointToPointRoute(-77.750333, 38.736103, -77.693102, 38.677640, map('pb.routing.engine.timeout', '300')) FROM <table_name>; Hive requires that all values in a MAP must be of the same type:
SELECT PointToPointRoute(-77.750333, 38.736103, -77.693102, 38.677640, map('pb.routing.engine.timeout', '300', 'pb.routing.allowFallback', 'false')) FROM <table_name>;