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"). It also accepts a string representing the column name in the input data. In this case, the tool will apply the cutoff value in the column on a per-facility basis. The cutoff value must be positive. Only the facilities with a positive cutoff value will be maintained in the output DataFrame. If the unit is missing, the tool will use the distance or time unit predefined in the travel mode.

• You can specify the output geometry type using setOutputType(). There are two options:

  • Polygons—The tool returns service areas as polygons, which cover the areas of the network that can be reached within the given cutoffs.

  • Polylines—The tool returns service areas as linestrings that cover the streets or network edges that can be reached within the given cutoffs. Linestrings are a truer representation of a service area than polygons since service area analyses are based on measurements along the network lines.

• You can specify the level of detail for the output geometry using setPolygonDetails() when output type is set to polygons. 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() when output type is set to polygons. 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.

• When output type is linestrings, two columns FromPosition and ToPosition are returned in the output DataFrame.

  FromPosition is the percentage along the underlying source feature that the service area line begins. The value ranges from 0 to 1, where 0 represents linestring starting at the from point of the underlying source feature and 1 represents linestring starting at the to point. For example, a value of 0.25 means that the linestring begins 25 percent along the digitized direction of the underlying source feature.

  ToPosition is the percentage along the underlying source feature that the service area line ends. The value ranges from 0 to 1, where 0 represents linestring ending at the from point of the underlying source feature and 1 represents that linestring ending at the to point. For example, a value of 0.25 that means the linestring ends 25 percent along the digitized direction of the underlying source feature.

• When output type is linestrings, use the setter accumulateAttributes() to include cost attributes accumulated from the facility to the beginning or end of the line feature. The cost attributes are defined in the network dataset. One or more From_Cumul_[Cost] and To_Cumul_[Cost] columns will be returned, where Cost is the name of the cost attribute. By default, the cost attribute of the specified travel mode will be accumulated and returned in the output DataFrame. Additional attributes will be accumulated if more costs are listed in this setter. For example, when analyzing driving time with Minutes as the cost attribute, and calling accumulateAttributes("Kilometers"), four output fields (From_Cumul_Minutes, To_Cumul_Minutes, From_Cumul_Kilometers, and To_Cumul_Kilometers) will be returned.

• When travel mode is configured wth traffic data, you can specify the time to depart from or arrive at the facilities of the service area analysis using setTime(day_of_week, time, time_zone = "UTC"). The time represents the departure time if travel direction is set to away from facilities. It represents the arrival time if travel direction is set to toward facilities. This parameter is most useful for finding the service areas that can be reached based on a travel mode that uses an impedance attribute that varies with the time of the day, such as one based on dynamic traffic conditions. Solving the same analysis using different day of week or time values allows you to see how a facility's reach changes over time. For example, the five-minute service area around a fire station may start out large in the early morning, diminish during the morning rush hour, grow in the late morning, and so on, throughout the day.

  Traffic information will not be used in network analysis when setTime() is not used, or when the setter is used but no traffic data is configured with the travel mode .

• GeoAnalytics Engine supports setting the start time as a specific time in a generic weekday using setTime(day_of_week, time, time_zone = "UTC").

  day_of_week is a string representing the day of the week. Acceptable values are:

  • 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_zone 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.

  • 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 time for Friday at 8:15 a.m. in the "America/New_York" time zone, you can use setTime("Friday", "08:15:00", "America/New_York"), setTime("Friday", datetime.time(8,15), "America/New_York"), or setTime("Friday", "13:15:00", "UTC").

• 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 or polylines. 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.

Results

The format of the output DataFrame differs depending on the output type. The two options for the output types are Polygons and Polylines.

Polygon output

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

Polyline output

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

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