Create service areas

Create Service Areas generates reachable service areas around facilities that represent all streets accessed within a specified travel distance or travel time. For example, the 10-minute walk-time service area around a subway station indicates a region where people can walk to the station within ten minutes.

Usage notes

• Create Service Areas requires that the input DataFrame has a point geometry column representing the facilities around which the service areas will be created.

• A network dataset is required to run any network analysis tool. It must be locally accessible to all nodes in your Spark cluster. Use setNetwork() to load the network dataset from a mobile map package or a mobile geodatabase.

• A travel mode refers to the mode of transportation, such as driving or walking. Use setTravelMode() 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.

• Use the setTravelDirection() setter to specify the direction of travel to or from the facilities. There are two options:

  • FromFacilities—The service area is calculated starting from the facilities and extending outward to the periphery within the specified impedance cutoffs.

  • ToFacilities—The service area is calculated from the periphery to the facilities within the specified impedance cutoffs.

  Which travel direction you should use is determined by the nature of the service area analysis. For example, to find all addresses around a restaurant that can be delivered-to within a certain amount of time, use FromFacilities. To find all restaurants around a single address that the residents of that address can reach within a certain amount of time, use ToFacilities.

• It is required to set impedance cutoffs using setCutoffs(). An impedance cutoff is used to calculate the extent of a service area and must be in the same units as the travel mode. For example, if the travel mode is driving time, the impedance cutoff should be an amount of time. There are two types of cutoffs supported in the Create Service Areas tool:

  • Distance cutoffs—Specify the maximum distance that can be traveled from or to the facilities. For example, when analyzing driving distance from a hospital, a cutoff value of 5 miles means to create a service area reachable within 5 miles driving from the hospital.

  • Time cutoffs—Specify the maximum time allowed to travel from or to the facilities. For example, when analyzing the time for trucks to deliver goods from a warehouse, a cutoff value of 30 minutes means to create a service area that the truck can reach within a 30-minute drive from the warehouse.

  setCutoffs() accepts a single cutoff value or an array of values. To find 2-mile service areas, use setCutoffs(2, "miles"). To find 5-, 10-, and 15-minute service areas, use setCutoffs([5, 10, 15], "minutes"). The cutoff value must be positive. If the unit is missing, the tool will use the distance or time unit predefined in the travel mode.

• You can specify the level of detail for the output geometry using setPolygonDetails(). There are two options:

  • Standard—Polygons will be created with a standard level of detail. Standard polygons are generated quickly and are fairly accurate, but quality deteriorates as you move toward the borders of the service area polygons. This is the default.

  • High—Polygons will be created with the highest level of detail. Holes in the polygon may exist; they represent islands of network elements, such as streets, that couldn't be reached without exceeding the cutoff impedance or due to travel restrictions. Use this option for applications in which precise results are important.

• You can specify whether concentric service area polygons will be created as disks or rings using setGeometryAtCutoff(). There are two options:

  • Rings—The polygons representing larger breaks will exclude the polygons of smaller breaks. This creates polygons between consecutive breaks. Use this option to find the area from one break to another. For instance, if you create 5- and 10-minute service areas, the 10-minute service area polygon will exclude the area under the 5-minute service area polygon. This is the default.

  • Disks—Polygons will be created from the facility to the break. For instance, if you create 5- and 10-minute service areas, the 10-minute service area polygon will include the area under the 5-minute service area polygon.

• Analysis will be completed in the coordinate system of the network dataset.

• The default geometry field of the output Dataframe is the service area polygons. The output Dataframe will have the same spatial reference as the network dataset.

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.

• GeoAnalytics Engine does not support using traffic info in network analysis.

Results

The output DataFrame contains all fields from the input facility DataFrame and two columns representing the service areas:

Performance notes

Improve the performance of Create Service Areas tool 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.
• Use a standard level of detail (the default) for the output polygons rather than a high level of detail.
• Use fewer cutoffs and smaller cutoff values.

Similar capabilities

• Create Routes tool
• Find Closest Facilities tool
• Generate OD Matrix tool

Syntax

For more details, go to the GeoAnalytics Engine API reference for create service areas.

Examples

Run Create Service Areas

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
# Log in
import geoanalytics
geoanalytics.auth(username="myusername", password="mypassword")

# Imports
from geoanalytics.tools import CreateServiceAreas
import matplotlib.pyplot as plt

# Path to the San Diego Fire Stations data
data_url = r"https://services.arcgis.com/P3ePLMYs2RVChkJx/ArcGIS/rest/services/SDFireStations/FeatureServer/0"

# Create a facility DataFrame
df = spark.read.format("feature-service").load(data_url) \
          .select("FACILITYID", "NAME", "FULLADDR", "PHONE", "ACTIVE", "shape")

# Access the Network Dataset
# This needs to be accessible to the machine that is running the Create Service Areas tool.
# If running on a cluster, it needs to be accessible to all nodes in the cluster.
california_network = r"/data/California.mmpk"

# Run the Create Service Areas tool
result = CreateServiceAreas() \
        .setNetwork(california_network) \
        .setTravelMode("driving time") \
        .setTravelDirection("FromFacilities") \
        .setCutoffs([2, 4], "minutes") \
        .setPolygonDetail("standard") \
        .setGeometryAtCutoff("rings") \
        .run(df)

# Show the first 5 results
result.sort("FACILITYID", "cutoff").show(5)

1
2
3
4
5
6
7
8
9
10
+----------+-----------+-----------------+------------+------+--------------------+---------+--------------------+
|FACILITYID|       NAME|         FULLADDR|       PHONE|ACTIVE|               shape|   cutoff|service_area_polygon|
+----------+-----------+-----------------+------------+------+--------------------+---------+--------------------+
|         1|SD FS 1/201|1222 First Avenue|619-533-4300|   Yes|{"x":-117.1644945...|2 minutes|{"rings":[[[-117....|
|         1|SD FS 1/201|1222 First Avenue|619-533-4300|   Yes|{"x":-117.1644945...|4 minutes|{"rings":[[[-117....|
|        10|   SD FS 10| 4605 62nd Street|619-533-4300|   Yes|{"x":-117.0637437...|2 minutes|{"rings":[[[-117....|
|        10|   SD FS 10| 4605 62nd Street|619-533-4300|   Yes|{"x":-117.0637437...|4 minutes|{"rings":[[[-117....|
|        11|   SD FS 11|  945 25th Street|619-533-4300|   Yes|{"x":-117.1400215...|2 minutes|{"rings":[[[-117....|
+----------+-----------+-----------------+------------+------+--------------------+---------+--------------------+
only showing top 5 rows

Plot results

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
# Plot the service areas around the Fire Stations in San Diego
colors = ['#016c59', '#67a9cf']
cmap = plt.cm.colors.ListedColormap(colors)

result_plot = result.st.plot(cmap_values="cutoff",
                             cmap=cmap, is_categorical=True,
                             basemap="light",
                             figsize=(15,15),
                             legend=True,
                             legend_kwds = {"title": "Cutoffs"});

df.st.plot(facecolor = "#bd0026", marker_size=5, ax=result_plot)
result_plot.set_title("Two- and four-minute drive-time service areas for fire stations in San Diego")
result_plot.set_xlabel("X (Degrees)")
result_plot.set_ylabel("Y (Degrees)");

Version table

Links to helpful information

• Network analysis
• Create Routes tool
• Find Closest Facilities tool
• Generate OD Matrix tool
• Visualizing results