The Create Routes tool finds the best route between a series of input points. The resulting DataFrame contains a linestring column with the routes that visit the input points.
The returned routes can be:
- The shortest route between two locations that minimizes the travel distance or travel time.
- A route that visits a series of locations in a specified order. This is referred to as a simple route.
- A route that finds the best sequence in which to visit a series of locations. This is referred to as an optimized route.
Usage notes
-
The Create Routes tool returns a route for each input record.
-
A network dataset is required to run any network analysis tool. It must be locally accessible to all nodes in your Spark cluster. Use
set
to load the network dataset from a mobile map package or a mobile geodatabase.Network() -
A travel mode refers to the mode of transportation, such as driving or walking. Use
set
to choose a mode defined in the network datasource, or a custom travel mode defined in a JSON string. By default, the tool uses the default travel mode in the network datasource.Travel Mode() -
The
set
parameter takes an array of points, referred to as stops, which are locations that the returned route will visit.Stops() -
The
set
parameter accepts one of the following inputs:Route Geometry() "
—Generates true paths along the network.Along Network" "
—Outputs simplified paths as straight lines.Straight Lines" "
—No lines are generated.No Lines"
-
The
set
setter determines the order in which the input stops will be visited to create a route. You can optimally route the stops by setting theSequence() find
parameter to_best True
. When you are optimially routing you can preserve one or both of the first and last stops by setting thepreserve
and_first preserve
parameters to_last True
. If you set thefind
parameter to_best False
, the route will use the sequence provided by your input inset
, and theStops() preserve
and_first preserve
parameters are not applied._last -
Below is an example of how the
set
setter works given a series of stops that were set by callingSequence() set
.Stops( A, B, C, D) -
Using
set
, the Create Routes tool will return a route that visits the points in the order they were passed in, which is A,B,C,D.Sequence(find _best= False) -
Using
set
, the Create Routes tool will return a route that visits the points in an optimized order that minimizes travel costs, which is A,C,D,B.Sequence(find _best= True) -
Using
set
, the Create Routes tool will return a route that visits the points in an optimized order that minimizes travel costs while still preserving the order of the first and last points, which is A,C,B,D:Sequence(find _best= False, preserve _first= True, preserve _last= True)
-
-
When travel mode is configured wth traffic data, you can specify the start time in a day of week for the route. Route start time is typically used to find routes based on the impedance attribute that varies with the time. For example, a start time of 7:00 a.m. can be used to find a route that considers rush hour traffic.
Traffic information will not be used in network analysis when
set
is not used, or when the setter is used but no traffic data is configured with the travel mode .Time() -
GeoAnalytics Engine supports setting the start time as a specific time in a generic weekday using
set
.Time(day _of _week, time, time _zone = " UT C") day
is a string representing the day of the week. Acceptable values are:_of _week Sunday
Monday
Tuesday
Wednesday
Thursday
Friday
Saturday
time
is the time of day when traffic will be modeled. It can be provided in two formats:- A string in the format "HH:mm:ss", for example, "14:30:00".
- A
datetime.time
object.
time
is an optional string representing the time zone. The default time zone is Coordinated Universal Time (UTC). You can specify a time zone ID in the following formats to use local time._zone - UTC offset—a fixed offset from UTC. For example "UTC-05:00" representing the time zone that is five hours behind UTC. GeoAnalytics Engine does not account for Daylight Savings Time (DST). Only Standard Time (SDT) is used for UTC offset.
- Time zone identifier—a standardized string that uniquely identifies a time zone region (e.g., "America/New_York"). For a comprehensive list of time zone identifiers, refer to this list of tz database time zones.
For example, to set the start time as Friday at 8:15 a.m. in the "America/New_York" time zone, you can use
set
,Time(" Friday", "08 :15 :00", " America/ New _York") set
, orTime(" Friday", datetime.time(8,15), " America/ New _York") set
.Time(" Friday", "13 :15 :00", " UT C")
Limitations
-
Network analysis requires a network dataset from a mobile map package or a mobile geodatabase. Loading network data from a file geodatabase is not supported. Using a network service, such as the ArcGIS Online network analysis service, is not supported.
-
GeoAnalytics Engine does not support adding barriers in network analysis.
Results
In addition to the fields from the input DataFrame, the fields in the following table are included in the output
DataFrame. The only exception to this is if the No
option is used for .set
, in which
the route
column won't be returned:
Field | Description |
---|---|
travel | The total travel time for the route in minutes. |
travel | The total travel distance for the route in meters. |
route | The linestring geometry representing the route. |
Performance notes
Improve the performance of Create Routes by doing one or more of the following:
-
Only analyze the records in your area of interest. You can pick the records of interest by using one of the following SQL functions:
- ST_Intersection—Clip to an area of interest represented by a polygon. This will modify your input records.
- ST_BboxIntersects—Select records that intersect an envelope.
- ST_EnvIntersects—Select records having an evelope that intersects the envelope of another geometry.
- ST_Intersects—Select records that intersect another dataset or area of intersect represented by a polygon.
- Set the route geometry to
Nolines
instead of theAlong
orNetwork Straight
if you are only interested in determining the total travel time or travel distance between a series of input points.Lines
Similar capabilities
Syntax
For more details, go to the GeoAnalytics Engine API reference for create routes.
Setter | Description | Required |
---|---|---|
run(dataframe) | Runs the Create Routes tool using the provided DataFrame. | Yes |
set | The path of the network dataset that will be used for the network analysis. | Yes |
set | A DataFrame column containing arrays of points that will be used to create the route. | Yes |
set | Determines the order in which the route will visit the input stops. | No |
set | Sets the route geometry representing the route between the stops. Choose from ' (default), ' or ' . | No |
set | Sets the start time for the routes. | No |
set | Sets the travel mode. By default, the tool uses the default travel mode in the network datasource. | No |
Examples
Run Create Routes
# Log in
import geoanalytics
geoanalytics.auth(username="myusername", password="mypassword")
# Imports
from pyspark.sql import functions as F
from geoanalytics.sql import functions as ST
from geoanalytics.tools import CreateRoutes
# Path to the New York vehicle start and end points
vehicle_locations_path = r"C:\nyc_vehicle_start_end_points"
# Path to the New York network dataset
network_dataset_path = r"C:\New_York.mmpk"
# Create a DataFrame with an array column made up of the vehicle start and end points along with two additional points
# to visit in New York city as part of the route
trip_locations_df = spark.read.format("geoparquet").load(vehicle_locations_path)\
.withColumn("empire_state_building", ST.point(F.lit(-73.9814406), F.lit(40.7342447), sr=4326))\
.withColumn("area_53", ST.point(F.lit(-73.9282016), F.lit(40.7122077), sr=4326))\
.withColumn("trip_locations", F.array("trip_start", "area_53", "empire_state_building", "trip_end"))
# Run the Create Routes tool to generate a route for each vehicle that minimizes the driving time to visit all of the
# stops, while preserving the trip start and end locations.
optimal_trip_routes = CreateRoutes()\
.setNetwork(network_dataset_path)\
.setStops("trip_locations")\
.setTravelMode("Driving Time")\
.setRouteGeometry("AlongNetwork")\
.setSequence(find_best=True, preserve_first=True, preserve_last=True)\
.run(trip_locations_df)
# Show selected columns from the results DataFrame
optimal_trip_routes.select("unique_id", "trip_locations", "travel_time", "travel_distance", "route_geometry").show(5)
+---------+--------------------+-----------------+------------------+--------------------+
|unique_id| trip_locations| travel_time| travel_distance| route_geometry|
+---------+--------------------+-----------------+------------------+--------------------+
| 0|[{"x":-73.8710784...|47.27411416634998| 23385.41041389714|{"paths":[[[-73.8...|
| 1|[{"x":-73.9837799...|55.21945154864122|22991.525780181702|{"paths":[[[-73.9...|
| 2|[{"x":-73.9820556...| 65.9056057881696|25997.134204527312|{"paths":[[[-73.9...|
| 3|[{"x":-74.0005111...|47.14527620656458|19792.443213209775|{"paths":[[[-74.0...|
| 4|[{"x":-73.8659591...|51.05305474030447| 25497.14207067214|{"paths":[[[-73.8...|
+---------+--------------------+-----------------+------------------+--------------------+
only showing top 5 rows
Plot results
# Select the route for vehicle 11 and tranform the route geometry and the input points for plotting to 32118 (NAD83 - New York Long Island)
vehicle_11_route = optimal_trip_routes.where("unique_id == 11")\
.withColumn("route_geometry", ST.transform("route_geometry", sr=32118))\
.withColumn("trip_start", ST.transform("trip_start", sr=32118))\
.withColumn("empire_state_building", ST.transform("empire_state_building", sr=32118))\
.withColumn("area_53", ST.transform("area_53", sr=32118))\
.withColumn("trip_end", ST.transform("trip_end", sr=32118))
# Plot the route for vehicle 11 that minimizes driving time
route_plot = vehicle_11_route.st.plot(geometry="route_geometry", basemap="light", figsize=(16, 10))
start_plot = vehicle_11_route.st.plot(ax=route_plot, geometry="trip_start", c="green", marker="d", s=100, label="Trip Start")
empire_state_building_plot = vehicle_11_route.st.plot(ax=start_plot, geometry="empire_state_building", c="darkorange", marker="d", s=100, label="Empire State Building")
area_53_plot = vehicle_11_route.st.plot(ax=empire_state_building_plot, geometry="area_53", c="violet", marker="d", s=100, label="Area 53 Adventure Park")
result_plot = vehicle_11_route.st.plot(ax=area_53_plot, geometry="trip_end", c="red", marker="d", s=100, legend=True, label="Trip End")
result_plot.legend(loc="upper right")
result_plot.set_title("Route That Minimizes The Driving Time To Visit All Of The New York Stops For Vehicle 11")
result_plot.set_xlabel("X (Meters)")
result_plot.set_ylabel("Y (Meters)");
Version table
Release | Notes |
---|---|
1.3.0 | Tool introduced |
1.4.0 | Added support for setting start time. |